clipwise 0.3.0 → 0.4.1

package/dist/compose/frame-worker.js

@@ -1,5 +1,6 @@
 // src/compose/frame-worker.ts
 import { parentPort } from "worker_threads";
+import sharp8 from "sharp";
 
 // src/compose/compose-frame.ts
 import sharp7 from "sharp";
@@ -202,6 +203,11 @@ async function applyMobileFrame(frameBuffer, deviceType, darkMode, frameWidth, f
     { input: maskedScreen, left: bezel.sides, top: bezel.top }
   ]).png().toBuffer();
 }
+async function buildBrowserChromeBuffer(viewportWidth, darkMode, dpr = 1) {
+  const tbarH = TITLE_BAR_HEIGHT * dpr;
+  const chromeSvg = buildBrowserChromeSvg(viewportWidth, darkMode, dpr);
+  return sharp(Buffer.from(chromeSvg)).resize(viewportWidth, tbarH).png().toBuffer();
+}
 async function applyDeviceFrame(frameBuffer, config, frameWidth, frameHeight, dpr = 1) {
   if (!config.enabled || config.type === "none") return frameBuffer;
   switch (config.type) {
@@ -383,6 +389,32 @@ function buildBackgroundSvg(config, width, height) {
     <rect width="${width}" height="${height}" fill="url(#bg)"/>
   </svg>`;
 }
+async function buildBackdropBuffer(config, outputWidth, outputHeight, extraOverlays = []) {
+  const padding = config.padding;
+  const contentWidth = outputWidth - padding * 2;
+  const contentHeight = outputHeight - padding * 2;
+  const bgSvg = buildBackgroundSvg(config, outputWidth, outputHeight);
+  const composites = [];
+  if (config.shadow && contentWidth > 0 && contentHeight > 0) {
+    const shadowSvg = Buffer.from(
+      `<svg xmlns="http://www.w3.org/2000/svg" width="${outputWidth}" height="${outputHeight}">
+        <defs>
+          <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+            <feDropShadow dx="0" dy="4" stdDeviation="16" flood-color="rgba(0,0,0,0.3)"/>
+          </filter>
+        </defs>
+        <rect x="${padding}" y="${padding}" width="${contentWidth}" height="${contentHeight}"
+              rx="${config.borderRadius}" ry="${config.borderRadius}" fill="rgba(0,0,0,0.15)" filter="url(#shadow)"/>
+      </svg>`
+    );
+    composites.push({ input: shadowSvg, left: 0, top: 0 });
+  }
+  for (const overlay of extraOverlays) {
+    composites.push({ input: overlay, left: 0, top: 0 });
+  }
+  const { data, info } = await sharp4(Buffer.from(bgSvg)).resize(outputWidth, outputHeight).composite(composites).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  return { data: Buffer.from(data), width: info.width, height: info.height };
+}
 async function applyBackground(frameBuffer, config, outputWidth, outputHeight) {
   const padding = config.padding;
   const contentWidth = outputWidth - padding * 2;
@@ -477,8 +509,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;
@@ -504,16 +536,47 @@ 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
+async function buildStaticLayers(effects, output, viewportWidth, dpr) {
+  const wmSvg = buildWatermarkSvg(effects.watermark, output.width, output.height);
+  const extraOverlays = wmSvg ? [Buffer.from(wmSvg)] : [];
+  const { data, width, height } = await buildBackdropBuffer(
+    effects.background,
+    output.width,
+    output.height,
+    extraOverlays
+  );
+  let browserChromePng = null;
+  let browserChromeHeight = 0;
+  if (effects.deviceFrame.enabled && effects.deviceFrame.type === "browser") {
+    browserChromeHeight = TITLE_BAR_HEIGHT * dpr;
+    browserChromePng = await buildBrowserChromeBuffer(
+      viewportWidth,
+      effects.deviceFrame.darkMode,
+      dpr
+    );
+  }
+  return {
+    backdropRaw: data,
+    backdropWidth: width,
+    backdropHeight: height,
+    browserChromePng,
+    browserChromeHeight
+  };
+}
 function getFrameOffset(config, dpr = 1) {
   if (!config.enabled) return { left: 0, top: 0 };
   switch (config.type) {
@@ -541,7 +604,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;
@@ -609,18 +683,57 @@ 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/compose/frame-worker.ts
+sharp8.concurrency(1);
+var cachedStaticLayers = null;
+var cachedEffectsKey = "";
 parentPort.on("message", async (msg) => {
   try {
     const { taskId, frame, effects, output, context } = msg;
@@ -628,12 +741,28 @@ parentPort.on("message", async (msg) => {
       ...frame,
       screenshot: Buffer.from(frame.screenshot)
     };
-    const result = await composeFrame(frameWithBuffer, effects, output, context);
+    const effectsKey = `${output.width}x${output.height}`;
+    if (!cachedStaticLayers || cachedEffectsKey !== effectsKey) {
+      const meta = await sharp8(frameWithBuffer.screenshot).metadata();
+      const dpr = Math.round((meta.width ?? frame.viewport.width) / frame.viewport.width) || 1;
+      cachedStaticLayers = await buildStaticLayers(
+        effects,
+        output,
+        frame.viewport.width,
+        dpr
+      );
+      cachedEffectsKey = effectsKey;
+    }
+    const result = await composeFrame(frameWithBuffer, effects, output, {
+      ...context,
+      staticLayers: cachedStaticLayers
+    });
     const reply = {
       taskId,
       index: result.index,
       timestamp: result.timestamp,
-      buffer: result.buffer
+      buffer: result.buffer,
+      rawInfo: result.rawInfo
     };
     parentPort.postMessage(reply);
   } catch (err) {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { EventEmitter } from 'events';
 
 declare const StepActionSchema: z.ZodDiscriminatedUnion<"action", [z.ZodObject<{
     action: z.ZodLiteral<"navigate">;
@@ -1794,12 +1795,45 @@ interface ComposedFrame {
     index: number;
     buffer: Buffer;
     timestamp: number;
+    /**
+     * Present when buffer contains raw RGBA pixels (not PNG).
+     * Allows the encoder to skip the PNG-decode step and consume pixels directly.
+     */
+    rawInfo?: {
+        width: number;
+        height: number;
+        channels: 4;
+    };
+}
+interface DedupStats {
+    /** CDP로부터 수신한 원본 프레임 수 */
+    received: number;
+    /** 중복 제거 후 실제 저장된 고유 프레임 수 */
+    stored: number;
+    /** 중복으로 판단해 건너뛴 프레임 수 */
+    skipped: number;
 }
 interface RecordingSession {
     scenario: Scenario;
     frames: CapturedFrame[];
     startTime: number;
     endTime?: number;
+    /** 정적 프레임 중복 제거 통계 */
+    dedupStats?: DedupStats;
+}
+/**
+ * Handle returned by ClipwiseRecorder.recordToChannel().
+ *
+ * frameStream: async iterable of CapturedFrames as they are captured
+ *   (post-dedup, no FPS resampling — frames arrive at CDP capture rate).
+ *   Closes automatically when recording ends.
+ *
+ * done: resolves with the full RecordingSession (including FPS-resampled
+ *   frames) when recording has completely finished.
+ */
+interface RecordingHandle {
+    frameStream: AsyncIterable<CapturedFrame>;
+    done: Promise<RecordingSession>;
 }
 
 declare class ClipwiseRecorder {
@@ -1820,6 +1854,10 @@ declare class ClipwiseRecorder {
     private cursorSpeed;
     private firstContentTimestamp;
     private pendingResponsePromises;
+    private lastFrameSignature;
+    private dedupStats;
+    private frameChannel;
+    private channelIndex;
     /**
      * Launch the browser and create a page with the scenario viewport.
      */
@@ -1837,6 +1875,26 @@ declare class ClipwiseRecorder {
      * Execute the full scenario with continuous capture and return a RecordingSession.
      */
     record(scenario: Scenario): Promise<RecordingSession>;
+    /**
+     * 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: Scenario): RecordingHandle;
+    /**
+     * 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.
+     */
+    private buildFrameOnline;
     /**
      * Wait for a given duration while forcing periodic repaints
      * so CDP screencast keeps sending frames even on static pages.
@@ -1890,6 +1948,30 @@ declare class ClipwiseRecorder {
     cleanup(): Promise<void>;
 }
 
+/**
+ * Pre-computed static layers that are identical for every frame in a session.
+ *
+ * backdropRaw: background gradient + shadow + watermark composited together at
+ *   output dimensions, stored as raw RGBA.  Workers composite the per-frame
+ *   screenshot onto this buffer instead of re-generating the background SVG
+ *   and shadow SVG on every frame — eliminating ~3 PNG encode/decode cycles.
+ *
+ * browserChromePng: pre-rasterized browser chrome bar PNG.  Applied via
+ *   Sharp's .extend() + .composite() in a single pipeline pass instead of the
+ *   current two-pass create-blank-canvas + composite pattern.
+ *
+ * Both are computed once per worker (first frame), then cached in memory for
+ * all subsequent frames handled by that worker.
+ */
+interface StaticLayers {
+    backdropRaw: Buffer;
+    backdropWidth: number;
+    backdropHeight: number;
+    /** Pre-rasterized browser chrome bar PNG.  Null when device frame is disabled or not "browser". */
+    browserChromePng: Buffer | null;
+    /** Pixel height of the chrome bar (0 when browserChromePng is null). */
+    browserChromeHeight: number;
+}
 interface FrameContext {
     zoomScale: number;
     clickProgress: number | null;
@@ -1897,6 +1979,8 @@ interface FrameContext {
         x: number;
         y: number;
     }>;
+    /** When present, skip redundant per-frame SVG generation for background/watermark/device-frame. */
+    staticLayers?: StaticLayers;
 }
 
 declare class CanvasRenderer {
@@ -1932,6 +2016,77 @@ declare class CanvasRenderer {
      * Apply speed ramping: slow down near actions, speed up during idle.
      */
     private applySpeedRamp;
+    /**
+     * 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(): boolean;
+    /**
+     * 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().
+     */
+    composeStreamOnline(source: AsyncIterable<CapturedFrame>): AsyncGenerator<ComposedFrame>;
+    /**
+     * 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.
+     */
+    private streamOnlineWithWorkers;
+    /**
+     * 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.
+     */
+    composeStream(frames: CapturedFrame[]): AsyncGenerator<ComposedFrame>;
+    /**
+     * 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.
+     */
+    private streamWithWorkers;
+    /**
+     * Sequential streaming fallback for small frame counts where worker
+     * thread overhead would exceed the parallelism benefit.
+     */
+    private streamSequential;
+    /**
+     * Pre-compute [startIdx, endIdx] windows for every fade transition so that
+     * applyTransitionsToStream can buffer only those frames.
+     */
+    private getTransitionWindows;
+    /**
+     * 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.
+     */
+    private applyTransitionsToStream;
     /**
      * Apply crossfade transitions at step boundaries where configured.
      */
@@ -1958,19 +2113,116 @@ declare function encodeGif(frames: ComposedFrame[], config: OutputConfig): Promi
  * Requires ffmpeg to be installed and available in PATH.
  */
 declare function encodeMp4(frames: ComposedFrame[], config: OutputConfig): Promise<Buffer>;
+/**
+ * Streaming variant of encodeMp4 — accepts an AsyncIterable so frames can
+ * be piped to FFmpeg as they arrive from the composition pipeline,
+ * overlapping composition and encoding rather than waiting for all frames.
+ */
+declare function encodeMp4Stream(frames: AsyncIterable<ComposedFrame>, config: OutputConfig): Promise<Buffer>;
 /**
  * Save a sequence of composed frames as individual PNG files.
  */
 declare function savePngSequence(frames: ComposedFrame[], config: OutputConfig): Promise<string[]>;
 
+/**
+ * Emitted by StreamingSession after each frame is composed.
+ */
+interface PipelineProgress {
+    /** Number of frames composed so far */
+    composed: number;
+    /** Total frames in the session */
+    total: number;
+    /** Completion percentage (0–100) */
+    pct: number;
+}
+interface ConcurrentResult {
+    /** Fully-encoded MP4 buffer. */
+    buffer: Buffer;
+    /** Full RecordingSession (FPS-resampled) returned when recording completed. */
+    session: RecordingSession;
+}
+/**
+ * ConcurrentSession overlaps recording and composition in the same process.
+ *
+ * While the recorder captures CDP screencast frames, the compositor begins
+ * applying effects immediately — each frame is dispatched to the worker pool
+ * as soon as its zoom lookahead window is satisfied.
+ *
+ * Total wall-clock time ≈ max(recordingMs, composeMs) instead of the sum.
+ * Requires renderer.canStreamOnline() === true (speedRamp must be disabled).
+ *
+ * Emits 'progress' after each composed frame.
+ * During recording the total is unknown (pct = -1); after recording ends and
+ * composition finishes, a final event with pct = 100 is emitted.
+ *
+ * Usage:
+ *   const pipeline = new ConcurrentSession(recorder, scenario, renderer);
+ *   pipeline.on("progress", ({ composed, total, pct }) => {
+ *     spinner.text = total > 0
+ *       ? `Processing... ${composed}/${total} (${pct}%)`
+ *       : `Recording & composing... ${composed} frames`;
+ *   });
+ *   const { buffer, session } = await pipeline.run();
+ */
+declare class ConcurrentSession extends EventEmitter {
+    private readonly recorder;
+    private readonly scenario;
+    private readonly renderer;
+    constructor(recorder: ClipwiseRecorder, scenario: Scenario, renderer: CanvasRenderer);
+    /**
+     * Start recording and compositing concurrently.
+     * Returns when both recording and encoding are complete.
+     */
+    run(): Promise<ConcurrentResult>;
+}
+/**
+ * StreamingSession bridges a recorded session to the compose+encode streaming
+ * pipeline and emits fine-grained progress events.
+ *
+ * Emits:
+ *   'progress' — after each frame is composed, with a PipelineProgress payload
+ *
+ * Usage:
+ *   const pipeline = new StreamingSession(session, renderer);
+ *   pipeline.on("progress", ({ composed, total, pct }) => {
+ *     spinner.text = `Composing & encoding... ${composed}/${total} (${pct}%)`;
+ *   });
+ *   const mp4Buffer = await pipeline.run();
+ */
+declare class StreamingSession extends EventEmitter {
+    private readonly session;
+    private readonly renderer;
+    constructor(session: RecordingSession, renderer: CanvasRenderer);
+    /** Total frames in the underlying recording session. */
+    get totalFrames(): number;
+    /**
+     * 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.
+     */
+    run(): Promise<Buffer>;
+}
+
 /**
  * Calculate adaptive zoom scale based on proximity to click/action frames.
  * Zooms in smoothly near important actions, stays at 1.0 during idle.
  *
+ * Scans only the ±transitionFrames influence window — frames outside that
+ * range always produce 1.0 anyway, so scanning the full array is wasted work.
+ * This reduces per-call cost from O(n) to O(transitionFrames).
+ *
+ * For bulk context calculation over many frames, prefer the lookup-based API:
+ *   buildZoomClickLookup() once → calculateAdaptiveZoomFromLookup() per frame
+ * which achieves O(n + n·log k) instead of O(n·transitionFrames).
+ *
  * @param frames - Array of frames with optional clickPosition
  * @param currentIndex - Index of the current frame
  * @param maxScale - Peak zoom scale
- * @param transitionFrames - Number of frames for zoom-in/zoom-out transition
+ * @param transitionFrames - Half-width of the zoom influence window (frames)
  * @returns Scale value for the current frame (1.0 = no zoom)
  */
 declare function calculateAdaptiveZoom(frames: Array<{
@@ -1979,6 +2231,42 @@ declare function calculateAdaptiveZoom(frames: Array<{
         y: number;
     } | null;
 }>, currentIndex: number, maxScale: number, transitionFrames: number): number;
+/**
+ * Pre-extract the indices of all click frames in a single O(n) pass.
+ * Pass the result to calculateAdaptiveZoomFromLookup() for O(log k) per-frame
+ * zoom computation, instead of O(transitionFrames) per frame.
+ *
+ * @returns Sorted array of frame indices that carry a clickPosition.
+ */
+declare function buildZoomClickLookup(frames: ReadonlyArray<{
+    clickPosition: unknown;
+}>): number[];
+/**
+ * Calculate adaptive zoom scale using a pre-built click index lookup.
+ * Binary-searches the lookup for the nearest click — O(log k) per call.
+ *
+ * Use buildZoomClickLookup() once before iterating, then call this per frame.
+ *
+ * @param clickLookup - Sorted array of click frame indices from buildZoomClickLookup()
+ * @param currentIndex - Index of the frame being evaluated
+ */
+declare function calculateAdaptiveZoomFromLookup(clickLookup: readonly number[], currentIndex: number, maxScale: number, transitionFrames: number): number;
+/**
+ * Calculate adaptive zoom scale using only a local window of frames.
+ * Does NOT need the full frame array — only frames within
+ * [currentIndex - transitionFrames, currentIndex + transitionFrames].
+ *
+ * This is the Phase 3-A compatible API: when composition runs concurrently
+ * with recording, only the ±transitionFrames lookahead buffer needs to be
+ * available before frame i can be composed.
+ *
+ * @param windowFrames - Slice of frames around currentIndex
+ * @param windowStart  - Absolute timeline index of windowFrames[0]
+ * @param currentIndex - Absolute timeline index of the frame being composed
+ */
+declare function calculateAdaptiveZoomInWindow(windowFrames: ReadonlyArray<{
+    clickPosition: unknown;
+}>, windowStart: number, currentIndex: number, maxScale: number, transitionFrames: number): number;
 /**
  * Calculate pan offset to keep a focus point centered when zoomed in.
  * The offset defines the top-left corner of the visible crop region.
@@ -2021,17 +2309,27 @@ type KeystrokeConfig = EffectsConfig["keystroke"];
  */
 declare function renderKeystrokeHud(frameBuffer: Buffer, keystrokes: KeystrokeEvent[], frameTimestamp: number, config: KeystrokeConfig, frameWidth: number, frameHeight: number, dpr?: number): Promise<Buffer>;
 
+type RawInfo = {
+    width: number;
+    height: number;
+    channels: 4;
+};
 /**
  * Apply a crossfade transition between two frame buffers.
  * Uses raw pixel weighted averaging for accurate blending.
  *
- * @param fromBuffer - The outgoing frame
- * @param toBuffer   - The incoming frame
- * @param progress   - 0 = fully "from", 1 = fully "to"
- * @param width      - Frame width
- * @param height     - Frame height
+ * @param fromBuffer  - The outgoing frame (PNG or raw RGBA)
+ * @param toBuffer    - The incoming frame (PNG or raw RGBA)
+ * @param progress    - 0 = fully "from", 1 = fully "to"
+ * @param width       - Frame width
+ * @param height      - Frame height
+ * @param fromRawInfo - Pass when fromBuffer is raw RGBA
+ * @param toRawInfo   - Pass when toBuffer is raw RGBA
  */
-declare function applyCrossfade(fromBuffer: Buffer, toBuffer: Buffer, progress: number, width: number, height: number): Promise<Buffer>;
+declare function applyCrossfade(fromBuffer: Buffer, toBuffer: Buffer, progress: number, width: number, height: number, fromRawInfo?: RawInfo, toRawInfo?: RawInfo): Promise<{
+    buffer: Buffer;
+    rawInfo: RawInfo;
+}>;
 
 type WatermarkConfig = EffectsConfig["watermark"];
 /**
@@ -2060,4 +2358,4 @@ interface ValidationResult {
  */
 declare function validateScenario(scenario: Scenario): ValidationResult;
 
-export { CanvasRenderer, type CapturedFrame, ClipwiseRecorder, type ComposedFrame, type EffectsConfig, type FrameContext, type KeystrokeEvent, type OutputConfig, type RecordingSession, type Scenario, type Step, type StepAction, applyCrossfade, calculateAdaptiveZoom, calculatePanOffset, encodeGif, encodeMp4, lerpZoom, loadScenario, parseScenario, renderCursorHighlight, renderCursorTrail, renderKeystrokeHud, renderWatermark, savePngSequence, validateScenario };
+export { CanvasRenderer, type CapturedFrame, ClipwiseRecorder, type ComposedFrame, type ConcurrentResult, ConcurrentSession, type EffectsConfig, type FrameContext, type KeystrokeEvent, type OutputConfig, type PipelineProgress, type RecordingHandle, type RecordingSession, type Scenario, type Step, type StepAction, StreamingSession, applyCrossfade, buildZoomClickLookup, calculateAdaptiveZoom, calculateAdaptiveZoomFromLookup, calculateAdaptiveZoomInWindow, calculatePanOffset, encodeGif, encodeMp4, encodeMp4Stream, lerpZoom, loadScenario, parseScenario, renderCursorHighlight, renderCursorTrail, renderKeystrokeHud, renderWatermark, savePngSequence, validateScenario };