clipwise 0.2.1 → 0.4.0

package/dist/index.js

@@ -52,16 +52,45 @@ async function getElementCenter(page, selector, timeout) {
 
 // src/core/recorder.ts
 var CLICK_EFFECT_DURATION_MS = 500;
-var REPAINT_INTERVAL_MS = 50;
+var REPAINT_INTERVAL_MS = 25;
 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
+  fast: { steps: 10, delay: 22 },
+  // ~220ms, ~9 frames captured
+  normal: { steps: 14, delay: 25 },
+  // ~350ms, ~14 frames captured
+  slow: { steps: 20, delay: 25 }
+  // ~500ms, ~20 frames captured
 };
+var FrameChannel = class {
+  buffer = [];
+  resolve = null;
+  closed = false;
+  push(frame) {
+    if (this.closed) return;
+    this.buffer.push(frame);
+    this.resolve?.();
+    this.resolve = null;
+  }
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.resolve?.();
+    this.resolve = null;
+  }
+  async *[Symbol.asyncIterator]() {
+    while (true) {
+      while (this.buffer.length > 0) {
+        yield this.buffer.shift();
+      }
+      if (this.closed) return;
+      await new Promise((r) => {
+        this.resolve = r;
+      });
+    }
+  }
+};
+var DEDUP_SIGNATURE_BYTES = 2048;
 var ClipwiseRecorder = class {
   browser = null;
   context = null;
@@ -74,11 +103,21 @@ var ClipwiseRecorder = class {
   currentStepIndex = 0;
   cursorPosition = { x: 0, y: 0 };
   viewport = { width: 1280, height: 800 };
+  deviceScaleFactor = 1;
   isCapturing = false;
   targetFps = 30;
   cursorSpeed = "fast";
   firstContentTimestamp = 0;
   pendingResponsePromises = /* @__PURE__ */ new Map();
+  // ── 중복 프레임 제거 (Phase 1-A) ──────────────────────────────────────────
+  // 직전 저장된 프레임의 앞부분 시그니처. 동일하면 화면 내용이 바뀌지 않은 것.
+  lastFrameSignature = null;
+  dedupStats = { received: 0, stored: 0, skipped: 0 };
+  // ── 스트리밍 채널 (Phase 3-B) ───────────────────────────────────────────
+  // Set during recordToChannel(); null in normal record() mode.
+  frameChannel = null;
+  channelIndex = 0;
+  // sequential index for channel-pushed frames
   /**
    * Launch the browser and create a page with the scenario viewport.
    */
@@ -102,6 +141,10 @@ var ClipwiseRecorder = class {
     this.cursorPosition = { x: 0, y: 0 };
     this.isCapturing = false;
     this.firstContentTimestamp = 0;
+    this.lastFrameSignature = null;
+    this.dedupStats = { received: 0, stored: 0, skipped: 0 };
+    this.frameChannel = null;
+    this.channelIndex = 0;
   }
   /**
    * Start CDP screencast for continuous frame capture.
@@ -116,10 +159,24 @@ var ClipwiseRecorder = class {
       async (event) => {
         if (!this.isCapturing || !this.cdpClient) return;
         const buffer = Buffer.from(event.data, "base64");
-        this.rawFrames.push({
-          buffer,
-          timestamp: Date.now()
-        });
+        this.dedupStats.received++;
+        const signature = buffer.subarray(0, DEDUP_SIGNATURE_BYTES);
+        const isDuplicate = this.lastFrameSignature !== null && this.lastFrameSignature.length === signature.length && this.lastFrameSignature.equals(signature);
+        if (isDuplicate) {
+          this.dedupStats.skipped++;
+        } else {
+          this.lastFrameSignature = Buffer.from(signature);
+          const captureTime = Date.now();
+          this.rawFrames.push({ buffer, timestamp: captureTime, stepIndex: this.currentStepIndex });
+          this.dedupStats.stored++;
+          if (this.frameChannel && this.firstContentTimestamp > 0) {
+            const frame = this.buildFrameOnline(
+              { buffer, timestamp: captureTime, stepIndex: this.currentStepIndex },
+              this.channelIndex++
+            );
+            this.frameChannel.push(frame);
+          }
+        }
         await this.cdpClient.send("Page.screencastFrameAck", {
           sessionId: event.sessionId
         }).catch(() => {
@@ -127,10 +184,9 @@ var ClipwiseRecorder = class {
       }
     );
     await this.cdpClient.send("Page.startScreencast", {
-      format: "jpeg",
-      quality: 95,
-      maxWidth: this.viewport.width,
-      maxHeight: this.viewport.height,
+      format: "png",
+      maxWidth: this.viewport.width * this.deviceScaleFactor,
+      maxHeight: this.viewport.height * this.deviceScaleFactor,
       everyNthFrame: 1
     });
     this.cursorTimeline.push({
@@ -159,13 +215,23 @@ var ClipwiseRecorder = class {
     await this.init(scenario);
     const startTime = Date.now();
     try {
+      if (scenario.steps.length > 0) {
+        const s0 = scenario.steps[0];
+        this.currentStepIndex = 0;
+        this.preRegisterResponseListeners(s0.actions);
+        for (let ai = 0; ai < s0.actions.length; ai++) {
+          await this.executeAction(s0.actions[ai], ai);
+        }
+      }
       await this.startCapture();
       for (let si = 0; si < scenario.steps.length; si++) {
         const step = scenario.steps[si];
         this.currentStepIndex = si;
-        this.preRegisterResponseListeners(step.actions);
-        for (let ai = 0; ai < step.actions.length; ai++) {
-          await this.executeAction(step.actions[ai], ai);
+        if (si > 0) {
+          this.preRegisterResponseListeners(step.actions);
+          for (let ai = 0; ai < step.actions.length; ai++) {
+            await this.executeAction(step.actions[ai], ai);
+          }
         }
         if (step.captureDelay > 0) {
           await this.waitWithRepaints(step.captureDelay);
@@ -186,7 +252,8 @@ var ClipwiseRecorder = class {
         scenario,
         frames,
         startTime,
-        endTime: Date.now()
+        endTime: Date.now(),
+        dedupStats: { ...this.dedupStats }
       };
     } catch (error) {
       await this.stopCapture().catch(() => {
@@ -202,13 +269,116 @@ var ClipwiseRecorder = class {
         scenario,
         frames,
         startTime,
-        endTime: Date.now()
+        endTime: Date.now(),
+        dedupStats: { ...this.dedupStats }
       };
       throw err;
     } finally {
       await this.cleanup();
     }
   }
+  // ─── Streaming recording API (Phase 3-B) ──────────────────────────────────
+  /**
+   * Start recording concurrently and return a RecordingHandle immediately.
+   *
+   * frameStream: yields CapturedFrames as each unique frame arrives from CDP
+   *   (post-dedup, sequential indices starting at 0, NO FPS resampling).
+   *   Closes when recording ends.
+   *
+   * done: resolves with the full RecordingSession (FPS-resampled) once
+   *   all steps have completed and the browser has been cleaned up.
+   *
+   * Use this with CanvasRenderer.composeStreamOnline() to overlap recording
+   * time with composition time — total wall-clock ≈ max(recordingMs, composeMs).
+   */
+  recordToChannel(scenario) {
+    const channel = new FrameChannel();
+    const done = (async () => {
+      try {
+        await this.init(scenario);
+        this.frameChannel = channel;
+        const startTime = Date.now();
+        if (scenario.steps.length > 0) {
+          const s0 = scenario.steps[0];
+          this.currentStepIndex = 0;
+          this.preRegisterResponseListeners(s0.actions);
+          for (let ai = 0; ai < s0.actions.length; ai++) {
+            await this.executeAction(s0.actions[ai], ai);
+          }
+        }
+        await this.startCapture();
+        for (let si = 0; si < scenario.steps.length; si++) {
+          const step = scenario.steps[si];
+          this.currentStepIndex = si;
+          if (si > 0) {
+            this.preRegisterResponseListeners(step.actions);
+            for (let ai = 0; ai < step.actions.length; ai++) {
+              await this.executeAction(step.actions[ai], ai);
+            }
+          }
+          if (step.captureDelay > 0) await this.waitWithRepaints(step.captureDelay);
+          if (step.holdDuration > 0) await this.waitWithRepaints(step.holdDuration);
+        }
+        await this.stopCapture();
+        channel.close();
+        const rawFrames = this.buildCapturedFrames();
+        const recordingDurationMs = Date.now() - startTime;
+        const frames = this.resampleToTargetFps(rawFrames, recordingDurationMs);
+        return {
+          scenario,
+          frames,
+          startTime,
+          endTime: Date.now(),
+          dedupStats: { ...this.dedupStats }
+        };
+      } catch (error) {
+        channel.close();
+        await this.stopCapture().catch(() => {
+        });
+        const rawFrames = this.buildCapturedFrames();
+        const session = {
+          scenario,
+          frames: rawFrames,
+          startTime: Date.now(),
+          dedupStats: { ...this.dedupStats }
+        };
+        const err = error instanceof Error ? error : new Error(String(error));
+        err.partialSession = session;
+        throw err;
+      } finally {
+        await this.cleanup();
+      }
+    })();
+    return { frameStream: channel, done };
+  }
+  /**
+   * Build a single CapturedFrame from a RawFrame in real-time.
+   * Used by recordToChannel() to emit frames as they arrive.
+   * Cursor/click data reflects the timeline up to this moment.
+   */
+  buildFrameOnline(raw, sequentialIndex) {
+    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) {
+      clickProgress = Math.min(1, (raw.timestamp - clickEvent.timestamp) / CLICK_EFFECT_DURATION_MS);
+    }
+    const frameKeystrokes = this.keystrokeTimeline.filter((k) => k.timestamp <= raw.timestamp);
+    return {
+      index: sequentialIndex,
+      screenshot: raw.buffer,
+      timestamp: raw.timestamp,
+      cursorPosition: cursorPos,
+      clickPosition: clickEvent?.position ?? null,
+      clickProgress,
+      viewport: { ...this.viewport },
+      deviceScaleFactor: this.deviceScaleFactor,
+      stepIndex: raw.stepIndex,
+      keystrokes: frameKeystrokes.length > 0 ? frameKeystrokes : void 0
+    };
+  }
   /**
    * Wait for a given duration while forcing periodic repaints
    * so CDP screencast keeps sending frames even on static pages.
@@ -444,8 +614,10 @@ var ClipwiseRecorder = class {
         clickPosition: clickEvent?.position ?? null,
         clickProgress,
         viewport: { ...this.viewport },
+        deviceScaleFactor: this.deviceScaleFactor,
         keystrokes: frameKeystrokes.length > 0 ? frameKeystrokes : void 0,
-        stepIndex: this.currentStepIndex
+        stepIndex: raw.stepIndex
+        // use per-frame step index captured at event time
       };
     });
   }
@@ -472,15 +644,9 @@ var ClipwiseRecorder = class {
     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 lo = this.binarySearchTimeline(frames, targetTimestamp);
+      const hi = Math.min(lo + 1, frames.length - 1);
+      const nearestIdx = Math.abs(frames[hi].timestamp - targetTimestamp) < Math.abs(frames[lo].timestamp - targetTimestamp) ? hi : lo;
       const cursorPos = this.interpolateCursorAt(targetTimestamp);
       const clickEvent = this.clickTimeline.find(
         (click) => targetTimestamp >= click.timestamp && targetTimestamp <= click.timestamp + CLICK_EFFECT_DURATION_MS
@@ -501,6 +667,7 @@ var ClipwiseRecorder = class {
         clickPosition: clickEvent?.position ?? null,
         clickProgress,
         viewport: { ...this.viewport },
+        deviceScaleFactor: this.deviceScaleFactor,
         stepName: frames[nearestIdx].stepName,
         stepIndex: frames[nearestIdx].stepIndex,
         keystrokes: frameKeystrokes.length > 0 ? frameKeystrokes : void 0
@@ -516,15 +683,9 @@ var ClipwiseRecorder = class {
     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;
-      }
-    }
+    const idx = this.binarySearchTimeline(this.cursorTimeline, timestamp);
+    const before = this.cursorTimeline[idx];
+    const after = this.cursorTimeline[Math.min(idx + 1, this.cursorTimeline.length - 1)];
     if (timestamp <= before.timestamp) return { ...before.position };
     if (timestamp >= after.timestamp) return { ...after.position };
     const t = (timestamp - before.timestamp) / (after.timestamp - before.timestamp);
@@ -537,6 +698,23 @@ var ClipwiseRecorder = class {
       )
     };
   }
+  /**
+   * Binary search: returns the index of the last entry whose timestamp <= target.
+   * Assumes the array is sorted by timestamp in ascending order.
+   */
+  binarySearchTimeline(timeline, target) {
+    let lo = 0;
+    let hi = timeline.length - 1;
+    while (lo < hi) {
+      const mid = lo + hi + 1 >> 1;
+      if (timeline[mid].timestamp <= target) {
+        lo = mid;
+      } else {
+        hi = mid - 1;
+      }
+    }
+    return lo;
+  }
   /**
    * Clean up browser resources. Always called after recording.
    */
@@ -561,7 +739,13 @@ var ClipwiseRecorder = class {
 };
 
 // src/compose/canvas-renderer.ts
-import sharp8 from "sharp";
+import { Worker } from "worker_threads";
+import os from "os";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+
+// src/compose/compose-frame.ts
+import sharp7 from "sharp";
 
 // src/effects/frame.ts
 import sharp from "sharp";
@@ -584,91 +768,113 @@ 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) {
+function buildBrowserChromeSvg(width, darkMode, dpr = 1) {
   const bg = darkMode ? "#2d2d2d" : "#e8e8e8";
   const addressBg = darkMode ? "#1a1a1a" : "#ffffff";
   const addressBorder = darkMode ? "#444444" : "#d0d0d0";
   const textColor = darkMode ? "#999999" : "#666666";
+  const tbarH = TITLE_BAR_HEIGHT * dpr;
+  const tlY = TRAFFIC_LIGHT_Y * dpr;
+  const tlR = TRAFFIC_LIGHT_RADIUS * dpr;
+  const tlStartX = TRAFFIC_LIGHTS_START_X * dpr;
+  const tlGap = TRAFFIC_LIGHT_GAP * dpr;
+  const aBarH = ADDRESS_BAR_HEIGHT * dpr;
+  const aBarMargin = ADDRESS_BAR_MARGIN * dpr;
+  const fontSize = 12 * dpr;
   const 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" }
+    { cx: tlStartX, fill: "#ff5f57" },
+    { cx: tlStartX + tlGap, fill: "#febc2e" },
+    { cx: tlStartX + tlGap * 2, fill: "#28c840" }
   ].map(
-    (light) => `<circle cx="${light.cx}" cy="${TRAFFIC_LIGHT_Y}" r="${TRAFFIC_LIGHT_RADIUS}" fill="${light.fill}"/>`
+    (light) => `<circle cx="${light.cx}" cy="${tlY}" r="${tlR}" 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}"/>
+  const addressBarWidth = width - aBarMargin * 2;
+  const addressBarX = aBarMargin;
+  const addressBarY = (tbarH - aBarH) / 2;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${tbarH}">
+    <rect width="${width}" height="${tbarH}" fill="${bg}"/>
     ${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}">
+    <rect x="${addressBarX}" y="${addressBarY}" width="${addressBarWidth}" height="${aBarH}"
+          rx="${6 * dpr}" ry="${6 * dpr}" fill="${addressBg}" stroke="${addressBorder}" stroke-width="${dpr}"/>
+    <text x="${width / 2}" y="${tlY + 4 * dpr}" text-anchor="middle"
+          font-family="system-ui, -apple-system, sans-serif" font-size="${fontSize}" fill="${textColor}">
       localhost
     </text>
   </svg>`;
 }
-function buildIPhoneFrameSvg(totalWidth, totalHeight, screenWidth, screenHeight, darkMode) {
+function buildIPhoneFrameSvg(totalWidth, totalHeight, screenWidth, screenHeight, darkMode, dpr = 1) {
   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;
+  const bezelTop = IPHONE_BEZEL.top * dpr;
+  const bezelBottom = IPHONE_BEZEL.bottom * dpr;
+  const bezelSides = IPHONE_BEZEL.sides * dpr;
+  const outerRadius = IPHONE_OUTER_RADIUS * dpr;
+  const innerRadius = IPHONE_INNER_RADIUS * dpr;
+  const islandW = IPHONE_ISLAND.width * dpr;
+  const islandH = IPHONE_ISLAND.height * dpr;
+  const homeBarW = IPHONE_HOME_BAR.width * dpr;
+  const homeBarH = IPHONE_HOME_BAR.height * dpr;
+  const islandX = (totalWidth - islandW) / 2;
+  const islandY = (bezelTop - islandH) / 2 + 4 * dpr;
+  const homeBarX = (totalWidth - homeBarW) / 2;
+  const homeBarY = totalHeight - bezelBottom / 2 - homeBarH / 2;
+  const screenX = bezelSides;
+  const screenY = bezelTop;
   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}"/>
+          rx="${outerRadius}" ry="${outerRadius}" fill="${bezelColor}"/>
     <!-- Screen cutout (transparent) -->
     <rect x="${screenX}" y="${screenY}" width="${screenWidth}" height="${screenHeight}"
-          rx="${IPHONE_INNER_RADIUS}" ry="${IPHONE_INNER_RADIUS}" fill="black"/>
+          rx="${innerRadius}" ry="${innerRadius}" 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}"/>
+    <rect x="${islandX}" y="${islandY}" width="${islandW}" height="${islandH}"
+          rx="${islandH / 2}" ry="${islandH / 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}"/>
+    <rect x="${homeBarX}" y="${homeBarY}" width="${homeBarW}" height="${homeBarH}"
+          rx="${homeBarH / 2}" ry="${homeBarH / 2}" fill="${homeBarColor}"/>
   </svg>`;
 }
-function buildIPadFrameSvg(totalWidth, totalHeight, screenWidth, screenHeight, darkMode) {
+function buildIPadFrameSvg(totalWidth, totalHeight, screenWidth, screenHeight, darkMode, dpr = 1) {
   const bezelColor = darkMode ? "#1a1a1a" : "#f5f5f7";
   const cameraColor = darkMode ? "#2a2a2a" : "#3a3a3a";
-  const screenX = IPAD_BEZEL.sides;
-  const screenY = IPAD_BEZEL.top;
+  const screenX = IPAD_BEZEL.sides * dpr;
+  const screenY = IPAD_BEZEL.top * dpr;
   const cameraCx = totalWidth / 2;
-  const cameraCy = IPAD_BEZEL.top / 2;
+  const cameraCy = IPAD_BEZEL.top * dpr / 2;
+  const outerRadius = IPAD_OUTER_RADIUS * dpr;
+  const innerRadius = IPAD_INNER_RADIUS * dpr;
   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}"/>
+          rx="${outerRadius}" ry="${outerRadius}" fill="${bezelColor}"/>
     <!-- Screen cutout -->
     <rect x="${screenX}" y="${screenY}" width="${screenWidth}" height="${screenHeight}"
-          rx="${IPAD_INNER_RADIUS}" ry="${IPAD_INNER_RADIUS}" fill="black"/>
+          rx="${innerRadius}" ry="${innerRadius}" fill="black"/>
     <!-- Front camera dot -->
-    <circle cx="${cameraCx}" cy="${cameraCy}" r="4" fill="${cameraColor}"/>
+    <circle cx="${cameraCx}" cy="${cameraCy}" r="${4 * dpr}" fill="${cameraColor}"/>
   </svg>`;
 }
-function buildAndroidFrameSvg(totalWidth, totalHeight, screenWidth, screenHeight, darkMode) {
+function buildAndroidFrameSvg(totalWidth, totalHeight, screenWidth, screenHeight, darkMode, dpr = 1) {
   const bezelColor = darkMode ? "#1a1a1a" : "#e8e8e8";
   const cameraColor = darkMode ? "#2a2a2a" : "#3a3a3a";
-  const screenX = ANDROID_BEZEL.sides;
-  const screenY = ANDROID_BEZEL.top;
+  const screenX = ANDROID_BEZEL.sides * dpr;
+  const screenY = ANDROID_BEZEL.top * dpr;
   const cameraCx = totalWidth / 2;
-  const cameraCy = ANDROID_BEZEL.top / 2;
+  const cameraCy = ANDROID_BEZEL.top * dpr / 2;
+  const outerRadius = ANDROID_OUTER_RADIUS * dpr;
+  const innerRadius = ANDROID_INNER_RADIUS * dpr;
+  const cameraR = ANDROID_CAMERA_RADIUS * dpr;
   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}"/>
+          rx="${outerRadius}" ry="${outerRadius}" fill="${bezelColor}"/>
     <!-- Screen cutout -->
     <rect x="${screenX}" y="${screenY}" width="${screenWidth}" height="${screenHeight}"
-          rx="${ANDROID_INNER_RADIUS}" ry="${ANDROID_INNER_RADIUS}" fill="black"/>
+          rx="${innerRadius}" ry="${innerRadius}" fill="black"/>
     <!-- Punch-hole camera -->
-    <circle cx="${cameraCx}" cy="${cameraCy}" r="${ANDROID_CAMERA_RADIUS}" fill="${cameraColor}"/>
+    <circle cx="${cameraCx}" cy="${cameraCy}" r="${cameraR}" fill="${cameraColor}"/>
   </svg>`;
 }
 function buildScreenMaskSvg(width, height, radius) {
@@ -676,21 +882,33 @@ function buildScreenMaskSvg(width, height, radius) {
     <rect width="${width}" height="${height}" rx="${radius}" ry="${radius}" fill="white"/>
   </svg>`;
 }
-async function applyMobileFrame(frameBuffer, deviceType, darkMode, frameWidth, frameHeight) {
+async function applyMobileFrame(frameBuffer, deviceType, darkMode, frameWidth, frameHeight, dpr = 1) {
   let bezel;
   let innerRadius;
   switch (deviceType) {
     case "iphone":
-      bezel = IPHONE_BEZEL;
-      innerRadius = IPHONE_INNER_RADIUS;
+      bezel = {
+        sides: IPHONE_BEZEL.sides * dpr,
+        top: IPHONE_BEZEL.top * dpr,
+        bottom: IPHONE_BEZEL.bottom * dpr
+      };
+      innerRadius = IPHONE_INNER_RADIUS * dpr;
       break;
     case "ipad":
-      bezel = IPAD_BEZEL;
-      innerRadius = IPAD_INNER_RADIUS;
+      bezel = {
+        sides: IPAD_BEZEL.sides * dpr,
+        top: IPAD_BEZEL.top * dpr,
+        bottom: IPAD_BEZEL.bottom * dpr
+      };
+      innerRadius = IPAD_INNER_RADIUS * dpr;
       break;
     case "android":
-      bezel = ANDROID_BEZEL;
-      innerRadius = ANDROID_INNER_RADIUS;
+      bezel = {
+        sides: ANDROID_BEZEL.sides * dpr,
+        top: ANDROID_BEZEL.top * dpr,
+        bottom: ANDROID_BEZEL.bottom * dpr
+      };
+      innerRadius = ANDROID_INNER_RADIUS * dpr;
       break;
   }
   const totalWidth = frameWidth + bezel.sides * 2;
@@ -698,13 +916,13 @@ async function applyMobileFrame(frameBuffer, deviceType, darkMode, frameWidth, f
   let frameSvg;
   switch (deviceType) {
     case "iphone":
-      frameSvg = buildIPhoneFrameSvg(totalWidth, totalHeight, frameWidth, frameHeight, darkMode);
+      frameSvg = buildIPhoneFrameSvg(totalWidth, totalHeight, frameWidth, frameHeight, darkMode, dpr);
       break;
     case "ipad":
-      frameSvg = buildIPadFrameSvg(totalWidth, totalHeight, frameWidth, frameHeight, darkMode);
+      frameSvg = buildIPadFrameSvg(totalWidth, totalHeight, frameWidth, frameHeight, darkMode, dpr);
       break;
     case "android":
-      frameSvg = buildAndroidFrameSvg(totalWidth, totalHeight, frameWidth, frameHeight, darkMode);
+      frameSvg = buildAndroidFrameSvg(totalWidth, totalHeight, frameWidth, frameHeight, darkMode, dpr);
       break;
   }
   const maskSvg = buildScreenMaskSvg(frameWidth, frameHeight, innerRadius);
@@ -727,12 +945,13 @@ async function applyMobileFrame(frameBuffer, deviceType, darkMode, frameWidth, f
     { input: maskedScreen, left: bezel.sides, top: bezel.top }
   ]).png().toBuffer();
 }
-async function applyDeviceFrame(frameBuffer, config, frameWidth, frameHeight) {
+async function applyDeviceFrame(frameBuffer, config, frameWidth, frameHeight, dpr = 1) {
   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 tbarH = TITLE_BAR_HEIGHT * dpr;
+      const totalHeight = frameHeight + tbarH;
+      const chromeSvg = buildBrowserChromeSvg(frameWidth, config.darkMode, dpr);
       const chromeBuffer = Buffer.from(chromeSvg);
       const canvas = await sharp({
         create: {
@@ -744,13 +963,13 @@ async function applyDeviceFrame(frameBuffer, config, frameWidth, frameHeight) {
       }).png().toBuffer();
       return sharp(canvas).composite([
         { input: chromeBuffer, left: 0, top: 0 },
-        { input: frameBuffer, left: 0, top: TITLE_BAR_HEIGHT }
+        { input: frameBuffer, left: 0, top: tbarH }
       ]).png().toBuffer();
     }
     case "iphone":
     case "ipad":
     case "android":
-      return applyMobileFrame(frameBuffer, config.type, config.darkMode, frameWidth, frameHeight);
+      return applyMobileFrame(frameBuffer, config.type, config.darkMode, frameWidth, frameHeight, dpr);
     default:
       return frameBuffer;
   }
@@ -760,7 +979,7 @@ async function applyDeviceFrame(frameBuffer, config, frameWidth, frameHeight) {
 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">
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${s}" height="${s}" viewBox="0 0 24 24" shape-rendering="geometricPrecision">
     <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>`;
@@ -769,7 +988,7 @@ 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}">
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" shape-rendering="geometricPrecision">
     <circle cx="${size / 2}" cy="${size / 2}" r="${currentRadius}"
             fill="none" stroke="${color}" stroke-width="2"
             opacity="${opacity.toFixed(3)}"/>
@@ -777,47 +996,35 @@ function buildClickRippleSvg(radius, color, progress) {
             fill="${color}" opacity="${(opacity * 0.4).toFixed(3)}"/>
   </svg>`;
 }
-async function renderCursor(frameBuffer, position, config, frameWidth, frameHeight) {
+async function renderCursor(frameBuffer, position, config, frameWidth, frameHeight, dpr = 1) {
   if (!config.enabled) return frameBuffer;
-  const cursorSvg = buildCursorSvg(config.size, config.color);
+  const size = Math.round(config.size * dpr);
+  const cursorSvg = buildCursorSvg(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));
+  const left = Math.max(0, Math.min(Math.round(position.x * dpr), frameWidth - 1));
+  const top = Math.max(0, Math.min(Math.round(position.y * dpr), frameHeight - 1));
   return sharp2(frameBuffer).composite([{ input: cursorBuffer, left, top }]).png().toBuffer();
 }
-async function renderClickEffect(frameBuffer, position, config, progress, frameWidth, frameHeight) {
+async function renderClickEffect(frameBuffer, position, config, progress, frameWidth, frameHeight, dpr = 1) {
   if (!config.enabled || !config.clickEffect) return frameBuffer;
+  const radius = config.clickRadius * dpr;
   const clampedProgress = Math.max(0, Math.min(1, progress));
-  const rippleSvg = buildClickRippleSvg(
-    config.clickRadius,
-    config.clickColor,
-    clampedProgress
-  );
+  const rippleSvg = buildClickRippleSvg(radius, 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
-    )
-  );
+  const rippleSize = Math.ceil(radius * 2 + 4);
+  const px = Math.round(position.x * dpr);
+  const py = Math.round(position.y * dpr);
+  const left = Math.max(0, Math.min(px - Math.round(rippleSize / 2), frameWidth - rippleSize));
+  const top = Math.max(0, Math.min(py - Math.round(rippleSize / 2), frameHeight - rippleSize));
   return sharp2(frameBuffer).composite([{ input: rippleBuffer, left, top }]).png().toBuffer();
 }
-async function renderCursorHighlight(frameBuffer, position, config, frameWidth, frameHeight) {
+async function renderCursorHighlight(frameBuffer, position, config, frameWidth, frameHeight, dpr = 1) {
   if (!config.enabled || !config.highlight) return frameBuffer;
-  const r = config.highlightRadius;
+  const r = config.highlightRadius * dpr;
   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}">
+  const highlightSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" shape-rendering="geometricPrecision">
     <defs>
       <radialGradient id="glow">
         <stop offset="0%" stop-color="${config.highlightColor}" />
@@ -827,27 +1034,29 @@ async function renderCursorHighlight(frameBuffer, position, config, frameWidth,
     </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));
+  const px = Math.round(position.x * dpr);
+  const py = Math.round(position.y * dpr);
+  const left = Math.max(0, Math.min(px - Math.round(cx), frameWidth - size));
+  const top = Math.max(0, Math.min(py - Math.round(cy), frameHeight - size));
   return sharp2(frameBuffer).composite([{ input: Buffer.from(highlightSvg), left, top }]).png().toBuffer();
 }
-async function renderCursorTrail(frameBuffer, positions, config, frameWidth, frameHeight) {
+async function renderCursorTrail(frameBuffer, positions, config, frameWidth, frameHeight, dpr = 1) {
   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 strokeWidth = (1 + i / positions.length * 2) * dpr;
     const p1 = positions[i - 1];
     const p2 = positions[i];
     segments.push(
-      `<line x1="${p1.x}" y1="${p1.y}" x2="${p2.x}" y2="${p2.y}"
+      `<line x1="${p1.x * dpr}" y1="${p1.y * dpr}" x2="${p2.x * dpr}" y2="${p2.y * dpr}"
             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}">
+  const trailSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${frameWidth}" height="${frameHeight}" shape-rendering="geometricPrecision">
     ${segments.join("\n    ")}
   </svg>`;
   return sharp2(frameBuffer).composite([{ input: Buffer.from(trailSvg), left: 0, top: 0 }]).png().toBuffer();
@@ -867,20 +1076,56 @@ async function applyZoom(frameBuffer, focusPoint, scale, frameWidth, frameHeight
 }
 function calculateAdaptiveZoom(frames, currentIndex, maxScale, transitionFrames) {
   if (maxScale <= 1) return 1;
+  const lo = Math.max(0, currentIndex - transitionFrames);
+  const hi = Math.min(frames.length - 1, currentIndex + transitionFrames);
   let minDistance = Infinity;
-  for (let i = 0; i < frames.length; i++) {
+  for (let i = lo; i <= hi; i++) {
     if (frames[i].clickPosition) {
       const distance = Math.abs(i - currentIndex);
-      minDistance = Math.min(minDistance, distance);
+      if (distance < minDistance) minDistance = distance;
+    }
+  }
+  if (minDistance > transitionFrames) return 1;
+  const t = 1 - minDistance / transitionFrames;
+  return 1 + (maxScale - 1) * easeInOutCubic2(t);
+}
+function buildZoomClickLookup(frames) {
+  const indices = [];
+  for (let i = 0; i < frames.length; i++) {
+    if (frames[i].clickPosition !== null && frames[i].clickPosition !== void 0) {
+      indices.push(i);
     }
   }
-  if (minDistance === Infinity) return 1;
-  if (minDistance <= transitionFrames) {
-    const t = 1 - minDistance / transitionFrames;
-    const eased = easeInOutCubic2(t);
-    return 1 + (maxScale - 1) * eased;
+  return indices;
+}
+function calculateAdaptiveZoomFromLookup(clickLookup, currentIndex, maxScale, transitionFrames) {
+  if (maxScale <= 1 || clickLookup.length === 0) return 1;
+  let lo = 0;
+  let hi = clickLookup.length;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (clickLookup[mid] < currentIndex) lo = mid + 1;
+    else hi = mid;
+  }
+  const distBefore = lo > 0 ? currentIndex - clickLookup[lo - 1] : Infinity;
+  const distAfter = lo < clickLookup.length ? clickLookup[lo] - currentIndex : Infinity;
+  const minDistance = Math.min(distBefore, distAfter);
+  if (minDistance > transitionFrames) return 1;
+  const t = 1 - minDistance / transitionFrames;
+  return 1 + (maxScale - 1) * easeInOutCubic2(t);
+}
+function calculateAdaptiveZoomInWindow(windowFrames, windowStart, currentIndex, maxScale, transitionFrames) {
+  if (maxScale <= 1) return 1;
+  let minDistance = Infinity;
+  for (let j = 0; j < windowFrames.length; j++) {
+    if (windowFrames[j].clickPosition !== null && windowFrames[j].clickPosition !== void 0) {
+      const dist = Math.abs(windowStart + j - currentIndex);
+      if (dist < minDistance) minDistance = dist;
+    }
   }
-  return 1;
+  if (minDistance > transitionFrames) return 1;
+  const t = 1 - minDistance / transitionFrames;
+  return 1 + (maxScale - 1) * easeInOutCubic2(t);
 }
 function calculatePanOffset(focusPoint, scale, frameWidth, frameHeight) {
   if (scale <= 1) return { x: 0, y: 0 };
@@ -993,7 +1238,7 @@ async function applyBackground(frameBuffer, config, outputWidth, outputHeight) {
 
 // src/effects/keystroke.ts
 import sharp5 from "sharp";
-async function renderKeystrokeHud(frameBuffer, keystrokes, frameTimestamp, config, frameWidth, frameHeight) {
+async function renderKeystrokeHud(frameBuffer, keystrokes, frameTimestamp, config, frameWidth, frameHeight, dpr = 1) {
   if (!config.enabled || keystrokes.length === 0) return frameBuffer;
   const recentKeys = keystrokes.filter(
     (k) => frameTimestamp - k.timestamp < config.fadeAfter
@@ -1001,25 +1246,28 @@ async function renderKeystrokeHud(frameBuffer, keystrokes, frameTimestamp, confi
   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 fontSize = config.fontSize * dpr;
+  const padding = config.padding * dpr;
+  const charWidth = 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 hudPadH = padding * 2;
+  const hudPadV = padding * 1.5;
+  const hudWidth = Math.min(textWidth + hudPadH * 2, frameWidth - 40 * dpr);
+  const hudHeight = Math.ceil(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;
+  const margin = 30 * dpr;
   let hudX;
-  const hudY = frameHeight - hudHeight - 30;
+  const hudY = frameHeight - hudHeight - margin;
   switch (config.position) {
     case "bottom-left":
-      hudX = 30;
+      hudX = margin;
       break;
     case "bottom-right":
-      hudX = frameWidth - hudWidth - 30;
+      hudX = frameWidth - hudWidth - margin;
       break;
     case "bottom-center":
     default:
@@ -1029,43 +1277,20 @@ async function renderKeystrokeHud(frameBuffer, keystrokes, frameTimestamp, confi
   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}">
+  const hudSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${frameWidth}" height="${frameHeight}" shape-rendering="geometricPrecision" text-rendering="geometricPrecision">
     <rect x="${hudX}" y="${hudY}" width="${hudWidth}" height="${hudHeight}"
-          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}"
+          rx="${8 * dpr}" ry="${8 * dpr}" fill="${config.backgroundColor}" opacity="${opacity.toFixed(3)}" />
+    <text x="${hudX + hudPadH}" y="${hudY + hudPadV + fontSize * 0.75}"
+          font-family="monospace, Menlo, Consolas" font-size="${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;
+import sharp6 from "sharp";
+function buildWatermarkSvg(config, frameWidth, frameHeight) {
+  if (!config.enabled || !config.text) return "";
   const charWidth = config.fontSize * 0.62;
   const textWidth = Math.ceil(config.text.length * charWidth);
   const margin = 16;
@@ -1091,31 +1316,228 @@ async function renderWatermark(frameBuffer, config, frameWidth, frameHeight) {
       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}">
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${frameWidth}" height="${frameHeight}" shape-rendering="geometricPrecision" text-rendering="geometricPrecision">
     <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();
+}
+async function renderWatermark(frameBuffer, config, frameWidth, frameHeight) {
+  if (!config.enabled || !config.text) return frameBuffer;
+  const svg = buildWatermarkSvg(config, frameWidth, frameHeight);
+  return sharp6(frameBuffer).composite([{ input: Buffer.from(svg), left: 0, top: 0 }]).png().toBuffer();
 }
 
-// src/compose/canvas-renderer.ts
-function getFrameOffset(config) {
+// src/compose/compose-frame.ts
+function getFrameOffset(config, dpr = 1) {
   if (!config.enabled) return { left: 0, top: 0 };
   switch (config.type) {
     case "browser":
-      return { left: 0, top: 40 };
+      return { left: 0, top: 40 * dpr };
     case "iphone":
-      return { left: 12, top: 50 };
+      return { left: 12 * dpr, top: 50 * dpr };
     case "ipad":
-      return { left: 20, top: 24 };
+      return { left: 20 * dpr, top: 24 * dpr };
     case "android":
-      return { left: 8, top: 32 };
+      return { left: 8 * dpr, top: 32 * dpr };
     default:
       return { left: 0, top: 0 };
   }
 }
+async function composeFrame(frame, effects, output, context) {
+  let buffer = frame.screenshot;
+  const meta = await sharp7(buffer).metadata();
+  let width = meta.width ?? frame.viewport.width;
+  let height = meta.height ?? frame.viewport.height;
+  const dpr = Math.round(width / frame.viewport.width);
+  const ctx = {
+    zoomScale: context?.zoomScale ?? 1,
+    clickProgress: context?.clickProgress ?? null,
+    cursorTrail: context?.cursorTrail ?? []
+  };
+  if (effects.deviceFrame.enabled) {
+    const sl2 = ctx.staticLayers;
+    if (sl2?.browserChromePng && effects.deviceFrame.type === "browser") {
+      buffer = await sharp7(buffer).extend({
+        top: sl2.browserChromeHeight,
+        bottom: 0,
+        left: 0,
+        right: 0,
+        background: { r: 0, g: 0, b: 0, alpha: 0 }
+      }).composite([{ input: sl2.browserChromePng, left: 0, top: 0 }]).png().toBuffer();
+    } else {
+      buffer = await applyDeviceFrame(buffer, effects.deviceFrame, width, height, dpr);
+    }
+    const meta2 = await sharp7(buffer).metadata();
+    width = meta2.width ?? width;
+    height = meta2.height ?? height;
+  }
+  if (effects.cursor.enabled && effects.cursor.highlight && frame.cursorPosition) {
+    buffer = await renderCursorHighlight(
+      buffer,
+      frame.cursorPosition,
+      effects.cursor,
+      width,
+      height,
+      dpr
+    );
+  }
+  if (effects.cursor.enabled && effects.cursor.trail && ctx.cursorTrail.length >= 2) {
+    buffer = await renderCursorTrail(
+      buffer,
+      ctx.cursorTrail,
+      effects.cursor,
+      width,
+      height,
+      dpr
+    );
+  }
+  if (effects.cursor.enabled && frame.cursorPosition) {
+    buffer = await renderCursor(
+      buffer,
+      frame.cursorPosition,
+      effects.cursor,
+      width,
+      height,
+      dpr
+    );
+  }
+  if (effects.cursor.enabled && effects.cursor.clickEffect && frame.clickPosition) {
+    const progress = ctx.clickProgress ?? frame.clickProgress ?? 0.5;
+    buffer = await renderClickEffect(
+      buffer,
+      frame.clickPosition,
+      effects.cursor,
+      progress,
+      width,
+      height,
+      dpr
+    );
+  }
+  if (effects.keystroke.enabled && frame.keystrokes) {
+    buffer = await renderKeystrokeHud(
+      buffer,
+      frame.keystrokes,
+      frame.timestamp,
+      effects.keystroke,
+      width,
+      height,
+      dpr
+    );
+  }
+  const scale = ctx.zoomScale;
+  if (effects.zoom.enabled && scale > 1) {
+    const rawFocus = frame.clickPosition ?? frame.cursorPosition ?? { x: frame.viewport.width / 2, y: frame.viewport.height / 2 };
+    const offset = getFrameOffset(effects.deviceFrame, dpr);
+    const focusPoint = {
+      x: rawFocus.x * dpr + offset.left,
+      y: rawFocus.y * dpr + offset.top
+    };
+    buffer = await applyZoom(buffer, focusPoint, scale, width, height);
+  }
+  const sl = ctx.staticLayers;
+  if (sl) {
+    const padding = effects.background.padding;
+    const contentWidth = output.width - padding * 2;
+    const contentHeight = output.height - padding * 2;
+    if (contentWidth > 0 && contentHeight > 0) {
+      const radius = effects.background.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 { data: maskedData, info: maskedInfo } = await sharp7(buffer).resize(contentWidth, contentHeight, { fit: "fill" }).composite([{ input: roundedMask, blend: "dest-in" }]).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+      const { data: composited, info: compInfo } = await sharp7(sl.backdropRaw, {
+        raw: { width: sl.backdropWidth, height: sl.backdropHeight, channels: 4 }
+      }).composite([{
+        input: Buffer.from(maskedData),
+        raw: { width: maskedInfo.width, height: maskedInfo.height, channels: 4 },
+        left: padding,
+        top: padding
+      }]).raw().toBuffer({ resolveWithObject: true });
+      return {
+        index: frame.index,
+        buffer: Buffer.from(composited),
+        timestamp: frame.timestamp,
+        rawInfo: { width: compInfo.width, height: compInfo.height, channels: 4 }
+      };
+    }
+    buffer = sl.backdropRaw;
+  } else {
+    buffer = await applyBackground(buffer, effects.background, output.width, output.height);
+    if (effects.watermark.enabled) {
+      buffer = await renderWatermark(buffer, effects.watermark, output.width, output.height);
+    }
+  }
+  const { data: finalData, info: finalInfo } = await sharp7(buffer).resize(output.width, output.height, {
+    fit: "fill",
+    kernel: sharp7.kernel.lanczos3
+  }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  return {
+    index: frame.index,
+    buffer: Buffer.from(finalData),
+    timestamp: frame.timestamp,
+    rawInfo: { width: finalInfo.width, height: finalInfo.height, channels: 4 }
+  };
+}
+
+// src/effects/transition.ts
+import sharp8 from "sharp";
+async function applyCrossfade(fromBuffer, toBuffer, progress, width, height, fromRawInfo, toRawInfo) {
+  const t = Math.max(0, Math.min(1, progress));
+  if (t <= 0) {
+    const rawInfo = fromRawInfo ?? { width, height, channels: 4 };
+    if (fromRawInfo) return { buffer: fromBuffer, rawInfo };
+    const { data, info } = await sharp8(fromBuffer).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    return { buffer: Buffer.from(data), rawInfo: { width: info.width, height: info.height, channels: 4 } };
+  }
+  if (t >= 1) {
+    const rawInfo = toRawInfo ?? { width, height, channels: 4 };
+    if (toRawInfo) return { buffer: toBuffer, rawInfo };
+    const { data, info } = await sharp8(toBuffer).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    return { buffer: Buffer.from(data), rawInfo: { width: info.width, height: info.height, channels: 4 } };
+  }
+  const fromSrc = fromRawInfo ? sharp8(fromBuffer, { raw: { width: fromRawInfo.width, height: fromRawInfo.height, channels: fromRawInfo.channels } }) : sharp8(fromBuffer);
+  const fromRaw = await fromSrc.ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  const toSrc = toRawInfo ? sharp8(toBuffer, { raw: { width: toRawInfo.width, height: toRawInfo.height, channels: toRawInfo.channels } }) : sharp8(toBuffer);
+  const toRaw = await toSrc.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 {
+    buffer: pixels,
+    rawInfo: { width: fromRaw.info.width, height: fromRaw.info.height, channels: 4 }
+  };
+}
+
+// src/compose/canvas-renderer.ts
+var MIN_FRAMES_PER_WORKER = 4;
+var cachedWorkerUrl = null;
+function getWorkerUrl() {
+  if (cachedWorkerUrl) return cachedWorkerUrl;
+  const base = import.meta.url;
+  const candidates = [
+    new URL("./frame-worker.js", base),
+    // from dist/compose/
+    new URL("../compose/frame-worker.js", base),
+    // from dist/cli/
+    new URL("./compose/frame-worker.js", base)
+    // from dist/
+  ];
+  for (const url of candidates) {
+    if (existsSync(fileURLToPath(url))) {
+      cachedWorkerUrl = url;
+      return url;
+    }
+  }
+  cachedWorkerUrl = candidates[1];
+  return cachedWorkerUrl;
+}
 var CanvasRenderer = class {
   constructor(effects, output, steps) {
     this.effects = effects;
@@ -1124,118 +1546,11 @@ var CanvasRenderer = class {
   }
   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
+   * Apply the full effects pipeline to a single frame.
+   * Delegates to the standalone composeFrame function.
    */
   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
-    };
+    return composeFrame(frame, this.effects, this.output, context);
   }
   /**
    * Process an entire sequence of captured frames through the effects pipeline.
@@ -1243,7 +1558,7 @@ var CanvasRenderer = class {
    * 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 3: Render frames in parallel using worker threads.
    *   Pass 4: Apply scene transitions at step boundaries.
    */
   async composeAll(frames) {
@@ -1253,10 +1568,19 @@ var CanvasRenderer = class {
       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);
+    const cpuCount = os.cpus().length;
+    const workerCount = Math.min(cpuCount, 8);
+    const useWorkers = workerCount >= 2 && processFrames.length >= workerCount * MIN_FRAMES_PER_WORKER;
+    let composed;
+    if (useWorkers) {
+      composed = await this.processWithWorkers(processFrames, contexts, workerCount);
+    } else {
+      composed = [];
+      for (let i = 0; i < processFrames.length; i++) {
+        composed.push(
+          await composeFrame(processFrames[i], this.effects, this.output, contexts[i])
+        );
+      }
     }
     if (this.steps.length > 0) {
       await this.applyTransitions(composed, processFrames);
@@ -1264,19 +1588,78 @@ var CanvasRenderer = class {
     return composed;
   }
   /**
-   * Calculate per-frame rendering context (zoom, click progress, cursor trail, tilt).
+   * Distribute frame composition across a pool of worker threads.
+   * Workers process frames concurrently; results are collected in order.
+   */
+  processWithWorkers(frames, contexts, workerCount) {
+    return new Promise((resolve, reject) => {
+      const results = new Array(frames.length);
+      let completed = 0;
+      let nextIndex = 0;
+      let failed = false;
+      const workerUrl = getWorkerUrl();
+      const workers = [];
+      const dispatch = (worker) => {
+        if (nextIndex >= frames.length || failed) return;
+        const i = nextIndex++;
+        worker.postMessage({
+          taskId: i,
+          frame: frames[i],
+          effects: this.effects,
+          output: this.output,
+          context: contexts[i]
+        });
+      };
+      for (let w = 0; w < workerCount; w++) {
+        const worker = new Worker(workerUrl);
+        workers.push(worker);
+        worker.on("message", (msg) => {
+          if (failed) return;
+          if (msg.error) {
+            failed = true;
+            workers.forEach((wk) => wk.terminate());
+            reject(new Error(`Worker failed on frame ${msg.taskId}: ${msg.error}`));
+            return;
+          }
+          results[msg.taskId] = {
+            index: frames[msg.taskId].index,
+            buffer: Buffer.from(msg.buffer),
+            timestamp: frames[msg.taskId].timestamp,
+            rawInfo: msg.rawInfo
+          };
+          completed++;
+          if (completed === frames.length) {
+            workers.forEach((wk) => wk.terminate());
+            resolve(results);
+          } else {
+            dispatch(worker);
+          }
+        });
+        worker.on("error", (err) => {
+          if (failed) return;
+          failed = true;
+          workers.forEach((wk) => wk.terminate());
+          reject(err);
+        });
+        dispatch(worker);
+      }
+    });
+  }
+  /**
+   * Calculate per-frame rendering context (zoom scale, click progress, cursor trail).
    */
   calculateFrameContexts(frames) {
     const contexts = [];
     const transitionFrames = Math.round(
       this.output.fps * (this.effects.zoom.duration / 1e3)
     );
+    const clickLookup = this.effects.zoom.enabled ? buildZoomClickLookup(frames) : [];
     for (let i = 0; i < frames.length; i++) {
       const frame = frames[i];
       let zoomScale = 1;
       if (this.effects.zoom.enabled) {
-        zoomScale = calculateAdaptiveZoom(
-          frames,
+        zoomScale = calculateAdaptiveZoomFromLookup(
+          clickLookup,
           i,
           this.effects.zoom.scale,
           transitionFrames
@@ -1296,7 +1679,6 @@ var CanvasRenderer = class {
   }
   /**
    * 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;
@@ -1327,9 +1709,371 @@ var CanvasRenderer = class {
     }
     return result;
   }
+  // ─── Online streaming pipeline (Phase 3-B) ─────────────────────────────────
+  /**
+   * Returns true when no effect requires the full frame array upfront.
+   *
+   * When true, composeStreamOnline() can be used: frames are composited as they
+   * arrive (no need to wait for all frames to be collected first).
+   *
+   * Currently the only blocking effect is speed ramp, which needs to scan all
+   * frames to compute action-proximity indices.  Zoom uses the window-based
+   * calculateAdaptiveZoomInWindow() so it works with a rolling lookahead buffer.
+   */
+  canStreamOnline() {
+    return !this.effects.speedRamp.enabled;
+  }
+  /**
+   * Online streaming compose — accepts an AsyncIterable of frames (e.g. from
+   * ClipwiseRecorder.recordToChannel()) and begins compositing immediately,
+   * without waiting for all frames to be collected.
+   *
+   * Each frame is dispatched to the worker pool as soon as its zoom lookahead
+   * window is satisfied (i.e. when frame i + transitionFrames has arrived).
+   * This creates a natural pipeline: recording produces frames while workers
+   * consume them in parallel.
+   *
+   * Requires canStreamOnline() === true (speedRamp must be disabled).
+   * Transitions (step boundaries with transition: fade) are applied inline
+   * using the same applyTransitionsToStream() logic as composeStream().
+   */
+  async *composeStreamOnline(source) {
+    const hasFadeTransitions = this.steps.some((s) => s.transition === "fade");
+    if (!hasFadeTransitions) {
+      const cpuCount = os.cpus().length;
+      const workerCount = Math.min(cpuCount, 8);
+      yield* this.streamOnlineWithWorkers(source, workerCount);
+      return;
+    }
+    const collected = [];
+    for await (const frame of source) {
+      collected.push(frame);
+    }
+    yield* this.composeStream(collected);
+  }
+  /**
+   * Worker-pool online streaming: dispatches frame i to a worker as soon as
+   * frame i + transitionFrames has arrived from the source.
+   *
+   * Uses a notify-on-progress pattern (same as streamWithWorkers) extended
+   * with an intake coroutine that feeds the growing frames[] buffer.
+   */
+  async *streamOnlineWithWorkers(source, workerCount) {
+    const transitionFrames = this.effects.zoom.enabled ? Math.round(this.output.fps * (this.effects.zoom.duration / 1e3)) : 0;
+    const trailLength = this.effects.cursor.trailLength;
+    const frames = [];
+    let sourceComplete = false;
+    let workerError = null;
+    let notify = null;
+    const trigger = () => {
+      notify?.();
+      notify = null;
+    };
+    const waitForProgress = () => new Promise((r) => {
+      notify = r;
+    });
+    const completed = /* @__PURE__ */ new Map();
+    const idleWorkers = [];
+    let nextToDispatch = 0;
+    let nextToYield = 0;
+    const canDispatch = (i) => i < frames.length && (sourceComplete || frames.length > i + transitionFrames);
+    const computeContext = (i) => {
+      const frame = frames[i];
+      let zoomScale = 1;
+      if (this.effects.zoom.enabled) {
+        const lo = Math.max(0, i - transitionFrames);
+        const hi = Math.min(frames.length - 1, i + transitionFrames);
+        zoomScale = calculateAdaptiveZoomInWindow(
+          frames.slice(lo, hi + 1),
+          lo,
+          i,
+          this.effects.zoom.scale,
+          transitionFrames
+        );
+      }
+      const clickProgress = frame.clickPosition != null ? frame.clickProgress ?? 0.5 : null;
+      const trail = [];
+      for (let j = Math.max(0, i - trailLength); j <= i; j++) {
+        if (frames[j].cursorPosition) trail.push(frames[j].cursorPosition);
+      }
+      return { zoomScale, clickProgress, cursorTrail: trail };
+    };
+    const dispatch = (worker) => {
+      if (canDispatch(nextToDispatch)) {
+        const i = nextToDispatch++;
+        worker.postMessage({
+          taskId: i,
+          frame: frames[i],
+          effects: this.effects,
+          output: this.output,
+          context: computeContext(i)
+        });
+      } else {
+        idleWorkers.push(worker);
+      }
+    };
+    const dispatchToIdle = () => {
+      while (idleWorkers.length > 0 && canDispatch(nextToDispatch)) {
+        dispatch(idleWorkers.shift());
+      }
+    };
+    const workerUrl = getWorkerUrl();
+    const workers = [];
+    for (let w = 0; w < workerCount; w++) {
+      const worker = new Worker(workerUrl);
+      workers.push(worker);
+      worker.on("message", (msg) => {
+        if (workerError) return;
+        if (msg.error) {
+          workerError = new Error(`Worker failed on frame ${msg.taskId}: ${msg.error}`);
+        } else {
+          completed.set(msg.taskId, {
+            index: frames[msg.taskId].index,
+            buffer: Buffer.from(msg.buffer),
+            timestamp: frames[msg.taskId].timestamp,
+            rawInfo: msg.rawInfo
+          });
+          dispatch(worker);
+        }
+        trigger();
+      });
+      worker.on("error", (err) => {
+        workerError = err;
+        trigger();
+      });
+      idleWorkers.push(worker);
+    }
+    const intakeTask = (async () => {
+      for await (const frame of source) {
+        frames.push(frame);
+        dispatchToIdle();
+        trigger();
+      }
+      sourceComplete = true;
+      dispatchToIdle();
+      trigger();
+    })();
+    try {
+      while (true) {
+        if (workerError) throw workerError;
+        if (sourceComplete && nextToDispatch >= frames.length && nextToYield >= frames.length) {
+          break;
+        }
+        if (completed.has(nextToYield)) {
+          const frame = completed.get(nextToYield);
+          completed.delete(nextToYield);
+          nextToYield++;
+          yield frame;
+          continue;
+        }
+        await waitForProgress();
+      }
+    } finally {
+      await intakeTask;
+      workers.forEach((w) => w.terminate());
+    }
+  }
+  // ─── Streaming pipeline (Phase 1-B) ────────────────────────────────────────
+  /**
+   * Stream frame composition — yields ComposedFrames as workers finish,
+   * in display order, so the encoder can start before all frames are composed.
+   *
+   * Same 4-pass structure as composeAll():
+   *   Pass 1 & 2 run upfront (need the full frame set).
+   *   Pass 3 streams via the worker pool (ordered yield).
+   *   Pass 4 transitions are buffered inline and applied at step boundaries.
+   */
+  async *composeStream(frames) {
+    if (frames.length === 0) return;
+    let processFrames = frames;
+    if (this.effects.speedRamp.enabled) {
+      processFrames = this.applySpeedRamp(frames);
+    }
+    const contexts = this.calculateFrameContexts(processFrames);
+    const windows = this.getTransitionWindows(processFrames);
+    const cpuCount = os.cpus().length;
+    const workerCount = Math.min(cpuCount, 8);
+    const useWorkers = workerCount >= 2 && processFrames.length >= workerCount * MIN_FRAMES_PER_WORKER;
+    const rawStream = useWorkers ? this.streamWithWorkers(processFrames, contexts, workerCount) : this.streamSequential(processFrames, contexts);
+    yield* this.applyTransitionsToStream(rawStream, windows);
+  }
+  /**
+   * Worker-pool streaming: dispatches frames to workers and yields results
+   * in display order as soon as each frame is ready.
+   *
+   * Uses a notify-on-progress pattern to bridge event-driven workers
+   * to an ordered AsyncGenerator without busy-polling.
+   */
+  async *streamWithWorkers(frames, contexts, workerCount) {
+    const completed = new Array(frames.length);
+    let workerError = null;
+    let notify = null;
+    const waitForProgress = () => new Promise((r) => {
+      notify = r;
+    });
+    const workerUrl = getWorkerUrl();
+    const workers = [];
+    let nextToDispatch = 0;
+    const dispatch = (worker) => {
+      if (nextToDispatch >= frames.length || workerError) return;
+      const i = nextToDispatch++;
+      worker.postMessage({
+        taskId: i,
+        frame: frames[i],
+        effects: this.effects,
+        output: this.output,
+        context: contexts[i]
+      });
+    };
+    for (let w = 0; w < workerCount; w++) {
+      const worker = new Worker(workerUrl);
+      workers.push(worker);
+      worker.on("message", (msg) => {
+        if (workerError) return;
+        if (msg.error) {
+          workerError = new Error(`Worker failed on frame ${msg.taskId}: ${msg.error}`);
+        } else {
+          completed[msg.taskId] = {
+            index: frames[msg.taskId].index,
+            buffer: Buffer.from(msg.buffer),
+            timestamp: frames[msg.taskId].timestamp,
+            rawInfo: msg.rawInfo
+          };
+          dispatch(worker);
+        }
+        notify?.();
+        notify = null;
+      });
+      worker.on("error", (err) => {
+        workerError = err;
+        notify?.();
+        notify = null;
+      });
+      dispatch(worker);
+    }
+    try {
+      for (let i = 0; i < frames.length; i++) {
+        while (completed[i] === void 0 && !workerError) {
+          await waitForProgress();
+        }
+        if (workerError) throw workerError;
+        const frame = completed[i];
+        completed[i] = void 0;
+        yield frame;
+      }
+    } finally {
+      workers.forEach((w) => w.terminate());
+    }
+  }
+  /**
+   * Sequential streaming fallback for small frame counts where worker
+   * thread overhead would exceed the parallelism benefit.
+   */
+  async *streamSequential(frames, contexts) {
+    for (let i = 0; i < frames.length; i++) {
+      yield await composeFrame(frames[i], this.effects, this.output, contexts[i]);
+    }
+  }
+  /**
+   * Pre-compute [startIdx, endIdx] windows for every fade transition so that
+   * applyTransitionsToStream can buffer only those frames.
+   */
+  getTransitionWindows(frames) {
+    if (this.steps.length === 0) return [];
+    const transitionFrames = Math.max(2, Math.round(this.output.fps * 0.3));
+    const windows = [];
+    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") {
+          const startIdx = Math.max(0, i - Math.floor(transitionFrames / 2));
+          const endIdx = Math.min(frames.length - 1, i + Math.ceil(transitionFrames / 2));
+          if (endIdx - startIdx >= 2) {
+            windows.push({ startIdx, endIdx });
+          }
+        }
+      }
+    }
+    return windows;
+  }
+  /**
+   * Wrap a ComposedFrame stream with inline transition buffering.
+   *
+   * Non-transition frames are yielded immediately.
+   * Frames inside a fade window are held until both endpoints are available,
+   * then the crossfade is applied and all window frames are flushed in order.
+   * A pending map maintains global display order across window boundaries.
+   */
+  async *applyTransitionsToStream(source, windows) {
+    if (windows.length === 0) {
+      yield* source;
+      return;
+    }
+    const frameToWindow = /* @__PURE__ */ new Map();
+    for (let wi = 0; wi < windows.length; wi++) {
+      for (let i = windows[wi].startIdx; i <= windows[wi].endIdx; i++) {
+        frameToWindow.set(i, wi);
+      }
+    }
+    const windowState = windows.map((w) => ({
+      frames: new Array(w.endIdx - w.startIdx + 1),
+      received: 0
+    }));
+    const pending = /* @__PURE__ */ new Map();
+    let nextToYield = 0;
+    let frameIdx = 0;
+    for await (const frame of source) {
+      const idx = frameIdx++;
+      const wi = frameToWindow.get(idx);
+      if (wi === void 0) {
+        pending.set(idx, frame);
+      } else {
+        const win = windows[wi];
+        const state = windowState[wi];
+        state.frames[idx - win.startIdx] = frame;
+        state.received++;
+        if (state.received === state.frames.length) {
+          const fromBuf = state.frames[0].buffer;
+          const toBuf = state.frames[state.frames.length - 1].buffer;
+          const range = state.frames.length - 1;
+          const fromRawInfo = state.frames[0].rawInfo;
+          const toRawInfo = state.frames[state.frames.length - 1].rawInfo;
+          for (let j = 1; j < state.frames.length - 1; j++) {
+            const blended = await applyCrossfade(
+              fromBuf,
+              toBuf,
+              j / range,
+              this.output.width,
+              this.output.height,
+              fromRawInfo,
+              toRawInfo
+            );
+            state.frames[j] = {
+              ...state.frames[j],
+              buffer: blended.buffer,
+              rawInfo: blended.rawInfo
+            };
+          }
+          for (let j = 0; j < state.frames.length; j++) {
+            pending.set(win.startIdx + j, state.frames[j]);
+          }
+        }
+      }
+      while (pending.has(nextToYield)) {
+        yield pending.get(nextToYield);
+        pending.delete(nextToYield);
+        nextToYield++;
+      }
+    }
+    while (pending.has(nextToYield)) {
+      yield pending.get(nextToYield);
+      pending.delete(nextToYield);
+      nextToYield++;
+    }
+  }
   /**
    * 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));
@@ -1350,17 +2094,21 @@ var CanvasRenderer = class {
       if (range < 2) continue;
       const fromBuffer = composed[startIdx].buffer;
       const toBuffer = composed[endIdx].buffer;
-      const width = this.output.width;
-      const height = this.output.height;
+      const fromRawInfo = composed[startIdx].rawInfo;
+      const toRawInfo = composed[endIdx].rawInfo;
       for (let i = startIdx + 1; i < endIdx; i++) {
         const progress = (i - startIdx) / range;
-        composed[i].buffer = await applyCrossfade(
+        const blended = await applyCrossfade(
           fromBuffer,
           toBuffer,
           progress,
-          width,
-          height
+          this.output.width,
+          this.output.height,
+          fromRawInfo,
+          toRawInfo
         );
+        composed[i].buffer = blended.buffer;
+        composed[i].rawInfo = blended.rawInfo;
       }
     }
   }
@@ -1369,11 +2117,45 @@ var CanvasRenderer = class {
 // src/compose/video-encoder.ts
 import gifenc from "gifenc";
 import sharp9 from "sharp";
-import { writeFile, mkdir, readFile, rm, mkdtemp } from "fs/promises";
+import { writeFile, mkdir, readFile, rm } from "fs/promises";
 import { join } from "path";
 import { tmpdir } from "os";
 import { spawn } from "child_process";
 var { GIFEncoder, quantize, applyPalette } = gifenc;
+var ENCODING_PRESETS = {
+  social: { crf: 22, vtQuality: 75 },
+  balanced: { crf: 18, vtQuality: 85 },
+  archive: { crf: 13, vtQuality: 92 }
+};
+function resolveEncodingParams(config) {
+  if (config.preset) return ENCODING_PRESETS[config.preset];
+  process.stderr.write(
+    `[clipwise] Deprecation: "quality" is deprecated. Use "preset: social | balanced | archive" instead.
+`
+  );
+  if (config.quality >= 75) return ENCODING_PRESETS.social;
+  if (config.quality >= 45) return ENCODING_PRESETS.balanced;
+  return ENCODING_PRESETS.archive;
+}
+var encoderDetectionPromise = null;
+function detectVideoEncoder() {
+  if (!encoderDetectionPromise) {
+    encoderDetectionPromise = new Promise((resolve) => {
+      const proc = spawn("ffmpeg", ["-encoders"], {
+        stdio: ["ignore", "pipe", "ignore"]
+      });
+      let out = "";
+      proc.stdout.on("data", (d) => out += d.toString());
+      proc.on("close", () => {
+        if (out.includes("hevc_videotoolbox")) resolve("hevc_videotoolbox");
+        else if (out.includes("h264_videotoolbox")) resolve("h264_videotoolbox");
+        else resolve("libx264");
+      });
+      proc.on("error", () => resolve("libx264"));
+    });
+  }
+  return encoderDetectionPromise;
+}
 async function encodeGif(frames, config) {
   if (frames.length === 0) {
     throw new Error("Cannot encode GIF: no frames provided");
@@ -1383,14 +2165,12 @@ async function encodeGif(frames, config) {
   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 src = frame.rawInfo ? sharp9(frame.buffer, { raw: { width: frame.rawInfo.width, height: frame.rawInfo.height, channels: frame.rawInfo.channels } }) : sharp9(frame.buffer);
+    const { data, info } = await src.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.writeFrame(indexed, width, height, { palette, delay });
   }
   gif.finish();
   return Buffer.from(gif.bytes());
@@ -1399,50 +2179,200 @@ 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-"));
+  const outputPath = join(tmpdir(), `clipwise-${Date.now()}-${Math.random().toString(36).slice(2)}.mp4`);
   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
-    ]);
+    const encoder = await detectVideoEncoder();
+    const params = resolveEncodingParams(config);
+    await pipeFramesToFfmpeg(frames, config, params, encoder, outputPath);
     return await readFile(outputPath);
   } finally {
-    await rm(tmpDir, { recursive: true, force: true }).catch(() => {
+    await rm(outputPath, { force: true }).catch(() => {
     });
   }
 }
-function runFfmpeg(args) {
+async function pipeFramesToFfmpeg(frames, config, params, encoder, outputPath) {
+  const videoArgs = encoder === "hevc_videotoolbox" ? [
+    "-c:v",
+    "hevc_videotoolbox",
+    "-q:v",
+    String(params.vtQuality),
+    "-pix_fmt",
+    "yuv420p",
+    "-tag:v",
+    "hvc1"
+    // required for playback in QuickTime / Apple devices
+  ] : encoder === "h264_videotoolbox" ? [
+    "-c:v",
+    "h264_videotoolbox",
+    "-q:v",
+    String(params.vtQuality),
+    "-pix_fmt",
+    "yuv420p"
+  ] : [
+    "-c:v",
+    "libx264",
+    "-crf",
+    String(params.crf),
+    "-preset",
+    "medium",
+    "-tune",
+    "stillimage",
+    "-profile:v",
+    "high",
+    "-level",
+    "4.1",
+    "-pix_fmt",
+    "yuv420p"
+  ];
   return new Promise((resolve, reject) => {
-    const proc = spawn("ffmpeg", args, { stdio: ["ignore", "pipe", "pipe"] });
+    const ffmpeg = spawn(
+      "ffmpeg",
+      [
+        "-y",
+        // Video input: raw RGB24 from stdin
+        "-f",
+        "rawvideo",
+        "-pixel_format",
+        "rgb24",
+        "-video_size",
+        `${config.width}x${config.height}`,
+        "-framerate",
+        String(config.fps),
+        "-i",
+        "pipe:0",
+        // Silent audio track for platform compatibility
+        "-f",
+        "lavfi",
+        "-i",
+        "anullsrc=r=48000:cl=stereo",
+        ...videoArgs,
+        "-c:a",
+        "aac",
+        "-b:a",
+        "128k",
+        "-shortest",
+        "-movflags",
+        "+faststart",
+        outputPath
+      ],
+      { stdio: ["pipe", "ignore", "pipe"] }
+    );
     let stderr = "";
-    proc.stderr.on("data", (data) => {
-      stderr += data.toString();
+    ffmpeg.stderr.on("data", (d) => stderr += d.toString());
+    ffmpeg.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("close", (code) => {
+    ffmpeg.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 () => {
+      for (const frame of frames) {
+        const src = frame.rawInfo ? sharp9(frame.buffer, { raw: { width: frame.rawInfo.width, height: frame.rawInfo.height, channels: frame.rawInfo.channels } }) : sharp9(frame.buffer);
+        const raw = await src.flatten({ background: { r: 0, g: 0, b: 0 } }).raw().toBuffer();
+        if (!ffmpeg.stdin.write(raw)) {
+          await new Promise((r) => ffmpeg.stdin.once("drain", r));
+        }
+      }
+      ffmpeg.stdin.end();
+    })().catch(reject);
+  });
+}
+async function encodeMp4Stream(frames, config) {
+  const outputPath = join(tmpdir(), `clipwise-${Date.now()}-${Math.random().toString(36).slice(2)}.mp4`);
+  try {
+    const encoder = await detectVideoEncoder();
+    const params = resolveEncodingParams(config);
+    await pipeStreamToFfmpeg(frames, config, params, encoder, outputPath);
+    return await readFile(outputPath);
+  } finally {
+    await rm(outputPath, { force: true }).catch(() => {
+    });
+  }
+}
+async function pipeStreamToFfmpeg(frames, config, params, encoder, outputPath) {
+  const videoArgs = encoder === "hevc_videotoolbox" ? [
+    "-c:v",
+    "hevc_videotoolbox",
+    "-q:v",
+    String(params.vtQuality),
+    "-pix_fmt",
+    "yuv420p",
+    "-tag:v",
+    "hvc1"
+  ] : encoder === "h264_videotoolbox" ? [
+    "-c:v",
+    "h264_videotoolbox",
+    "-q:v",
+    String(params.vtQuality),
+    "-pix_fmt",
+    "yuv420p"
+  ] : [
+    "-c:v",
+    "libx264",
+    "-crf",
+    String(params.crf),
+    "-preset",
+    "medium",
+    "-tune",
+    "stillimage",
+    "-profile:v",
+    "high",
+    "-level",
+    "4.1",
+    "-pix_fmt",
+    "yuv420p"
+  ];
+  return new Promise((resolve, reject) => {
+    const ffmpeg = spawn(
+      "ffmpeg",
+      [
+        "-y",
+        "-f",
+        "rawvideo",
+        "-pixel_format",
+        "rgb24",
+        "-video_size",
+        `${config.width}x${config.height}`,
+        "-framerate",
+        String(config.fps),
+        "-i",
+        "pipe:0",
+        "-f",
+        "lavfi",
+        "-i",
+        "anullsrc=r=48000:cl=stereo",
+        ...videoArgs,
+        "-c:a",
+        "aac",
+        "-b:a",
+        "128k",
+        "-shortest",
+        "-movflags",
+        "+faststart",
+        outputPath
+      ],
+      { stdio: ["pipe", "ignore", "pipe"] }
+    );
+    let stderr = "";
+    ffmpeg.stderr.on("data", (d) => stderr += d.toString());
+    ffmpeg.on("close", (code) => {
       if (code === 0) {
         resolve();
       } else {
@@ -1454,7 +2384,7 @@ function runFfmpeg(args) {
         );
       }
     });
-    proc.on("error", (err) => {
+    ffmpeg.on("error", (err) => {
       if (err.code === "ENOENT") {
         reject(
           new Error(
@@ -1465,6 +2395,16 @@ function runFfmpeg(args) {
         reject(err);
       }
     });
+    (async () => {
+      for await (const frame of frames) {
+        const src = frame.rawInfo ? sharp9(frame.buffer, { raw: { width: frame.rawInfo.width, height: frame.rawInfo.height, channels: frame.rawInfo.channels } }) : sharp9(frame.buffer);
+        const raw = await src.flatten({ background: { r: 0, g: 0, b: 0 } }).raw().toBuffer();
+        if (!ffmpeg.stdin.write(raw)) {
+          await new Promise((r) => ffmpeg.stdin.once("drain", r));
+        }
+      }
+      ffmpeg.stdin.end();
+    })().catch(reject);
   });
 }
 async function savePngSequence(frames, config) {
@@ -1486,6 +2426,76 @@ async function savePngSequence(frames, config) {
   return paths;
 }
 
+// src/compose/streaming-session.ts
+import { EventEmitter } from "events";
+var ConcurrentSession = class extends EventEmitter {
+  constructor(recorder, scenario, renderer) {
+    super();
+    this.recorder = recorder;
+    this.scenario = scenario;
+    this.renderer = renderer;
+  }
+  /**
+   * Start recording and compositing concurrently.
+   * Returns when both recording and encoding are complete.
+   */
+  async run() {
+    const handle = this.recorder.recordToChannel(this.scenario);
+    let composed = 0;
+    const self = this;
+    const buffer = await encodeMp4Stream(
+      (async function* () {
+        for await (const frame of self.renderer.composeStreamOnline(handle.frameStream)) {
+          composed++;
+          self.emit("progress", { composed, total: -1, pct: -1 });
+          yield frame;
+        }
+      })(),
+      this.scenario.output
+    );
+    const session = await handle.done;
+    this.emit("progress", { composed, total: composed, pct: 100 });
+    return { buffer, session };
+  }
+};
+var StreamingSession = class extends EventEmitter {
+  constructor(session, renderer) {
+    super();
+    this.session = session;
+    this.renderer = renderer;
+  }
+  /** Total frames in the underlying recording session. */
+  get totalFrames() {
+    return this.session.frames.length;
+  }
+  /**
+   * Run the compose → encode pipeline.
+   *
+   * Composes frames via the worker pool (Phase 1-B streaming, ordered yield),
+   * forwarding each to FFmpeg as it completes.  Emits a 'progress' event after
+   * every composed frame so callers can update a spinner or progress bar.
+   *
+   * @returns The fully-encoded MP4 as a Buffer.
+   */
+  async run() {
+    const { frames, scenario } = this.session;
+    const total = frames.length;
+    let composed = 0;
+    const self = this;
+    return encodeMp4Stream(
+      (async function* () {
+        for await (const frame of self.renderer.composeStream(frames)) {
+          composed++;
+          const pct = total > 0 ? Math.round(composed / total * 100) : 100;
+          self.emit("progress", { composed, total, pct });
+          yield frame;
+        }
+      })(),
+      scenario.output
+    );
+  }
+};
+
 // src/script/parser.ts
 import { parse as parseYaml } from "yaml";
 import { readFile as readFile2 } from "fs/promises";
@@ -1655,8 +2665,13 @@ 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),
+  fps: z.number().min(1).max(60).default(30),
   quality: z.number().min(1).max(100).default(80),
+  // Encoding preset for MP4 output. Overrides quality when set.
+  // social   — optimized for Twitter/X and YouTube (CRF 25, capped bitrate)
+  // balanced — general-purpose, good quality/size trade-off (CRF 20)
+  // archive  — high-fidelity storage, larger file (CRF 15)
+  preset: z.enum(["social", "balanced", "archive"]).optional(),
   outputDir: z.string().default("./output"),
   filename: z.string().default("clipwise-recording")
 });
@@ -1790,11 +2805,17 @@ function validateScenario(scenario) {
 export {
   CanvasRenderer,
   ClipwiseRecorder,
+  ConcurrentSession,
+  StreamingSession,
   applyCrossfade,
+  buildZoomClickLookup,
   calculateAdaptiveZoom,
+  calculateAdaptiveZoomFromLookup,
+  calculateAdaptiveZoomInWindow,
   calculatePanOffset,
   encodeGif,
   encodeMp4,
+  encodeMp4Stream,
   lerpZoom,
   loadScenario,
   parseScenario,