clipwise 0.6.1 → 0.7.1

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, StepEffectsOverrideSchema, TransitionTypeSchema, StepSchema, AudioConfigSchema, ScenarioSchema;
+var SafeSelectorSchema, NavigateActionSchema, ClickActionSchema, TypeActionSchema, ScrollActionSchema, WaitActionSchema, HoverActionSchema, ScreenshotActionSchema, WaitForSelectorActionSchema, WaitForNavigationActionSchema, WaitForURLActionSchema, WaitForFunctionActionSchema, WaitForResponseActionSchema, SmartWaitActionSchema, StepActionSchema, ZoomIntensitySchema, AutoZoomConfigSchema, ZoomEffectSchema, CursorEffectSchema, BackgroundSchema, DeviceFrameSchema, SpeedRampConfigSchema, SmartSpeedConfigSchema, KeystrokeConfigSchema, WatermarkConfigSchema, EffectsConfigSchema, OutputConfigSchema, StepEffectsOverrideSchema, TransitionTypeSchema, StepSchema, AudioConfigSchema, ScenarioSchema;
 var init_types = __esm({
   "src/script/types.ts"() {
     "use strict";
@@ -87,6 +87,17 @@ var init_types = __esm({
       status: z.number().min(100).max(599).optional(),
       timeout: z.number().min(0).default(3e4)
     });
+    SmartWaitActionSchema = z.object({
+      action: z.literal("smartWait"),
+      /** Condition to wait for */
+      until: z.enum(["networkIdle", "selector", "domStable"]).default("networkIdle"),
+      /** CSS selector (required when until="selector") */
+      selector: SafeSelectorSchema.optional(),
+      /** Maximum wait in ms */
+      timeout: z.number().min(0).default(3e4),
+      /** Speed multiplier for the wait period in the output video (default: 8×) */
+      displaySpeed: z.number().min(1).max(32).default(8)
+    });
     StepActionSchema = z.discriminatedUnion("action", [
       NavigateActionSchema,
       ClickActionSchema,
@@ -99,7 +110,8 @@ var init_types = __esm({
       WaitForNavigationActionSchema,
       WaitForURLActionSchema,
       WaitForFunctionActionSchema,
-      WaitForResponseActionSchema
+      WaitForResponseActionSchema,
+      SmartWaitActionSchema
     ]);
     ZoomIntensitySchema = z.enum([
       "subtle",
@@ -129,7 +141,7 @@ var init_types = __esm({
        */
       intensity: ZoomIntensitySchema.default("light"),
       duration: z.number().default(800),
-      easing: z.enum(["ease-in-out", "ease-in", "ease-out", "linear"]).default("ease-in-out"),
+      easing: z.enum(["ease-in-out", "ease-in", "ease-out", "linear", "spring"]).default("ease-in-out"),
       autoZoom: AutoZoomConfigSchema.default({})
     });
     CursorEffectSchema = z.object({
@@ -166,6 +178,17 @@ var init_types = __esm({
       actionSpeed: z.number().min(0.25).max(2).default(0.8),
       transitionFrames: z.number().default(15)
     });
+    SmartSpeedConfigSchema = z.object({
+      enabled: z.boolean().default(false),
+      /** Speed multiplier for frames during smartWait (overridden by per-action displaySpeed) */
+      waitSpeed: z.number().min(1).max(32).default(8),
+      /** Speed multiplier for idle frames (no DOM/network changes) */
+      idleSpeed: z.number().min(1).max(16).default(4),
+      /** Duration (ms) to ease between speed changes (prevents jarring jumps) */
+      transitionDuration: z.number().default(300),
+      /** Minimum segment duration (ms) — don't speed up very short segments */
+      minSegmentDuration: z.number().default(500)
+    });
     KeystrokeConfigSchema = z.object({
       enabled: z.boolean().default(false),
       /**
@@ -200,6 +223,7 @@ var init_types = __esm({
       background: BackgroundSchema.default({}),
       deviceFrame: DeviceFrameSchema.default({}),
       speedRamp: SpeedRampConfigSchema.default({}),
+      smartSpeed: SmartSpeedConfigSchema.default({}),
       keystroke: KeystrokeConfigSchema.default({}),
       watermark: WatermarkConfigSchema.default({})
     });
@@ -215,6 +239,8 @@ var init_types = __esm({
       // balanced — general-purpose, good quality/size trade-off (CRF 20)
       // archive  — high-fidelity storage, larger file (CRF 15)
       preset: z.enum(["social", "balanced", "archive"]).optional(),
+      /** Codec override: h264 (default), hevc (10-bit), av1 (smallest files, slow encode) */
+      codec: z.enum(["auto", "h264", "hevc", "av1"]).default("auto"),
       outputDir: z.string().default("./output"),
       filename: z.string().default("clipwise-recording")
     });
@@ -224,6 +250,7 @@ var init_types = __esm({
       background: BackgroundSchema.partial().optional(),
       deviceFrame: DeviceFrameSchema.partial().optional(),
       speedRamp: SpeedRampConfigSchema.partial().optional(),
+      smartSpeed: SmartSpeedConfigSchema.partial().optional(),
       keystroke: KeystrokeConfigSchema.partial().optional(),
       watermark: WatermarkConfigSchema.partial().optional()
     }).optional();
@@ -505,6 +532,12 @@ var ClipwiseRecorder = class {
   keystrokeSessionId = 0;
   currentStepIndex = 0;
   isScrolling = false;
+  isWaitingPhase = false;
+  currentDisplaySpeed;
+  /** Tracks active infinite CSS animations (spinners/loaders). Count > 0 → loading state. */
+  activeLoaderAnimations = /* @__PURE__ */ new Set();
+  /** Whether auto-loader detection is active (derived from smartSpeed.enabled). */
+  loaderDetectionEnabled = false;
   cursorPosition = { x: 0, y: 0 };
   viewport = { width: 1280, height: 800 };
   deviceScaleFactor = 1;
@@ -532,6 +565,7 @@ var ClipwiseRecorder = class {
     };
     this.targetFps = scenario.output.fps;
     this.cursorSpeed = scenario.effects.cursor.speed;
+    this.loaderDetectionEnabled = scenario.effects.smartSpeed?.enabled ?? false;
     this.browser = await chromium.launch({ headless: true });
     this.context = await this.browser.newContext({
       viewport: this.viewport
@@ -544,6 +578,9 @@ var ClipwiseRecorder = class {
     this.keystrokeSessionId = 0;
     this.currentStepIndex = 0;
     this.isScrolling = false;
+    this.isWaitingPhase = false;
+    this.currentDisplaySpeed = void 0;
+    this.activeLoaderAnimations.clear();
     this.cursorPosition = { x: 0, y: 0 };
     this.isCapturing = false;
     this.firstContentTimestamp = 0;
@@ -567,13 +604,15 @@ var ClipwiseRecorder = class {
         const buffer = Buffer.from(event.data, "base64");
         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);
+        const isInLoadingState = this.isWaitingPhase || this.loaderDetectionEnabled && this.activeLoaderAnimations.size > 0;
+        const isDuplicate = !isInLoadingState && 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();
-          const rawFrame = { buffer, timestamp: captureTime, stepIndex: this.currentStepIndex, isScrolling: this.isScrolling };
+          const isLoading = this.isWaitingPhase || this.loaderDetectionEnabled && this.activeLoaderAnimations.size > 0;
+          const rawFrame = { buffer, timestamp: captureTime, stepIndex: this.currentStepIndex, isScrolling: this.isScrolling, isWaitingPhase: isLoading, displaySpeed: this.currentDisplaySpeed };
           this.rawFrames.push(rawFrame);
           this.dedupStats.stored++;
           if (this.frameChannel && this.firstContentTimestamp > 0) {
@@ -590,6 +629,23 @@ var ClipwiseRecorder = class {
         });
       }
     );
+    if (this.loaderDetectionEnabled) {
+      this.cdpClient.on("Animation.animationStarted", (event) => {
+        const anim = event.animation;
+        const iterations = anim?.source?.iterations ?? 0;
+        const isInfinite = iterations === -1 || iterations > 100;
+        const animName = anim?.name || "";
+        const isLoaderPattern = /spin|rotate|pulse|bounce|loading|skeleton|shimmer/i.test(animName);
+        if (anim?.type === "CSSAnimation" && isInfinite && isLoaderPattern) {
+          this.activeLoaderAnimations.add(anim.id);
+        }
+      });
+      this.cdpClient.on("Animation.animationCanceled", (event) => {
+        this.activeLoaderAnimations.delete(event.id);
+      });
+      await this.cdpClient.send("Animation.enable").catch(() => {
+      });
+    }
     await this.cdpClient.send("Page.startScreencast", {
       format: "png",
       maxWidth: this.viewport.width * this.deviceScaleFactor,
@@ -784,7 +840,9 @@ var ClipwiseRecorder = class {
       deviceScaleFactor: this.deviceScaleFactor,
       stepIndex: raw.stepIndex,
       keystrokes: frameKeystrokes.length > 0 ? frameKeystrokes : void 0,
-      isScrolling: raw.isScrolling || void 0
+      isScrolling: raw.isScrolling || void 0,
+      isWaitingPhase: raw.isWaitingPhase || void 0,
+      displaySpeed: raw.displaySpeed
     };
   }
   /**
@@ -903,6 +961,7 @@ var ClipwiseRecorder = class {
         await this.page.click(action.selector);
         this.keystrokeSessionId++;
         const currentSessionId = this.keystrokeSessionId;
+        let lastClickRefresh = Date.now();
         let typeRepaintToggle = false;
         for (const char of action.text) {
           await this.page.keyboard.type(char);
@@ -914,7 +973,19 @@ var ClipwiseRecorder = class {
             sessionId: currentSessionId
           });
           await new Promise((resolve2) => setTimeout(resolve2, action.delay));
+          const now = Date.now();
+          if (now - lastClickRefresh >= 400) {
+            this.clickTimeline.push({
+              position: { ...inputTarget },
+              timestamp: now
+            });
+            lastClickRefresh = now;
+          }
         }
+        this.clickTimeline.push({
+          position: { ...inputTarget },
+          timestamp: Date.now()
+        });
         break;
       }
       case "scroll": {
@@ -1009,6 +1080,60 @@ var ClipwiseRecorder = class {
         }
         break;
       }
+      case "smartWait": {
+        this.isWaitingPhase = true;
+        this.currentDisplaySpeed = action.displaySpeed;
+        try {
+          let conditionPromise;
+          switch (action.until) {
+            case "networkIdle":
+              conditionPromise = this.page.waitForLoadState("networkidle", { timeout: action.timeout });
+              break;
+            case "selector":
+              conditionPromise = action.selector ? this.page.locator(action.selector).first().waitFor({ state: "visible", timeout: action.timeout }) : Promise.resolve();
+              break;
+            case "domStable":
+              conditionPromise = this.page.waitForFunction(
+                () => new Promise((resolve2) => {
+                  let timer;
+                  const observer = new MutationObserver(() => {
+                    clearTimeout(timer);
+                    timer = setTimeout(() => {
+                      observer.disconnect();
+                      resolve2(true);
+                    }, 500);
+                  });
+                  observer.observe(document.body, { childList: true, subtree: true, attributes: true });
+                  timer = setTimeout(() => {
+                    observer.disconnect();
+                    resolve2(true);
+                  }, 500);
+                }),
+                void 0,
+                { timeout: action.timeout }
+              );
+              break;
+            default:
+              conditionPromise = Promise.resolve();
+          }
+          let waitDone = false;
+          const repaintLoop = (async () => {
+            let toggle = false;
+            while (!waitDone && this.isCapturing && this.page) {
+              await this.forceRepaint(toggle);
+              toggle = !toggle;
+              await new Promise((r) => setTimeout(r, REPAINT_INTERVAL_MS));
+            }
+          })();
+          await conditionPromise;
+          waitDone = true;
+          await repaintLoop;
+        } finally {
+          this.isWaitingPhase = false;
+          this.currentDisplaySpeed = void 0;
+        }
+        break;
+      }
     }
     await this.waitWithRepaints(ACTION_GAP_MS);
   }
@@ -1128,7 +1253,9 @@ var ClipwiseRecorder = class {
         keystrokes: frameKeystrokes.length > 0 ? frameKeystrokes : void 0,
         stepIndex: raw.stepIndex,
         // use per-frame step index captured at event time
-        isScrolling: raw.isScrolling || void 0
+        isScrolling: raw.isScrolling || void 0,
+        isWaitingPhase: raw.isWaitingPhase || void 0,
+        displaySpeed: raw.displaySpeed
       };
     });
   }
@@ -1488,52 +1615,31 @@ async function applyDeviceFrame(frameBuffer, config, frameWidth, frameHeight, dp
 
 // src/effects/cursor.ts
 import sharp2 from "sharp";
-function buildCursorSvg(size, color) {
-  const s = size;
-  return `<svg xmlns="http://www.w3.org/2000/svg" width="${s}" height="${s}" viewBox="0 0 24 24" shape-rendering="geometricPrecision">
-    <path d="M4 0 L4 22 L10 16 L16 24 L20 22 L14 14 L22 14 Z"
-          fill="${color}" stroke="#ffffff" stroke-width="1.5" stroke-linejoin="round"/>
-  </svg>`;
-}
-function buildClickRippleSvg(radius, color, progress) {
-  const currentRadius = radius * progress;
-  const opacity = Math.max(0, 1 - progress);
-  const size = Math.ceil(radius * 2 + 4);
-  return `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" shape-rendering="geometricPrecision">
-    <circle cx="${size / 2}" cy="${size / 2}" r="${currentRadius}"
-            fill="none" stroke="${color}" stroke-width="2"
-            opacity="${opacity.toFixed(3)}"/>
-    <circle cx="${size / 2}" cy="${size / 2}" r="${currentRadius * 0.6}"
-            fill="${color}" opacity="${(opacity * 0.4).toFixed(3)}"/>
-  </svg>`;
-}
-async function renderCursor(frameBuffer, position, config, frameWidth, frameHeight, dpr = 1) {
-  if (!config.enabled) return frameBuffer;
+function buildCursorOverlay(position, config, frameWidth, frameHeight, dpr = 1) {
+  if (!config.enabled) return null;
   const size = Math.round(config.size * dpr);
   const cursorSvg = buildCursorSvg(size, config.color);
-  const cursorBuffer = Buffer.from(cursorSvg);
   const tipOffsetX = Math.round(4 / 24 * size);
   const px = Math.round(position.x * dpr);
   const py = Math.round(position.y * dpr);
   const left = Math.max(0, Math.min(px - tipOffsetX, frameWidth - size));
   const top = Math.max(0, Math.min(py, frameHeight - size));
-  return sharp2(frameBuffer).composite([{ input: cursorBuffer, left, top }]).png().toBuffer();
+  return { input: Buffer.from(cursorSvg), left, top };
 }
-async function renderClickEffect(frameBuffer, position, config, progress, frameWidth, frameHeight, dpr = 1) {
-  if (!config.enabled || !config.clickEffect) return frameBuffer;
+function buildClickRippleOverlay(position, config, progress, frameWidth, frameHeight, dpr = 1) {
+  if (!config.enabled || !config.clickEffect) return null;
   const radius = config.clickRadius * dpr;
   const clampedProgress = Math.max(0, Math.min(1, progress));
   const rippleSvg = buildClickRippleSvg(radius, config.clickColor, clampedProgress);
-  const rippleBuffer = Buffer.from(rippleSvg);
   const rippleSize = Math.ceil(radius * 2 + 4);
   const px = Math.round(position.x * dpr);
   const py = Math.round(position.y * dpr);
   const left = Math.max(0, Math.min(px - Math.round(rippleSize / 2), frameWidth - rippleSize));
   const top = Math.max(0, Math.min(py - Math.round(rippleSize / 2), frameHeight - rippleSize));
-  return sharp2(frameBuffer).composite([{ input: rippleBuffer, left, top }]).png().toBuffer();
+  return { input: Buffer.from(rippleSvg), left, top };
 }
-async function renderCursorHighlight(frameBuffer, position, config, frameWidth, frameHeight, dpr = 1) {
-  if (!config.enabled || !config.highlight) return frameBuffer;
+function buildHighlightOverlay(position, config, frameWidth, frameHeight, dpr = 1) {
+  if (!config.enabled || !config.highlight) return null;
   const r = config.highlightRadius * dpr;
   const size = Math.ceil(r * 2 + 4);
   const cx = size / 2;
@@ -1552,12 +1658,10 @@ async function renderCursorHighlight(frameBuffer, position, config, frameWidth,
   const py = Math.round(position.y * dpr);
   const left = Math.max(0, Math.min(px - Math.round(cx), frameWidth - size));
   const top = Math.max(0, Math.min(py - Math.round(cy), frameHeight - size));
-  return sharp2(frameBuffer).composite([{ input: Buffer.from(highlightSvg), left, top }]).png().toBuffer();
+  return { input: Buffer.from(highlightSvg), left, top };
 }
-async function renderCursorTrail(frameBuffer, positions, config, frameWidth, frameHeight, dpr = 1) {
-  if (!config.enabled || !config.trail || positions.length < 2) {
-    return frameBuffer;
-  }
+function buildTrailOverlay(positions, config, frameWidth, frameHeight, dpr = 1) {
+  if (!config.enabled || !config.trail || positions.length < 2) return null;
   const segments = [];
   for (let i = 1; i < positions.length; i++) {
     const opacity = i / positions.length * 0.6;
@@ -1573,7 +1677,26 @@ async function renderCursorTrail(frameBuffer, positions, config, frameWidth, fra
   const trailSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${frameWidth}" height="${frameHeight}" shape-rendering="geometricPrecision">
     ${segments.join("\n    ")}
   </svg>`;
-  return sharp2(frameBuffer).composite([{ input: Buffer.from(trailSvg), left: 0, top: 0 }]).png().toBuffer();
+  return { input: Buffer.from(trailSvg), left: 0, top: 0 };
+}
+function buildCursorSvg(size, color) {
+  const s = size;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${s}" height="${s}" viewBox="0 0 24 24" shape-rendering="geometricPrecision">
+    <path d="M4 0 L4 22 L10 16 L16 24 L20 22 L14 14 L22 14 Z"
+          fill="${color}" stroke="#ffffff" stroke-width="1.5" stroke-linejoin="round"/>
+  </svg>`;
+}
+function buildClickRippleSvg(radius, color, progress) {
+  const currentRadius = radius * progress;
+  const opacity = Math.max(0, 1 - progress);
+  const size = Math.ceil(radius * 2 + 4);
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" shape-rendering="geometricPrecision">
+    <circle cx="${size / 2}" cy="${size / 2}" r="${currentRadius}"
+            fill="none" stroke="${color}" stroke-width="2"
+            opacity="${opacity.toFixed(3)}"/>
+    <circle cx="${size / 2}" cy="${size / 2}" r="${currentRadius * 0.6}"
+            fill="${color}" opacity="${(opacity * 0.4).toFixed(3)}"/>
+  </svg>`;
 }
 
 // src/effects/zoom.ts
@@ -1640,6 +1763,51 @@ function calculateAdaptiveZoomInWindow(windowFrames, windowStart, currentIndex,
 function easeInOutCubic2(t) {
   return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
 }
+function springEasing(t) {
+  const omega = 6.5;
+  const raw = 1 - (1 + omega * t) * Math.exp(-omega * t);
+  const endVal = 1 - (1 + omega) * Math.exp(-omega);
+  return Math.max(0, Math.min(1, raw / endVal));
+}
+function applyZoomEasing(t, easing = "cubic") {
+  return easing === "spring" ? springEasing(t) : easeInOutCubic2(t);
+}
+function mergeClickZones(clickLookup, mergeGap) {
+  if (clickLookup.length === 0) return [];
+  const zones = [];
+  let start = clickLookup[0];
+  let end = clickLookup[0];
+  for (let i = 1; i < clickLookup.length; i++) {
+    if (clickLookup[i] - end <= mergeGap) {
+      end = clickLookup[i];
+    } else {
+      zones.push({ start, end });
+      start = clickLookup[i];
+      end = clickLookup[i];
+    }
+  }
+  zones.push({ start, end });
+  return zones;
+}
+function calculateAdaptiveZoomFromZones(zones, currentIndex, maxScale, transitionFrames, easing = "spring") {
+  if (maxScale <= 1 || zones.length === 0) return 1;
+  let lo = 0;
+  let hi = zones.length;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (zones[mid].end < currentIndex) lo = mid + 1;
+    else hi = mid;
+  }
+  if (lo < zones.length && currentIndex >= zones[lo].start && currentIndex <= zones[lo].end) {
+    return maxScale;
+  }
+  const distBefore = lo > 0 ? currentIndex - zones[lo - 1].end : Infinity;
+  const distAfter = lo < zones.length ? zones[lo].start - currentIndex : Infinity;
+  const minDistance = Math.min(distBefore, distAfter);
+  if (minDistance > transitionFrames) return 1;
+  const t = 1 - minDistance / transitionFrames;
+  return 1 + (maxScale - 1) * applyZoomEasing(t, easing);
+}
 
 // src/effects/background.ts
 import sharp4 from "sharp";
@@ -1886,73 +2054,87 @@ async function composeFrame(frame, effects, output, context) {
     cursorTrail: context?.cursorTrail ?? []
   };
   const frameOffset = getFrameOffset(effects.deviceFrame, dpr);
-  const withFrameOffset = (pos) => ({
+  const sl = context?.staticLayers;
+  const preZoomOverlays = [];
+  const hasBrowserChrome = effects.deviceFrame.enabled && effects.deviceFrame.type === "browser" && sl?.browserChromePng;
+  const extTop = hasBrowserChrome ? sl.browserChromeHeight : 0;
+  const extWidth = width;
+  const extHeight = height + extTop;
+  if (hasBrowserChrome) {
+    preZoomOverlays.push({ input: sl.browserChromePng, left: 0, top: 0 });
+  }
+  const withExtFrameOffset = (pos) => ({
     x: pos.x + frameOffset.left / Math.max(1, dpr),
     y: pos.y + frameOffset.top / Math.max(1, dpr)
   });
-  if (effects.deviceFrame.enabled) {
-    const sl2 = ctx.staticLayers;
-    if (sl2?.browserChromePng && effects.deviceFrame.type === "browser") {
-      buffer = await sharp7(buffer).extend({
-        top: sl2.browserChromeHeight,
-        bottom: 0,
-        left: 0,
-        right: 0,
-        background: { r: 0, g: 0, b: 0, alpha: 0 }
-      }).composite([{ input: sl2.browserChromePng, left: 0, top: 0 }]).png().toBuffer();
-    } else {
-      buffer = await applyDeviceFrame(buffer, effects.deviceFrame, width, height, dpr);
-    }
-    const meta2 = await sharp7(buffer).metadata();
-    width = meta2.width ?? width;
-    height = meta2.height ?? height;
-  }
   if (effects.cursor.enabled && effects.cursor.highlight && frame.cursorPosition) {
-    buffer = await renderCursorHighlight(
-      buffer,
-      withFrameOffset(frame.cursorPosition),
+    const overlay = buildHighlightOverlay(
+      withExtFrameOffset(frame.cursorPosition),
       effects.cursor,
-      width,
-      height,
+      extWidth,
+      extHeight,
       dpr
     );
+    if (overlay) preZoomOverlays.push(overlay);
   }
   if (effects.cursor.enabled && effects.cursor.trail && ctx.cursorTrail.length >= 2) {
-    buffer = await renderCursorTrail(
-      buffer,
-      ctx.cursorTrail.map(withFrameOffset),
+    const overlay = buildTrailOverlay(
+      ctx.cursorTrail.map(withExtFrameOffset),
       effects.cursor,
-      width,
-      height,
+      extWidth,
+      extHeight,
       dpr
     );
+    if (overlay) preZoomOverlays.push(overlay);
   }
   if (effects.cursor.enabled && frame.cursorPosition) {
-    buffer = await renderCursor(
-      buffer,
-      withFrameOffset(frame.cursorPosition),
+    const overlay = buildCursorOverlay(
+      withExtFrameOffset(frame.cursorPosition),
       effects.cursor,
-      width,
-      height,
+      extWidth,
+      extHeight,
       dpr
     );
+    if (overlay) preZoomOverlays.push(overlay);
   }
   if (effects.cursor.enabled && effects.cursor.clickEffect && frame.clickPosition) {
     const progress = ctx.clickProgress ?? frame.clickProgress ?? 0.5;
-    buffer = await renderClickEffect(
-      buffer,
-      withFrameOffset(frame.clickPosition),
+    const overlay = buildClickRippleOverlay(
+      withExtFrameOffset(frame.clickPosition),
       effects.cursor,
       progress,
-      width,
-      height,
+      extWidth,
+      extHeight,
       dpr
     );
+    if (overlay) preZoomOverlays.push(overlay);
+  }
+  if (hasBrowserChrome || preZoomOverlays.length > 0) {
+    let pipeline = sharp7(buffer);
+    if (hasBrowserChrome) {
+      pipeline = pipeline.extend({
+        top: extTop,
+        bottom: 0,
+        left: 0,
+        right: 0,
+        background: { r: 0, g: 0, b: 0, alpha: 0 }
+      });
+    }
+    if (preZoomOverlays.length > 0) {
+      pipeline = pipeline.composite(preZoomOverlays);
+    }
+    buffer = await pipeline.png().toBuffer();
+    width = extWidth;
+    height = extHeight;
+  } else if (effects.deviceFrame.enabled) {
+    buffer = await applyDeviceFrame(buffer, effects.deviceFrame, width, height, dpr);
+    const devMeta = await sharp7(buffer).metadata();
+    width = devMeta.width ?? width;
+    height = devMeta.height ?? height;
   }
   const scale = ctx.zoomScale;
   if (effects.zoom.enabled && scale > 1) {
-    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 rawFocus = ctx.focusOverride ?? (effects.zoom.autoZoom.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,
@@ -1971,7 +2153,6 @@ async function composeFrame(frame, effects, output, context) {
       dpr
     );
   }
-  const sl = ctx.staticLayers;
   if (sl) {
     const padding = effects.background.padding;
     const contentWidth = output.width - padding * 2;
@@ -2180,6 +2361,7 @@ function mergeStepEffects(global, stepIndex, steps) {
     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,
+    smartSpeed: override.smartSpeed ? { ...global.smartSpeed, ...override.smartSpeed } : global.smartSpeed,
     keystroke: override.keystroke ? { ...global.keystroke, ...override.keystroke } : global.keystroke,
     watermark: override.watermark ? { ...global.watermark, ...override.watermark } : global.watermark
   };
@@ -2233,7 +2415,10 @@ var CanvasRenderer = class {
     if (frames.length === 0) return [];
     let processFrames = frames;
     if (this.effects.speedRamp.enabled) {
-      processFrames = this.applySpeedRamp(frames);
+      processFrames = this.applySpeedRamp(processFrames);
+    }
+    if (this.effects.smartSpeed.enabled) {
+      processFrames = this.applySmartSpeed(processFrames);
     }
     const contexts = this.calculateFrameContexts(processFrames);
     const cpuCount = os.cpus().length;
@@ -2329,11 +2514,27 @@ var CanvasRenderer = class {
       this.effects.zoom.scale,
       this.effects.zoom.intensity
     );
+    const mergeGap = Math.round(transitionFrames * 1.5);
+    const zoomZones = this.effects.zoom.enabled ? mergeClickZones(clickLookup, mergeGap) : [];
+    const zoomEasing = this.effects.zoom.easing === "spring" ? "spring" : "cubic";
+    const clickPositions = /* @__PURE__ */ new Map();
+    if (this.effects.zoom.enabled) {
+      for (const ci of clickLookup) {
+        const pos = frames[ci].clickPosition;
+        if (pos) clickPositions.set(ci, pos);
+      }
+    }
     for (let i = 0; i < frames.length; i++) {
       const frame = frames[i];
       let zoomScale = 1;
       if (this.effects.zoom.enabled) {
-        zoomScale = calculateAdaptiveZoomFromLookup(
+        zoomScale = zoomZones.length > 0 ? calculateAdaptiveZoomFromZones(
+          zoomZones,
+          i,
+          effectiveScale,
+          transitionFrames,
+          zoomEasing
+        ) : calculateAdaptiveZoomFromLookup(
           clickLookup,
           i,
           effectiveScale,
@@ -2351,10 +2552,56 @@ var CanvasRenderer = class {
           trail.push(frames[j].cursorPosition);
         }
       }
-      contexts.push({ zoomScale, clickProgress, cursorTrail: trail });
+      let focusOverride;
+      if (zoomScale > 1 && zoomZones.length > 0 && clickLookup.length > 1) {
+        focusOverride = this.interpolateFocusInZone(
+          i,
+          clickLookup,
+          clickPositions,
+          frames
+        );
+      }
+      contexts.push({ zoomScale, clickProgress, cursorTrail: trail, focusOverride });
     }
     return contexts;
   }
+  /**
+   * Interpolate the zoom focus point between adjacent clicks within a zone.
+   *
+   * Without this, the camera jumps instantly from one click position to the
+   * next when a merged zone contains multiple clicks.  This method produces
+   * a smooth pan by linearly interpolating between the previous and next
+   * click positions relative to the current frame index.
+   *
+   * Falls back to the nearest click position when the frame is before the
+   * first click or after the last click in the lookup.
+   */
+  interpolateFocusInZone(frameIndex, clickLookup, clickPositions, frames) {
+    let lo = 0;
+    let hi = clickLookup.length;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      if (clickLookup[mid] < frameIndex) lo = mid + 1;
+      else hi = mid;
+    }
+    const prevIdx = lo > 0 ? clickLookup[lo - 1] : -1;
+    const nextIdx = lo < clickLookup.length ? clickLookup[lo] : -1;
+    const prevPos = prevIdx >= 0 ? clickPositions.get(prevIdx) : void 0;
+    const nextPos = nextIdx >= 0 ? clickPositions.get(nextIdx) : void 0;
+    if (nextIdx === frameIndex && nextPos) return nextPos;
+    if (prevPos && nextPos && prevIdx < frameIndex && nextIdx > frameIndex) {
+      const span = nextIdx - prevIdx;
+      if (span <= 0) return prevPos;
+      const t = (frameIndex - prevIdx) / span;
+      return {
+        x: prevPos.x + (nextPos.x - prevPos.x) * t,
+        y: prevPos.y + (nextPos.y - prevPos.y) * t
+      };
+    }
+    if (prevPos) return prevPos;
+    if (nextPos) return nextPos;
+    return void 0;
+  }
   /**
    * Apply speed ramping: slow down near actions, speed up during idle.
    */
@@ -2387,6 +2634,69 @@ var CanvasRenderer = class {
     }
     return result;
   }
+  /**
+   * Apply smart speed: compress smartWait periods based on per-frame metadata.
+   *
+   * Unlike applySpeedRamp (which uses click proximity heuristics), smartSpeed
+   * reads the `isWaitingPhase` flag set by the recorder during smartWait actions.
+   * Frames in a waiting phase are downsampled by their `displaySpeed` multiplier.
+   *
+   * Streaming-compatible: each frame is independently decidable (no lookahead
+   * needed), so this can run inline during streaming composition.
+   */
+  applySmartSpeed(frames) {
+    const config = this.effects.smartSpeed;
+    if (!config.enabled) return frames;
+    const transitionMargin = Math.round(
+      this.output.fps * (config.transitionDuration / 1e3)
+    );
+    const segments = [];
+    let segStart = -1;
+    let segSpeed = config.waitSpeed;
+    for (let i = 0; i < frames.length; i++) {
+      if (frames[i].isWaitingPhase) {
+        if (segStart < 0) {
+          segStart = i;
+          segSpeed = frames[i].displaySpeed ?? config.waitSpeed;
+        }
+      } else if (segStart >= 0) {
+        segments.push({ start: segStart, end: i - 1, speed: segSpeed });
+        segStart = -1;
+      }
+    }
+    if (segStart >= 0) segments.push({ start: segStart, end: frames.length - 1, speed: segSpeed });
+    const skipRates = new Array(frames.length).fill(1);
+    for (const seg of segments) {
+      const segLen = seg.end - seg.start + 1;
+      const skipRate = Math.max(1, Math.round(seg.speed));
+      for (let i = seg.start; i <= seg.end; i++) {
+        const fromStart = i - seg.start;
+        const fromEnd = seg.end - i;
+        if (fromStart < transitionMargin || fromEnd < transitionMargin) {
+          skipRates[i] = 1;
+        } else if (segLen < transitionMargin * 3) {
+          skipRates[i] = Math.max(1, Math.round(skipRate / 2));
+        } else {
+          skipRates[i] = skipRate;
+        }
+      }
+    }
+    const result = [];
+    let skipCounter = 0;
+    for (let i = 0; i < frames.length; i++) {
+      const rate = skipRates[i];
+      if (rate <= 1) {
+        skipCounter = 0;
+        result.push({ ...frames[i], index: result.length });
+      } else {
+        skipCounter++;
+        if (skipCounter % rate === 1) {
+          result.push({ ...frames[i], index: result.length });
+        }
+      }
+    }
+    return result;
+  }
   // ─── Online streaming pipeline (Phase 3-B) ─────────────────────────────────
   /**
    * Returns true when no effect requires the full frame array upfront.
@@ -2416,19 +2726,56 @@ var CanvasRenderer = class {
    * using the same applyTransitionsToStream() logic as composeStream().
    */
   async *composeStreamOnline(source) {
+    const filteredSource = this.effects.smartSpeed.enabled ? this.filterSmartSpeedInline(source) : source;
     const hasFadeTransitions = this.steps.some((s) => s.transition !== "none");
     if (!hasFadeTransitions) {
       const cpuCount = os.cpus().length;
       const workerCount = Math.min(cpuCount, 8);
-      yield* this.streamOnlineWithWorkers(source, workerCount);
+      yield* this.streamOnlineWithWorkers(filteredSource, workerCount);
       return;
     }
     const collected = [];
-    for await (const frame of source) {
+    for await (const frame of filteredSource) {
       collected.push(frame);
     }
     yield* this.composeStream(collected);
   }
+  /**
+   * Inline async filter for smartSpeed in streaming pipelines.
+   *
+   * Applies ease-in at the start of a waiting phase: the first
+   * `transitionMargin` frames are kept at normal speed so the loader
+   * is visible, then frames are skipped at displaySpeed rate.
+   * When waiting ends, frames immediately return to normal speed.
+   */
+  async *filterSmartSpeedInline(source) {
+    const config = this.effects.smartSpeed;
+    const transitionMargin = Math.round(
+      this.output.fps * (config.transitionDuration / 1e3)
+    );
+    let waitFrameCounter = 0;
+    let skipCounter = 0;
+    let outputIndex = 0;
+    for await (const frame of source) {
+      if (frame.isWaitingPhase) {
+        waitFrameCounter++;
+        if (waitFrameCounter <= transitionMargin) {
+          yield { ...frame, index: outputIndex++ };
+        } else {
+          const speed = frame.displaySpeed ?? config.waitSpeed;
+          const skipRate = Math.max(1, Math.round(speed));
+          skipCounter++;
+          if (skipCounter % skipRate === 1) {
+            yield { ...frame, index: outputIndex++ };
+          }
+        }
+      } else {
+        waitFrameCounter = 0;
+        skipCounter = 0;
+        yield { ...frame, index: outputIndex++ };
+      }
+    }
+  }
   /**
    * Worker-pool online streaming: dispatches frame i to a worker as soon as
    * frame i + transitionFrames has arrived from the source.
@@ -2573,7 +2920,10 @@ var CanvasRenderer = class {
     if (frames.length === 0) return;
     let processFrames = frames;
     if (this.effects.speedRamp.enabled) {
-      processFrames = this.applySpeedRamp(frames);
+      processFrames = this.applySpeedRamp(processFrames);
+    }
+    if (this.effects.smartSpeed.enabled) {
+      processFrames = this.applySmartSpeed(processFrames);
     }
     const contexts = this.calculateFrameContexts(processFrames);
     const windows = this.getTransitionWindows(processFrames);
@@ -2816,9 +3166,9 @@ import { tmpdir } from "os";
 import { spawn } from "child_process";
 var { GIFEncoder, quantize, applyPalette } = gifenc;
 var ENCODING_PRESETS = {
-  social: { crf: 22, vtQuality: 75 },
-  balanced: { crf: 18, vtQuality: 85 },
-  archive: { crf: 13, vtQuality: 92 }
+  social: { crf: 22, vtQuality: 75, x264Preset: "medium" },
+  balanced: { crf: 18, vtQuality: 85, x264Preset: "slow" },
+  archive: { crf: 13, vtQuality: 92, x264Preset: "veryslow" }
 };
 function resolveEncodingParams(config) {
   if (config.preset) return ENCODING_PRESETS[config.preset];
@@ -2830,24 +3180,42 @@ function resolveEncodingParams(config) {
   if (config.quality >= 45) return ENCODING_PRESETS.balanced;
   return ENCODING_PRESETS.archive;
 }
-var encoderDetectionPromise = null;
-function detectVideoEncoder() {
-  if (!encoderDetectionPromise) {
-    encoderDetectionPromise = new Promise((resolve2) => {
+var encoderScanPromise = null;
+function scanAvailableEncoders() {
+  if (!encoderScanPromise) {
+    encoderScanPromise = new Promise((resolve2) => {
       const proc = spawn("ffmpeg", ["-encoders"], {
         stdio: ["ignore", "pipe", "ignore"]
       });
       let out = "";
       proc.stdout.on("data", (d) => out += d.toString());
       proc.on("close", () => {
-        if (out.includes("hevc_videotoolbox")) resolve2("hevc_videotoolbox");
-        else if (out.includes("h264_videotoolbox")) resolve2("h264_videotoolbox");
-        else resolve2("libx264");
+        resolve2({
+          hevcHw: out.includes("hevc_videotoolbox"),
+          h264Hw: out.includes("h264_videotoolbox"),
+          av1: out.includes("libsvtav1")
+        });
       });
-      proc.on("error", () => resolve2("libx264"));
+      proc.on("error", () => resolve2({ hevcHw: false, h264Hw: false, av1: false }));
     });
   }
-  return encoderDetectionPromise;
+  return encoderScanPromise;
+}
+async function detectVideoEncoder(codec = "auto") {
+  const avail = await scanAvailableEncoders();
+  switch (codec) {
+    case "av1":
+      return avail.av1 ? "libsvtav1" : "libx264";
+    case "hevc":
+      return avail.hevcHw ? "hevc_videotoolbox" : "libx264";
+    case "h264":
+      return avail.h264Hw ? "h264_videotoolbox" : "libx264";
+    case "auto":
+    default:
+      if (avail.hevcHw) return "hevc_videotoolbox";
+      if (avail.h264Hw) return "h264_videotoolbox";
+      return "libx264";
+  }
 }
 async function encodeGif(frames, config) {
   if (frames.length === 0) {
@@ -2871,7 +3239,7 @@ async function encodeGif(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 encoder = await detectVideoEncoder(config.codec);
     const params = resolveEncodingParams(config);
     await pipeStreamToFfmpeg(frames, config, params, encoder, outputPath, audio);
     return await readFile2(outputPath);
@@ -2887,9 +3255,15 @@ async function pipeStreamToFfmpeg(frames, config, params, encoder, outputPath, a
     "-q:v",
     String(params.vtQuality),
     "-pix_fmt",
-    "yuv420p",
+    "p010le",
     "-tag:v",
-    "hvc1"
+    "hvc1",
+    "-color_primaries",
+    "bt709",
+    "-color_trc",
+    "bt709",
+    "-colorspace",
+    "bt709"
   ] : encoder === "h264_videotoolbox" ? [
     "-c:v",
     "h264_videotoolbox",
@@ -2903,9 +3277,9 @@ async function pipeStreamToFfmpeg(frames, config, params, encoder, outputPath, a
     "-crf",
     String(params.crf),
     "-preset",
-    "medium",
+    params.x264Preset,
     "-tune",
-    "stillimage",
+    "animation",
     "-profile:v",
     "high",
     "-level",