clipwise 0.4.1 → 0.5.0

package/dist/compose/frame-worker.js

@@ -264,8 +264,11 @@ async function renderCursor(frameBuffer, position, config, frameWidth, frameHeig
   const size = Math.round(config.size * dpr);
   const cursorSvg = buildCursorSvg(size, config.color);
   const cursorBuffer = Buffer.from(cursorSvg);
-  const left = Math.max(0, Math.min(Math.round(position.x * dpr), frameWidth - 1));
-  const top = Math.max(0, Math.min(Math.round(position.y * dpr), frameHeight - 1));
+  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) {
@@ -458,30 +461,55 @@ async function applyBackground(frameBuffer, config, outputWidth, outputHeight) {
 
 // src/effects/keystroke.ts
 import sharp5 from "sharp";
+function escapeXml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function buildSessions(keystrokes) {
+  const hasSessionIds = keystrokes.some((k) => k.sessionId !== void 0);
+  if (!hasSessionIds) {
+    const text = keystrokes.map((k) => k.key).join("");
+    return text.length > 0 ? [text] : [];
+  }
+  const map = /* @__PURE__ */ new Map();
+  for (const k of keystrokes) {
+    const sid = k.sessionId ?? 0;
+    map.set(sid, (map.get(sid) ?? "") + k.key);
+  }
+  return Array.from(map.entries()).sort(([a], [b]) => a - b).map(([, text]) => text).filter((t) => t.length > 0);
+}
 async function renderKeystrokeHud(frameBuffer, keystrokes, frameTimestamp, config, frameWidth, frameHeight, dpr = 1) {
   if (!config.enabled || keystrokes.length === 0) return frameBuffer;
-  const recentKeys = keystrokes.filter(
-    (k) => frameTimestamp - k.timestamp < config.fadeAfter
-  );
-  if (recentKeys.length === 0) return frameBuffer;
-  const displayText = recentKeys.map((k) => k.key).join("");
-  if (displayText.length === 0) return frameBuffer;
+  if (!config.showTyping) return frameBuffer;
+  const lastKeystroke = keystrokes[keystrokes.length - 1];
+  const age = frameTimestamp - lastKeystroke.timestamp;
+  if (age >= config.fadeAfter) return frameBuffer;
+  const fadeStart = config.fadeAfter * 0.6;
+  const globalOpacity = age > fadeStart ? Math.max(0, 1 - (age - fadeStart) / (config.fadeAfter - fadeStart)) : 1;
+  if (globalOpacity <= 0) return frameBuffer;
+  const allSessions = buildSessions(keystrokes);
+  if (allSessions.length === 0) return frameBuffer;
+  const sessions = allSessions.slice(-3);
+  const lineCount = sessions.length;
   const fontSize = config.fontSize * dpr;
   const padding = config.padding * dpr;
-  const charWidth = fontSize * 0.62;
-  const textWidth = Math.ceil(displayText.length * charWidth);
   const hudPadH = padding * 2;
-  const hudPadV = padding * 1.5;
-  const hudWidth = Math.min(textWidth + hudPadH * 2, frameWidth - 40 * dpr);
-  const hudHeight = Math.ceil(fontSize + hudPadV * 2);
-  const newest = recentKeys[recentKeys.length - 1];
-  const age = frameTimestamp - newest.timestamp;
-  const fadeStart = config.fadeAfter * 0.6;
-  const opacity = age > fadeStart ? Math.max(0, 1 - (age - fadeStart) / (config.fadeAfter - fadeStart)) : 1;
-  if (opacity <= 0) return frameBuffer;
+  const hudPadV = padding * 1.4;
+  const lineGap = Math.round(fontSize * 0.45);
+  const charWidth = fontSize * 0.615;
+  const maxHudWidth = frameWidth - 60 * dpr;
+  const maxCharsPerLine = Math.max(10, Math.floor((maxHudWidth - hudPadH * 2) / charWidth));
+  const lines = sessions.map(
+    (text) => text.length > maxCharsPerLine ? text.slice(-maxCharsPerLine) : text
+  );
+  const maxLineLen = Math.max(...lines.map((l) => l.length));
+  const hudWidth = Math.min(
+    Math.ceil(maxLineLen * charWidth) + hudPadH * 2,
+    maxHudWidth
+  );
+  const hudHeight = Math.ceil(fontSize * lineCount + lineGap * (lineCount - 1) + hudPadV * 2);
   const margin = 30 * dpr;
-  let hudX;
   const hudY = frameHeight - hudHeight - margin;
+  let hudX;
   switch (config.position) {
     case "bottom-left":
       hudX = margin;
@@ -492,17 +520,24 @@ async function renderKeystrokeHud(frameBuffer, keystrokes, frameTimestamp, confi
     case "bottom-center":
     default:
       hudX = Math.round((frameWidth - hudWidth) / 2);
-      break;
   }
-  const maxChars = Math.floor((hudWidth - hudPadH * 2) / charWidth);
-  const truncated = displayText.length > maxChars ? displayText.slice(-maxChars) : displayText;
-  const escaped = truncated.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  const LINE_OPACITY_FACTORS = [0.45, 0.7, 1];
+  const opacityFactors = LINE_OPACITY_FACTORS.slice(-lineCount);
+  const rx = (8 * dpr).toFixed(1);
+  const boxOp = (globalOpacity * 0.92).toFixed(3);
+  const textX = hudX + hudPadH;
+  const baselineY = hudY + hudPadV + fontSize * 0.82;
+  const textElements = lines.map((line, i) => {
+    const op = (globalOpacity * opacityFactors[i]).toFixed(3);
+    const lineY = baselineY + i * (fontSize + lineGap);
+    return `<text x="${textX}" y="${lineY}"
+          font-family="monospace, Menlo, Consolas" font-size="${fontSize}"
+          fill="${config.textColor}" opacity="${op}">${escapeXml(line)}</text>`;
+  }).join("\n    ");
   const hudSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${frameWidth}" height="${frameHeight}" shape-rendering="geometricPrecision" text-rendering="geometricPrecision">
     <rect x="${hudX}" y="${hudY}" width="${hudWidth}" height="${hudHeight}"
-          rx="${8 * dpr}" ry="${8 * dpr}" fill="${config.backgroundColor}" opacity="${opacity.toFixed(3)}" />
-    <text x="${hudX + hudPadH}" y="${hudY + hudPadV + fontSize * 0.75}"
-          font-family="monospace, Menlo, Consolas" font-size="${fontSize}"
-          fill="${config.textColor}" opacity="${opacity.toFixed(3)}">${escaped}</text>
+          rx="${rx}" ry="${rx}" fill="${config.backgroundColor}" opacity="${boxOp}" />
+    ${textElements}
   </svg>`;
   return sharp5(frameBuffer).composite([{ input: Buffer.from(hudSvg), left: 0, top: 0 }]).png().toBuffer();
 }
@@ -603,6 +638,11 @@ async function composeFrame(frame, effects, output, context) {
     clickProgress: context?.clickProgress ?? null,
     cursorTrail: context?.cursorTrail ?? []
   };
+  const frameOffset = getFrameOffset(effects.deviceFrame, dpr);
+  const withFrameOffset = (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") {
@@ -623,7 +663,7 @@ async function composeFrame(frame, effects, output, context) {
   if (effects.cursor.enabled && effects.cursor.highlight && frame.cursorPosition) {
     buffer = await renderCursorHighlight(
       buffer,
-      frame.cursorPosition,
+      withFrameOffset(frame.cursorPosition),
       effects.cursor,
       width,
       height,
@@ -633,7 +673,7 @@ async function composeFrame(frame, effects, output, context) {
   if (effects.cursor.enabled && effects.cursor.trail && ctx.cursorTrail.length >= 2) {
     buffer = await renderCursorTrail(
       buffer,
-      ctx.cursorTrail,
+      ctx.cursorTrail.map(withFrameOffset),
       effects.cursor,
       width,
       height,
@@ -643,7 +683,7 @@ async function composeFrame(frame, effects, output, context) {
   if (effects.cursor.enabled && frame.cursorPosition) {
     buffer = await renderCursor(
       buffer,
-      frame.cursorPosition,
+      withFrameOffset(frame.cursorPosition),
       effects.cursor,
       width,
       height,
@@ -654,7 +694,7 @@ async function composeFrame(frame, effects, output, context) {
     const progress = ctx.clickProgress ?? frame.clickProgress ?? 0.5;
     buffer = await renderClickEffect(
       buffer,
-      frame.clickPosition,
+      withFrameOffset(frame.clickPosition),
       effects.cursor,
       progress,
       width,
@@ -662,6 +702,16 @@ async function composeFrame(frame, effects, output, context) {
       dpr
     );
   }
+  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 offset = getFrameOffset(effects.deviceFrame, dpr);
+    const focusPoint = {
+      x: rawFocus.x * dpr + offset.left,
+      y: rawFocus.y * dpr + offset.top
+    };
+    buffer = await applyZoom(buffer, focusPoint, scale, width, height);
+  }
   if (effects.keystroke.enabled && frame.keystrokes) {
     buffer = await renderKeystrokeHud(
       buffer,
@@ -673,16 +723,6 @@ async function composeFrame(frame, effects, output, context) {
       dpr
     );
   }
-  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 offset = getFrameOffset(effects.deviceFrame, dpr);
-    const focusPoint = {
-      x: rawFocus.x * dpr + offset.left,
-      y: rawFocus.y * dpr + offset.top
-    };
-    buffer = await applyZoom(buffer, focusPoint, scale, width, height);
-  }
   const sl = ctx.staticLayers;
   if (sl) {
     const padding = effects.background.padding;

package/dist/index.d.ts

@@ -174,11 +174,21 @@ type StepAction = z.infer<typeof StepActionSchema>;
 declare const EffectsConfigSchema: z.ZodObject<{
     zoom: z.ZodDefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * Numeric zoom scale (1.0 = no zoom).  Overridden by `intensity` when set.
+         * Default lowered from 1.8 → 1.35 to match "moderate" intensity.
+         */
         scale: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Intensity preset — overrides `scale` when set.
+         * Calibrated against Loom (light≈1.25x) and Camtasia (moderate≈1.35x).
+         */
+        intensity: z.ZodOptional<z.ZodEnum<["subtle", "light", "moderate", "strong", "dramatic"]>>;
         duration: z.ZodDefault<z.ZodNumber>;
         easing: z.ZodDefault<z.ZodEnum<["ease-in-out", "ease-in", "ease-out", "linear"]>>;
         autoZoom: z.ZodDefault<z.ZodObject<{
             followCursor: z.ZodDefault<z.ZodBoolean>;
+            /** @deprecated Use `intensity` on the parent zoom config instead. */
             maxScale: z.ZodDefault<z.ZodNumber>;
             transitionDuration: z.ZodDefault<z.ZodNumber>;
             padding: z.ZodDefault<z.ZodNumber>;
@@ -204,10 +214,12 @@ declare const EffectsConfigSchema: z.ZodObject<{
             transitionDuration: number;
             padding: number;
         };
+        intensity?: "subtle" | "light" | "moderate" | "strong" | "dramatic" | undefined;
     }, {
         duration?: number | undefined;
         enabled?: boolean | undefined;
         scale?: number | undefined;
+        intensity?: "subtle" | "light" | "moderate" | "strong" | "dramatic" | undefined;
         easing?: "ease-in-out" | "ease-in" | "ease-out" | "linear" | undefined;
         autoZoom?: {
             followCursor?: boolean | undefined;
@@ -312,6 +324,17 @@ declare const EffectsConfigSchema: z.ZodObject<{
     }>>;
     keystroke: z.ZodDefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * Show regular typed text (alphabetic/numeric characters) in the HUD.
+         *
+         * Industry default is false — Screen Studio, KeyCastr, and ScreenFlow all
+         * hide regular typing by default, showing only modifier+key shortcuts.
+         * Typed content is already visible inside the focused input element, so
+         * displaying it again in the HUD is redundant and creates overflow issues.
+         *
+         * Set to true to display a 2-line rolling HUD that follows the typed text.
+         */
+        showTyping: z.ZodDefault<z.ZodBoolean>;
         position: z.ZodDefault<z.ZodEnum<["bottom-center", "bottom-left", "bottom-right"]>>;
         fontSize: z.ZodDefault<z.ZodNumber>;
         backgroundColor: z.ZodDefault<z.ZodString>;
@@ -321,6 +344,7 @@ declare const EffectsConfigSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         padding: number;
         enabled: boolean;
+        showTyping: boolean;
         position: "bottom-center" | "bottom-left" | "bottom-right";
         fontSize: number;
         backgroundColor: string;
@@ -329,6 +353,7 @@ declare const EffectsConfigSchema: z.ZodObject<{
     }, {
         padding?: number | undefined;
         enabled?: boolean | undefined;
+        showTyping?: boolean | undefined;
         position?: "bottom-center" | "bottom-left" | "bottom-right" | undefined;
         fontSize?: number | undefined;
         backgroundColor?: string | undefined;
@@ -369,6 +394,7 @@ declare const EffectsConfigSchema: z.ZodObject<{
             transitionDuration: number;
             padding: number;
         };
+        intensity?: "subtle" | "light" | "moderate" | "strong" | "dramatic" | undefined;
     };
     cursor: {
         enabled: boolean;
@@ -407,6 +433,7 @@ declare const EffectsConfigSchema: z.ZodObject<{
     keystroke: {
         padding: number;
         enabled: boolean;
+        showTyping: boolean;
         position: "bottom-center" | "bottom-left" | "bottom-right";
         fontSize: number;
         backgroundColor: string;
@@ -426,6 +453,7 @@ declare const EffectsConfigSchema: z.ZodObject<{
         duration?: number | undefined;
         enabled?: boolean | undefined;
         scale?: number | undefined;
+        intensity?: "subtle" | "light" | "moderate" | "strong" | "dramatic" | undefined;
         easing?: "ease-in-out" | "ease-in" | "ease-out" | "linear" | undefined;
         autoZoom?: {
             followCursor?: boolean | undefined;
@@ -471,6 +499,7 @@ declare const EffectsConfigSchema: z.ZodObject<{
     keystroke?: {
         padding?: number | undefined;
         enabled?: boolean | undefined;
+        showTyping?: boolean | undefined;
         position?: "bottom-center" | "bottom-left" | "bottom-right" | undefined;
         fontSize?: number | undefined;
         backgroundColor?: string | undefined;
@@ -832,11 +861,21 @@ declare const ScenarioSchema: z.ZodObject<{
     effects: z.ZodDefault<z.ZodObject<{
         zoom: z.ZodDefault<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
+            /**
+             * Numeric zoom scale (1.0 = no zoom).  Overridden by `intensity` when set.
+             * Default lowered from 1.8 → 1.35 to match "moderate" intensity.
+             */
             scale: z.ZodDefault<z.ZodNumber>;
+            /**
+             * Intensity preset — overrides `scale` when set.
+             * Calibrated against Loom (light≈1.25x) and Camtasia (moderate≈1.35x).
+             */
+            intensity: z.ZodOptional<z.ZodEnum<["subtle", "light", "moderate", "strong", "dramatic"]>>;
             duration: z.ZodDefault<z.ZodNumber>;
             easing: z.ZodDefault<z.ZodEnum<["ease-in-out", "ease-in", "ease-out", "linear"]>>;
             autoZoom: z.ZodDefault<z.ZodObject<{
                 followCursor: z.ZodDefault<z.ZodBoolean>;
+                /** @deprecated Use `intensity` on the parent zoom config instead. */
                 maxScale: z.ZodDefault<z.ZodNumber>;
                 transitionDuration: z.ZodDefault<z.ZodNumber>;
                 padding: z.ZodDefault<z.ZodNumber>;
@@ -862,10 +901,12 @@ declare const ScenarioSchema: z.ZodObject<{
                 transitionDuration: number;
                 padding: number;
             };
+            intensity?: "subtle" | "light" | "moderate" | "strong" | "dramatic" | undefined;
         }, {
             duration?: number | undefined;
             enabled?: boolean | undefined;
             scale?: number | undefined;
+            intensity?: "subtle" | "light" | "moderate" | "strong" | "dramatic" | undefined;
             easing?: "ease-in-out" | "ease-in" | "ease-out" | "linear" | undefined;
             autoZoom?: {
                 followCursor?: boolean | undefined;
@@ -970,6 +1011,17 @@ declare const ScenarioSchema: z.ZodObject<{
         }>>;
         keystroke: z.ZodDefault<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
+            /**
+             * Show regular typed text (alphabetic/numeric characters) in the HUD.
+             *
+             * Industry default is false — Screen Studio, KeyCastr, and ScreenFlow all
+             * hide regular typing by default, showing only modifier+key shortcuts.
+             * Typed content is already visible inside the focused input element, so
+             * displaying it again in the HUD is redundant and creates overflow issues.
+             *
+             * Set to true to display a 2-line rolling HUD that follows the typed text.
+             */
+            showTyping: z.ZodDefault<z.ZodBoolean>;
             position: z.ZodDefault<z.ZodEnum<["bottom-center", "bottom-left", "bottom-right"]>>;
             fontSize: z.ZodDefault<z.ZodNumber>;
             backgroundColor: z.ZodDefault<z.ZodString>;
@@ -979,6 +1031,7 @@ declare const ScenarioSchema: z.ZodObject<{
         }, "strip", z.ZodTypeAny, {
             padding: number;
             enabled: boolean;
+            showTyping: boolean;
             position: "bottom-center" | "bottom-left" | "bottom-right";
             fontSize: number;
             backgroundColor: string;
@@ -987,6 +1040,7 @@ declare const ScenarioSchema: z.ZodObject<{
         }, {
             padding?: number | undefined;
             enabled?: boolean | undefined;
+            showTyping?: boolean | undefined;
             position?: "bottom-center" | "bottom-left" | "bottom-right" | undefined;
             fontSize?: number | undefined;
             backgroundColor?: string | undefined;
@@ -1027,6 +1081,7 @@ declare const ScenarioSchema: z.ZodObject<{
                 transitionDuration: number;
                 padding: number;
             };
+            intensity?: "subtle" | "light" | "moderate" | "strong" | "dramatic" | undefined;
         };
         cursor: {
             enabled: boolean;
@@ -1065,6 +1120,7 @@ declare const ScenarioSchema: z.ZodObject<{
         keystroke: {
             padding: number;
             enabled: boolean;
+            showTyping: boolean;
             position: "bottom-center" | "bottom-left" | "bottom-right";
             fontSize: number;
             backgroundColor: string;
@@ -1084,6 +1140,7 @@ declare const ScenarioSchema: z.ZodObject<{
             duration?: number | undefined;
             enabled?: boolean | undefined;
             scale?: number | undefined;
+            intensity?: "subtle" | "light" | "moderate" | "strong" | "dramatic" | undefined;
             easing?: "ease-in-out" | "ease-in" | "ease-out" | "linear" | undefined;
             autoZoom?: {
                 followCursor?: boolean | undefined;
@@ -1129,6 +1186,7 @@ declare const ScenarioSchema: z.ZodObject<{
         keystroke?: {
             padding?: number | undefined;
             enabled?: boolean | undefined;
+            showTyping?: boolean | undefined;
             position?: "bottom-center" | "bottom-left" | "bottom-right" | undefined;
             fontSize?: number | undefined;
             backgroundColor?: string | undefined;
@@ -1489,6 +1547,7 @@ declare const ScenarioSchema: z.ZodObject<{
                 transitionDuration: number;
                 padding: number;
             };
+            intensity?: "subtle" | "light" | "moderate" | "strong" | "dramatic" | undefined;
         };
         cursor: {
             enabled: boolean;
@@ -1527,6 +1586,7 @@ declare const ScenarioSchema: z.ZodObject<{
         keystroke: {
             padding: number;
             enabled: boolean;
+            showTyping: boolean;
             position: "bottom-center" | "bottom-left" | "bottom-right";
             fontSize: number;
             backgroundColor: string;
@@ -1691,6 +1751,7 @@ declare const ScenarioSchema: z.ZodObject<{
             duration?: number | undefined;
             enabled?: boolean | undefined;
             scale?: number | undefined;
+            intensity?: "subtle" | "light" | "moderate" | "strong" | "dramatic" | undefined;
             easing?: "ease-in-out" | "ease-in" | "ease-out" | "linear" | undefined;
             autoZoom?: {
                 followCursor?: boolean | undefined;
@@ -1736,6 +1797,7 @@ declare const ScenarioSchema: z.ZodObject<{
         keystroke?: {
             padding?: number | undefined;
             enabled?: boolean | undefined;
+            showTyping?: boolean | undefined;
             position?: "bottom-center" | "bottom-left" | "bottom-right" | undefined;
             fontSize?: number | undefined;
             backgroundColor?: string | undefined;
@@ -1766,6 +1828,12 @@ type Scenario = z.infer<typeof ScenarioSchema>;
 interface KeystrokeEvent {
     key: string;
     timestamp: number;
+    /**
+     * Typing session ID — incremented each time a new input is focused via the
+     * `type` action.  HUD groups keystrokes by sessionId so each input field's
+     * typed content appears on its own line.  Undefined for legacy recordings.
+     */
+    sessionId?: number;
 }
 interface CapturedFrame {
     index: number;
@@ -1845,6 +1913,9 @@ declare class ClipwiseRecorder {
     private cursorTimeline;
     private clickTimeline;
     private keystrokeTimeline;
+    /** Incremented at the start of each `type` action so the HUD can render
+     *  each input field's text on a separate line. */
+    private keystrokeSessionId;
     private currentStepIndex;
     private cursorPosition;
     private viewport;
@@ -1895,6 +1966,21 @@ declare class ClipwiseRecorder {
      * Cursor/click data reflects the timeline up to this moment.
      */
     private buildFrameOnline;
+    /**
+     * Force a unique DOM repaint visible in the top scanlines of the captured PNG.
+     *
+     * Uses a 1×1 px fixed-position element at z-index MAX, sitting above ALL
+     * overlays including modals (position:fixed;z-index:100;backdrop-filter:blur).
+     * Alternates background between #000001 and #000100 — two colors that are
+     * visually indistinguishable (1/255 difference in R or G channel against a
+     * dark page) but produce distinct PNG byte sequences, defeating dedup.
+     *
+     * This replaces the previous `document.documentElement.style.outline` approach
+     * which failed whenever a full-viewport fixed overlay (e.g. modal backdrop)
+     * was composited on top of the outline, making y=0 PNG bytes identical across
+     * frames and causing dedup to collapse all modal-typing frames into one.
+     */
+    private forceRepaint;
     /**
      * Wait for a given duration while forcing periodic repaints
      * so CDP screencast keeps sending frames even on static pages.
@@ -1913,9 +1999,38 @@ declare class ClipwiseRecorder {
      */
     private executeAction;
     /**
-     * Move cursor smoothly from current position to target using
-     * manual step-by-step movement with delays between each step.
-     * Speed is controlled by the cursor.speed preset (fast/normal/slow).
+     * Suppress all CSS transitions and animations on the page during cursor
+     * movement.  Hover-state transitions (background, transform, box-shadow,
+     * etc.) on elements the cursor passes over generate CSS-animation-driven
+     * CDP frames that arrive asynchronously relative to our cursor step
+     * intervals.  Those extra frames are timestamped when they're ACK-drained,
+     * which can be many milliseconds after the actual cursor moved — causing
+     * interpolateCursorAt() to map them to a newer cursor position while the
+     * screenshot still shows older content → visible stutter.
+     *
+     * Suppressing transitions during movement eliminates these extra frames
+     * entirely regardless of which elements the path crosses.  Transitions are
+     * restored immediately after arrival, so hover effects on the final target
+     * element still appear during the subsequent holdDuration.
+     */
+    private suppressTransitions;
+    private restoreTransitions;
+    /**
+     * Move cursor smoothly from current position to target.
+     *
+     * Key design decisions:
+     *  1. Adaptive step count — proportional to travel distance so short and
+     *     long movements feel equally paced (pixelsPerStep controls speed).
+     *  2. Forced repaint per step — moving the mouse in headless Chrome does NOT
+     *     visually change the screenshot (the cursor is rendered in post-processing).
+     *     Without a forced repaint, dedup collapses every intermediate frame into
+     *     the first one, making the cursor appear to teleport.
+     *  3. Transition suppression — CSS transitions on hovered elements generate
+     *     asynchronous CDP frames that desync cursor position from screenshot
+     *     content.  All transitions are suppressed for the duration of movement
+     *     and restored on arrival (see suppressTransitions / restoreTransitions).
+     *  4. Capped bezier curve — perpendicular offset is capped at 30 px regardless
+     *     of distance, preventing a visible arc on long-distance movements.
      */
     private moveCursorSmooth;
     /**
@@ -2207,6 +2322,26 @@ declare class StreamingSession extends EventEmitter {
     run(): Promise<Buffer>;
 }
 
+/**
+ * Preset zoom intensity levels for auto-zoom.
+ *
+ * Calibrated against industry tools (Loom ≈1.2x, Camtasia SmartFocus ≈1.3-1.4x,
+ * ScreenFlow ≈1.25x) so the focus point is clear without cutting off surrounding
+ * context (navigation bars, sidebars, etc.).
+ *
+ * - subtle   1.15x  — barely noticeable; good for dense UIs or large viewports
+ * - light    1.25x  — Loom-style gentle pull-in; draws attention, keeps context
+ * - moderate 1.35x  — balanced default; Camtasia-range, works for most demos
+ * - strong   1.5x   — clear focus; some peripheral context sacrificed
+ * - dramatic 1.8x   — maximum emphasis; use only for simple, sparse UIs
+ */
+type ZoomIntensity = "subtle" | "light" | "moderate" | "strong" | "dramatic";
+declare const ZOOM_INTENSITY_SCALES: Record<ZoomIntensity, number>;
+/**
+ * Resolve the effective zoom scale from an explicit `scale` value or an
+ * `intensity` preset.  When both are provided, `intensity` takes precedence.
+ */
+declare function resolveZoomScale(scale: number, intensity?: ZoomIntensity): number;
 /**
  * Calculate adaptive zoom scale based on proximity to click/action frames.
  * Zooms in smoothly near important actions, stays at 1.0 during idle.
@@ -2304,8 +2439,19 @@ declare function renderCursorTrail(frameBuffer: Buffer, positions: Array<{
 
 type KeystrokeConfig = EffectsConfig["keystroke"];
 /**
- * Render a keystroke HUD overlay showing recently typed keys.
- * Inspired by KeyCastr / CursorClip.
+ * Render a keystroke HUD overlay on the frame.
+ *
+ * showTyping: false (default, industry standard)
+ *   No typing text is shown — consistent with Screen Studio, KeyCastr, and
+ *   ScreenFlow which hide regular typing by default.
+ *
+ * showTyping: true
+ *   Multi-session rolling HUD.  Each `type` action (= each input field) gets
+ *   its own line.  Up to 3 recent sessions are shown simultaneously, oldest
+ *   at the top and dimmed, newest at the bottom at full brightness.  Lines
+ *   that are too long to fit are truncated from the left (showing the most
+ *   recently typed characters).  The HUD fades `fadeAfter` ms after the last
+ *   keystroke of the last session.
  */
 declare function renderKeystrokeHud(frameBuffer: Buffer, keystrokes: KeystrokeEvent[], frameTimestamp: number, config: KeystrokeConfig, frameWidth: number, frameHeight: number, dpr?: number): Promise<Buffer>;
 
@@ -2358,4 +2504,4 @@ interface ValidationResult {
  */
 declare function validateScenario(scenario: Scenario): ValidationResult;
 
-export { CanvasRenderer, type CapturedFrame, ClipwiseRecorder, type ComposedFrame, type ConcurrentResult, ConcurrentSession, type EffectsConfig, type FrameContext, type KeystrokeEvent, type OutputConfig, type PipelineProgress, type RecordingHandle, type RecordingSession, type Scenario, type Step, type StepAction, StreamingSession, applyCrossfade, buildZoomClickLookup, calculateAdaptiveZoom, calculateAdaptiveZoomFromLookup, calculateAdaptiveZoomInWindow, calculatePanOffset, encodeGif, encodeMp4, encodeMp4Stream, lerpZoom, loadScenario, parseScenario, renderCursorHighlight, renderCursorTrail, renderKeystrokeHud, renderWatermark, savePngSequence, validateScenario };
+export { CanvasRenderer, type CapturedFrame, ClipwiseRecorder, type ComposedFrame, type ConcurrentResult, ConcurrentSession, type EffectsConfig, type FrameContext, type KeystrokeEvent, type OutputConfig, type PipelineProgress, type RecordingHandle, type RecordingSession, type Scenario, type Step, type StepAction, StreamingSession, ZOOM_INTENSITY_SCALES, type ZoomIntensity, applyCrossfade, buildZoomClickLookup, calculateAdaptiveZoom, calculateAdaptiveZoomFromLookup, calculateAdaptiveZoomInWindow, calculatePanOffset, encodeGif, encodeMp4, encodeMp4Stream, lerpZoom, loadScenario, parseScenario, renderCursorHighlight, renderCursorTrail, renderKeystrokeHud, renderWatermark, resolveZoomScale, savePngSequence, validateScenario };