clipwise 0.6.0 → 0.7.0

package/dist/index.js

@@ -106,6 +106,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;
@@ -133,6 +139,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
@@ -145,6 +152,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;
@@ -168,13 +178,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) {
@@ -191,6 +203,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,
@@ -385,7 +414,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
     };
   }
   /**
@@ -504,6 +535,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);
@@ -515,7 +547,19 @@ var ClipwiseRecorder = class {
             sessionId: currentSessionId
           });
           await new Promise((resolve) => setTimeout(resolve, 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": {
@@ -610,6 +654,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((resolve) => {
+                  let timer;
+                  const observer = new MutationObserver(() => {
+                    clearTimeout(timer);
+                    timer = setTimeout(() => {
+                      observer.disconnect();
+                      resolve(true);
+                    }, 500);
+                  });
+                  observer.observe(document.body, { childList: true, subtree: true, attributes: true });
+                  timer = setTimeout(() => {
+                    observer.disconnect();
+                    resolve(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);
   }
@@ -729,7 +827,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
       };
     });
   }
@@ -1089,6 +1189,70 @@ async function applyDeviceFrame(frameBuffer, config, frameWidth, frameHeight, dp
 
 // src/effects/cursor.ts
 import sharp2 from "sharp";
+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 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 { input: Buffer.from(cursorSvg), left, top };
+}
+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 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 { input: Buffer.from(rippleSvg), left, top };
+}
+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;
+  const cy = size / 2;
+  const highlightSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" shape-rendering="geometricPrecision">
+    <defs>
+      <radialGradient id="glow">
+        <stop offset="0%" stop-color="${config.highlightColor}" />
+        <stop offset="70%" stop-color="${config.highlightColor}" />
+        <stop offset="100%" stop-color="transparent" />
+      </radialGradient>
+    </defs>
+    <circle cx="${cx}" cy="${cy}" r="${r}" fill="url(#glow)" />
+  </svg>`;
+  const px = Math.round(position.x * dpr);
+  const py = Math.round(position.y * dpr);
+  const left = Math.max(0, Math.min(px - Math.round(cx), frameWidth - size));
+  const top = Math.max(0, Math.min(py - Math.round(cy), frameHeight - size));
+  return { input: Buffer.from(highlightSvg), left, top };
+}
+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;
+    const strokeWidth = (1 + i / positions.length * 2) * dpr;
+    const p1 = positions[i - 1];
+    const p2 = positions[i];
+    segments.push(
+      `<line x1="${p1.x * dpr}" y1="${p1.y * dpr}" x2="${p2.x * dpr}" y2="${p2.y * dpr}"
+            stroke="${config.trailColor}" stroke-width="${strokeWidth.toFixed(1)}"
+            stroke-linecap="round" opacity="${opacity.toFixed(3)}"/>`
+    );
+  }
+  const trailSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${frameWidth}" height="${frameHeight}" shape-rendering="geometricPrecision">
+    ${segments.join("\n    ")}
+  </svg>`;
+  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">
@@ -1108,31 +1272,6 @@ function buildClickRippleSvg(radius, color, progress) {
             fill="${color}" opacity="${(opacity * 0.4).toFixed(3)}"/>
   </svg>`;
 }
-async function renderCursor(frameBuffer, position, config, frameWidth, frameHeight, dpr = 1) {
-  if (!config.enabled) return frameBuffer;
-  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();
-}
-async function renderClickEffect(frameBuffer, position, config, progress, frameWidth, frameHeight, dpr = 1) {
-  if (!config.enabled || !config.clickEffect) return frameBuffer;
-  const radius = config.clickRadius * dpr;
-  const clampedProgress = Math.max(0, Math.min(1, progress));
-  const rippleSvg = buildClickRippleSvg(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();
-}
 async function renderCursorHighlight(frameBuffer, position, config, frameWidth, frameHeight, dpr = 1) {
   if (!config.enabled || !config.highlight) return frameBuffer;
   const r = config.highlightRadius * dpr;
@@ -1269,6 +1408,51 @@ function lerpZoom(current, target, factor) {
 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";
@@ -1515,73 +1699,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,
@@ -1600,7 +1798,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;
@@ -1809,6 +2006,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
   };
@@ -1862,7 +2060,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;
@@ -1958,11 +2159,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,
@@ -1980,10 +2197,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.
    */
@@ -2016,6 +2279,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.
@@ -2045,19 +2371,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.
@@ -2202,7 +2565,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);
@@ -2445,9 +2811,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];
@@ -2459,24 +2825,106 @@ 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((resolve) => {
+var encoderScanPromise = null;
+function scanAvailableEncoders() {
+  if (!encoderScanPromise) {
+    encoderScanPromise = new Promise((resolve) => {
       const proc = spawn("ffmpeg", ["-encoders"], {
         stdio: ["ignore", "pipe", "ignore"]
       });
       let out = "";
       proc.stdout.on("data", (d) => out += d.toString());
       proc.on("close", () => {
-        if (out.includes("hevc_videotoolbox")) resolve("hevc_videotoolbox");
-        else if (out.includes("h264_videotoolbox")) resolve("h264_videotoolbox");
-        else resolve("libx264");
+        resolve({
+          hevcHw: out.includes("hevc_videotoolbox"),
+          h264Hw: out.includes("h264_videotoolbox"),
+          av1: out.includes("libsvtav1")
+        });
       });
-      proc.on("error", () => resolve("libx264"));
+      proc.on("error", () => resolve({ 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";
+  }
+}
+function buildVideoArgs(encoder, params) {
+  switch (encoder) {
+    case "hevc_videotoolbox":
+      return [
+        "-c:v",
+        "hevc_videotoolbox",
+        "-q:v",
+        String(params.vtQuality),
+        "-pix_fmt",
+        "p010le",
+        "-tag:v",
+        "hvc1",
+        "-color_primaries",
+        "bt709",
+        "-color_trc",
+        "bt709",
+        "-colorspace",
+        "bt709"
+      ];
+    case "h264_videotoolbox":
+      return [
+        "-c:v",
+        "h264_videotoolbox",
+        "-q:v",
+        String(params.vtQuality),
+        "-pix_fmt",
+        "yuv420p"
+      ];
+    case "libsvtav1":
+      return [
+        "-c:v",
+        "libsvtav1",
+        "-crf",
+        String(params.crf + 12),
+        // AV1 CRF scale differs: +12 ≈ equivalent quality
+        "-preset",
+        "6",
+        // 6 = good speed/quality balance
+        "-svtav1-params",
+        "scm=2",
+        // Screen Content Mode: optimized for UI/text
+        "-pix_fmt",
+        "yuv420p10le"
+      ];
+    case "libx264":
+    default:
+      return [
+        "-c:v",
+        "libx264",
+        "-crf",
+        String(params.crf),
+        "-preset",
+        params.x264Preset,
+        "-tune",
+        "animation",
+        "-profile:v",
+        "high",
+        "-level",
+        "4.1",
+        "-pix_fmt",
+        "yuv420p"
+      ];
+  }
 }
 async function encodeGif(frames, config) {
   if (frames.length === 0) {
@@ -2503,7 +2951,7 @@ async function encodeMp4(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 pipeFramesToFfmpeg(frames, config, params, encoder, outputPath, audio);
     return await readFile(outputPath);
@@ -2513,39 +2961,7 @@ async function encodeMp4(frames, config, audio) {
   }
 }
 async function pipeFramesToFfmpeg(frames, config, params, encoder, outputPath, audio) {
-  const videoArgs = encoder === "hevc_videotoolbox" ? [
-    "-c:v",
-    "hevc_videotoolbox",
-    "-q:v",
-    String(params.vtQuality),
-    "-pix_fmt",
-    "yuv420p",
-    "-tag:v",
-    "hvc1"
-    // required for playback in QuickTime / Apple devices
-  ] : encoder === "h264_videotoolbox" ? [
-    "-c:v",
-    "h264_videotoolbox",
-    "-q:v",
-    String(params.vtQuality),
-    "-pix_fmt",
-    "yuv420p"
-  ] : [
-    "-c:v",
-    "libx264",
-    "-crf",
-    String(params.crf),
-    "-preset",
-    "medium",
-    "-tune",
-    "stillimage",
-    "-profile:v",
-    "high",
-    "-level",
-    "4.1",
-    "-pix_fmt",
-    "yuv420p"
-  ];
+  const videoArgs = buildVideoArgs(encoder, params);
   const audioInputArgs = audio ? ["-i", audio.file] : ["-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo"];
   const audioFilters = [];
   if (audio) {
@@ -2625,7 +3041,7 @@ async function pipeFramesToFfmpeg(frames, config, params, encoder, outputPath, a
 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 readFile(outputPath);
@@ -2641,9 +3057,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",
@@ -2657,9 +3079,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",
@@ -2910,6 +3332,17 @@ var WaitForResponseActionSchema = z.object({
   status: z.number().min(100).max(599).optional(),
   timeout: z.number().min(0).default(3e4)
 });
+var 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)
+});
 var StepActionSchema = z.discriminatedUnion("action", [
   NavigateActionSchema,
   ClickActionSchema,
@@ -2922,7 +3355,8 @@ var StepActionSchema = z.discriminatedUnion("action", [
   WaitForNavigationActionSchema,
   WaitForURLActionSchema,
   WaitForFunctionActionSchema,
-  WaitForResponseActionSchema
+  WaitForResponseActionSchema,
+  SmartWaitActionSchema
 ]);
 var ZoomIntensitySchema = z.enum([
   "subtle",
@@ -2952,7 +3386,7 @@ var ZoomEffectSchema = z.object({
    */
   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({})
 });
 var CursorEffectSchema = z.object({
@@ -2989,6 +3423,17 @@ var SpeedRampConfigSchema = z.object({
   actionSpeed: z.number().min(0.25).max(2).default(0.8),
   transitionFrames: z.number().default(15)
 });
+var 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)
+});
 var KeystrokeConfigSchema = z.object({
   enabled: z.boolean().default(false),
   /**
@@ -3023,6 +3468,7 @@ var EffectsConfigSchema = z.object({
   background: BackgroundSchema.default({}),
   deviceFrame: DeviceFrameSchema.default({}),
   speedRamp: SpeedRampConfigSchema.default({}),
+  smartSpeed: SmartSpeedConfigSchema.default({}),
   keystroke: KeystrokeConfigSchema.default({}),
   watermark: WatermarkConfigSchema.default({})
 });
@@ -3038,6 +3484,8 @@ var OutputConfigSchema = z.object({
   // 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")
 });
@@ -3047,6 +3495,7 @@ var StepEffectsOverrideSchema = z.object({
   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();
@@ -3208,9 +3657,11 @@ export {
   applyCrossfade,
   applySlide,
   applyTransition,
+  applyZoomEasing,
   buildZoomClickLookup,
   calculateAdaptiveZoom,
   calculateAdaptiveZoomFromLookup,
+  calculateAdaptiveZoomFromZones,
   calculateAdaptiveZoomInWindow,
   calculatePanOffset,
   encodeGif,
@@ -3218,6 +3669,7 @@ export {
   encodeMp4Stream,
   lerpZoom,
   loadScenario,
+  mergeClickZones,
   parseScenario,
   renderCursorHighlight,
   renderCursorTrail,
@@ -3225,5 +3677,6 @@ export {
   renderWatermark,
   resolveZoomScale,
   savePngSequence,
+  springEasing,
   validateScenario
 };