sessionsnap 0.0.1

package/src/core/replayer.js

@@ -0,0 +1,886 @@
+/**
+ * Replay engine — executes recorded actions on a live page.
+ * Works with both Puppeteer and Playwright through a unified interface.
+ */
+
+const DEFAULT_ACTION_DELAY = 500; // ms between actions
+
+/**
+ * Inject a visual mouse cursor overlay into the page.
+ * Returns a function to move the cursor to (x, y) with smooth animation.
+ */
+async function injectVisualCursor(page) {
+  await page.evaluate(() => {
+    if (document.getElementById('__sessionsnap_cursor')) return;
+    const cursor = document.createElement('div');
+    cursor.id = '__sessionsnap_cursor';
+    cursor.innerHTML = `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <path d="M5 3L19 12L12 13L9 20L5 3Z" fill="#4F46E5" stroke="#fff" stroke-width="1.2" stroke-linejoin="round"/>
+    </svg>`;
+    cursor.style.cssText = `
+      position: fixed; top: 0; left: 0; z-index: 2147483647;
+      pointer-events: none; width: 24px; height: 24px;
+      transition: transform 0.25s cubic-bezier(0.4, 0, 0.2, 1);
+      transform: translate(-105px, -103px);
+      filter: drop-shadow(1px 2px 2px rgba(0,0,0,0.3));
+    `;
+    document.body.appendChild(cursor);
+
+    // Click ripple effect container
+    const ripple = document.createElement('div');
+    ripple.id = '__sessionsnap_ripple';
+    ripple.style.cssText = `
+      position: fixed; top: 0; left: 0; z-index: 2147483646;
+      pointer-events: none; width: 20px; height: 20px;
+      border-radius: 50%; border: 2px solid #4F46E5;
+      transform: translate(-100px, -100px) scale(0);
+      opacity: 0;
+    `;
+    document.body.appendChild(ripple);
+  });
+}
+
+/**
+ * Move the visual cursor to (x, y) and optionally show a click ripple.
+ */
+async function moveVisualCursor(page, x, y, showRipple = false) {
+  await page.evaluate(({ x, y, showRipple }) => {
+    const cursor = document.getElementById('__sessionsnap_cursor');
+    if (cursor) {
+      // SVG path starts at (5, 3) which is the cursor tip, so offset to align tip with (x, y)
+      cursor.style.transform = `translate(${x - 5}px, ${y - 3}px)`;
+    }
+    if (showRipple) {
+      const ripple = document.getElementById('__sessionsnap_ripple');
+      if (ripple) {
+        // Reset animation (ripple is 20px, so center at -10, -10)
+        ripple.style.transition = 'none';
+        ripple.style.transform = `translate(${x - 10}px, ${y - 10}px) scale(0)`;
+        ripple.style.opacity = '1';
+        ripple.offsetHeight; // force reflow
+        ripple.style.transition = 'transform 0.4s ease-out, opacity 0.4s ease-out';
+        ripple.style.transform = `translate(${x - 10}px, ${y - 10}px) scale(2.5)`;
+        ripple.style.opacity = '0';
+      }
+    }
+  }, { x, y, showRipple });
+  // Wait for cursor animation to settle
+  await sleep(280);
+}
+
+/**
+ * Resolve the target coordinates for a given action by querying the element on the page.
+ * Returns { x, y } or null if the element cannot be found.
+ */
+async function resolveActionCoords(page, action) {
+  // If action already has coordinates, use them
+  if (action.x != null && action.y != null) return { x: action.x, y: action.y };
+
+  // Try to find the element by selector
+  if (action.selector && action.selector !== 'unknown') {
+    try {
+      const coords = await page.evaluate((sel) => {
+        const el = document.querySelector(sel);
+        if (!el) return null;
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return null;
+        return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+      }, action.selector);
+      if (coords) return coords;
+    } catch { /* ignore */ }
+  }
+
+  // Try to find by text content
+  if (action.text && action.text.trim()) {
+    try {
+      const coords = await page.evaluate((text) => {
+        const candidates = document.querySelectorAll('a, button, div, span, li, td, th, label, input, select, textarea, summary, details');
+        for (const el of candidates) {
+          const elText = (el.innerText || el.value || '').trim();
+          if (elText === text || elText.startsWith(text.slice(0, 30))) {
+            const rect = el.getBoundingClientRect();
+            if (rect.width > 0 && rect.height > 0) {
+              return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+            }
+          }
+        }
+        return null;
+      }, action.text.trim());
+      if (coords) return coords;
+    } catch { /* ignore */ }
+  }
+
+  return null;
+}
+
+/**
+ * Replay a list of recorded actions on the given page.
+ *
+ * @param {object} page - Puppeteer or Playwright page instance
+ * @param {Array} actions - Array of recorded action objects
+ * @param {object} options
+ * @param {'puppeteer'|'playwright'} options.runner
+ * @param {number} [options.speed=1] - Playback speed multiplier (2 = 2x faster)
+ * @param {boolean} [options.visual=false] - Show a visual mouse cursor during replay
+ * @param {function} [options.onAction] - Callback after each action: (action, index, total) => void
+ */
+export async function replayActions(page, actions, { runner, speed = 1, bail = false, visual = false, onAction } = {}) {
+  if (!actions || actions.length === 0) {
+    console.log('[sessionsnap] No actions to replay.');
+    return;
+  }
+
+  const baseDelay = DEFAULT_ACTION_DELAY / speed;
+  console.log(`[sessionsnap] Replaying ${actions.length} actions (speed: ${speed}x${bail ? ', bail on failure' : ''}${visual ? ', visual cursor' : ''})...`);
+
+  // Inject visual cursor if enabled
+  if (visual) {
+    await injectVisualCursor(page);
+  }
+
+  let failed = 0;
+  let mousemoveBatchCount = 0;
+  let mousemoveBatchStart = -1;
+
+  for (let i = 0; i < actions.length; i++) {
+    const action = actions[i];
+
+    // Batch mousemove actions: execute immediately without delay for smooth movement
+    if (action.type === 'mousemove') {
+      if (mousemoveBatchStart === -1) {
+        mousemoveBatchStart = i;
+      }
+      mousemoveBatchCount++;
+      
+      // Execute mousemove immediately (no delay, no visual cursor update for each move)
+      try {
+        await executeAction(page, action, runner);
+        if (onAction) onAction(action, i, actions.length);
+        
+        // Update visual cursor only every 5 mousemoves to reduce lag
+        if (visual && mousemoveBatchCount % 5 === 0) {
+          try {
+            const coords = await resolveActionCoords(page, action);
+            if (coords) {
+              // Use direct DOM update instead of moveVisualCursor to avoid sleep delay
+              await page.evaluate(({ x, y }) => {
+                const cursor = document.getElementById('__sessionsnap_cursor');
+                if (cursor) {
+                  cursor.style.transform = `translate(${x - 5}px, ${y - 3}px)`;
+                }
+              }, { x: coords.x, y: coords.y });
+            }
+          } catch { /* ignore */ }
+        }
+        
+        // Log every 10 mousemoves
+        if (mousemoveBatchCount % 10 === 0) {
+          console.log(`[sessionsnap] [${i + 1}/${actions.length}] mousemove batch: ${mousemoveBatchCount} moves`);
+        }
+      } catch (err) {
+        failed++;
+        console.log(`[sessionsnap] [${i + 1}/${actions.length}] mousemove FAILED: ${err.message}`);
+        if (bail) {
+          console.log(`[sessionsnap] Bail: stopping replay due to failure at action ${i + 1}.`);
+          return { completed: i, failed, total: actions.length, bailedAt: i + 1 };
+        }
+      }
+      
+      // Continue to next action (no delay for mousemove)
+      continue;
+    }
+
+    // Non-mousemove action: log mousemove batch if we just finished one
+    if (mousemoveBatchCount > 0) {
+      // Update visual cursor to final position of mousemove batch
+      if (visual && i > 0) {
+        try {
+          const lastMousemove = actions[i - 1];
+          if (lastMousemove && lastMousemove.type === 'mousemove') {
+            const coords = await resolveActionCoords(page, lastMousemove);
+            if (coords) {
+              await page.evaluate(({ x, y }) => {
+                const cursor = document.getElementById('__sessionsnap_cursor');
+                if (cursor) {
+                  cursor.style.transform = `translate(${x - 5}px, ${y - 3}px)`;
+                }
+              }, { x: coords.x, y: coords.y });
+            }
+          }
+        } catch { /* ignore */ }
+      }
+      
+      if (mousemoveBatchCount % 10 !== 0) {
+        // Log remaining mousemoves if batch wasn't already logged
+        console.log(`[sessionsnap] [${mousemoveBatchStart + 1}-${i}/${actions.length}] mousemove batch: ${mousemoveBatchCount} moves`);
+      }
+      mousemoveBatchCount = 0;
+      mousemoveBatchStart = -1;
+    }
+
+    // Calculate delay from timestamps if available
+    let delay = baseDelay;
+    if (i > 0 && actions[i].timestamp && actions[i - 1].timestamp) {
+      const realDelay = actions[i].timestamp - actions[i - 1].timestamp;
+      delay = Math.min(Math.max(realDelay / speed, 50), 5000); // clamp 50ms–5s
+    }
+    await sleep(delay);
+
+    // Move visual cursor to target position before executing the action
+    if (visual && action.type !== 'navigation' && action.type !== 'keydown') {
+      try {
+        const coords = await resolveActionCoords(page, action);
+        if (coords) {
+          const isClick = ['click', 'dblclick', 'checkbox', 'submit'].includes(action.type);
+          // For hover, use direct DOM update (no sleep delay) for smooth movement
+          if (action.type === 'hover') {
+            await page.evaluate(({ x, y }) => {
+              const cursor = document.getElementById('__sessionsnap_cursor');
+              if (cursor) {
+                cursor.style.transform = `translate(${x - 5}px, ${y - 3}px)`;
+              }
+            }, { x: coords.x, y: coords.y });
+          } else {
+            // For clicks, use moveVisualCursor to show ripple effect
+            const showRipple = isClick;
+            await moveVisualCursor(page, coords.x, coords.y, showRipple);
+          }
+        }
+      } catch { /* visual cursor is best-effort, ignore errors */ }
+    }
+
+    try {
+      await executeAction(page, action, runner);
+      if (onAction) onAction(action, i, actions.length);
+      console.log(`[sessionsnap] [${i + 1}/${actions.length}] ${action.type}: ${describeAction(action)}`);
+    } catch (err) {
+      failed++;
+      console.log(`[sessionsnap] [${i + 1}/${actions.length}] ${action.type} FAILED: ${err.message}`);
+      if (bail) {
+        console.log(`[sessionsnap] Bail: stopping replay due to failure at action ${i + 1}.`);
+        return { completed: i, failed, total: actions.length, bailedAt: i + 1 };
+      }
+    }
+  }
+
+  // Log final mousemove batch if any and update visual cursor
+  if (mousemoveBatchCount > 0) {
+    // Update visual cursor to final position of mousemove batch
+    if (visual && actions.length > 0) {
+      try {
+        const lastMousemove = actions[actions.length - 1];
+        if (lastMousemove && lastMousemove.type === 'mousemove') {
+          const coords = await resolveActionCoords(page, lastMousemove);
+          if (coords) {
+            await page.evaluate(({ x, y }) => {
+              const cursor = document.getElementById('__sessionsnap_cursor');
+              if (cursor) {
+                cursor.style.transform = `translate(${x - 5}px, ${y - 3}px)`;
+              }
+            }, { x: coords.x, y: coords.y });
+          }
+        }
+      } catch { /* ignore */ }
+    }
+    
+    if (mousemoveBatchCount % 10 !== 0) {
+      console.log(`[sessionsnap] [${mousemoveBatchStart + 1}-${actions.length}/${actions.length}] mousemove batch: ${mousemoveBatchCount} moves`);
+    }
+  }
+
+  // Remove visual cursor
+  if (visual) {
+    await page.evaluate(() => {
+      document.getElementById('__sessionsnap_cursor')?.remove();
+      document.getElementById('__sessionsnap_ripple')?.remove();
+    }).catch(() => {});
+  }
+
+  console.log(`[sessionsnap] Replay complete. ${failed > 0 ? `(${failed} failed)` : ''}`);
+  return { completed: actions.length, failed, total: actions.length, bailedAt: null };
+}
+
+async function executeAction(page, action, runner) {
+  switch (action.type) {
+    case 'click':
+      await executeClick(page, action, runner);
+      break;
+    case 'dblclick':
+      await executeDblclick(page, action, runner);
+      break;
+    case 'hover':
+      await executeHover(page, action, runner);
+      break;
+    case 'mousemove':
+      await executeMousemove(page, action, runner);
+      break;
+    case 'input':
+      await executeInput(page, action, runner);
+      break;
+    case 'select':
+      await executeSelect(page, action, runner);
+      break;
+    case 'checkbox':
+      await executeCheckbox(page, action, runner);
+      break;
+    case 'keydown':
+      await executeKeydown(page, action, runner);
+      break;
+    case 'submit':
+      await executeSubmit(page, action, runner);
+      break;
+    case 'scroll':
+      await executeScroll(page, action, runner);
+      break;
+    case 'file':
+      console.log(`[sessionsnap]   Skipping file input: ${action.selector} (${action.fileCount} file(s): ${(action.fileNames || []).join(', ')}) — file selection cannot be replayed`);
+      break;
+    case 'navigation':
+      await executeNavigation(page, action, runner);
+      break;
+    default:
+      console.log(`[sessionsnap] Unknown action type: ${action.type}`);
+  }
+}
+
+async function executeClick(page, action, runner) {
+  // Strategy 1: click by recorded coordinates (most accurate, simulates real user click)
+  if (action.x != null && action.y != null) {
+    // Move mouse to recorded position first, then click
+    await page.mouse.move(action.x, action.y, { steps: 1 });
+    await page.mouse.click(action.x, action.y);
+    return;
+  }
+
+  // Strategy 2: CSS selector + move to element center if coordinates not available
+  try {
+    if (runner === 'puppeteer') {
+      await page.waitForSelector(action.selector, { timeout: 1000 });
+      // Get element center coordinates for more accurate click
+      const coords = await page.evaluate((sel) => {
+        const el = document.querySelector(sel);
+        if (!el) return null;
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return null;
+        return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+      }, action.selector);
+      if (coords) {
+        await page.mouse.move(coords.x, coords.y, { steps: 1 });
+        await page.mouse.click(coords.x, coords.y);
+      } else {
+        await page.click(action.selector);
+      }
+      return;
+    } else {
+      const locator = page.locator(action.selector).first();
+      await locator.waitFor({ timeout: 1000, state: 'visible' });
+      // Get element center coordinates for more accurate click
+      const coords = await page.evaluate((sel) => {
+        const el = document.querySelector(sel);
+        if (!el) return null;
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return null;
+        return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+      }, action.selector);
+      if (coords) {
+        await page.mouse.move(coords.x, coords.y, { steps: 1 });
+        await page.mouse.click(coords.x, coords.y);
+      } else {
+        await locator.click({ timeout: 1000 });
+      }
+      return;
+    }
+  } catch { /* selector failed, try next strategy */ }
+
+  // Strategy 3: find element by text content
+  if (action.text && action.text.trim()) {
+    try {
+      const result = await page.evaluate((text) => {
+        // Search all visible elements for matching text
+        const candidates = document.querySelectorAll('a, button, div, span, li, td, th, label, p, h1, h2, h3, h4, h5, h6');
+        for (const el of candidates) {
+          const elText = (el.innerText || '').trim();
+          if (elText === text || elText.startsWith(text.slice(0, 30))) {
+            // Verify element is visible
+            const rect = el.getBoundingClientRect();
+            if (rect.width > 0 && rect.height > 0) {
+              return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+            }
+          }
+        }
+        return null;
+      }, action.text.trim());
+      if (result) {
+        await page.mouse.move(result.x, result.y, { steps: 1 });
+        await page.mouse.click(result.x, result.y);
+        return;
+      }
+    } catch { /* text search failed */ }
+  }
+
+  throw new Error(`Element not found: ${action.selector} (text: "${action.text || ''}")`);
+}
+
+async function executeDblclick(page, action, runner) {
+  // Strategy 1: double-click by recorded coordinates (most accurate, simulates real user dblclick)
+  if (action.x != null && action.y != null) {
+    // Move mouse to recorded position first, then double-click
+    await page.mouse.move(action.x, action.y, { steps: 1 });
+    await page.mouse.click(action.x, action.y, { clickCount: 2 });
+    return;
+  }
+
+  // Strategy 2: CSS selector + move to element center if coordinates not available
+  try {
+    if (runner === 'puppeteer') {
+      await page.waitForSelector(action.selector, { timeout: 1000 });
+      // Get element center coordinates for more accurate click
+      const coords = await page.evaluate((sel) => {
+        const el = document.querySelector(sel);
+        if (!el) return null;
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return null;
+        return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+      }, action.selector);
+      if (coords) {
+        await page.mouse.move(coords.x, coords.y, { steps: 1 });
+        await page.mouse.click(coords.x, coords.y, { clickCount: 2 });
+      } else {
+        await page.click(action.selector, { clickCount: 2 });
+      }
+      return;
+    } else {
+      const locator = page.locator(action.selector).first();
+      await locator.waitFor({ timeout: 1000, state: 'visible' });
+      // Get element center coordinates for more accurate click
+      const coords = await page.evaluate((sel) => {
+        const el = document.querySelector(sel);
+        if (!el) return null;
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return null;
+        return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+      }, action.selector);
+      if (coords) {
+        await page.mouse.move(coords.x, coords.y, { steps: 1 });
+        await page.mouse.click(coords.x, coords.y, { clickCount: 2 });
+      } else {
+        await locator.dblclick({ timeout: 1000 });
+      }
+      return;
+    }
+  } catch { /* selector failed, try next strategy */ }
+
+  // Strategy 3: find element by text content
+  if (action.text && action.text.trim()) {
+    try {
+      const result = await page.evaluate((text) => {
+        const candidates = document.querySelectorAll('a, button, div, span, li, td, th, label, p, h1, h2, h3, h4, h5, h6');
+        for (const el of candidates) {
+          const elText = (el.innerText || '').trim();
+          if (elText === text || elText.startsWith(text.slice(0, 30))) {
+            const rect = el.getBoundingClientRect();
+            if (rect.width > 0 && rect.height > 0) {
+              return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+            }
+          }
+        }
+        return null;
+      }, action.text.trim());
+      if (result) {
+        await page.mouse.move(result.x, result.y, { steps: 1 });
+        await page.mouse.click(result.x, result.y, { clickCount: 2 });
+        return;
+      }
+    } catch { /* text search failed */ }
+  }
+
+  throw new Error(`Element not found for dblclick: ${action.selector}`);
+}
+
+async function executeHover(page, action, runner) {
+  // Strategy 1: CSS selector + mouse position
+  try {
+    if (runner === 'puppeteer') {
+      await page.waitForSelector(action.selector, { timeout: 1000 });
+      // Move mouse to recorded position first for accuracy, then hover element
+      if (action.x != null && action.y != null) {
+        await page.mouse.move(action.x, action.y, { steps: 1 }); // steps: 1 for instant movement
+      }
+      await page.hover(action.selector);
+      return;
+    } else {
+      const locator = page.locator(action.selector).first();
+      await locator.waitFor({ timeout: 1000, state: 'visible' });
+      // Move mouse to recorded position first for accuracy, then hover element
+      if (action.x != null && action.y != null) {
+        await page.mouse.move(action.x, action.y, { steps: 1 }); // steps: 1 for instant movement
+      }
+      await locator.hover({ timeout: 1000 });
+      return;
+    }
+  } catch { /* selector failed, try text fallback */ }
+
+  // Strategy 2: find element by text content and hover via mouse move
+  if (action.text && action.text.trim()) {
+    try {
+      const result = await page.evaluate((text) => {
+        const candidates = document.querySelectorAll('a, button, div, span, li, td, th, label, summary, details');
+        for (const el of candidates) {
+          const elText = (el.innerText || '').trim();
+          if (elText === text || elText.startsWith(text.slice(0, 30))) {
+            const rect = el.getBoundingClientRect();
+            if (rect.width > 0 && rect.height > 0) {
+              return { 
+                x: rect.x + rect.width / 2, 
+                y: rect.y + rect.height / 2,
+                selector: el.id ? '#' + el.id : null
+              };
+            }
+          }
+        }
+        return null;
+      }, action.text.trim());
+      if (result) {
+        // Use recorded position if available, otherwise use element center
+        const x = action.x != null ? action.x : result.x;
+        const y = action.y != null ? action.y : result.y;
+        await page.mouse.move(x, y, { steps: 1 }); // steps: 1 for instant movement
+        // Also trigger hover event on element
+        if (result.selector) {
+          try {
+            if (runner === 'puppeteer') {
+              await page.hover(result.selector);
+            } else {
+              await page.locator(result.selector).first().hover();
+            }
+          } catch { /* ignore if hover fails */ }
+        }
+        return;
+      }
+    } catch { /* text search failed */ }
+  }
+
+  // Strategy 3: hover by recorded coordinates only (fallback)
+  if (action.x != null && action.y != null) {
+    await page.mouse.move(action.x, action.y, { steps: 1 }); // steps: 1 for instant movement
+    // Try to trigger hover event by dispatching mouseover on element at that position
+    await page.evaluate(({ x, y }) => {
+      const el = document.elementFromPoint(x, y);
+      if (el) {
+        const event = new MouseEvent('mouseover', { 
+          bubbles: true, 
+          cancelable: true,
+          clientX: x,
+          clientY: y,
+          view: window
+        });
+        el.dispatchEvent(event);
+      }
+    }, { x: action.x, y: action.y });
+    return;
+  }
+
+  throw new Error(`Element not found for hover: ${action.selector}`);
+}
+
+async function executeMousemove(page, action, runner) {
+  // Strict mouse movement: move to exact recorded coordinates
+  if (action.x != null && action.y != null) {
+    await page.mouse.move(action.x, action.y);
+    return;
+  }
+  // Should not happen if recording is correct, but handle gracefully
+  console.log(`[sessionsnap]   Warning: mousemove action missing coordinates`);
+}
+
+async function executeInput(page, action, runner) {
+  if (action.value === '***') {
+    console.log(`[sessionsnap]   Skipping password field: ${action.selector}`);
+    return;
+  }
+
+  if (runner === 'puppeteer') {
+    await page.waitForSelector(action.selector, { timeout: 3000 });
+    // Clear existing value then type
+    await page.click(action.selector, { clickCount: 3 });
+    await page.type(action.selector, action.value);
+  } else {
+    const locator = page.locator(action.selector).first();
+    await locator.fill(action.value, { timeout: 3000 });
+  }
+}
+
+async function executeSelect(page, action, runner) {
+  if (runner === 'puppeteer') {
+    await page.waitForSelector(action.selector, { timeout: 3000 });
+    await page.select(action.selector, action.value);
+  } else {
+    await page.locator(action.selector).first().selectOption(action.value, { timeout: 3000 });
+  }
+}
+
+async function executeCheckbox(page, action, runner) {
+  // Use recorded coordinates if available for accurate click simulation
+  if (action.x != null && action.y != null) {
+    if (runner === 'puppeteer') {
+      // Check current state before clicking
+      const currentChecked = await page.evaluate(({ x, y }) => {
+        const el = document.elementFromPoint(x, y);
+        if (el && (el.type === 'checkbox' || el.type === 'radio')) {
+          return el.checked;
+        }
+        return null;
+      }, { x: action.x, y: action.y });
+      
+      if (currentChecked !== null && currentChecked !== action.checked) {
+        await page.mouse.move(action.x, action.y, { steps: 1 });
+        await page.mouse.click(action.x, action.y);
+      }
+      return;
+    } else {
+      // For Playwright, check state and click if needed
+      const currentChecked = await page.evaluate(({ x, y }) => {
+        const el = document.elementFromPoint(x, y);
+        if (el && (el.type === 'checkbox' || el.type === 'radio')) {
+          return el.checked;
+        }
+        return null;
+      }, { x: action.x, y: action.y });
+      
+      if (currentChecked !== null && currentChecked !== action.checked) {
+        await page.mouse.move(action.x, action.y, { steps: 1 });
+        await page.mouse.click(action.x, action.y);
+      }
+      return;
+    }
+  }
+
+  // Fallback to selector-based approach
+  if (runner === 'puppeteer') {
+    await page.waitForSelector(action.selector, { timeout: 1000 });
+    // Get element center coordinates for more accurate click
+    const coords = await page.evaluate((sel) => {
+      const el = document.querySelector(sel);
+      if (!el) return null;
+      const rect = el.getBoundingClientRect();
+      if (rect.width === 0 && rect.height === 0) return null;
+      return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+    }, action.selector);
+    
+    const currentChecked = await page.$eval(action.selector, (el) => el.checked);
+    if (currentChecked !== action.checked) {
+      if (coords) {
+        await page.mouse.move(coords.x, coords.y, { steps: 1 });
+        await page.mouse.click(coords.x, coords.y);
+      } else {
+        await page.click(action.selector);
+      }
+    }
+  } else {
+    const locator = page.locator(action.selector).first();
+    await locator.waitFor({ timeout: 1000, state: 'visible' });
+    // Get element center coordinates for more accurate click
+    const coords = await page.evaluate((sel) => {
+      const el = document.querySelector(sel);
+      if (!el) return null;
+      const rect = el.getBoundingClientRect();
+      if (rect.width === 0 && rect.height === 0) return null;
+      return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+    }, action.selector);
+    
+    if (coords) {
+      const currentChecked = await page.evaluate((sel) => {
+        const el = document.querySelector(sel);
+        return el ? el.checked : null;
+      }, action.selector);
+      
+      if (currentChecked !== null && currentChecked !== action.checked) {
+        await page.mouse.move(coords.x, coords.y, { steps: 1 });
+        await page.mouse.click(coords.x, coords.y);
+      }
+    } else {
+      if (action.checked) {
+        await locator.check({ timeout: 1000 });
+      } else {
+        await locator.uncheck({ timeout: 1000 });
+      }
+    }
+  }
+}
+
+async function executeKeydown(page, action, runner) {
+  // Reconstruct key combo for Puppeteer/Playwright keyboard API
+  const modifiers = [];
+  if (action.combo) {
+    if (action.combo.includes('Ctrl+')) modifiers.push('Control');
+    if (action.combo.includes('Meta+')) modifiers.push('Meta');
+    if (action.combo.includes('Alt+')) modifiers.push('Alt');
+    if (action.combo.includes('Shift+')) modifiers.push('Shift');
+  }
+
+  // Press modifiers down
+  for (const mod of modifiers) {
+    await page.keyboard.down(mod);
+  }
+
+  await page.keyboard.press(action.key);
+
+  // Release modifiers
+  for (const mod of modifiers.reverse()) {
+    await page.keyboard.up(mod);
+  }
+}
+
+async function executeScroll(page, action) {
+  if (action.target === 'element' && action.selector) {
+    // Inner element scroll
+    await page.evaluate(({ sel, left, top }) => {
+      const el = document.querySelector(sel);
+      if (el) el.scrollTo(left, top);
+    }, { sel: action.selector, left: action.scrollLeft || 0, top: action.scrollTop || 0 });
+    await sleep(200);
+  } else if (action.scrollX != null && action.scrollY != null) {
+    // Window scroll
+    await page.evaluate(({ x, y }) => {
+      window.scrollTo(x, y);
+    }, { x: action.scrollX, y: action.scrollY });
+    await sleep(200);
+  }
+}
+
+async function executeSubmit(page, action, runner) {
+  // Try to submit the form by clicking a submit button or dispatching submit event
+  try {
+    if (runner === 'puppeteer') {
+      await page.evaluate((sel) => {
+        const form = document.querySelector(sel);
+        if (form) form.requestSubmit();
+      }, action.selector);
+    } else {
+      await page.evaluate((sel) => {
+        const form = document.querySelector(sel);
+        if (form) form.requestSubmit();
+      }, action.selector);
+    }
+  } catch {
+    // Try pressing Enter on the last focused element as fallback
+    await page.keyboard.press('Enter');
+  }
+}
+
+async function executeNavigation(page, action, runner) {
+  if (action.to) {
+    try {
+      if (runner === 'puppeteer') {
+        await page.goto(action.to, { waitUntil: 'domcontentloaded', timeout: 10000 });
+      } else {
+        await page.goto(action.to, { waitUntil: 'domcontentloaded', timeout: 10000 });
+      }
+    } catch {
+      console.log(`[sessionsnap]   Navigation to ${action.to} timed out, continuing...`);
+    }
+  }
+}
+
+function describeAction(action) {
+  switch (action.type) {
+    case 'click':
+      return `${action.selector}${action.text ? ' "' + action.text.slice(0, 30) + '"' : ''}`;
+    case 'dblclick':
+      return `${action.selector}${action.text ? ' "' + action.text.slice(0, 30) + '"' : ''}`;
+    case 'hover':
+      return `${action.selector}${action.text ? ' "' + action.text.slice(0, 30) + '"' : ''} (${action.x ?? '?'}, ${action.y ?? '?'})`;
+    case 'mousemove':
+      return `(${action.x ?? '?'}, ${action.y ?? '?'})`;
+    case 'input':
+      return `${action.selector} → ${action.value === '***' ? '(password)' : '"' + action.value.slice(0, 30) + '"'}`;
+    case 'select':
+      return `${action.selector} → "${action.text || action.value}"`;
+    case 'checkbox':
+      return `${action.selector} ${action.checked ? '☑' : '☐'} (${action.inputType})`;
+    case 'keydown':
+      return `[${action.combo}] on ${action.selector}`;
+    case 'submit':
+      return `${action.selector} [${action.method}]`;
+    case 'scroll':
+      if (action.target === 'element') return `${action.selector} → (${action.scrollLeft}, ${action.scrollTop})`;
+      return `window → (${action.scrollX}, ${action.scrollY})`;
+    case 'file':
+      return `${action.selector} — skipped`;
+    case 'navigation':
+      return `${action.from} → ${action.to}`;
+    default:
+      return JSON.stringify(action);
+  }
+}
+
+/**
+ * Wait for the page to stabilize after an action:
+ * - Network requests to settle
+ * - DOM mutations to stop
+ * - CSS transitions/animations to complete
+ */
+async function waitForStabilization(page, runner, actionType) {
+  try {
+    // Wait for network idle (short timeout to avoid blocking too long)
+    if (runner === 'puppeteer') {
+      await page.waitForNetworkIdle({ idleTime: 200, timeout: 1000 }).catch(() => {});
+    } else {
+      await page.waitForLoadState('networkidle', { timeout: 1000 }).catch(() => {});
+    }
+  } catch { /* ignore network idle timeout */ }
+
+  // Wait for DOM to stabilize (no mutations for 100ms)
+  try {
+    await page.evaluate(() => {
+      return new Promise((resolve) => {
+        let timeout;
+        const observer = new MutationObserver(() => {
+          clearTimeout(timeout);
+          timeout = setTimeout(resolve, 100);
+        });
+        observer.observe(document.body, {
+          childList: true,
+          subtree: true,
+          attributes: true,
+          attributeOldValue: false,
+        });
+        timeout = setTimeout(() => {
+          observer.disconnect();
+          resolve();
+        }, 100);
+      });
+    });
+  } catch { /* ignore DOM stabilization errors */ }
+
+  // Wait for CSS transitions/animations to complete
+  // Simple approach: wait a few animation frames to let transitions/animations settle
+  try {
+    await page.evaluate(() => {
+      return new Promise((resolve) => {
+        let framesWaited = 0;
+        const maxFrames = 3; // Wait up to 3 frames (~50ms at 60fps)
+        const checkFrame = () => {
+          framesWaited++;
+          if (framesWaited >= maxFrames) {
+            resolve();
+          } else {
+            requestAnimationFrame(checkFrame);
+          }
+        };
+        requestAnimationFrame(checkFrame);
+        // Max wait time (300ms) as fallback
+        setTimeout(resolve, 300);
+      });
+    });
+  } catch { /* ignore animation check errors */ }
+
+  // Extra wait for specific action types that typically trigger UI changes
+  if (['click', 'dblclick', 'hover', 'navigation', 'submit'].includes(actionType)) {
+    await sleep(100); // Additional 100ms for UI to respond
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}