clipwise 0.5.2 → 0.6.0

package/dist/cli/index.js

@@ -11,7 +11,7 @@ var __export = (target, all) => {
 
 // src/script/types.ts
 import { z } from "zod";
-var SafeSelectorSchema, NavigateActionSchema, ClickActionSchema, TypeActionSchema, ScrollActionSchema, WaitActionSchema, HoverActionSchema, ScreenshotActionSchema, WaitForSelectorActionSchema, WaitForNavigationActionSchema, WaitForURLActionSchema, WaitForFunctionActionSchema, WaitForResponseActionSchema, StepActionSchema, ZoomIntensitySchema, AutoZoomConfigSchema, ZoomEffectSchema, CursorEffectSchema, BackgroundSchema, DeviceFrameSchema, SpeedRampConfigSchema, KeystrokeConfigSchema, WatermarkConfigSchema, EffectsConfigSchema, OutputConfigSchema, StepSchema, ScenarioSchema;
+var SafeSelectorSchema, NavigateActionSchema, ClickActionSchema, TypeActionSchema, ScrollActionSchema, WaitActionSchema, HoverActionSchema, ScreenshotActionSchema, WaitForSelectorActionSchema, WaitForNavigationActionSchema, WaitForURLActionSchema, WaitForFunctionActionSchema, WaitForResponseActionSchema, StepActionSchema, ZoomIntensitySchema, AutoZoomConfigSchema, ZoomEffectSchema, CursorEffectSchema, BackgroundSchema, DeviceFrameSchema, SpeedRampConfigSchema, KeystrokeConfigSchema, WatermarkConfigSchema, EffectsConfigSchema, OutputConfigSchema, StepEffectsOverrideSchema, TransitionTypeSchema, StepSchema, AudioConfigSchema, ScenarioSchema;
 var init_types = __esm({
   "src/script/types.ts"() {
     "use strict";
@@ -119,15 +119,16 @@ var init_types = __esm({
       enabled: z.boolean().default(true),
       /**
        * Numeric zoom scale (1.0 = no zoom).  Overridden by `intensity` when set.
-       * Default lowered from 1.8 → 1.35 to match "moderate" intensity.
+       * Default: 1.25 to match "light" intensity (industry standard).
        */
-      scale: z.number().min(1).max(5).default(1.35),
+      scale: z.number().min(1).max(5).default(1.25),
       /**
        * Intensity preset — overrides `scale` when set.
        * Calibrated against Loom (light≈1.25x) and Camtasia (moderate≈1.35x).
+       * Default: "light" (1.25x) — matches industry standard (Screen Studio, Loom).
        */
-      intensity: ZoomIntensitySchema.optional(),
-      duration: z.number().default(600),
+      intensity: ZoomIntensitySchema.default("light"),
+      duration: z.number().default(800),
       easing: z.enum(["ease-in-out", "ease-in", "ease-out", "linear"]).default("ease-in-out"),
       autoZoom: AutoZoomConfigSchema.default({})
     });
@@ -135,7 +136,7 @@ var init_types = __esm({
       enabled: z.boolean().default(true),
       size: z.number().default(20),
       color: z.string().default("#000000"),
-      speed: z.enum(["fast", "normal", "slow"]).default("fast"),
+      speed: z.enum(["fast", "normal", "slow"]).default("normal"),
       smoothing: z.boolean().default(true),
       clickEffect: z.boolean().default(true),
       clickColor: z.string().default("rgba(59, 130, 246, 0.3)"),
@@ -161,7 +162,7 @@ var init_types = __esm({
     });
     SpeedRampConfigSchema = z.object({
       enabled: z.boolean().default(false),
-      idleSpeed: z.number().min(0.5).max(8).default(3),
+      idleSpeed: z.number().min(0.5).max(8).default(2),
       actionSpeed: z.number().min(0.25).max(2).default(0.8),
       transitionFrames: z.number().default(15)
     });
@@ -203,10 +204,11 @@ var init_types = __esm({
       watermark: WatermarkConfigSchema.default({})
     });
     OutputConfigSchema = z.object({
-      format: z.enum(["gif", "mp4", "webm", "png-sequence"]).default("gif"),
+      format: z.enum(["gif", "mp4", "webm", "png-sequence"]).default("mp4"),
       width: z.number().default(1280),
       height: z.number().default(800),
       fps: z.number().min(1).max(60).default(30),
+      /** @deprecated Use `preset` instead. Will be removed in v0.7. */
       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)
@@ -216,12 +218,40 @@ var init_types = __esm({
       outputDir: z.string().default("./output"),
       filename: z.string().default("clipwise-recording")
     });
+    StepEffectsOverrideSchema = z.object({
+      zoom: ZoomEffectSchema.partial().optional(),
+      cursor: CursorEffectSchema.partial().optional(),
+      background: BackgroundSchema.partial().optional(),
+      deviceFrame: DeviceFrameSchema.partial().optional(),
+      speedRamp: SpeedRampConfigSchema.partial().optional(),
+      keystroke: KeystrokeConfigSchema.partial().optional(),
+      watermark: WatermarkConfigSchema.partial().optional()
+    }).optional();
+    TransitionTypeSchema = z.enum([
+      "none",
+      "fade",
+      "slide-left",
+      "slide-up",
+      "blur"
+    ]);
     StepSchema = z.object({
       name: z.string().optional(),
       actions: z.array(StepActionSchema),
       captureDelay: z.number().default(300),
       holdDuration: z.number().default(1500),
-      transition: z.enum(["fade", "none"]).default("none")
+      transition: TransitionTypeSchema.default("none"),
+      /** Per-step effects override — merges with global effects config. */
+      effects: StepEffectsOverrideSchema
+    });
+    AudioConfigSchema = z.object({
+      /** Path to the audio file (MP3, WAV, AAC, etc.). */
+      file: z.string().min(1),
+      /** Volume level (0.0 = silent, 1.0 = full). */
+      volume: z.number().min(0).max(1).default(1),
+      /** Fade-in duration in milliseconds. */
+      fadeIn: z.number().min(0).default(0),
+      /** Fade-out duration in milliseconds. */
+      fadeOut: z.number().min(0).default(0)
     });
     ScenarioSchema = z.object({
       name: z.string(),
@@ -232,6 +262,8 @@ var init_types = __esm({
       }).default({}),
       effects: EffectsConfigSchema.default({}),
       output: OutputConfigSchema.default({}),
+      /** Optional audio narration — muxed into MP4 output. */
+      audio: AudioConfigSchema.optional(),
       steps: z.array(StepSchema).min(1)
     });
   }
@@ -472,12 +504,13 @@ var ClipwiseRecorder = class {
    *  each input field's text on a separate line. */
   keystrokeSessionId = 0;
   currentStepIndex = 0;
+  isScrolling = false;
   cursorPosition = { x: 0, y: 0 };
   viewport = { width: 1280, height: 800 };
   deviceScaleFactor = 1;
   isCapturing = false;
   targetFps = 30;
-  cursorSpeed = "fast";
+  cursorSpeed = "normal";
   firstContentTimestamp = 0;
   pendingResponsePromises = /* @__PURE__ */ new Map();
   // ── 중복 프레임 제거 (Phase 1-A) ──────────────────────────────────────────
@@ -510,6 +543,7 @@ var ClipwiseRecorder = class {
     this.keystrokeTimeline = [];
     this.keystrokeSessionId = 0;
     this.currentStepIndex = 0;
+    this.isScrolling = false;
     this.cursorPosition = { x: 0, y: 0 };
     this.isCapturing = false;
     this.firstContentTimestamp = 0;
@@ -539,11 +573,12 @@ var ClipwiseRecorder = class {
         } else {
           this.lastFrameSignature = Buffer.from(signature);
           const captureTime = Date.now();
-          this.rawFrames.push({ buffer, timestamp: captureTime, stepIndex: this.currentStepIndex });
+          const rawFrame = { buffer, timestamp: captureTime, stepIndex: this.currentStepIndex, isScrolling: this.isScrolling };
+          this.rawFrames.push(rawFrame);
           this.dedupStats.stored++;
           if (this.frameChannel && this.firstContentTimestamp > 0) {
             const frame = this.buildFrameOnline(
-              { buffer, timestamp: captureTime, stepIndex: this.currentStepIndex },
+              rawFrame,
               this.channelIndex++
             );
             this.frameChannel.push(frame);
@@ -748,7 +783,8 @@ var ClipwiseRecorder = class {
       viewport: { ...this.viewport },
       deviceScaleFactor: this.deviceScaleFactor,
       stepIndex: raw.stepIndex,
-      keystrokes: frameKeystrokes.length > 0 ? frameKeystrokes : void 0
+      keystrokes: frameKeystrokes.length > 0 ? frameKeystrokes : void 0,
+      isScrolling: raw.isScrolling || void 0
     };
   }
   /**
@@ -884,6 +920,7 @@ var ClipwiseRecorder = class {
       case "scroll": {
         const scrollTarget = action.selector ? await getElementCenter(this.page, action.selector, action.timeout) : null;
         const scrollDistance = Math.abs(action.y) + Math.abs(action.x);
+        this.isScrolling = true;
         if (action.smooth && scrollDistance > 0) {
           const scrollSteps = Math.max(12, Math.round(scrollDistance / 25));
           const yStep = action.y / scrollSteps;
@@ -923,6 +960,7 @@ var ClipwiseRecorder = class {
             timestamp: Date.now()
           });
         }
+        this.isScrolling = false;
         await this.waitWithRepaints(120);
         break;
       }
@@ -1088,8 +1126,9 @@ var ClipwiseRecorder = class {
         viewport: { ...this.viewport },
         deviceScaleFactor: this.deviceScaleFactor,
         keystrokes: frameKeystrokes.length > 0 ? frameKeystrokes : void 0,
-        stepIndex: raw.stepIndex
+        stepIndex: raw.stepIndex,
         // use per-frame step index captured at event time
+        isScrolling: raw.isScrolling || void 0
       };
     });
   }
@@ -1912,7 +1951,8 @@ async function composeFrame(frame, effects, output, context) {
   }
   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 followCursor = effects.zoom.autoZoom.followCursor;
+    const rawFocus = followCursor ? frame.cursorPosition ?? frame.clickPosition ?? { x: frame.viewport.width / 2, y: frame.viewport.height / 2 } : 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,
@@ -1980,37 +2020,170 @@ async function composeFrame(frame, effects, output, context) {
 
 // src/effects/transition.ts
 import sharp8 from "sharp";
+async function decodeToRaw(buf, rawInfo, targetWidth, targetHeight) {
+  const src = rawInfo ? sharp8(buf, { raw: { width: rawInfo.width, height: rawInfo.height, channels: rawInfo.channels } }) : sharp8(buf);
+  const pipeline = targetWidth && targetHeight ? src.resize(targetWidth, targetHeight, { fit: "fill" }).ensureAlpha().raw() : src.ensureAlpha().raw();
+  const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });
+  return { data: Buffer.from(data), width: info.width, height: info.height };
+}
+function returnRaw(buf, rawInfo, w, h) {
+  if (rawInfo) return { buffer: buf, rawInfo };
+  return null;
+}
 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 } };
+    const fast = returnRaw(fromBuffer, fromRawInfo, width, height);
+    if (fast) return fast;
+    const d = await decodeToRaw(fromBuffer, void 0);
+    return { buffer: d.data, rawInfo: { width: d.width, height: d.height, channels: 4 } };
+  }
+  if (t >= 1) {
+    const fast = returnRaw(toBuffer, toRawInfo, width, height);
+    if (fast) return fast;
+    const d = await decodeToRaw(toBuffer, void 0);
+    return { buffer: d.data, rawInfo: { width: d.width, height: d.height, channels: 4 } };
+  }
+  const from = await decodeToRaw(fromBuffer, fromRawInfo);
+  const to = await decodeToRaw(toBuffer, toRawInfo, from.width, from.height);
+  const pixels = Buffer.alloc(from.data.length);
+  for (let i = 0; i < from.data.length; i++) {
+    pixels[i] = Math.round(from.data[i] * (1 - t) + to.data[i] * t);
+  }
+  return { buffer: pixels, rawInfo: { width: from.width, height: from.height, channels: 4 } };
+}
+async function applySlide(fromBuffer, toBuffer, progress, width, height, direction, fromRawInfo, toRawInfo) {
+  const t = Math.max(0, Math.min(1, progress));
+  if (t <= 0) {
+    const fast = returnRaw(fromBuffer, fromRawInfo, width, height);
+    if (fast) return fast;
+    const d = await decodeToRaw(fromBuffer, void 0);
+    return { buffer: d.data, rawInfo: { width: d.width, height: d.height, channels: 4 } };
+  }
+  if (t >= 1) {
+    const fast = returnRaw(toBuffer, toRawInfo, width, height);
+    if (fast) return fast;
+    const d = await decodeToRaw(toBuffer, void 0);
+    return { buffer: d.data, rawInfo: { width: d.width, height: d.height, channels: 4 } };
+  }
+  const from = await decodeToRaw(fromBuffer, fromRawInfo);
+  const to = await decodeToRaw(toBuffer, toRawInfo, from.width, from.height);
+  const w = from.width;
+  const h = from.height;
+  const pixels = Buffer.alloc(from.data.length);
+  const eased = easeInOutCubic3(t);
+  if (direction === "left") {
+    const offsetX = Math.round(w * (1 - eased));
+    for (let y = 0; y < h; y++) {
+      for (let x = 0; x < w; x++) {
+        const dstIdx = (y * w + x) * 4;
+        const srcX = x + offsetX;
+        if (srcX < w) {
+          const srcIdx = (y * w + srcX) * 4;
+          pixels[dstIdx] = to.data[srcIdx];
+          pixels[dstIdx + 1] = to.data[srcIdx + 1];
+          pixels[dstIdx + 2] = to.data[srcIdx + 2];
+          pixels[dstIdx + 3] = to.data[srcIdx + 3];
+        } else {
+          const fromX = srcX - w;
+          if (fromX < w) {
+            const srcIdx = (y * w + fromX) * 4;
+            pixels[dstIdx] = from.data[srcIdx];
+            pixels[dstIdx + 1] = from.data[srcIdx + 1];
+            pixels[dstIdx + 2] = from.data[srcIdx + 2];
+            pixels[dstIdx + 3] = from.data[srcIdx + 3];
+          }
+        }
+      }
+    }
+  } else {
+    const offsetY = Math.round(h * (1 - eased));
+    for (let y = 0; y < h; y++) {
+      for (let x = 0; x < w; x++) {
+        const dstIdx = (y * w + x) * 4;
+        const srcY = y + offsetY;
+        if (srcY < h) {
+          const srcIdx = (srcY * w + x) * 4;
+          pixels[dstIdx] = to.data[srcIdx];
+          pixels[dstIdx + 1] = to.data[srcIdx + 1];
+          pixels[dstIdx + 2] = to.data[srcIdx + 2];
+          pixels[dstIdx + 3] = to.data[srcIdx + 3];
+        } else {
+          const fromY = srcY - h;
+          if (fromY < h) {
+            const srcIdx = (fromY * w + x) * 4;
+            pixels[dstIdx] = from.data[srcIdx];
+            pixels[dstIdx + 1] = from.data[srcIdx + 1];
+            pixels[dstIdx + 2] = from.data[srcIdx + 2];
+            pixels[dstIdx + 3] = from.data[srcIdx + 3];
+          }
+        }
+      }
+    }
+  }
+  return { buffer: pixels, rawInfo: { width: w, height: h, channels: 4 } };
+}
+async function applyBlur(fromBuffer, toBuffer, progress, width, height, fromRawInfo, toRawInfo) {
+  const t = Math.max(0, Math.min(1, progress));
+  if (t <= 0) {
+    const fast = returnRaw(fromBuffer, fromRawInfo, width, height);
+    if (fast) return fast;
+    const d = await decodeToRaw(fromBuffer, void 0);
+    return { buffer: d.data, rawInfo: { width: d.width, height: d.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 fast = returnRaw(toBuffer, toRawInfo, width, height);
+    if (fast) return fast;
+    const d = await decodeToRaw(toBuffer, void 0);
+    return { buffer: d.data, rawInfo: { width: d.width, height: d.height, channels: 4 } };
   }
+  const sigma = t * 20;
   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
-    );
+  const blurredFrom = await fromSrc.blur(Math.max(0.3, sigma)).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  const to = await decodeToRaw(toBuffer, toRawInfo, blurredFrom.info.width, blurredFrom.info.height);
+  const pixels = Buffer.alloc(blurredFrom.data.length);
+  for (let i = 0; i < blurredFrom.data.length; i++) {
+    pixels[i] = Math.round(blurredFrom.data[i] * (1 - t) + to.data[i] * t);
   }
   return {
     buffer: pixels,
-    rawInfo: { width: fromRaw.info.width, height: fromRaw.info.height, channels: 4 }
+    rawInfo: { width: blurredFrom.info.width, height: blurredFrom.info.height, channels: 4 }
   };
 }
+async function applyTransition(type, fromBuffer, toBuffer, progress, width, height, fromRawInfo, toRawInfo) {
+  switch (type) {
+    case "fade":
+      return applyCrossfade(fromBuffer, toBuffer, progress, width, height, fromRawInfo, toRawInfo);
+    case "slide-left":
+      return applySlide(fromBuffer, toBuffer, progress, width, height, "left", fromRawInfo, toRawInfo);
+    case "slide-up":
+      return applySlide(fromBuffer, toBuffer, progress, width, height, "up", fromRawInfo, toRawInfo);
+    case "blur":
+      return applyBlur(fromBuffer, toBuffer, progress, width, height, fromRawInfo, toRawInfo);
+    case "none":
+    default:
+      const d = await decodeToRaw(toBuffer, toRawInfo);
+      return { buffer: d.data, rawInfo: { width: d.width, height: d.height, channels: 4 } };
+  }
+}
+function easeInOutCubic3(t) {
+  return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+}
 
 // src/compose/canvas-renderer.ts
+function mergeStepEffects(global, stepIndex, steps) {
+  if (stepIndex === void 0 || !steps[stepIndex]?.effects) return global;
+  const override = steps[stepIndex].effects;
+  return {
+    zoom: override.zoom ? { ...global.zoom, ...override.zoom } : global.zoom,
+    cursor: override.cursor ? { ...global.cursor, ...override.cursor } : global.cursor,
+    background: override.background ? { ...global.background, ...override.background } : global.background,
+    deviceFrame: override.deviceFrame ? { ...global.deviceFrame, ...override.deviceFrame } : global.deviceFrame,
+    speedRamp: override.speedRamp ? { ...global.speedRamp, ...override.speedRamp } : global.speedRamp,
+    keystroke: override.keystroke ? { ...global.keystroke, ...override.keystroke } : global.keystroke,
+    watermark: override.watermark ? { ...global.watermark, ...override.watermark } : global.watermark
+  };
+}
 var MIN_FRAMES_PER_WORKER = 4;
 var cachedWorkerUrl = null;
 function getWorkerUrl() {
@@ -2066,14 +2239,17 @@ var CanvasRenderer = class {
     const cpuCount = os.cpus().length;
     const workerCount = Math.min(cpuCount, 8);
     const useWorkers = workerCount >= 2 && processFrames.length >= workerCount * MIN_FRAMES_PER_WORKER;
+    const perFrameEffects = processFrames.map(
+      (f) => mergeStepEffects(this.effects, f.stepIndex, this.steps)
+    );
     let composed;
     if (useWorkers) {
-      composed = await this.processWithWorkers(processFrames, contexts, workerCount);
+      composed = await this.processWithWorkers(processFrames, contexts, workerCount, perFrameEffects);
     } else {
       composed = [];
       for (let i = 0; i < processFrames.length; i++) {
         composed.push(
-          await composeFrame(processFrames[i], this.effects, this.output, contexts[i])
+          await composeFrame(processFrames[i], perFrameEffects[i], this.output, contexts[i])
         );
       }
     }
@@ -2086,7 +2262,7 @@ var CanvasRenderer = class {
    * Distribute frame composition across a pool of worker threads.
    * Workers process frames concurrently; results are collected in order.
    */
-  processWithWorkers(frames, contexts, workerCount) {
+  processWithWorkers(frames, contexts, workerCount, perFrameEffects) {
     return new Promise((resolve2, reject) => {
       const results = new Array(frames.length);
       let completed = 0;
@@ -2100,7 +2276,7 @@ var CanvasRenderer = class {
         worker.postMessage({
           taskId: i,
           frame: frames[i],
-          effects: this.effects,
+          effects: perFrameEffects ? perFrameEffects[i] : this.effects,
           output: this.output,
           context: contexts[i]
         });
@@ -2163,6 +2339,9 @@ var CanvasRenderer = class {
           effectiveScale,
           transitionFrames
         );
+        if (frame.isScrolling && zoomScale > 1) {
+          zoomScale = 1;
+        }
       }
       const clickProgress = frame.clickPosition != null ? frame.clickProgress ?? 0.5 : null;
       const trailLength = this.effects.cursor.trailLength;
@@ -2237,7 +2416,7 @@ var CanvasRenderer = class {
    * using the same applyTransitionsToStream() logic as composeStream().
    */
   async *composeStreamOnline(source) {
-    const hasFadeTransitions = this.steps.some((s) => s.transition === "fade");
+    const hasFadeTransitions = this.steps.some((s) => s.transition !== "none");
     if (!hasFadeTransitions) {
       const cpuCount = os.cpus().length;
       const workerCount = Math.min(cpuCount, 8);
@@ -2293,6 +2472,9 @@ var CanvasRenderer = class {
           effectiveScale,
           transitionFrames
         );
+        if (frame.isScrolling && zoomScale > 1) {
+          zoomScale = 1;
+        }
       }
       const clickProgress = frame.clickPosition != null ? frame.clickProgress ?? 0.5 : null;
       const trail = [];
@@ -2304,10 +2486,11 @@ var CanvasRenderer = class {
     const dispatch = (worker) => {
       if (canDispatch(nextToDispatch)) {
         const i = nextToDispatch++;
+        const frameEffects = mergeStepEffects(this.effects, frames[i].stepIndex, this.steps);
         worker.postMessage({
           taskId: i,
           frame: frames[i],
-          effects: this.effects,
+          effects: frameEffects,
           output: this.output,
           context: computeContext(i)
         });
@@ -2417,13 +2600,16 @@ var CanvasRenderer = class {
     const workerUrl = getWorkerUrl();
     const workers = [];
     let nextToDispatch = 0;
+    const perFrameEffects = frames.map(
+      (f) => mergeStepEffects(this.effects, f.stepIndex, this.steps)
+    );
     const dispatch = (worker) => {
       if (nextToDispatch >= frames.length || workerError) return;
       const i = nextToDispatch++;
       worker.postMessage({
         taskId: i,
         frame: frames[i],
-        effects: this.effects,
+        effects: perFrameEffects[i],
         output: this.output,
         context: contexts[i]
       });
@@ -2474,7 +2660,8 @@ var CanvasRenderer = class {
    */
   async *streamSequential(frames, contexts) {
     for (let i = 0; i < frames.length; i++) {
-      yield await composeFrame(frames[i], this.effects, this.output, contexts[i]);
+      const frameEffects = mergeStepEffects(this.effects, frames[i].stepIndex, this.steps);
+      yield await composeFrame(frames[i], frameEffects, this.output, contexts[i]);
     }
   }
   /**
@@ -2489,11 +2676,11 @@ var CanvasRenderer = class {
       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") {
+        if (step && step.transition !== "none") {
           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 });
+            windows.push({ startIdx, endIdx, type: step.transition });
           }
         }
       }
@@ -2540,10 +2727,12 @@ var CanvasRenderer = class {
           const fromBuf = state.frames[0].buffer;
           const toBuf = state.frames[state.frames.length - 1].buffer;
           const range = state.frames.length - 1;
+          const transType = win.type;
           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(
+            const blended = await applyTransition(
+              transType,
               fromBuf,
               toBuf,
               j / range,
@@ -2585,8 +2774,8 @@ var CanvasRenderer = class {
       if (frames[i].stepIndex !== void 0 && frames[i - 1].stepIndex !== void 0 && frames[i].stepIndex !== frames[i - 1].stepIndex) {
         const stepIdx = frames[i].stepIndex;
         const step = this.steps[stepIdx];
-        if (step && step.transition === "fade") {
-          boundaries.push({ index: i, stepIndex: stepIdx });
+        if (step && step.transition !== "none") {
+          boundaries.push({ index: i, stepIndex: stepIdx, type: step.transition });
         }
       }
     }
@@ -2601,7 +2790,8 @@ var CanvasRenderer = class {
       const toRawInfo = composed[endIdx].rawInfo;
       for (let i = startIdx + 1; i < endIdx; i++) {
         const progress = (i - startIdx) / range;
-        const blended = await applyCrossfade(
+        const blended = await applyTransition(
+          boundary.type,
           fromBuffer,
           toBuffer,
           progress,
@@ -2678,19 +2868,19 @@ async function encodeGif(frames, config) {
   gif.finish();
   return Buffer.from(gif.bytes());
 }
-async function encodeMp4Stream(frames, config) {
+async function encodeMp4Stream(frames, config, audio) {
   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);
+    await pipeStreamToFfmpeg(frames, config, params, encoder, outputPath, audio);
     return await readFile2(outputPath);
   } finally {
     await rm(outputPath, { force: true }).catch(() => {
     });
   }
 }
-async function pipeStreamToFfmpeg(frames, config, params, encoder, outputPath) {
+async function pipeStreamToFfmpeg(frames, config, params, encoder, outputPath, audio) {
   const videoArgs = encoder === "hevc_videotoolbox" ? [
     "-c:v",
     "hevc_videotoolbox",
@@ -2723,6 +2913,14 @@ async function pipeStreamToFfmpeg(frames, config, params, encoder, outputPath) {
     "-pix_fmt",
     "yuv420p"
   ];
+  const audioInputArgs = audio ? ["-i", audio.file] : ["-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo"];
+  const audioFilters = [];
+  if (audio) {
+    if (audio.volume !== 1) audioFilters.push(`volume=${audio.volume}`);
+    if (audio.fadeIn > 0) audioFilters.push(`afade=t=in:d=${audio.fadeIn / 1e3}`);
+    if (audio.fadeOut > 0) audioFilters.push(`afade=t=out:st=999999:d=${audio.fadeOut / 1e3}`);
+  }
+  const audioFilterArgs = audioFilters.length > 0 ? ["-af", audioFilters.join(",")] : [];
   return new Promise((resolve2, reject) => {
     const ffmpeg = spawn(
       "ffmpeg",
@@ -2738,15 +2936,13 @@ async function pipeStreamToFfmpeg(frames, config, params, encoder, outputPath) {
         String(config.fps),
         "-i",
         "pipe:0",
-        "-f",
-        "lavfi",
-        "-i",
-        "anullsrc=r=48000:cl=stereo",
+        ...audioInputArgs,
         ...videoArgs,
         "-c:a",
         "aac",
         "-b:a",
         "128k",
+        ...audioFilterArgs,
         "-shortest",
         "-movflags",
         "+faststart",
@@ -2835,7 +3031,8 @@ var ConcurrentSession = class extends EventEmitter {
           yield frame;
         }
       })(),
-      this.scenario.output
+      this.scenario.output,
+      this.scenario.audio
     );
     const session = await handle.done;
     this.emit("progress", { composed, total: composed, pct: 100 });
@@ -2875,7 +3072,8 @@ var StreamingSession = class extends EventEmitter {
           yield frame;
         }
       })(),
-      scenario.output
+      scenario.output,
+      scenario.audio
     );
   }
 };
@@ -2888,7 +3086,7 @@ import { homedir } from "os";
 var program = new Command();
 program.name("clipwise").description(
   "Playwright-based cinematic screen recorder for product demos"
-).version("0.1.0");
+).version("0.6.0");
 program.command("record").description("Record a demo from a YAML scenario file").argument("<scenario>", "Path to YAML scenario file").option("-o, --output <dir>", "Output directory", "./output").option(
   "-f, --format <format>",
   "Output format (gif|mp4|png-sequence)"
@@ -3007,7 +3205,8 @@ program.command("record").description("Record a demo from a YAML scenario file")
         }
         await writeFile2(outputPath, mp4Buffer);
         const sizeMB = (mp4Buffer.length / (1024 * 1024)).toFixed(2);
-        spinner.succeed(`MP4 saved to ${chalk.bold(outputPath)} (${sizeMB} MB)`);
+        const audioMsg = scenario.audio ? ` + audio: ${scenario.audio.file}` : "";
+        spinner.succeed(`MP4 saved to ${chalk.bold(outputPath)} (${sizeMB} MB${audioMsg})`);
       } else {
         let composedFrames;
         if (options.effects !== false) {
@@ -3150,7 +3349,7 @@ program.command("demo").description("Record a demo video of the Clipwise showcas
 ).action(async (options) => {
   const spinner = ora();
   try {
-    const demoUrl = options.url ?? "https://kwakseongjae.github.io/clipwise/";
+    const demoUrl = options.url ?? "https://kwakseongjae.github.io/clipwise/demo/";
     const device = options.device;
     const isMobile = device === "iphone" || device === "android";
     const isTablet = device === "ipad";
@@ -3165,7 +3364,10 @@ program.command("demo").description("Record a demo video of the Clipwise showcas
         name: "Load dashboard",
         captureDelay: 100,
         holdDuration: 1e3,
-        actions: [{ action: "navigate", url: demoUrl, waitUntil: "load" }]
+        actions: [
+          { action: "navigate", url: demoUrl, waitUntil: "load" },
+          { action: "waitForSelector", selector: "#stat-users", state: "visible", timeout: 15e3 }
+        ]
       },
       {
         name: "Hover Users stat",

package/dist/compose/frame-worker.js

@@ -704,7 +704,8 @@ async function composeFrame(frame, effects, output, context) {
   }
   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 followCursor = effects.zoom.autoZoom.followCursor;
+    const rawFocus = followCursor ? frame.cursorPosition ?? frame.clickPosition ?? { x: frame.viewport.width / 2, y: frame.viewport.height / 2 } : 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,