browser-pilot 0.0.5 → 0.0.7

package/dist/cli.cjs

@@ -1464,6 +1464,13 @@ var Page = class {
     this.cdp = cdp;
     this.batchExecutor = new BatchExecutor(this);
   }
+  /**
+   * Get the underlying CDP client for advanced operations.
+   * Use with caution - prefer high-level Page methods when possible.
+   */
+  get cdpClient() {
+    return this.cdp;
+  }
   /**
    * Initialize the page (enable required CDP domains)
    */
@@ -3460,12 +3467,1007 @@ COMMON ACTIONS
   snapshot    {"action":"snapshot"}
   screenshot  {"action":"screenshot"}
 
+RECORDING (FOR HUMANS)
+  Want to create automations by demonstrating instead of coding?
+  Use 'bp record' to capture your browser interactions as replayable JSON:
+
+    bp record                 # Record from local Chrome
+    bp exec --file login.json # Replay the recording
+
+  Great for creating initial automation scripts that AI agents can refine.
+
 Run 'bp actions' for the complete action reference.
 `;
 async function quickstartCommand() {
   console.log(QUICKSTART);
 }
 
+// src/recording/aggregator.ts
+var INPUT_DEBOUNCE_MS = 300;
+var NAVIGATION_DEBOUNCE_MS = 500;
+function selectBestSelectors(candidates) {
+  const qualityOrder = {
+    "role-name": 0,
+    text: 1,
+    "aria-label": 2,
+    testid: 3,
+    "stable-attr": 4,
+    id: 5,
+    "name-attr": 6,
+    "css-path": 7
+  };
+  const sorted = [...candidates].sort((a, b) => {
+    const aOrder = qualityOrder[a.quality] ?? 8;
+    const bOrder = qualityOrder[b.quality] ?? 8;
+    return aOrder - bOrder;
+  });
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const candidate of sorted) {
+    if (!seen.has(candidate.selector)) {
+      seen.add(candidate.selector);
+      result.push(candidate.selector);
+    }
+  }
+  return result;
+}
+function generateAnnotation(event) {
+  const { kind, element, url } = event;
+  const name = element?.accessibleName || element?.text || element?.ariaLabel;
+  const role = element?.computedRole || element?.role || element?.tag || "";
+  switch (kind) {
+    case "click":
+      if (name && role) {
+        return `Clicked '${name}' ${role}`;
+      } else if (name) {
+        return `Clicked '${name}'`;
+      } else if (role) {
+        return `Clicked ${role}`;
+      }
+      return "Clicked element";
+    case "dblclick":
+      if (name && role) {
+        return `Double-clicked '${name}' ${role}`;
+      }
+      return "Double-clicked element";
+    case "input":
+      if (name) {
+        return `Filled '${name}' with value`;
+      }
+      return "Filled input with value";
+    case "change":
+      if (element?.type === "checkbox" || element?.type === "radio") {
+        const action = event.checked ? "Checked" : "Unchecked";
+        if (name) {
+          return `${action} '${name}' ${element.type}`;
+        }
+        return `${action} ${element.type}`;
+      }
+      if (element?.tag === "select") {
+        if (name) {
+          return `Selected option in '${name}'`;
+        }
+        return "Selected option";
+      }
+      if (name) {
+        return `Changed '${name}'`;
+      }
+      return "Changed element";
+    case "submit":
+      if (name) {
+        return `Submitted '${name}' form`;
+      }
+      return "Submitted form";
+    case "keydown":
+      if (event.key === "Enter") {
+        return "Pressed Enter";
+      }
+      return `Pressed ${event.key}`;
+    case "navigation":
+      return `Navigated to ${url}`;
+    default:
+      if (name) {
+        return `${kind} on '${name}'`;
+      }
+      return `${kind} on element`;
+  }
+}
+function debounceInputEvents(events) {
+  const result = [];
+  for (let i = 0; i < events.length; i++) {
+    const event = events[i];
+    if (event.kind !== "input") {
+      result.push(event);
+      continue;
+    }
+    const primarySelector = event.selectors[0]?.selector;
+    if (!primarySelector) {
+      result.push(event);
+      continue;
+    }
+    let finalEvent = event;
+    let j = i + 1;
+    while (j < events.length) {
+      const nextEvent = events[j];
+      if (nextEvent.timestamp - finalEvent.timestamp > INPUT_DEBOUNCE_MS) {
+        break;
+      }
+      if (nextEvent.kind !== "input") {
+        break;
+      }
+      const nextPrimarySelector = nextEvent.selectors[0]?.selector;
+      if (nextPrimarySelector !== primarySelector) {
+        break;
+      }
+      finalEvent = nextEvent;
+      j++;
+    }
+    i = j - 1;
+    result.push(finalEvent);
+  }
+  return result;
+}
+function debounceNavigationEvents(events) {
+  const result = [];
+  for (let i = 0; i < events.length; i++) {
+    const event = events[i];
+    if (event.kind !== "navigation") {
+      result.push(event);
+      continue;
+    }
+    let finalEvent = event;
+    let j = i + 1;
+    while (j < events.length) {
+      const nextEvent = events[j];
+      if (nextEvent.timestamp - finalEvent.timestamp > NAVIGATION_DEBOUNCE_MS) {
+        break;
+      }
+      if (nextEvent.kind !== "navigation") {
+        break;
+      }
+      finalEvent = nextEvent;
+      j++;
+    }
+    i = j - 1;
+    result.push(finalEvent);
+  }
+  return result;
+}
+function insertNavigationSteps(events, startUrl) {
+  const result = [];
+  let lastUrl = startUrl || null;
+  for (const event of events) {
+    if (lastUrl !== null && event.url !== lastUrl) {
+      result.push({
+        kind: "navigation",
+        timestamp: event.timestamp,
+        url: event.url,
+        selectors: []
+      });
+    }
+    result.push(event);
+    lastUrl = event.url;
+  }
+  return result;
+}
+function buildElementMeta(event) {
+  const el = event.element;
+  if (!el) return void 0;
+  return {
+    role: el.computedRole || el.role,
+    name: el.accessibleName || el.text || el.ariaLabel,
+    tag: el.tag
+  };
+}
+function eventToStep(event) {
+  const selectors = selectBestSelectors(event.selectors);
+  const elementMeta = buildElementMeta(event);
+  const annotation = generateAnnotation(event);
+  switch (event.kind) {
+    case "click":
+    case "dblclick":
+      if (selectors.length === 0) return null;
+      return {
+        action: "click",
+        selector: selectors.length === 1 ? selectors[0] : selectors,
+        element: elementMeta,
+        annotation
+      };
+    case "input":
+      if (selectors.length === 0) return null;
+      return {
+        action: "fill",
+        selector: selectors.length === 1 ? selectors[0] : selectors,
+        value: event.value ?? "",
+        element: elementMeta,
+        annotation
+      };
+    case "change": {
+      if (selectors.length === 0) return null;
+      const element = event.element;
+      const tag = element?.tag;
+      const type = element?.type?.toLowerCase();
+      if (tag === "select") {
+        return {
+          action: "select",
+          selector: selectors.length === 1 ? selectors[0] : selectors,
+          value: event.value ?? "",
+          element: elementMeta,
+          annotation
+        };
+      }
+      if (type === "checkbox" || type === "radio") {
+        return {
+          action: event.checked ? "check" : "uncheck",
+          selector: selectors.length === 1 ? selectors[0] : selectors,
+          element: elementMeta,
+          annotation
+        };
+      }
+      return {
+        action: "fill",
+        selector: selectors.length === 1 ? selectors[0] : selectors,
+        value: event.value ?? "",
+        element: elementMeta,
+        annotation
+      };
+    }
+    case "keydown":
+      if (event.key === "Enter") {
+        if (selectors.length === 0) return null;
+        return {
+          action: "submit",
+          selector: selectors.length === 1 ? selectors[0] : selectors,
+          method: "enter",
+          element: elementMeta,
+          annotation
+        };
+      }
+      return null;
+    case "submit":
+      if (selectors.length === 0) return null;
+      return {
+        action: "submit",
+        selector: selectors.length === 1 ? selectors[0] : selectors,
+        element: elementMeta,
+        annotation
+      };
+    case "navigation":
+      return {
+        action: "goto",
+        url: event.url,
+        annotation
+      };
+    default:
+      return null;
+  }
+}
+function deduplicateSteps(steps) {
+  const result = [];
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const prevStep = result[result.length - 1];
+    if (step.action === "submit" && prevStep?.action === "submit" && JSON.stringify(step.selector) === JSON.stringify(prevStep.selector)) {
+      continue;
+    }
+    result.push(step);
+  }
+  return result;
+}
+function aggregateEvents(events, startUrl) {
+  if (events.length === 0) return [];
+  let processed = insertNavigationSteps(events, startUrl);
+  processed = debounceNavigationEvents(processed);
+  processed = debounceInputEvents(processed);
+  const steps = [];
+  for (const event of processed) {
+    const step = eventToStep(event);
+    if (step) {
+      steps.push(step);
+    }
+  }
+  return deduplicateSteps(steps);
+}
+
+// src/recording/script.ts
+var RECORDER_BINDING_NAME = "__recorder";
+var RECORDER_SCRIPT = `(function() {
+  // Guard against multiple installations
+  if (window.__recorderInstalled) return;
+  window.__recorderInstalled = true;
+
+  const BINDING_NAME = '__recorder';
+
+  // Safe JSON stringify
+  function safeJson(obj) {
+    try {
+      return JSON.stringify(obj);
+    } catch (e) {
+      return JSON.stringify({ error: 'unserializable' });
+    }
+  }
+
+  // Send event to CDP client via binding
+  function sendEvent(payload) {
+    try {
+      if (typeof window[BINDING_NAME] === 'function') {
+        window[BINDING_NAME](safeJson(payload));
+      }
+    } catch (e) {
+      // Binding not ready, ignore
+    }
+  }
+
+  // CSS escape for identifiers
+  function cssEscape(str) {
+    return String(str).replace(/([\\[\\]#.:>+~=|^$*!"'(){}])/g, '\\\\$1');
+  }
+
+  // Check if selector is unique in document
+  function isUnique(selector, root) {
+    try {
+      return (root || document).querySelectorAll(selector).length === 1;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  // Get stable attribute selector (data-testid, aria-label, name, etc.)
+  function getStableAttrSelector(el) {
+    if (!el || el.nodeType !== 1) return null;
+    const attrs = ['data-testid', 'data-test', 'data-qa', 'aria-label', 'name'];
+    for (const attr of attrs) {
+      const val = el.getAttribute(attr);
+      if (val && val.length <= 200) {
+        const escaped = val.replace(/"/g, '\\\\"');
+        return '[' + attr + '="' + escaped + '"]';
+      }
+    }
+    return null;
+  }
+
+  // Get ID selector
+  function getIdSelector(el) {
+    if (!el || !el.id || el.id.length > 100) return null;
+    // Skip dynamic-looking IDs
+    if (/^[0-9]|^:/.test(el.id)) return null;
+    return '#' + cssEscape(el.id);
+  }
+
+  // Build CSS path for element
+  function buildCssPath(el) {
+    if (!el || el.nodeType !== 1) return null;
+    const parts = [];
+    let cur = el;
+
+    for (let depth = 0; cur && cur !== document.body && depth < 8; depth++) {
+      let part = cur.tagName.toLowerCase();
+
+      // If ID exists and looks stable, use it and stop
+      if (cur.id && !/^[0-9]|^:/.test(cur.id) && cur.id.length <= 50) {
+        part = '#' + cssEscape(cur.id);
+        parts.unshift(part);
+        break;
+      }
+
+      // Add stable classes (skip dynamic ones)
+      const classes = Array.from(cur.classList || [])
+        .filter(c => c.length < 40 && !/^css-|^_|^[0-9]/.test(c))
+        .slice(0, 2);
+      if (classes.length) {
+        part += '.' + classes.map(cssEscape).join('.');
+      }
+
+      // Add position if siblings have same tag
+      const parent = cur.parentElement;
+      if (parent) {
+        const sameTag = Array.from(parent.children).filter(c => c.tagName === cur.tagName);
+        if (sameTag.length > 1) {
+          const idx = sameTag.indexOf(cur) + 1;
+          part += ':nth-of-type(' + idx + ')';
+        }
+      }
+
+      parts.unshift(part);
+      cur = cur.parentElement;
+    }
+
+    return parts.join(' > ');
+  }
+
+  // Generate selector candidates ordered by quality
+  function getSelectorCandidates(el) {
+    const candidates = [];
+
+    // Get semantic info for role-based selectors
+    const role = getRole(el);
+    const name = getAccessibleName(el);
+
+    // 1. Role + name selector (highest priority for semantic elements)
+    if (role && name) {
+      const escapedName = name.replace(/'/g, "\\\\'");
+      candidates.push({
+        selector: "role=" + role + "[name='" + escapedName + "']",
+        quality: 'role-name'
+      });
+    }
+
+    // 2. Text-based selector (for buttons, links, menuitems)
+    if (name && ['button', 'link', 'menuitem'].includes(role)) {
+      candidates.push({
+        selector: "text=" + name,
+        quality: 'text'
+      });
+    }
+
+    // 3. aria-label attribute selector
+    const ariaLabel = el.getAttribute('aria-label');
+    if (ariaLabel) {
+      const escaped = ariaLabel.replace(/"/g, '\\\\"');
+      candidates.push({
+        selector: '[aria-label="' + escaped + '"]',
+        quality: 'aria-label'
+      });
+    }
+
+    // 4. Stable attributes (testid, name)
+    const stableAttr = getStableAttrSelector(el);
+    if (stableAttr) {
+      candidates.push({ selector: stableAttr, quality: 'stable-attr' });
+    }
+
+    // 5. ID selector
+    const idSel = getIdSelector(el);
+    if (idSel) {
+      candidates.push({ selector: idSel, quality: 'id' });
+    }
+
+    // 6. CSS path (fallback)
+    const cssPath = buildCssPath(el);
+    if (cssPath) {
+      candidates.push({ selector: cssPath, quality: 'css-path' });
+    }
+
+    return candidates;
+  }
+
+  // Compute accessible name per W3C AccName spec
+  // Priority: aria-labelledby > aria-label > label > title > content > alt > placeholder
+  function getAccessibleName(el) {
+    if (!el || el.nodeType !== 1) return null;
+
+    // 1. aria-labelledby
+    const labelledBy = el.getAttribute('aria-labelledby');
+    if (labelledBy) {
+      const labels = labelledBy.split(/\\s+/)
+        .map(function(id) {
+          const ref = document.getElementById(id);
+          return ref ? ref.textContent : null;
+        })
+        .filter(Boolean);
+      if (labels.length) return labels.join(' ').trim().slice(0, 100);
+    }
+
+    // 2. aria-label
+    const ariaLabel = el.getAttribute('aria-label');
+    if (ariaLabel) return ariaLabel.trim().slice(0, 100);
+
+    // 3. Native <label> for form elements
+    if (el.labels && el.labels.length) {
+      const labelTexts = Array.from(el.labels)
+        .map(function(l) { return l.textContent; })
+        .filter(Boolean);
+      if (labelTexts.length) return labelTexts.join(' ').trim().slice(0, 100);
+    }
+
+    // 4. title attribute
+    const title = el.getAttribute('title');
+    if (title) return title.trim().slice(0, 100);
+
+    // 5. Content for buttons, links, summary
+    const tag = el.tagName.toLowerCase();
+    const role = el.getAttribute('role');
+    if (['button', 'a', 'summary'].includes(tag) || role === 'button' || role === 'link' || role === 'menuitem') {
+      const text = (el.textContent || '').trim();
+      if (text) return text.slice(0, 100);
+    }
+
+    // 6. alt for images
+    if (tag === 'img') {
+      const alt = el.getAttribute('alt');
+      if (alt) return alt.trim().slice(0, 100);
+    }
+
+    // 7. placeholder for inputs
+    if (['input', 'textarea'].includes(tag)) {
+      const placeholder = el.getAttribute('placeholder');
+      if (placeholder) return placeholder.trim().slice(0, 100);
+    }
+
+    return null;
+  }
+
+  // Get explicit ARIA role or implicit role from HTML tag
+  function getRole(el) {
+    if (!el || el.nodeType !== 1) return null;
+
+    // 1. Explicit role attribute
+    const explicitRole = el.getAttribute('role');
+    if (explicitRole) return explicitRole;
+
+    // 2. Implicit role from tag/type
+    const tag = el.tagName.toLowerCase();
+    const type = (el.getAttribute('type') || '').toLowerCase();
+
+    // Input types to roles
+    if (tag === 'input') {
+      var inputRoles = {
+        'button': 'button',
+        'submit': 'button',
+        'reset': 'button',
+        'image': 'button',
+        'checkbox': 'checkbox',
+        'radio': 'radio',
+        'range': 'slider',
+        'search': 'searchbox'
+      };
+      if (inputRoles[type]) return inputRoles[type];
+      // text, email, tel, url, number, password all map to textbox
+      return 'textbox';
+    }
+
+    // Other tags with implicit roles
+    var tagRoles = {
+      'button': 'button',
+      'select': 'combobox',
+      'textarea': 'textbox',
+      'nav': 'navigation',
+      'main': 'main',
+      'header': 'banner',
+      'footer': 'contentinfo',
+      'aside': 'complementary',
+      'article': 'article',
+      'ul': 'list',
+      'ol': 'list',
+      'li': 'listitem',
+      'table': 'table',
+      'tr': 'row',
+      'td': 'cell',
+      'th': 'columnheader',
+      'form': 'form',
+      'img': 'img',
+      'dialog': 'dialog',
+      'menu': 'menu',
+      'summary': 'button'
+    };
+    if (tagRoles[tag]) return tagRoles[tag];
+
+    // Anchor with href is a link
+    if (tag === 'a' && el.hasAttribute('href')) return 'link';
+
+    // Section with aria-label or aria-labelledby is a region
+    if (tag === 'section' && (el.hasAttribute('aria-label') || el.hasAttribute('aria-labelledby'))) {
+      return 'region';
+    }
+
+    return null;
+  }
+
+  // Get element summary for debugging
+  function getElementSummary(el) {
+    if (!el || el.nodeType !== 1) return null;
+    const text = (el.innerText || '').trim().replace(/\\s+/g, ' ').slice(0, 120);
+    return {
+      tag: el.tagName.toLowerCase(),
+      id: el.id || null,
+      name: el.getAttribute('name') || null,
+      type: el.getAttribute('type') || null,
+      role: el.getAttribute('role') || null,
+      ariaLabel: el.getAttribute('aria-label') || null,
+      testid: el.getAttribute('data-testid') || null,
+      text: text || null,
+      accessibleName: getAccessibleName(el),
+      computedRole: getRole(el)
+    };
+  }
+
+  // Get event target, handling shadow DOM via composedPath
+  function getEventTarget(ev) {
+    const path = ev.composedPath ? ev.composedPath() : null;
+    if (path && path.length > 0) {
+      for (const node of path) {
+        if (node && node.nodeType === 1) return node;
+      }
+    }
+    return ev.target && ev.target.nodeType === 1 ? ev.target : null;
+  }
+
+  // Find clickable ancestor (button, a, [role=button])
+  function findClickableAncestor(el) {
+    if (!el) return el;
+    const clickable = el.closest('button, a, [role="button"], [role="link"]');
+    return clickable || el;
+  }
+
+  // Check if element is a password input
+  function isPasswordInput(el) {
+    if (!el) return false;
+    const tag = el.tagName.toLowerCase();
+    if (tag !== 'input') return false;
+    const type = (el.getAttribute('type') || '').toLowerCase();
+    return type === 'password';
+  }
+
+  // Get input value, redacting passwords
+  function getInputValue(el) {
+    if (isPasswordInput(el)) return '[REDACTED]';
+    if (el.value !== undefined) return el.value;
+    if (el.isContentEditable) return el.textContent || '';
+    return '';
+  }
+
+  // Current timestamp
+  function now() { return Date.now(); }
+
+  // Click handler
+  window.addEventListener('click', function(ev) {
+    const rawTarget = getEventTarget(ev);
+    if (!rawTarget) return;
+
+    // Bubble up to clickable ancestor for better selectors
+    const el = findClickableAncestor(rawTarget);
+
+    sendEvent({
+      kind: 'click',
+      timestamp: now(),
+      url: location.href,
+      element: getElementSummary(el),
+      selectors: getSelectorCandidates(el),
+      client: { x: ev.clientX, y: ev.clientY }
+    });
+  }, true);
+
+  // Double click handler
+  window.addEventListener('dblclick', function(ev) {
+    const rawTarget = getEventTarget(ev);
+    if (!rawTarget) return;
+
+    const el = findClickableAncestor(rawTarget);
+
+    sendEvent({
+      kind: 'dblclick',
+      timestamp: now(),
+      url: location.href,
+      element: getElementSummary(el),
+      selectors: getSelectorCandidates(el),
+      client: { x: ev.clientX, y: ev.clientY }
+    });
+  }, true);
+
+  // Input handler (for text inputs, textareas, contenteditable)
+  window.addEventListener('input', function(ev) {
+    const el = getEventTarget(ev);
+    if (!el) return;
+
+    const tag = el.tagName.toLowerCase();
+    const isTexty = tag === 'input' || tag === 'textarea' || el.isContentEditable;
+    if (!isTexty) return;
+
+    sendEvent({
+      kind: 'input',
+      timestamp: now(),
+      url: location.href,
+      element: getElementSummary(el),
+      selectors: getSelectorCandidates(el),
+      value: getInputValue(el)
+    });
+  }, true);
+
+  // Change handler (for select, checkbox, radio)
+  window.addEventListener('change', function(ev) {
+    const el = getEventTarget(ev);
+    if (!el) return;
+
+    const tag = el.tagName.toLowerCase();
+    const type = (el.getAttribute('type') || '').toLowerCase();
+    const isCheckable = type === 'checkbox' || type === 'radio';
+
+    sendEvent({
+      kind: 'change',
+      timestamp: now(),
+      url: location.href,
+      element: getElementSummary(el),
+      selectors: getSelectorCandidates(el),
+      value: isCheckable ? undefined : getInputValue(el),
+      checked: isCheckable ? el.checked : undefined
+    });
+  }, true);
+
+  // Keydown handler (capture Enter for form submission)
+  window.addEventListener('keydown', function(ev) {
+    if (ev.key !== 'Enter') return;
+
+    const el = getEventTarget(ev);
+
+    sendEvent({
+      kind: 'keydown',
+      timestamp: now(),
+      url: location.href,
+      key: ev.key,
+      element: el ? getElementSummary(el) : null,
+      selectors: el ? getSelectorCandidates(el) : []
+    });
+  }, true);
+
+  // Submit handler
+  window.addEventListener('submit', function(ev) {
+    const el = getEventTarget(ev);
+
+    sendEvent({
+      kind: 'submit',
+      timestamp: now(),
+      url: location.href,
+      element: el ? getElementSummary(el) : null,
+      selectors: el ? getSelectorCandidates(el) : []
+    });
+  }, true);
+})();`;
+
+// src/recording/recorder.ts
+var Recorder = class {
+  cdp;
+  events = [];
+  recording = false;
+  startTime = 0;
+  startUrl = "";
+  bindingHandler = null;
+  constructor(cdp) {
+    this.cdp = cdp;
+  }
+  /**
+   * Check if recording is currently active.
+   */
+  get isRecording() {
+    return this.recording;
+  }
+  /**
+   * Start recording browser interactions.
+   *
+   * Sets up CDP bindings and injects the recorder script into
+   * the current page and all future navigations.
+   */
+  async start() {
+    if (this.recording) {
+      throw new Error("Recording already in progress");
+    }
+    this.events = [];
+    this.startTime = Date.now();
+    this.recording = true;
+    await this.cdp.send("Runtime.enable");
+    await this.cdp.send("Page.enable");
+    try {
+      const result = await this.cdp.send("Runtime.evaluate", {
+        expression: "location.href",
+        returnByValue: true
+      });
+      this.startUrl = result.result.value;
+    } catch {
+      this.startUrl = "";
+    }
+    await this.cdp.send("Runtime.addBinding", { name: RECORDER_BINDING_NAME });
+    await this.cdp.send("Page.addScriptToEvaluateOnNewDocument", {
+      source: RECORDER_SCRIPT
+    });
+    await this.cdp.send("Runtime.evaluate", {
+      expression: RECORDER_SCRIPT,
+      awaitPromise: false
+    });
+    this.bindingHandler = (params) => {
+      if (params["name"] === RECORDER_BINDING_NAME) {
+        this.handleBindingCall(params["payload"]);
+      }
+    };
+    this.cdp.on("Runtime.bindingCalled", this.bindingHandler);
+  }
+  /**
+   * Stop recording and return aggregated output.
+   *
+   * Returns a RecordingOutput with steps compatible with page.batch().
+   */
+  async stop() {
+    if (!this.recording) {
+      throw new Error("No recording in progress");
+    }
+    this.recording = false;
+    const duration = Date.now() - this.startTime;
+    if (this.bindingHandler) {
+      this.cdp.off("Runtime.bindingCalled", this.bindingHandler);
+      this.bindingHandler = null;
+    }
+    const steps = aggregateEvents(this.events, this.startUrl);
+    return {
+      recordedAt: new Date(this.startTime).toISOString(),
+      startUrl: this.startUrl,
+      duration,
+      steps
+    };
+  }
+  /**
+   * Get raw recorded events (for debugging).
+   */
+  getEvents() {
+    return [...this.events];
+  }
+  /**
+   * Handle incoming binding call from the browser.
+   */
+  handleBindingCall(payload) {
+    if (!this.recording) return;
+    try {
+      const event = JSON.parse(payload);
+      this.events.push(event);
+    } catch {
+    }
+  }
+};
+
+// src/cli/commands/record.ts
+var RECORD_HELP = `
+bp record - Record browser actions to JSON
+
+Usage:
+  bp record [options]
+
+Options:
+  -s, --session [id]  Session to use:
+                        - omit -s: auto-connect to local browser
+                        - -s alone: use most recent session
+                        - -s <id>: use specific session
+  -f, --file <path>   Output file (default: recording.json)
+  --timeout <ms>      Auto-stop after timeout (optional)
+  -h, --help          Show this help
+
+Examples:
+  bp record                        # Auto-connect to local Chrome
+  bp record -s                     # Use most recent session
+  bp record -s mysession           # Use specific session
+  bp record -f login.json          # Save to specific file
+  bp record --timeout 60000        # Auto-stop after 60s
+
+Recording captures: clicks, inputs, form submissions, navigation.
+Password fields are automatically redacted as [REDACTED].
+
+Press Ctrl+C to stop recording and save.
+`;
+function parseRecordArgs(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-f" || arg === "--file") {
+      options.file = args[++i];
+    } else if (arg === "--timeout") {
+      options.timeout = Number.parseInt(args[++i] ?? "", 10);
+    } else if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else if (arg === "-s" || arg === "--session") {
+      const nextArg = args[i + 1];
+      if (!nextArg || nextArg.startsWith("-")) {
+        options.useLatestSession = true;
+      }
+    }
+  }
+  return options;
+}
+async function resolveConnection(sessionId, useLatestSession, trace) {
+  if (sessionId) {
+    const session2 = await loadSession(sessionId);
+    const browser2 = await connect({
+      provider: session2.provider,
+      wsUrl: session2.wsUrl,
+      debug: trace
+    });
+    return { browser: browser2, session: session2, isNewSession: false };
+  }
+  if (useLatestSession) {
+    const session2 = await getDefaultSession();
+    if (!session2) {
+      throw new Error(
+        'No sessions found. Run "bp connect" first or use "bp record" to auto-connect.'
+      );
+    }
+    const browser2 = await connect({
+      provider: session2.provider,
+      wsUrl: session2.wsUrl,
+      debug: trace
+    });
+    return { browser: browser2, session: session2, isNewSession: false };
+  }
+  let wsUrl;
+  try {
+    wsUrl = await getBrowserWebSocketUrl("localhost:9222");
+  } catch {
+    throw new Error(
+      "Could not auto-discover browser.\nEither:\n  1. Start Chrome with: --remote-debugging-port=9222\n  2. Use an existing session: bp record -s <session-id>\n  3. Use latest session: bp record -s"
+    );
+  }
+  const browser = await connect({
+    provider: "generic",
+    wsUrl,
+    debug: trace
+  });
+  const page = await browser.page();
+  const currentUrl = await page.url();
+  const newSessionId = generateSessionId();
+  const session = {
+    id: newSessionId,
+    provider: "generic",
+    wsUrl: browser.wsUrl,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    lastActivity: (/* @__PURE__ */ new Date()).toISOString(),
+    currentUrl
+  };
+  await saveSession(session);
+  return { browser, session, isNewSession: true };
+}
+async function recordCommand(args, globalOptions) {
+  const options = parseRecordArgs(args);
+  if (options.help || globalOptions.help) {
+    console.log(RECORD_HELP);
+    return;
+  }
+  const outputFile = options.file ?? "recording.json";
+  const { browser, session, isNewSession } = await resolveConnection(
+    globalOptions.session,
+    options.useLatestSession ?? false,
+    globalOptions.trace ?? false
+  );
+  if (isNewSession) {
+    console.log(`Created new session: ${session.id}`);
+  }
+  const page = await browser.page();
+  const cdp = page.cdpClient;
+  const recorder = new Recorder(cdp);
+  let stopping = false;
+  async function stopAndSave() {
+    if (stopping) return;
+    stopping = true;
+    try {
+      const recording = await recorder.stop();
+      const fs = await import("fs/promises");
+      await fs.writeFile(outputFile, JSON.stringify(recording, null, 2));
+      const currentUrl = await page.url();
+      await updateSession(session.id, { currentUrl });
+      await browser.disconnect();
+      console.log(`
+Saved ${recording.steps.length} steps to ${outputFile}`);
+      if (globalOptions.output === "json") {
+        output(
+          {
+            success: true,
+            file: outputFile,
+            steps: recording.steps.length,
+            duration: recording.duration
+          },
+          "json"
+        );
+      }
+      process.exit(0);
+    } catch (error) {
+      console.error("Error saving recording:", error);
+      process.exit(1);
+    }
+  }
+  process.on("SIGINT", stopAndSave);
+  process.on("SIGTERM", stopAndSave);
+  if (options.timeout && options.timeout > 0) {
+    setTimeout(stopAndSave, options.timeout);
+  }
+  await recorder.start();
+  console.log(`Recording... Press Ctrl+C to stop and save to ${outputFile}`);
+  console.log(`Session: ${session.id}`);
+  console.log(`URL: ${await page.url()}`);
+}
+
 // src/cli/commands/screenshot.ts
 function parseScreenshotArgs(args) {
   const options = {};
@@ -3639,6 +4641,7 @@ Commands:
   quickstart  Getting started guide (start here!)
   connect     Create browser session
   exec        Execute actions
+  record      Record browser actions to JSON
   snapshot    Get page with element refs
   text        Extract text content
   screenshot  Take screenshot
@@ -3659,6 +4662,8 @@ Examples:
   bp exec '{"action":"goto","url":"https://example.com"}'
   bp snapshot --format text
   bp exec '{"action":"click","selector":"ref:e3"}'
+  bp record                        # Record from local browser
+  bp record -s -f login.json       # Record from latest session
 
 Run 'bp quickstart' for CLI workflow guide.
 Run 'bp actions' for complete action reference.
@@ -3761,6 +4766,9 @@ async function main() {
       case "actions":
         await actionsCommand();
         break;
+      case "record":
+        await recordCommand(remaining, options);
+        break;
       case "help":
       case "--help":
       case "-h":