clipwise 0.3.0 → 0.4.1

package/dist/index.js

@@ -62,6 +62,35 @@ var CURSOR_SPEED_PRESETS = {
   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;
@@ -80,6 +109,15 @@ var ClipwiseRecorder = class {
   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.
    */
@@ -103,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.
@@ -117,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(() => {
@@ -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.
@@ -446,7 +616,8 @@ var ClipwiseRecorder = class {
         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
       };
     });
   }
@@ -905,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 === Infinity) return 1;
-  if (minDistance <= transitionFrames) {
-    const t = 1 - minDistance / transitionFrames;
-    const eased = easeInOutCubic2(t);
-    return 1 + (maxScale - 1) * eased;
+  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);
+    }
   }
-  return 1;
+  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;
+    }
+  }
+  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 };
@@ -1082,8 +1289,8 @@ async function renderKeystrokeHud(frameBuffer, keystrokes, frameTimestamp, confi
 
 // src/effects/watermark.ts
 import sharp6 from "sharp";
-async function renderWatermark(frameBuffer, config, frameWidth, frameHeight) {
-  if (!config.enabled || !config.text) return frameBuffer;
+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;
@@ -1109,13 +1316,17 @@ 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}" shape-rendering="geometricPrecision" text-rendering="geometricPrecision">
+  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 sharp6(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/compose-frame.ts
@@ -1146,7 +1357,18 @@ async function composeFrame(frame, effects, output, context) {
     cursorTrail: context?.cursorTrail ?? []
   };
   if (effects.deviceFrame.enabled) {
-    buffer = await applyDeviceFrame(buffer, effects.deviceFrame, width, height, dpr);
+    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;
@@ -1214,38 +1436,83 @@ async function composeFrame(frame, effects, output, context) {
     };
     buffer = await applyZoom(buffer, focusPoint, scale, width, height);
   }
-  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 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);
+    }
   }
-  buffer = await sharp7(buffer).resize(output.width, output.height, {
+  const { data: finalData, info: finalInfo } = await sharp7(buffer).resize(output.width, output.height, {
     fit: "fill",
     kernel: sharp7.kernel.lanczos3
-  }).png().toBuffer();
-  return { index: frame.index, buffer, timestamp: frame.timestamp };
+  }).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) {
+async function applyCrossfade(fromBuffer, toBuffer, progress, width, height, fromRawInfo, toRawInfo) {
   const t = Math.max(0, Math.min(1, progress));
-  if (t <= 0) return fromBuffer;
-  if (t >= 1) return toBuffer;
-  const fromRaw = await sharp8(fromBuffer).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
-  const toRaw = await sharp8(toBuffer).resize(fromRaw.info.width, fromRaw.info.height, { fit: "fill" }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  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 sharp8(pixels, {
-    raw: {
-      width: fromRaw.info.width,
-      height: fromRaw.info.height,
-      channels: 4
-    }
-  }).png().toBuffer();
+  return {
+    buffer: pixels,
+    rawInfo: { width: fromRaw.info.width, height: fromRaw.info.height, channels: 4 }
+  };
 }
 
 // src/compose/canvas-renderer.ts
@@ -1357,7 +1624,8 @@ var CanvasRenderer = class {
           results[msg.taskId] = {
             index: frames[msg.taskId].index,
             buffer: Buffer.from(msg.buffer),
-            timestamp: frames[msg.taskId].timestamp
+            timestamp: frames[msg.taskId].timestamp,
+            rawInfo: msg.rawInfo
           };
           completed++;
           if (completed === frames.length) {
@@ -1385,12 +1653,13 @@ var CanvasRenderer = class {
     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
@@ -1440,6 +1709,369 @@ 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.
    */
@@ -1462,15 +2094,21 @@ var CanvasRenderer = class {
       if (range < 2) continue;
       const fromBuffer = composed[startIdx].buffer;
       const toBuffer = composed[endIdx].buffer;
+      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,
           this.output.width,
-          this.output.height
+          this.output.height,
+          fromRawInfo,
+          toRawInfo
         );
+        composed[i].buffer = blended.buffer;
+        composed[i].rawInfo = blended.rawInfo;
       }
     }
   }
@@ -1527,7 +2165,8 @@ 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);
@@ -1645,7 +2284,121 @@ async function pipeFramesToFfmpeg(frames, config, params, encoder, outputPath) {
     });
     (async () => {
       for (const frame of frames) {
-        const raw = await sharp9(frame.buffer).flatten({ background: { r: 0, g: 0, b: 0 } }).raw().toBuffer();
+        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 {
+        reject(
+          new Error(
+            `FFmpeg encoding failed (exit code ${code}). Make sure ffmpeg is installed: brew install ffmpeg
+` + stderr.slice(-500)
+          )
+        );
+      }
+    });
+    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 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));
         }
@@ -1673,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";
@@ -1982,11 +2805,17 @@ function validateScenario(scenario) {
 export {
   CanvasRenderer,
   ClipwiseRecorder,
+  ConcurrentSession,
+  StreamingSession,
   applyCrossfade,
+  buildZoomClickLookup,
   calculateAdaptiveZoom,
+  calculateAdaptiveZoomFromLookup,
+  calculateAdaptiveZoomInWindow,
   calculatePanOffset,
   encodeGif,
   encodeMp4,
+  encodeMp4Stream,
   lerpZoom,
   loadScenario,
   parseScenario,