sessionsnap 0.0.1

package/src/core/heuristics.js

@@ -0,0 +1,53 @@
+const LOGIN_URL_PATTERN = /login|signin|sign-in|auth/i;
+const POLL_INTERVAL_MS = 2000;
+const DEFAULT_TIMEOUT_MIN = 5;
+
+function isLoginUrl(url) {
+  return LOGIN_URL_PATTERN.test(url);
+}
+
+export async function getCookieCount(page, runner) {
+  if (runner === 'puppeteer') {
+    const client = await page.createCDPSession();
+    const { cookies } = await client.send('Network.getAllCookies');
+    await client.detach();
+    return cookies.length;
+  }
+  // playwright
+  const cookies = await page.context().cookies();
+  return cookies.length;
+}
+
+export async function waitForLoginComplete(page, { runner, waitMinutes } = {}) {
+  const timeout = (waitMinutes ?? DEFAULT_TIMEOUT_MIN) * 60 * 1000;
+  const start = Date.now();
+  const initialCookieCount = await getCookieCount(page, runner);
+
+  return new Promise((resolve) => {
+    const timer = setInterval(async () => {
+      const elapsed = Date.now() - start;
+
+      // timeout reached — resolve anyway
+      if (elapsed >= timeout) {
+        clearInterval(timer);
+        console.log('[sessionsnap] Timeout reached, capturing current state...');
+        resolve(false);
+        return;
+      }
+
+      const currentUrl = page.url();
+      const urlClear = !isLoginUrl(currentUrl);
+
+      let cookieIncreased = false;
+      try {
+        const count = await getCookieCount(page, runner);
+        cookieIncreased = count > initialCookieCount;
+      } catch { /* page may have navigated */ }
+
+      if (urlClear || cookieIncreased) {
+        clearInterval(timer);
+        resolve(true);
+      }
+    }, POLL_INTERVAL_MS);
+  });
+}

package/src/core/recorder.js

@@ -0,0 +1,576 @@
+/**
+ * Action Recorder — injects a script into the page that captures user actions
+ * and sends them immediately to Node.js via page.exposeFunction.
+ *
+ * Uses css-selector-generator (https://github.com/fczbkk/css-selector-generator)
+ * for robust, unique CSS selector generation.
+ *
+ * CRITICAL: Actions are written to disk IMMEDIATELY using writeFileSync.
+ * This ensures no data loss even on Ctrl+C, SIGINT, or abrupt process exit.
+ */
+
+import { writeFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+
+// Load the UMD bundle of css-selector-generator to inject into pages.
+// createRequire uses the "require" condition in package.json exports,
+// which resolves to the UMD build (build/index.js).
+const require = createRequire(import.meta.url);
+const cssSelectorGeneratorPath = require.resolve('css-selector-generator');
+const CSS_SELECTOR_GENERATOR_LIB = readFileSync(cssSelectorGeneratorPath, 'utf-8');
+
+// The script injected into every page document.
+const INJECTED_SCRIPT = `
+(function() {
+  if (window.__sessionsnap_recorder_active) return;
+  window.__sessionsnap_recorder_active = true;
+
+  // css-selector-generator is available as window.CssSelectorGenerator.getCssSelector
+
+  // Walk up from the raw target to the nearest interactive/identifiable element
+  var INTERACTIVE = ['A','BUTTON','INPUT','TEXTAREA','SELECT','LABEL','FORM','DETAILS','SUMMARY'];
+  function closestUseful(el) {
+    var cur = el;
+    for (var i = 0; i < 5 && cur && cur !== document.body; i++) {
+      if (INTERACTIVE.indexOf(cur.tagName) !== -1) return cur;
+      if (cur.id) return cur;
+      if (cur.getAttribute && (cur.getAttribute('data-testid') || cur.getAttribute('data-test') || cur.getAttribute('data-cy'))) return cur;
+      if (cur.getAttribute && cur.getAttribute('role')) return cur;
+      cur = cur.parentElement;
+    }
+    return el;
+  }
+
+  // CSS-in-JS blacklist patterns
+  var cssInJsBlacklist = [
+    /^\\.(css|sc|emotion|styled|tw|svelte)-/,
+    /^\\.[a-z]{1,3}[A-Z][a-zA-Z]{2,}$/,
+    /^\\.[a-f0-9]{5,}$/i,
+    /^\\._/,
+  ];
+
+  // Hover-state class blacklist — classes added dynamically on hover/focus/active
+  // that won't exist before the interaction, making selectors unreplayable.
+  var hoverStateBlacklist = [
+    // CSS-in-JS (same as above)
+    /^\\.(css|sc|emotion|styled|tw|svelte)-/,
+    /^\\.[a-z]{1,3}[A-Z][a-zA-Z]{2,}$/,
+    /^\\.[a-f0-9]{5,}$/i,
+    /^\\._/,
+    // State classes: *-open, *-active, *-hover, *-visible, *-show, etc.
+    /-(open|opened|active|hover|hovered|focus|focused|visible|show|shown|selected|highlighted|pressed|entered|expanded|collapsed)$/i,
+    // Ant Design state classes
+    /^\\.(ant|antd)-.*-(open|active|focused|selected|checked|disabled|loading)$/,
+    /^\\.ant-dropdown-open$/,
+    // Bootstrap state classes
+    /^\\.(show|open|active|hover|focus|collapse|collapsing|fade)$/,
+    // Material UI state classes
+    /^\\.Mui-(active|focused|selected|expanded|checked|disabled|error)/,
+    // Element Plus / Vuetify / general frameworks
+    /^\\.(is|el|v)-[a-z]+-?(open|active|focus|hover|visible|show|selected|expanded)/i,
+    // Generic state patterns
+    /^\\.(active|open|show|shown|visible|hover|focus|selected|expanded|collapsed|pressed|entered)$/i,
+    // aria-state driven class toggles (common pattern)
+    /^\\.\\[aria-/,
+  ];
+
+  var selectorWhitelist = [
+    /^#/,                      // IDs
+    /data-testid/,             // test IDs
+    /data-test/,
+    /data-cy/,
+    /\\[name=/,                 // name attributes
+    /\\[aria-label=/,           // accessibility
+    /\\[role=/,
+    /\\[href=/,                 // links
+    /\\[placeholder=/,          // inputs
+  ];
+
+  function getSelector(el) {
+    if (!el || !el.tagName) return 'unknown';
+
+    // Walk up to a meaningful element
+    var useful = closestUseful(el);
+
+    try {
+      if (typeof CssSelectorGenerator !== 'undefined' && CssSelectorGenerator.getCssSelector) {
+        return CssSelectorGenerator.getCssSelector(useful, {
+          selectors: ['id', 'attribute', 'class', 'tag', 'nthoftype'],
+          blacklist: cssInJsBlacklist,
+          whitelist: selectorWhitelist,
+          combineWithinSelector: true,
+          combineBetweenSelectors: true,
+          includeTag: false,
+          maxCombinations: 50,
+          maxCandidates: 10,
+        });
+      }
+    } catch (e) {
+      // library failed — use basic fallback
+    }
+
+    // Fallback: tag name
+    return useful.tagName.toLowerCase();
+  }
+
+  // Hover-specific selector: excludes dynamically-added state classes
+  // so the selector stays valid BEFORE the hover interaction.
+  function getHoverSelector(el) {
+    if (!el || !el.tagName) return 'unknown';
+
+    try {
+      if (typeof CssSelectorGenerator !== 'undefined' && CssSelectorGenerator.getCssSelector) {
+        return CssSelectorGenerator.getCssSelector(el, {
+          selectors: ['id', 'attribute', 'class', 'tag', 'nthoftype'],
+          blacklist: hoverStateBlacklist,
+          whitelist: selectorWhitelist,
+          combineWithinSelector: true,
+          combineBetweenSelectors: true,
+          includeTag: false,
+          maxCombinations: 50,
+          maxCandidates: 10,
+        });
+      }
+    } catch (e) {
+      // library failed — use basic fallback
+    }
+
+    return el.tagName.toLowerCase();
+  }
+
+  function send(action) {
+    action.timestamp = Date.now();
+    action.url = location.href;
+    try {
+      if (typeof window.__sessionsnap_push === 'function') {
+        window.__sessionsnap_push(JSON.stringify(action));
+      }
+    } catch (e) {
+      // silently ignore if binding is not yet available
+    }
+  }
+
+  // --- Click ---
+  document.addEventListener('click', function(e) {
+    var el = e.target;
+    send({
+      type: 'click',
+      selector: getSelector(el),
+      tag: el.tagName.toLowerCase(),
+      text: (el.innerText || '').slice(0, 100).trim(),
+      x: e.clientX,
+      y: e.clientY,
+    });
+  }, true);
+
+  // --- Double click ---
+  document.addEventListener('dblclick', function(e) {
+    var el = e.target;
+    send({
+      type: 'dblclick',
+      selector: getSelector(el),
+      tag: el.tagName.toLowerCase(),
+      text: (el.innerText || '').slice(0, 100).trim(),
+      x: e.clientX,
+      y: e.clientY,
+    });
+  }, true);
+
+  // --- Hover (debounced 200ms, interactive/hoverable elements only) ---
+  // mouseenter does NOT bubble — use mouseover which bubbles up to document.
+  // Dedicated closestHoverable: walks further up (8 levels), considers
+  // nav items, menu triggers, roles, aria attributes — not just INTERACTIVE tags.
+  var HOVERABLE = ['A','BUTTON','INPUT','TEXTAREA','SELECT','LABEL','FORM','DETAILS','SUMMARY','LI','NAV','HEADER','FOOTER'];
+  var HOVER_ROLES = ['menuitem','tab','option','treeitem','listbox','menu','tablist','toolbar','tooltip'];
+  function closestHoverable(el) {
+    var cur = el;
+    for (var i = 0; i < 8 && cur && cur !== document.body; i++) {
+      if (HOVERABLE.indexOf(cur.tagName) !== -1) return cur;
+      if (cur.id) return cur;
+      if (cur.getAttribute) {
+        if (cur.getAttribute('data-testid') || cur.getAttribute('data-test') || cur.getAttribute('data-cy')) return cur;
+        var role = cur.getAttribute('role');
+        if (role && HOVER_ROLES.indexOf(role) !== -1) return cur;
+        if (cur.getAttribute('aria-haspopup') || cur.getAttribute('aria-expanded') !== null) return cur;
+        if (cur.getAttribute('data-toggle') || cur.getAttribute('data-bs-toggle')) return cur;
+      }
+      cur = cur.parentElement;
+    }
+    return el;
+  }
+
+  var hoverQueue = [];
+  var hoverFlushTimer = null;
+  var lastHoverEl = null;
+  var HOVER_DEBOUNCE = 150;
+  var HOVER_FLUSH_INTERVAL = 300;
+
+  function flushHoverQueue() {
+    if (hoverQueue.length === 0) return;
+    // Send all queued hovers (deduplicated by element reference)
+    var seen = [];
+    for (var i = 0; i < hoverQueue.length; i++) {
+      var item = hoverQueue[i];
+      if (seen.indexOf(item.el) === -1) {
+        seen.push(item.el);
+        send({
+          type: 'hover',
+          selector: getHoverSelector(item.el),
+          tag: item.el.tagName.toLowerCase(),
+          text: (item.el.innerText || '').slice(0, 100).trim(),
+          x: item.x,
+          y: item.y,
+        });
+      }
+    }
+    hoverQueue = [];
+  }
+
+  var hoverTimer = null;
+  document.addEventListener('mouseover', function(e) {
+    var el = e.target;
+    if (!el || !el.tagName) return;
+    var useful = closestHoverable(el);
+    // Only record if we found a meaningful parent or the element itself is hoverable
+    if (useful === el && HOVERABLE.indexOf(el.tagName) === -1 && !(el.getAttribute && el.getAttribute('role'))) return;
+    // Skip if same element as last hover (unless element was detached from DOM)
+    if (useful === lastHoverEl && useful.isConnected !== false) return;
+
+    // Record mouse's actual position for hover (e.clientX, e.clientY)
+    // This captures where the user actually moved the mouse
+    var x = Math.round(e.clientX);
+    var y = Math.round(e.clientY);
+
+    var coords = { el: useful, x: x, y: y };
+
+    // Debounce per transition: wait HOVER_DEBOUNCE ms, then queue
+    if (hoverTimer) clearTimeout(hoverTimer);
+    hoverTimer = setTimeout(function() {
+      lastHoverEl = useful;
+      hoverQueue.push(coords);
+      // Schedule a flush if not already pending
+      if (!hoverFlushTimer) {
+        hoverFlushTimer = setTimeout(function() {
+          hoverFlushTimer = null;
+          flushHoverQueue();
+        }, HOVER_FLUSH_INTERVAL);
+      }
+    }, HOVER_DEBOUNCE);
+  }, true);
+
+  // Also flush on click/navigation so queued hovers are not lost
+  document.addEventListener('click', function() {
+    if (hoverTimer) { clearTimeout(hoverTimer); hoverTimer = null; }
+    flushHoverQueue();
+  }, true);
+  window.addEventListener('beforeunload', function() {
+    flushHoverQueue();
+  });
+
+  // --- Mouse Movement (strict tracking for precise replay) ---
+  // Record all mouse movements with debouncing to capture precise path
+  var mouseMoveQueue = [];
+  var mouseMoveFlushTimer = null;
+  var lastMouseMoveTime = 0;
+  var MOUSE_MOVE_DEBOUNCE = 16; // ~60fps (16ms between moves)
+  var MOUSE_MOVE_FLUSH_INTERVAL = 100; // Flush queue every 100ms
+
+  function flushMouseMoveQueue() {
+    if (mouseMoveQueue.length === 0) return;
+    // Send all queued mouse movements
+    for (var i = 0; i < mouseMoveQueue.length; i++) {
+      var move = mouseMoveQueue[i];
+      send({
+        type: 'mousemove',
+        x: move.x,
+        y: move.y,
+      });
+    }
+    mouseMoveQueue = [];
+  }
+
+  var mouseMoveTimer = null;
+  document.addEventListener('mousemove', function(e) {
+    var now = Date.now();
+    // Throttle to ~60fps (16ms minimum between moves)
+    if (now - lastMouseMoveTime < MOUSE_MOVE_DEBOUNCE) return;
+    lastMouseMoveTime = now;
+
+    var x = Math.round(e.clientX);
+    var y = Math.round(e.clientY);
+
+    mouseMoveQueue.push({ x: x, y: y });
+
+    // Schedule flush if not already pending
+    if (!mouseMoveFlushTimer) {
+      mouseMoveFlushTimer = setTimeout(function() {
+        mouseMoveFlushTimer = null;
+        flushMouseMoveQueue();
+      }, MOUSE_MOVE_FLUSH_INTERVAL);
+    }
+  }, true);
+
+  // Flush mouse moves on click/navigation/unload
+  document.addEventListener('click', function() {
+    if (mouseMoveTimer) { clearTimeout(mouseMoveTimer); mouseMoveTimer = null; }
+    flushMouseMoveQueue();
+  }, true);
+  window.addEventListener('beforeunload', function() {
+    flushMouseMoveQueue();
+  });
+
+  // --- Input (debounced 500ms per element) ---
+  var inputTimers = new WeakMap();
+  document.addEventListener('input', function(e) {
+    var el = e.target;
+    if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.tagName === 'SELECT') {
+      if (inputTimers.has(el)) clearTimeout(inputTimers.get(el));
+      inputTimers.set(el, setTimeout(function() {
+        send({
+          type: 'input',
+          selector: getSelector(el),
+          tag: el.tagName.toLowerCase(),
+          inputType: el.type || '',
+          value: el.type === 'password' ? '***' : el.value,
+        });
+      }, 500));
+    }
+  }, true);
+
+  // --- Select / Checkbox / Radio change ---
+  document.addEventListener('change', function(e) {
+    var el = e.target;
+    if (el.tagName === 'SELECT') {
+      send({
+        type: 'select',
+        selector: getSelector(el),
+        value: el.value,
+        text: (el.options[el.selectedIndex] || {}).text || '',
+      });
+    } else if (el.tagName === 'INPUT' && (el.type === 'checkbox' || el.type === 'radio')) {
+      send({
+        type: 'checkbox',
+        selector: getSelector(el),
+        inputType: el.type,
+        checked: el.checked,
+        name: el.name || '',
+        value: el.value || '',
+      });
+    } else if (el.tagName === 'INPUT' && el.type === 'file') {
+      var names = [];
+      if (el.files) {
+        for (var i = 0; i < el.files.length; i++) names.push(el.files[i].name);
+      }
+      send({
+        type: 'file',
+        selector: getSelector(el),
+        fileNames: names,
+        fileCount: names.length,
+      });
+    }
+  }, true);
+
+  // --- Keydown (special keys & modifier combos only) ---
+  var SPECIAL_KEYS = ['Enter','Escape','Tab','Backspace','Delete','ArrowUp','ArrowDown','ArrowLeft','ArrowRight','Home','End','PageUp','PageDown','F1','F2','F3','F4','F5','F6','F7','F8','F9','F10','F11','F12'];
+  document.addEventListener('keydown', function(e) {
+    var isSpecial = SPECIAL_KEYS.indexOf(e.key) !== -1;
+    var hasModifier = e.ctrlKey || e.metaKey || e.altKey;
+    if (!isSpecial && !hasModifier) return;
+    // Skip bare modifier key presses (Control, Meta, Alt, Shift alone)
+    if (['Control','Meta','Alt','Shift'].indexOf(e.key) !== -1) return;
+    var combo = '';
+    if (e.ctrlKey) combo += 'Ctrl+';
+    if (e.metaKey) combo += 'Meta+';
+    if (e.altKey) combo += 'Alt+';
+    if (e.shiftKey && !isSpecial) combo += 'Shift+';
+    combo += e.key;
+    var target = e.target;
+    send({
+      type: 'keydown',
+      key: e.key,
+      combo: combo,
+      selector: getSelector(target),
+      tag: target.tagName.toLowerCase(),
+    });
+  }, true);
+
+  // --- Form submit ---
+  document.addEventListener('submit', function(e) {
+    var form = e.target;
+    send({
+      type: 'submit',
+      selector: getSelector(form),
+      action: form.action || '',
+      method: form.method || 'get',
+    });
+  }, true);
+
+  // --- Scroll (debounced 400ms, supports both window and inner element scrolls) ---
+  // scroll events do NOT bubble, but capture phase on document catches them all.
+  var scrollTimers = new WeakMap();
+  var windowScrollTimer = null;
+  document.addEventListener('scroll', function(e) {
+    var target = e.target;
+
+    // Window / document-level scroll
+    if (target === document || target === document.documentElement) {
+      if (windowScrollTimer) clearTimeout(windowScrollTimer);
+      windowScrollTimer = setTimeout(function() {
+        send({
+          type: 'scroll',
+          target: 'window',
+          scrollX: Math.round(window.scrollX || window.pageXOffset || 0),
+          scrollY: Math.round(window.scrollY || window.pageYOffset || 0),
+          scrollHeight: document.documentElement.scrollHeight,
+          viewportHeight: window.innerHeight,
+        });
+      }, 400);
+      return;
+    }
+
+    // Inner element scroll — must be an element with overflow
+    if (target && target.nodeType === 1) {
+      if (scrollTimers.has(target)) clearTimeout(scrollTimers.get(target));
+      scrollTimers.set(target, setTimeout(function() {
+        send({
+          type: 'scroll',
+          target: 'element',
+          selector: getSelector(target),
+          tag: target.tagName.toLowerCase(),
+          scrollLeft: Math.round(target.scrollLeft),
+          scrollTop: Math.round(target.scrollTop),
+          scrollWidth: target.scrollWidth,
+          scrollHeight: target.scrollHeight,
+          clientWidth: target.clientWidth,
+          clientHeight: target.clientHeight,
+        });
+      }, 400));
+    }
+  }, true);
+
+  // --- SPA navigation tracking ---
+  var lastUrl = location.href;
+  function checkNav() {
+    if (location.href !== lastUrl) {
+      send({ type: 'navigation', from: lastUrl, to: location.href });
+      lastUrl = location.href;
+    }
+  }
+  var target = document.body || document.documentElement;
+  if (target) {
+    var obs = new MutationObserver(checkNav);
+    obs.observe(target, { childList: true, subtree: true });
+  }
+  window.addEventListener('popstate', checkNav);
+  window.addEventListener('hashchange', checkNav);
+
+  console.log('[sessionsnap] Action recorder active (12 action types).');
+})();
+`;
+
+// Full script to inject: library + recorder
+const FULL_INJECT_SCRIPT = CSS_SELECTOR_GENERATOR_LIB + ';\n' + INJECTED_SCRIPT;
+
+export function getInjectedScript() {
+  return FULL_INJECT_SCRIPT;
+}
+
+function describeAction(action) {
+  switch (action.type) {
+    case 'click':
+      return `click ${action.selector}${action.text ? ' "' + action.text.slice(0, 40) + '"' : ''}`;
+    case 'dblclick':
+      return `dblclick ${action.selector}${action.text ? ' "' + action.text.slice(0, 40) + '"' : ''}`;
+    case 'hover':
+      return `hover ${action.selector}${action.text ? ' "' + action.text.slice(0, 40) + '"' : ''} (${action.x}, ${action.y})`;
+    case 'mousemove':
+      return `mousemove → (${action.x}, ${action.y})`;
+    case 'input':
+      return `input ${action.selector} → ${action.value === '***' ? '(password)' : '"' + String(action.value).slice(0, 30) + '"'}`;
+    case 'select':
+      return `select ${action.selector} → "${action.text || action.value}"`;
+    case 'checkbox':
+      return `checkbox ${action.selector} ${action.checked ? '☑' : '☐'} (${action.inputType})`;
+    case 'keydown':
+      return `keydown [${action.combo}] on ${action.selector}`;
+    case 'submit':
+      return `submit ${action.selector}`;
+    case 'scroll':
+      if (action.target === 'element') return `scroll ${action.selector} → (${action.scrollLeft}, ${action.scrollTop})`;
+      return `scroll window → (${action.scrollX}, ${action.scrollY})`;
+    case 'file':
+      return `file ${action.selector} → ${action.fileCount} file(s): ${(action.fileNames || []).join(', ')}`;
+    case 'navigation':
+      return `navigate → ${action.to}`;
+    default:
+      return `${action.type}`;
+  }
+}
+
+/**
+ * Set up action recording on a page.
+ *
+ * Actions are immediately:
+ *   1. Pushed to an in-memory array
+ *   2. Written to disk with writeFileSync (crash-safe)
+ *   3. Logged to the console in real-time
+ *
+ * @param {object} page - Puppeteer or Playwright page
+ * @param {'puppeteer'|'playwright'} runner
+ * @param {string} profileDir - Absolute path to the profile directory
+ * @param {string} [label='capture'] - Label for the actions file
+ * @returns {Promise<{ getActions: () => Array, filePath: string }>}
+ */
+export async function setupRecorder(page, runner, profileDir, label = 'capture') {
+  const actions = [];
+
+  // Create the actions file path upfront
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const filePath = join(profileDir, `actions-${label}-${ts}.json`);
+
+  // Ensure profile dir exists (sync for safety)
+  mkdirSync(profileDir, { recursive: true });
+
+  // Write initial empty file so it exists even if no actions are recorded
+  writeFileSync(filePath, '[]', 'utf-8');
+
+  // 1. Expose the push callback — survives navigations
+  await page.exposeFunction('__sessionsnap_push', (jsonStr) => {
+    try {
+      const action = JSON.parse(jsonStr);
+      actions.push(action);
+
+      // IMMEDIATELY write to disk — survives any crash/SIGINT/kill
+      try {
+        writeFileSync(filePath, JSON.stringify(actions, null, 2), 'utf-8');
+      } catch { /* disk write failed — at least we have in-memory */ }
+
+      // Real-time log
+      const desc = describeAction(action);
+      console.log(`[sessionsnap] 🔴 REC [${actions.length}] ${desc}`);
+    } catch { /* malformed JSON — skip */ }
+  });
+
+  // 2. Register script for all future new-document events
+  if (runner === 'puppeteer') {
+    await page.evaluateOnNewDocument(FULL_INJECT_SCRIPT);
+  } else {
+    await page.context().addInitScript(FULL_INJECT_SCRIPT);
+  }
+
+  // 3. Inject into the current document right now
+  await page.evaluate(FULL_INJECT_SCRIPT).catch(() => {});
+
+  console.log(`[sessionsnap] Action recorder enabled. File: ${filePath}`);
+
+  return {
+    getActions() {
+      return actions;
+    },
+    get count() {
+      return actions.length;
+    },
+    filePath,
+  };
+}