browser-pilot 0.0.13 → 0.0.15

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -62,6 +72,230 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
+// src/actions/executor.ts
+var fs = __toESM(require("fs"), 1);
+var import_node_path = require("path");
+
+// src/recording/redaction.ts
+var REDACTED_VALUE = "[REDACTED]";
+var SENSITIVE_AUTOCOMPLETE_TOKENS = [
+  "current-password",
+  "new-password",
+  "one-time-code",
+  "cc-number",
+  "cc-csc",
+  "cc-exp",
+  "cc-exp-month",
+  "cc-exp-year"
+];
+function autocompleteTokens(autocomplete) {
+  if (!autocomplete) return [];
+  return autocomplete.toLowerCase().split(/\s+/).map((token) => token.trim()).filter(Boolean);
+}
+function isSensitiveFieldMetadata(metadata) {
+  if (!metadata) return false;
+  if (metadata.sensitiveValue) return true;
+  const inputType = metadata.inputType?.toLowerCase();
+  if (inputType === "password" || inputType === "hidden") {
+    return true;
+  }
+  const sensitiveAutocompleteTokens = new Set(SENSITIVE_AUTOCOMPLETE_TOKENS);
+  return autocompleteTokens(metadata.autocomplete).some(
+    (token) => sensitiveAutocompleteTokens.has(token)
+  );
+}
+function redactValueForRecording(value, metadata) {
+  if (value === void 0) return void 0;
+  return isSensitiveFieldMetadata(metadata) ? REDACTED_VALUE : value;
+}
+
+// src/browser/action-highlight.ts
+var HIGHLIGHT_STYLES = {
+  click: { outline: "3px solid rgba(229,57,53,0.8)", badge: "#e53935", marker: "crosshair" },
+  fill: { outline: "3px solid rgba(33,150,243,0.8)", badge: "#2196f3" },
+  type: { outline: "3px solid rgba(33,150,243,0.6)", badge: "#2196f3" },
+  select: { outline: "3px solid rgba(156,39,176,0.8)", badge: "#9c27b0" },
+  hover: { outline: "2px dashed rgba(158,158,158,0.5)", badge: "#9e9e9e" },
+  scroll: { outline: "none", badge: "#607d8b", marker: "arrow" },
+  navigate: { outline: "none", badge: "#4caf50" },
+  submit: { outline: "3px solid rgba(255,152,0,0.8)", badge: "#ff9800" },
+  "assert-pass": { outline: "3px solid rgba(76,175,80,0.8)", badge: "#4caf50", marker: "check" },
+  "assert-fail": { outline: "3px solid rgba(244,67,54,0.8)", badge: "#f44336", marker: "cross" },
+  evaluate: { outline: "none", badge: "#ffc107" },
+  focus: { outline: "3px dotted rgba(33,150,243,0.6)", badge: "#2196f3" }
+};
+function buildHighlightScript(options) {
+  const style = HIGHLIGHT_STYLES[options.kind];
+  const label = options.label ? options.label.slice(0, 80) : void 0;
+  const escapedLabel = label ? label.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n") : "";
+  return `(function() {
+    // Remove any existing highlight
+    var existing = document.getElementById('__bp-action-highlight');
+    if (existing) existing.remove();
+
+    var container = document.createElement('div');
+    container.id = '__bp-action-highlight';
+    container.style.cssText = 'position:fixed;top:0;left:0;width:100%;height:100%;pointer-events:none;z-index:99999;';
+
+    ${options.bbox ? `
+    // Element outline
+    var outline = document.createElement('div');
+    outline.style.cssText = 'position:fixed;' +
+      'left:${options.bbox.x}px;top:${options.bbox.y}px;' +
+      'width:${options.bbox.width}px;height:${options.bbox.height}px;' +
+      '${style.outline !== "none" ? `outline:${style.outline};outline-offset:-1px;` : ""}' +
+      'pointer-events:none;box-sizing:border-box;';
+    container.appendChild(outline);
+    ` : ""}
+
+    ${options.point && style.marker === "crosshair" ? `
+    // Crosshair at click point
+    var hLine = document.createElement('div');
+    hLine.style.cssText = 'position:fixed;left:${options.point.x - 12}px;top:${options.point.y}px;' +
+      'width:24px;height:2px;background:${style.badge};pointer-events:none;';
+    var vLine = document.createElement('div');
+    vLine.style.cssText = 'position:fixed;left:${options.point.x}px;top:${options.point.y - 12}px;' +
+      'width:2px;height:24px;background:${style.badge};pointer-events:none;';
+    // Dot at center
+    var dot = document.createElement('div');
+    dot.style.cssText = 'position:fixed;left:${options.point.x - 4}px;top:${options.point.y - 4}px;' +
+      'width:8px;height:8px;border-radius:50%;background:${style.badge};pointer-events:none;';
+    container.appendChild(hLine);
+    container.appendChild(vLine);
+    container.appendChild(dot);
+    ` : ""}
+
+    ${label ? `
+    // Badge with label
+    var badge = document.createElement('div');
+    badge.style.cssText = 'position:fixed;' +
+      ${options.bbox ? `'left:${options.bbox.x}px;top:${Math.max(0, options.bbox.y - 28)}px;'` : options.kind === "navigate" ? "'left:50%;top:8px;transform:translateX(-50%);'" : "'right:8px;top:8px;'"} +
+      'background:${style.badge};color:white;padding:4px 8px;' +
+      'font-family:monospace;font-size:12px;font-weight:bold;' +
+      'border-radius:3px;white-space:nowrap;max-width:400px;overflow:hidden;text-overflow:ellipsis;' +
+      'pointer-events:none;';
+    badge.textContent = '${escapedLabel}';
+    container.appendChild(badge);
+    ` : ""}
+
+    ${style.marker === "check" && options.bbox ? `
+    // Checkmark
+    var check = document.createElement('div');
+    check.style.cssText = 'position:fixed;left:${options.bbox.x + options.bbox.width / 2 - 10}px;' +
+      'top:${options.bbox.y + options.bbox.height / 2 - 10}px;' +
+      'width:20px;height:20px;font-size:18px;color:${style.badge};pointer-events:none;text-align:center;line-height:20px;';
+    check.textContent = '\\u2713';
+    container.appendChild(check);
+    ` : ""}
+
+    ${style.marker === "cross" && options.bbox ? `
+    // Cross mark
+    var cross = document.createElement('div');
+    cross.style.cssText = 'position:fixed;left:${options.bbox.x + options.bbox.width / 2 - 10}px;' +
+      'top:${options.bbox.y + options.bbox.height / 2 - 10}px;' +
+      'width:20px;height:20px;font-size:18px;color:${style.badge};pointer-events:none;text-align:center;line-height:20px;font-weight:bold;';
+    cross.textContent = '\\u2717';
+    container.appendChild(cross);
+    ` : ""}
+
+    document.body.appendChild(container);
+    window.__bpRemoveActionHighlight = function() {
+      var el = document.getElementById('__bp-action-highlight');
+      if (el) el.remove();
+      delete window.__bpRemoveActionHighlight;
+    };
+  })();`;
+}
+async function injectActionHighlight(page, options) {
+  try {
+    await page.evaluate(buildHighlightScript(options));
+  } catch {
+  }
+}
+async function removeActionHighlight(page) {
+  try {
+    await page.evaluate(`(function() {
+      if (window.__bpRemoveActionHighlight) {
+        window.__bpRemoveActionHighlight();
+      }
+    })()`);
+  } catch {
+  }
+}
+function stepToHighlightKind(step) {
+  switch (step.action) {
+    case "click":
+      return "click";
+    case "fill":
+      return "fill";
+    case "type":
+      return "type";
+    case "select":
+      return "select";
+    case "hover":
+      return "hover";
+    case "scroll":
+      return "scroll";
+    case "goto":
+      return "navigate";
+    case "submit":
+      return "submit";
+    case "focus":
+      return "focus";
+    case "evaluate":
+    case "press":
+    case "shortcut":
+      return "evaluate";
+    case "assertVisible":
+    case "assertExists":
+    case "assertText":
+    case "assertUrl":
+    case "assertValue":
+      return step.success ? "assert-pass" : "assert-fail";
+    // Observation-only actions — no highlight
+    case "wait":
+    case "snapshot":
+    case "forms":
+    case "text":
+    case "screenshot":
+    case "newTab":
+    case "closeTab":
+    case "switchFrame":
+    case "switchToMain":
+      return null;
+    default:
+      return null;
+  }
+}
+function getHighlightLabel(step, result, targetMetadata) {
+  switch (step.action) {
+    case "fill":
+    case "type":
+      return typeof step.value === "string" ? `"${redactValueForRecording(step.value, targetMetadata)}"` : void 0;
+    case "select":
+      return redactValueForRecording(
+        typeof step.value === "string" ? step.value : void 0,
+        targetMetadata
+      );
+    case "goto":
+      return step.url;
+    case "evaluate":
+      return "JS";
+    case "press":
+      return step.key;
+    case "shortcut":
+      return step.combo;
+    case "assertText":
+    case "assertUrl":
+    case "assertValue":
+    case "assertVisible":
+    case "assertExists":
+      return result.success ? "\u2713" : "\u2717";
+    default:
+      return void 0;
+  }
+}
+
 // src/browser/actionability.ts
 var ActionabilityError = class extends Error {
   failureType;
@@ -686,8 +920,677 @@ var CDPError = class extends Error {
   }
 };
 
+// src/trace/views.ts
+function takeRecent(events, limit = 5) {
+  return events.slice(-limit).map((event) => ({
+    ts: event.ts,
+    event: event.event,
+    summary: event.summary,
+    severity: event.severity,
+    url: event.url
+  }));
+}
+function buildTraceSummaries(events) {
+  return {
+    ws: summarizeWs(events),
+    voice: summarizeVoice(events),
+    console: summarizeConsole(events),
+    permissions: summarizePermissions(events),
+    media: summarizeMedia(events),
+    ui: summarizeUi(events),
+    session: summarizeSession(events)
+  };
+}
+function summarizeWs(events) {
+  const relevant = events.filter((event) => event.channel === "ws" || event.event.startsWith("ws."));
+  const connections = /* @__PURE__ */ new Map();
+  for (const event of relevant) {
+    const id = event.connectionId ?? event.requestId ?? event.traceId;
+    let connection = connections.get(id);
+    if (!connection) {
+      connection = { id, sent: 0, received: 0, lastMessages: [] };
+      connections.set(id, connection);
+    }
+    connection.url = event.url ?? connection.url;
+    if (event.event === "ws.connection.created") {
+      connection.createdAt = event.ts;
+    }
+    if (event.event === "ws.connection.closed") {
+      connection.closedAt = event.ts;
+    }
+    if (event.event === "ws.frame.sent") {
+      connection.sent += 1;
+      const payload = typeof event.data["payload"] === "string" ? event.data["payload"] : "";
+      if (payload) connection.lastMessages.push(`sent: ${payload}`);
+    }
+    if (event.event === "ws.frame.received") {
+      connection.received += 1;
+      const payload = typeof event.data["payload"] === "string" ? event.data["payload"] : "";
+      if (payload) connection.lastMessages.push(`recv: ${payload}`);
+    }
+    connection.lastMessages = connection.lastMessages.slice(-3);
+  }
+  const values = [...connections.values()];
+  const reconnects = values.reduce((count, connection) => {
+    return connection.closedAt && !connection.createdAt ? count : count;
+  }, 0);
+  return {
+    view: "ws",
+    totalEvents: relevant.length,
+    connections: values.map((connection) => ({
+      id: connection.id,
+      url: connection.url ?? null,
+      createdAt: connection.createdAt ?? null,
+      closedAt: connection.closedAt ?? null,
+      sent: connection.sent,
+      received: connection.received,
+      lastMessages: connection.lastMessages,
+      connectedButSilent: !!connection.createdAt && !connection.closedAt && connection.sent + connection.received === 0
+    })),
+    reconnects,
+    recent: takeRecent(relevant)
+  };
+}
+function summarizeConsole(events) {
+  const relevant = events.filter(
+    (event) => event.channel === "console" || event.event.startsWith("console.") || event.event === "runtime.exception" || event.event === "runtime.unhandledRejection"
+  );
+  return {
+    view: "console",
+    errors: relevant.filter(
+      (event) => event.event === "console.error" || event.event === "runtime.exception" || event.event === "runtime.unhandledRejection"
+    ).length,
+    warnings: relevant.filter((event) => event.event === "console.warn").length,
+    logs: relevant.filter((event) => event.event === "console.log").length,
+    recent: takeRecent(relevant)
+  };
+}
+function summarizePermissions(events) {
+  const relevant = events.filter(
+    (event) => event.channel === "permission" || event.event.startsWith("permission.")
+  );
+  const latest = /* @__PURE__ */ new Map();
+  for (const event of relevant) {
+    const name = typeof event.data["name"] === "string" ? event.data["name"] : null;
+    const state = typeof event.data["state"] === "string" ? event.data["state"] : null;
+    if (name && state) {
+      latest.set(name, state);
+    }
+  }
+  return {
+    view: "permissions",
+    states: Object.fromEntries(latest),
+    changes: relevant.filter((event) => event.event === "permission.changed").length,
+    recent: takeRecent(relevant)
+  };
+}
+function summarizeMedia(events) {
+  const relevant = events.filter(
+    (event) => event.channel === "media" || event.event.startsWith("media.")
+  );
+  const liveTracks = /* @__PURE__ */ new Map();
+  for (const event of relevant) {
+    const label = typeof event.data["label"] === "string" ? event.data["label"] : "";
+    const kind = typeof event.data["kind"] === "string" ? event.data["kind"] : "";
+    const key = `${kind}:${label}`;
+    if (event.event === "media.track.started") {
+      liveTracks.set(key, kind);
+    }
+    if (event.event === "media.track.ended") {
+      liveTracks.delete(key);
+    }
+  }
+  return {
+    view: "media",
+    tracksStarted: relevant.filter((event) => event.event === "media.track.started").length,
+    tracksEnded: relevant.filter((event) => event.event === "media.track.ended").length,
+    playbackStarted: relevant.filter((event) => event.event === "media.playback.started").length,
+    playbackStopped: relevant.filter((event) => event.event === "media.playback.stopped").length,
+    liveTracks: [...liveTracks.values()],
+    recent: takeRecent(relevant)
+  };
+}
+function summarizeVoice(events) {
+  const relevant = events.filter(
+    (event) => event.channel === "voice" || event.event.startsWith("voice.")
+  );
+  return {
+    view: "voice",
+    ready: relevant.filter((event) => event.event === "voice.pipeline.ready").length,
+    notReady: relevant.filter((event) => event.event === "voice.pipeline.notReady").length,
+    captureStarted: relevant.filter((event) => event.event === "voice.capture.started").length,
+    captureStopped: relevant.filter((event) => event.event === "voice.capture.stopped").length,
+    detectedAudio: relevant.filter((event) => event.event === "voice.capture.detectedAudio").length,
+    recent: takeRecent(relevant)
+  };
+}
+function summarizeUi(events) {
+  const relevant = events.filter(
+    (event) => event.channel === "dom" || event.event.startsWith("dom.") || event.channel === "action"
+  );
+  return {
+    view: "ui",
+    actions: relevant.filter((event) => event.channel === "action").length,
+    domChanges: relevant.filter((event) => event.channel === "dom").length,
+    recent: takeRecent(relevant)
+  };
+}
+function summarizeSession(events) {
+  const byChannel = /* @__PURE__ */ new Map();
+  const failedActions = events.filter((event) => event.event === "action.failed").length;
+  for (const event of events) {
+    byChannel.set(event.channel, (byChannel.get(event.channel) ?? 0) + 1);
+  }
+  return {
+    view: "session",
+    totalEvents: events.length,
+    byChannel: Object.fromEntries(byChannel),
+    failedActions,
+    recent: takeRecent(events)
+  };
+}
+
+// src/recording/manifest.ts
+function isCanonicalRecordingManifest(value) {
+  return Boolean(
+    value && typeof value === "object" && value.version === 2 && typeof value.session === "object"
+  );
+}
+function isLegacyRecordingManifest(value) {
+  return Boolean(
+    value && typeof value === "object" && value.version === 1 && Array.isArray(value.frames)
+  );
+}
+function createRecordingManifest(input) {
+  const actions = input.frames.map((frame) => {
+    const actionId = frame.actionId ?? `action-${frame.seq}`;
+    return {
+      id: actionId,
+      stepIndex: frame.stepIndex ?? Math.max(0, frame.seq - 1),
+      action: frame.action,
+      selector: frame.selector,
+      selectorUsed: frame.selectorUsed ?? frame.selector,
+      value: frame.value,
+      url: frame.url,
+      success: frame.success,
+      durationMs: frame.durationMs,
+      error: frame.error,
+      ts: new Date(frame.timestamp).toISOString(),
+      pageUrl: frame.pageUrl,
+      pageTitle: frame.pageTitle,
+      coordinates: frame.coordinates,
+      boundingBox: frame.boundingBox
+    };
+  });
+  const screenshots = input.frames.map((frame) => ({
+    id: `shot-${frame.seq}`,
+    stepIndex: frame.stepIndex ?? Math.max(0, frame.seq - 1),
+    actionId: frame.actionId ?? `action-${frame.seq}`,
+    file: frame.screenshot,
+    ts: new Date(frame.timestamp).toISOString(),
+    success: frame.success,
+    pageUrl: frame.pageUrl,
+    pageTitle: frame.pageTitle,
+    coordinates: frame.coordinates,
+    boundingBox: frame.boundingBox
+  }));
+  return {
+    version: 2,
+    recordedAt: input.recordedAt,
+    session: {
+      id: input.sessionId,
+      startUrl: input.startUrl,
+      endUrl: input.endUrl,
+      targetId: input.targetId,
+      profile: input.profile
+    },
+    recipe: {
+      steps: input.steps
+    },
+    actions,
+    screenshots,
+    trace: {
+      events: input.traceEvents,
+      summaries: buildTraceSummaries(input.traceEvents)
+    },
+    assertions: input.assertions ?? [],
+    notes: input.notes ?? [],
+    artifacts: {
+      recordingManifest: input.recordingManifest ?? "recording.json",
+      screenshotDir: input.screenshotDir ?? "screenshots/"
+    }
+  };
+}
+function canonicalizeRecordingArtifact(value) {
+  if (isCanonicalRecordingManifest(value)) {
+    return value;
+  }
+  if (!isLegacyRecordingManifest(value)) {
+    throw new Error("Unsupported recording artifact");
+  }
+  const traceEvents = buildTraceEventsFromLegacy(value);
+  const steps = value.frames.map((frame) => frameToStep(frame));
+  return createRecordingManifest({
+    recordedAt: value.recordedAt,
+    sessionId: value.sessionId,
+    startUrl: value.startUrl,
+    endUrl: value.endUrl,
+    steps,
+    frames: value.frames,
+    traceEvents,
+    notes: ["Converted from legacy recording manifest"]
+  });
+}
+function buildTraceEventsFromLegacy(value) {
+  const events = [];
+  for (const frame of value.frames) {
+    events.push({
+      traceId: frame.actionId ?? `legacy-${frame.seq}`,
+      sessionId: value.sessionId,
+      ts: new Date(frame.timestamp).toISOString(),
+      elapsedMs: frame.timestamp - new Date(value.recordedAt).getTime(),
+      channel: "action",
+      event: frame.success ? "action.succeeded" : "action.failed",
+      severity: frame.success ? "info" : "error",
+      summary: `${frame.action}${frame.selector ? ` ${frame.selector}` : ""}`,
+      data: {
+        action: frame.action,
+        selector: frame.selector,
+        value: frame.value ?? null,
+        pageUrl: frame.pageUrl ?? null,
+        pageTitle: frame.pageTitle ?? null,
+        screenshot: frame.screenshot
+      },
+      actionId: frame.actionId ?? `action-${frame.seq}`,
+      stepIndex: frame.stepIndex ?? Math.max(0, frame.seq - 1),
+      selector: frame.selector,
+      selectorUsed: frame.selectorUsed ?? frame.selector,
+      url: frame.pageUrl ?? frame.url
+    });
+  }
+  return events;
+}
+function frameToStep(frame) {
+  switch (frame.action) {
+    case "fill":
+      return { action: "fill", selector: frame.selector, value: frame.value };
+    case "submit":
+      return { action: "submit", selector: frame.selector };
+    case "goto":
+      return { action: "goto", url: frame.url ?? frame.pageUrl };
+    case "press":
+      return { action: "press", key: frame.value ?? "Enter" };
+    default:
+      return { action: "click", selector: frame.selector };
+  }
+}
+
+// src/trace/script.ts
+var TRACE_BINDING_NAME = "__bpTraceBinding";
+var TRACE_SCRIPT = `
+(() => {
+  if (window.__bpTraceInstalled) return;
+  window.__bpTraceInstalled = true;
+
+  const binding = globalThis.${TRACE_BINDING_NAME};
+  if (typeof binding !== 'function') return;
+
+  const emit = (event, data = {}, severity = 'info', summary) => {
+    try {
+      globalThis.__bpTraceRecentEvents = globalThis.__bpTraceRecentEvents || [];
+      const payload = {
+        event,
+        severity,
+        summary: summary || event,
+        ts: Date.now(),
+        data,
+      };
+      globalThis.__bpTraceRecentEvents.push(payload);
+      if (globalThis.__bpTraceRecentEvents.length > 200) {
+        globalThis.__bpTraceRecentEvents.splice(0, globalThis.__bpTraceRecentEvents.length - 200);
+      }
+      binding(JSON.stringify(payload));
+    } catch {}
+  };
+
+  const patchWebSocket = () => {
+    const NativeWebSocket = window.WebSocket;
+    if (typeof NativeWebSocket !== 'function' || window.__bpTraceWebSocketInstalled) return;
+    window.__bpTraceWebSocketInstalled = true;
+
+    const nextId = () => Math.random().toString(36).slice(2, 10);
+
+    const patchInstance = (socket, urlValue) => {
+      if (!socket || socket.__bpTracePatched) return socket;
+      socket.__bpTracePatched = true;
+      socket.__bpTraceId = socket.__bpTraceId || nextId();
+      socket.__bpTraceUrl = String(urlValue || socket.url || '');
+      globalThis.__bpTrackedWebSockets = globalThis.__bpTrackedWebSockets || new Set();
+      globalThis.__bpTrackedWebSockets.add(socket);
+
+      emit(
+        'ws.connection.created',
+        { connectionId: socket.__bpTraceId, url: socket.__bpTraceUrl },
+        'info',
+        'WebSocket opened ' + socket.__bpTraceUrl
+      );
+
+      const originalSend = socket.send;
+      socket.send = function(data) {
+        const payload =
+          typeof data === 'string'
+            ? data
+            : data && typeof data.toString === 'function'
+              ? data.toString()
+              : '[binary]';
+        emit(
+          'ws.frame.sent',
+          {
+            connectionId: socket.__bpTraceId,
+            url: socket.__bpTraceUrl,
+            payload,
+            length: payload.length,
+          },
+          'info',
+          'WebSocket frame sent'
+        );
+        return originalSend.call(this, data);
+      };
+
+      socket.addEventListener('message', (event) => {
+        if (socket.__bpOfflineNotified || socket.__bpTraceClosed) {
+          return;
+        }
+        const data = event && 'data' in event ? event.data : '';
+        const payload =
+          typeof data === 'string'
+            ? data
+            : data && typeof data.toString === 'function'
+              ? data.toString()
+              : '[binary]';
+        emit(
+          'ws.frame.received',
+          {
+            connectionId: socket.__bpTraceId,
+            url: socket.__bpTraceUrl,
+            payload,
+            length: payload.length,
+          },
+          'info',
+          'WebSocket frame received'
+        );
+      });
+
+      socket.addEventListener('close', (event) => {
+        if (socket.__bpTraceClosed) {
+          return;
+        }
+        socket.__bpTraceClosed = true;
+        try {
+          globalThis.__bpTrackedWebSockets.delete(socket);
+        } catch {}
+        emit(
+          'ws.connection.closed',
+          {
+            connectionId: socket.__bpTraceId,
+            url: socket.__bpTraceUrl,
+            code: event.code,
+            reason: event.reason,
+          },
+          'warn',
+          'WebSocket closed'
+        );
+      });
+
+      return socket;
+    };
+
+    const TracedWebSocket = function(url, protocols) {
+      return arguments.length > 1
+        ? patchInstance(new NativeWebSocket(url, protocols), url)
+        : patchInstance(new NativeWebSocket(url), url);
+    };
+    TracedWebSocket.prototype = NativeWebSocket.prototype;
+    Object.setPrototypeOf(TracedWebSocket, NativeWebSocket);
+    window.WebSocket = TracedWebSocket;
+  };
+
+  window.addEventListener('error', (errorEvent) => {
+    emit(
+      'runtime.exception',
+      {
+        message: errorEvent.message,
+        filename: errorEvent.filename,
+        line: errorEvent.lineno,
+        column: errorEvent.colno,
+      },
+      'error',
+      errorEvent.message || 'Uncaught error'
+    );
+  });
+
+  window.addEventListener('unhandledrejection', (event) => {
+    const reason = event && 'reason' in event ? String(event.reason) : 'Unhandled rejection';
+    emit('runtime.unhandledRejection', { reason }, 'error', reason);
+  });
+
+  const patchPermissions = async () => {
+    if (!navigator.permissions || !navigator.permissions.query) return;
+
+    const names = ['geolocation', 'microphone', 'camera', 'notifications'];
+    for (const name of names) {
+      try {
+        const status = await navigator.permissions.query({ name });
+        emit(
+          'permission.state',
+          { name, state: status.state },
+          status.state === 'denied' ? 'warn' : 'info',
+          name + ': ' + status.state
+        );
+        status.addEventListener('change', () => {
+          emit(
+            'permission.changed',
+            { name, state: status.state },
+            status.state === 'denied' ? 'warn' : 'info',
+            name + ': ' + status.state
+          );
+        });
+      } catch {}
+    }
+  };
+
+  const patchMediaElement = (element) => {
+    if (!element || element.__bpTracePatched) return;
+    element.__bpTracePatched = true;
+
+    element.addEventListener('play', () => {
+      emit(
+        'media.playback.started',
+        { tag: element.tagName.toLowerCase(), src: element.currentSrc || element.src || null },
+        'info',
+        'Media playback started'
+      );
+    });
+
+    const onStop = () => {
+      emit(
+        'media.playback.stopped',
+        { tag: element.tagName.toLowerCase(), src: element.currentSrc || element.src || null },
+        'warn',
+        'Media playback stopped'
+      );
+    };
+
+    element.addEventListener('pause', onStop);
+    element.addEventListener('ended', onStop);
+  };
+
+  const patchMediaElements = () => {
+    document.querySelectorAll('audio,video').forEach(patchMediaElement);
+  };
+
+  patchMediaElements();
+  patchWebSocket();
+
+  if (document.documentElement) {
+    const observer = new MutationObserver(() => {
+      patchMediaElements();
+    });
+    observer.observe(document.documentElement, { childList: true, subtree: true });
+  }
+
+  if (navigator.mediaDevices && navigator.mediaDevices.getUserMedia) {
+    const original = navigator.mediaDevices.getUserMedia.bind(navigator.mediaDevices);
+    navigator.mediaDevices.getUserMedia = async (...args) => {
+      emit('voice.capture.started', { constraints: args[0] || null }, 'info', 'Voice capture started');
+      try {
+        const stream = await original(...args);
+        const tracks = stream.getTracks();
+
+        for (const track of tracks) {
+          emit(
+            'media.track.started',
+            { kind: track.kind, label: track.label, readyState: track.readyState },
+            'info',
+            track.kind + ' track started'
+          );
+          track.addEventListener('ended', () => {
+            emit(
+              'media.track.ended',
+              { kind: track.kind, label: track.label, readyState: track.readyState },
+              'warn',
+              track.kind + ' track ended'
+            );
+            emit(
+              'voice.capture.stopped',
+              { kind: track.kind, label: track.label, readyState: track.readyState },
+              'warn',
+              'Voice capture stopped'
+            );
+          });
+        }
+
+        emit(
+          'voice.capture.detectedAudio',
+          { trackCount: tracks.length, kinds: tracks.map((track) => track.kind) },
+          'info',
+          'Voice capture detected audio'
+        );
+
+        return stream;
+      } catch (error) {
+        emit(
+          'voice.pipeline.notReady',
+          { message: String(error && error.message ? error.message : error) },
+          'error',
+          String(error && error.message ? error.message : error)
+        );
+        throw error;
+      }
+    };
+  }
+
+  document.addEventListener('visibilitychange', () => {
+    emit(
+      'dom.state.changed',
+      { visibilityState: document.visibilityState },
+      document.visibilityState === 'hidden' ? 'warn' : 'info',
+      'Visibility ' + document.visibilityState
+    );
+  });
+
+  patchPermissions();
+  emit('voice.pipeline.ready', { url: location.href }, 'info', 'Trace hooks ready');
+})();
+`;
+
+// src/trace/model.ts
+function createTraceId(prefix = "evt") {
+  const random = Math.random().toString(36).slice(2, 10);
+  return `${prefix}-${Date.now().toString(36)}-${random}`;
+}
+function normalizeTraceEvent(event) {
+  return {
+    traceId: event.traceId ?? createTraceId(event.channel),
+    ts: event.ts ?? (/* @__PURE__ */ new Date()).toISOString(),
+    elapsedMs: event.elapsedMs ?? 0,
+    severity: event.severity ?? inferSeverity(event.event),
+    data: event.data ?? {},
+    ...event
+  };
+}
+function inferSeverity(eventName) {
+  if (eventName.includes(".failed") || eventName.includes(".error") || eventName.includes("exception") || eventName.includes("notReady")) {
+    return "error";
+  }
+  if (eventName.includes(".closed") || eventName.includes(".warn") || eventName.includes(".changed")) {
+    return "warn";
+  }
+  return "info";
+}
+
+// src/trace/live.ts
+function globToRegex(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const withWildcards = escaped.replace(/\*/g, ".*");
+  return new RegExp(`^${withWildcards}$`);
+}
+
 // src/actions/executor.ts
 var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_RECORDING_SKIP_ACTIONS = [
+  "wait",
+  "snapshot",
+  "forms",
+  "text",
+  "screenshot"
+];
+function loadExistingRecording(manifestPath) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+    if (raw.version === 1) {
+      const legacy = raw;
+      return {
+        frames: Array.isArray(legacy.frames) ? legacy.frames : [],
+        traceEvents: [],
+        recordedAt: legacy.recordedAt,
+        startUrl: legacy.startUrl
+      };
+    }
+    const artifact = canonicalizeRecordingArtifact(raw);
+    const screenshotsByAction = new Map(artifact.screenshots.map((shot) => [shot.actionId, shot]));
+    const frames = artifact.actions.map((action, index) => {
+      const screenshot = screenshotsByAction.get(action.id);
+      return {
+        seq: index + 1,
+        timestamp: Date.parse(action.ts),
+        action: action.action,
+        selector: action.selector,
+        selectorUsed: action.selectorUsed,
+        value: action.value,
+        url: action.url,
+        coordinates: action.coordinates,
+        boundingBox: action.boundingBox,
+        success: action.success,
+        durationMs: action.durationMs,
+        error: action.error,
+        screenshot: screenshot?.file ?? "",
+        pageUrl: action.pageUrl,
+        pageTitle: action.pageTitle,
+        stepIndex: action.stepIndex,
+        actionId: action.id
+      };
+    });
+    return {
+      frames,
+      traceEvents: artifact.trace.events,
+      recordedAt: artifact.recordedAt,
+      startUrl: artifact.session.startUrl
+    };
+  } catch {
+    return { frames: [], traceEvents: [] };
+  }
+}
 function classifyFailure(error) {
   if (error instanceof ElementNotFoundError) {
     return { reason: "missing" };
@@ -767,6 +1670,12 @@ var BatchExecutor = class {
     const { timeout = DEFAULT_TIMEOUT, onFail = "stop" } = options;
     const results = [];
     const startTime = Date.now();
+    const recording = options.record ? this.createRecordingContext(options.record) : null;
+    if (steps.some((step) => step.action === "waitForWsMessage")) {
+      await this.ensureTraceHooks();
+    }
+    const startUrl = recording ? await this.getPageUrlSafe() : "";
+    let stoppedAtIndex;
     for (let i = 0; i < steps.length; i++) {
       const step = steps[i];
       const stepStart = Date.now();
@@ -774,13 +1683,34 @@ var BatchExecutor = class {
       const retryDelay = step.retryDelay ?? 500;
       let lastError;
       let succeeded = false;
+      if (recording) {
+        recording.traceEvents.push(
+          normalizeTraceEvent({
+            traceId: createTraceId("action"),
+            elapsedMs: Date.now() - startTime,
+            channel: "action",
+            event: "action.started",
+            summary: `${step.action}${step.selector ? ` ${Array.isArray(step.selector) ? step.selector[0] : step.selector}` : ""}`,
+            data: {
+              action: step.action,
+              selector: step.selector ?? null,
+              url: step.url ?? null
+            },
+            actionId: `action-${i + 1}`,
+            stepIndex: i,
+            selector: step.selector,
+            url: step.url
+          })
+        );
+      }
       for (let attempt = 0; attempt < maxAttempts; attempt++) {
         if (attempt > 0) {
           await new Promise((resolve) => setTimeout(resolve, retryDelay));
         }
         try {
+          this.page.resetLastActionPosition();
           const result = await this.executeStep(step, timeout);
-          results.push({
+          const stepResult = {
             index: i,
             action: step.action,
             selector: step.selector,
@@ -788,8 +1718,37 @@ var BatchExecutor = class {
             success: true,
             durationMs: Date.now() - stepStart,
             result: result.value,
-            text: result.text
-          });
+            text: result.text,
+            timestamp: Date.now(),
+            coordinates: this.page.getLastActionCoordinates() ?? void 0,
+            boundingBox: this.page.getLastActionBoundingBox() ?? void 0
+          };
+          if (recording && !recording.skipActions.has(step.action)) {
+            await this.captureRecordingFrame(step, stepResult, recording);
+          }
+          if (recording) {
+            recording.traceEvents.push(
+              normalizeTraceEvent({
+                traceId: createTraceId("action"),
+                elapsedMs: Date.now() - startTime,
+                channel: "action",
+                event: "action.succeeded",
+                summary: `${step.action} succeeded`,
+                data: {
+                  action: step.action,
+                  selector: step.selector ?? null,
+                  selectorUsed: result.selectorUsed ?? null,
+                  durationMs: Date.now() - stepStart
+                },
+                actionId: `action-${i + 1}`,
+                stepIndex: i,
+                selector: step.selector,
+                selectorUsed: result.selectorUsed,
+                url: step.url
+              })
+            );
+          }
+          results.push(stepResult);
           succeeded = true;
           break;
         } catch (error) {
@@ -810,7 +1769,7 @@ var BatchExecutor = class {
           } catch {
           }
         }
-        results.push({
+        const failedResult = {
           index: i,
           action: step.action,
           selector: step.selector,
@@ -820,25 +1779,183 @@ var BatchExecutor = class {
           hints,
           failureReason: reason,
           coveringElement,
-          suggestion: getSuggestion(reason)
-        });
+          suggestion: getSuggestion(reason),
+          timestamp: Date.now()
+        };
+        if (recording && !recording.skipActions.has(step.action)) {
+          await this.captureRecordingFrame(step, failedResult, recording);
+        }
+        if (recording) {
+          recording.traceEvents.push(
+            normalizeTraceEvent({
+              traceId: createTraceId("action"),
+              elapsedMs: Date.now() - startTime,
+              channel: "action",
+              event: "action.failed",
+              severity: "error",
+              summary: `${step.action} failed: ${errorMessage}`,
+              data: {
+                action: step.action,
+                selector: step.selector ?? null,
+                error: errorMessage,
+                reason
+              },
+              actionId: `action-${i + 1}`,
+              stepIndex: i,
+              selector: step.selector,
+              url: step.url
+            })
+          );
+        }
+        results.push(failedResult);
         if (onFail === "stop" && !step.optional) {
-          return {
-            success: false,
-            stoppedAtIndex: i,
-            steps: results,
-            totalDurationMs: Date.now() - startTime
-          };
+          stoppedAtIndex = i;
+          break;
         }
       }
     }
-    const allSuccess = results.every((r) => r.success || steps[r.index]?.optional);
+    const totalDurationMs = Date.now() - startTime;
+    const allSuccess = stoppedAtIndex === void 0 && results.every((result) => result.success || steps[result.index]?.optional);
+    let recordingManifest;
+    if (recording) {
+      recordingManifest = await this.writeRecordingManifest(
+        recording,
+        startTime,
+        startUrl,
+        allSuccess,
+        steps
+      );
+    }
     return {
       success: allSuccess,
+      stoppedAtIndex,
       steps: results,
-      totalDurationMs: Date.now() - startTime
+      totalDurationMs,
+      recordingManifest
     };
   }
+  createRecordingContext(record) {
+    const baseDir = record.outputDir ?? (0, import_node_path.join)(process.cwd(), ".browser-pilot");
+    const screenshotDir = (0, import_node_path.join)(baseDir, "screenshots");
+    const manifestPath = (0, import_node_path.join)(baseDir, "recording.json");
+    const existing = loadExistingRecording(manifestPath);
+    fs.mkdirSync(screenshotDir, { recursive: true });
+    return {
+      baseDir,
+      screenshotDir,
+      sessionId: record.sessionId ?? this.page.targetId,
+      frames: existing.frames,
+      traceEvents: existing.traceEvents,
+      format: record.format ?? "webp",
+      quality: Math.max(0, Math.min(100, record.quality ?? 40)),
+      highlights: record.highlights !== false,
+      skipActions: new Set(record.skipActions ?? DEFAULT_RECORDING_SKIP_ACTIONS)
+    };
+  }
+  async getPageUrlSafe() {
+    try {
+      return await this.page.url();
+    } catch {
+      return "";
+    }
+  }
+  /**
+   * Capture a recording screenshot frame with optional highlight overlay
+   */
+  async captureRecordingFrame(step, stepResult, recording) {
+    const targetMetadata = this.page.getLastActionTargetMetadata();
+    let highlightInjected = false;
+    try {
+      const ts = Date.now();
+      const seq = String(recording.frames.length + 1).padStart(4, "0");
+      const filename = `${seq}-${ts}-${stepResult.action}.${recording.format}`;
+      const filepath = (0, import_node_path.join)(recording.screenshotDir, filename);
+      if (recording.highlights) {
+        const kind = stepToHighlightKind(stepResult);
+        if (kind) {
+          await injectActionHighlight(this.page, {
+            kind,
+            bbox: stepResult.boundingBox,
+            point: stepResult.coordinates,
+            label: getHighlightLabel(step, stepResult, targetMetadata)
+          });
+          highlightInjected = true;
+        }
+      }
+      const base64 = await this.page.screenshot({
+        format: recording.format,
+        quality: recording.quality
+      });
+      const buffer = Buffer.from(base64, "base64");
+      fs.writeFileSync(filepath, buffer);
+      stepResult.screenshotPath = filepath;
+      let pageUrl;
+      let pageTitle;
+      try {
+        pageUrl = await this.page.url();
+        pageTitle = await this.page.title();
+      } catch {
+      }
+      recording.frames.push({
+        seq: recording.frames.length + 1,
+        timestamp: ts,
+        action: stepResult.action,
+        selector: stepResult.selectorUsed ?? (Array.isArray(step.selector) ? step.selector[0] : step.selector),
+        selectorUsed: stepResult.selectorUsed,
+        value: redactValueForRecording(
+          typeof step.value === "string" ? step.value : void 0,
+          targetMetadata
+        ),
+        url: step.url,
+        coordinates: stepResult.coordinates,
+        boundingBox: stepResult.boundingBox,
+        success: stepResult.success,
+        durationMs: stepResult.durationMs,
+        error: stepResult.error,
+        screenshot: filename,
+        pageUrl,
+        pageTitle,
+        stepIndex: stepResult.index,
+        actionId: `action-${stepResult.index + 1}`
+      });
+    } catch {
+    } finally {
+      if (recording.highlights || highlightInjected) {
+        await removeActionHighlight(this.page);
+      }
+    }
+  }
+  /**
+   * Write recording manifest to disk
+   */
+  async writeRecordingManifest(recording, startTime, startUrl, success, steps) {
+    let endUrl = startUrl;
+    try {
+      endUrl = await this.page.url();
+    } catch {
+    }
+    const manifestPath = (0, import_node_path.join)(recording.baseDir, "recording.json");
+    let recordedAt = new Date(startTime).toISOString();
+    let originalStartUrl = startUrl;
+    const existing = loadExistingRecording(manifestPath);
+    if (existing.recordedAt) recordedAt = existing.recordedAt;
+    if (existing.startUrl) originalStartUrl = existing.startUrl;
+    const manifest = createRecordingManifest({
+      recordedAt,
+      sessionId: recording.sessionId,
+      startUrl: originalStartUrl,
+      endUrl,
+      targetId: this.page.targetId,
+      steps,
+      frames: recording.frames,
+      traceEvents: recording.traceEvents,
+      notes: success ? [] : ["Replay ended with at least one failed action."],
+      recordingManifest: "recording.json",
+      screenshotDir: "screenshots/"
+    });
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    return manifestPath;
+  }
   /**
    * Execute a single step
    */
@@ -1118,6 +2235,39 @@ var BatchExecutor = class {
         }
         return { selectorUsed: usedSelector, value: actual };
       }
+      case "waitForWsMessage": {
+        if (typeof step.match !== "string") {
+          throw new Error("waitForWsMessage requires match");
+        }
+        const message = await this.waitForWsMessage(step.match, step.where, timeout);
+        return { value: message };
+      }
+      case "assertNoConsoleErrors": {
+        await this.assertNoConsoleErrors(step.windowMs ?? timeout);
+        return {};
+      }
+      case "assertTextChanged": {
+        const selector = Array.isArray(step.selector) ? step.selector[0] : step.selector;
+        if (typeof step.to !== "string") {
+          throw new Error("assertTextChanged requires to");
+        }
+        const text = await this.assertTextChanged(selector, step.from, step.to, timeout);
+        return { selectorUsed: selector, text };
+      }
+      case "assertPermission": {
+        if (!step.name || !step.state) {
+          throw new Error("assertPermission requires name and state");
+        }
+        const permission = await this.assertPermission(step.name, step.state);
+        return { value: permission };
+      }
+      case "assertMediaTrackLive": {
+        if (!step.kind) {
+          throw new Error("assertMediaTrackLive requires kind");
+        }
+        const media = await this.assertMediaTrackLive(step.kind);
+        return { value: media };
+      }
       default: {
         const action = step.action;
         const aliases = {
@@ -1171,7 +2321,7 @@ var BatchExecutor = class {
         };
         const suggestion = aliases[action.toLowerCase()];
         const hint = suggestion ? ` Did you mean "${suggestion}"?` : "";
-        const valid = "goto, click, fill, type, select, check, uncheck, submit, press, shortcut, focus, hover, scroll, wait, snapshot, forms, screenshot, evaluate, text, newTab, closeTab, switchFrame, switchToMain, assertVisible, assertExists, assertText, assertUrl, assertValue";
+        const valid = "goto, click, fill, type, select, check, uncheck, submit, press, shortcut, focus, hover, scroll, wait, snapshot, forms, screenshot, evaluate, text, newTab, closeTab, switchFrame, switchToMain, assertVisible, assertExists, assertText, assertUrl, assertValue, waitForWsMessage, assertNoConsoleErrors, assertTextChanged, assertPermission, assertMediaTrackLive";
         throw new Error(`Unknown action "${action}".${hint}
 
 Valid actions: ${valid}`);
@@ -1187,6 +2337,233 @@ Valid actions: ${valid}`);
     if (matched) return matched;
     return Array.isArray(selector) ? selector[0] : selector;
   }
+  async ensureTraceHooks() {
+    await this.page.cdpClient.send("Runtime.enable");
+    await this.page.cdpClient.send("Page.enable");
+    await this.page.cdpClient.send("Network.enable");
+    try {
+      await this.page.cdpClient.send("Runtime.addBinding", { name: TRACE_BINDING_NAME });
+    } catch {
+    }
+    await this.page.cdpClient.send("Page.addScriptToEvaluateOnNewDocument", { source: TRACE_SCRIPT });
+    await this.page.cdpClient.send("Runtime.evaluate", { expression: TRACE_SCRIPT, awaitPromise: false });
+  }
+  async waitForWsMessage(match, where, timeout) {
+    await this.ensureTraceHooks();
+    const regex = globToRegex(match);
+    const wsUrls = /* @__PURE__ */ new Map();
+    const recentMatch = await this.findRecentWsMessage(regex, where);
+    if (recentMatch) {
+      return recentMatch;
+    }
+    return new Promise((resolve, reject) => {
+      const cleanup = () => {
+        this.page.cdpClient.off("Network.webSocketCreated", onCreated);
+        this.page.cdpClient.off("Network.webSocketFrameReceived", onFrame);
+        this.page.cdpClient.off("Runtime.bindingCalled", onBinding);
+        clearTimeout(timer);
+      };
+      const onCreated = (params) => {
+        wsUrls.set(String(params["requestId"] ?? ""), String(params["url"] ?? ""));
+      };
+      const onFrame = (params) => {
+        const requestId = String(params["requestId"] ?? "");
+        const response = params["response"] ?? {};
+        const payload = String(response.payloadData ?? "");
+        const url = wsUrls.get(requestId) ?? "";
+        if (!regex.test(url) && !regex.test(payload)) {
+          return;
+        }
+        if (where && !this.payloadMatchesWhere(payload, where)) {
+          return;
+        }
+        cleanup();
+        resolve({ requestId, url, payload });
+      };
+      const onBinding = (params) => {
+        if (params["name"] !== TRACE_BINDING_NAME) {
+          return;
+        }
+        try {
+          const parsed = JSON.parse(String(params["payload"] ?? ""));
+          if (parsed.event !== "ws.frame.received") {
+            return;
+          }
+          const data = parsed.data ?? {};
+          const payload = String(data["payload"] ?? "");
+          const url = String(data["url"] ?? "");
+          if (!regex.test(url) && !regex.test(payload)) {
+            return;
+          }
+          if (where && !this.payloadMatchesWhere(payload, where)) {
+            return;
+          }
+          cleanup();
+          resolve({
+            requestId: String(data["connectionId"] ?? ""),
+            url,
+            payload
+          });
+        } catch {
+        }
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error(`Timed out waiting for WebSocket message matching ${match}`));
+      }, timeout);
+      this.page.cdpClient.on("Network.webSocketCreated", onCreated);
+      this.page.cdpClient.on("Network.webSocketFrameReceived", onFrame);
+      this.page.cdpClient.on("Runtime.bindingCalled", onBinding);
+    });
+  }
+  payloadMatchesWhere(payload, where) {
+    try {
+      const parsed = JSON.parse(payload);
+      return Object.entries(where).every(([key, expected]) => {
+        const actual = key.split(".").reduce((current, part) => {
+          if (!current || typeof current !== "object") {
+            return void 0;
+          }
+          return current[part];
+        }, parsed);
+        return actual === expected;
+      });
+    } catch {
+      return false;
+    }
+  }
+  async findRecentWsMessage(regex, where) {
+    const recent = await this.page.evaluate(
+      "(() => Array.isArray(globalThis.__bpTraceRecentEvents) ? globalThis.__bpTraceRecentEvents : [])()"
+    );
+    if (!Array.isArray(recent)) {
+      return null;
+    }
+    for (let i = recent.length - 1; i >= 0; i--) {
+      const entry = recent[i];
+      if (!entry || typeof entry !== "object") {
+        continue;
+      }
+      const event = String(entry["event"] ?? "");
+      if (event !== "ws.frame.received") {
+        continue;
+      }
+      const data = entry["data"] ?? {};
+      const payload = String(data["payload"] ?? "");
+      const url = String(data["url"] ?? "");
+      if (!regex.test(url) && !regex.test(payload)) {
+        continue;
+      }
+      if (where && !this.payloadMatchesWhere(payload, where)) {
+        continue;
+      }
+      return {
+        requestId: String(data["connectionId"] ?? ""),
+        url,
+        payload
+      };
+    }
+    return null;
+  }
+  async assertNoConsoleErrors(windowMs) {
+    await this.page.cdpClient.send("Runtime.enable");
+    return new Promise((resolve, reject) => {
+      const errors = [];
+      const cleanup = () => {
+        this.page.cdpClient.off("Runtime.consoleAPICalled", onConsole);
+        this.page.cdpClient.off("Runtime.exceptionThrown", onException);
+        clearTimeout(timer);
+      };
+      const onConsole = (params) => {
+        if (params["type"] !== "error") {
+          return;
+        }
+        const args = Array.isArray(params["args"]) ? params["args"] : [];
+        errors.push(
+          args.map((entry) => String(entry["value"] ?? entry["description"] ?? "")).filter(Boolean).join(" ")
+        );
+      };
+      const onException = (params) => {
+        const details = params["exceptionDetails"] ?? {};
+        errors.push(String(details["text"] ?? "Runtime exception"));
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        if (errors.length > 0) {
+          reject(new Error(`Console errors detected: ${errors.join(" | ")}`));
+          return;
+        }
+        resolve();
+      }, windowMs);
+      this.page.cdpClient.on("Runtime.consoleAPICalled", onConsole);
+      this.page.cdpClient.on("Runtime.exceptionThrown", onException);
+    });
+  }
+  async assertTextChanged(selector, from, to, timeout) {
+    const initialText = from ?? await this.page.text(selector);
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      const text = await this.page.text(selector);
+      if (text !== initialText && text.includes(to)) {
+        return text;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+    throw new Error(`Text did not change to include ${JSON.stringify(to)}`);
+  }
+  async assertPermission(name, state) {
+    const result = await this.page.evaluate(
+      `(() => navigator.permissions.query({ name: ${JSON.stringify(name)} }).then((status) => ({ name: ${JSON.stringify(name)}, state: status.state })))()`
+    );
+    if (!result || typeof result !== "object" || result.state !== state) {
+      throw new Error(`Permission ${name} is not ${state}`);
+    }
+    return result;
+  }
+  async assertMediaTrackLive(kind) {
+    const result = await this.page.evaluate(
+      `(() => {
+        const requestedKind = ${JSON.stringify(kind)};
+        const mediaElements = Array.from(document.querySelectorAll('audio,video')).map((el) => {
+          const tracks = [];
+          if (el.srcObject && typeof el.srcObject.getTracks === 'function') {
+            tracks.push(...el.srcObject.getTracks());
+          }
+          return {
+            tag: el.tagName.toLowerCase(),
+            paused: !!el.paused,
+            tracks: tracks.map((track) => ({
+              kind: track.kind,
+              readyState: track.readyState,
+              enabled: track.enabled,
+              label: track.label,
+            })),
+          };
+        });
+
+        const globalTracks =
+          window.__bpStream && typeof window.__bpStream.getTracks === 'function'
+            ? window.__bpStream.getTracks().map((track) => ({
+                kind: track.kind,
+                readyState: track.readyState,
+                enabled: track.enabled,
+                label: track.label,
+              }))
+            : [];
+
+        const liveTracks = mediaElements
+          .flatMap((entry) => entry.tracks)
+          .concat(globalTracks)
+          .filter((track) => track.kind === requestedKind && track.readyState === 'live');
+
+        return { live: liveTracks.length > 0, mediaElements, globalTracks, liveTracks };
+      })()`
+    );
+    if (!result || typeof result !== "object" || !result.live) {
+      throw new Error(`No live ${kind} media track detected`);
+    }
+    return result;
+  }
 };
 function addBatchToPage(page) {
   const executor = new BatchExecutor(page);
@@ -1317,7 +2694,7 @@ var ACTION_RULES = {
       value: { type: "string|string[]" },
       trigger: { type: "string|string[]" },
       option: { type: "string|string[]" },
-      match: { type: "string", enum: ["text", "value", "contains"] }
+      match: { type: "string" }
     }
   },
   check: {
@@ -1448,6 +2825,38 @@ var ACTION_RULES = {
       expect: { type: "string" },
       value: { type: "string" }
     }
+  },
+  waitForWsMessage: {
+    required: { match: { type: "string" } },
+    optional: {
+      where: { type: "object" }
+    }
+  },
+  assertNoConsoleErrors: {
+    required: {},
+    optional: {
+      windowMs: { type: "number" }
+    }
+  },
+  assertTextChanged: {
+    required: { to: { type: "string" } },
+    optional: {
+      selector: { type: "string|string[]" },
+      from: { type: "string" }
+    }
+  },
+  assertPermission: {
+    required: {
+      name: { type: "string" },
+      state: { type: "string" }
+    },
+    optional: {}
+  },
+  assertMediaTrackLive: {
+    required: {
+      kind: { type: "string", enum: ["audio", "video"] }
+    },
+    optional: {}
   }
 };
 var VALID_ACTIONS = Object.keys(ACTION_RULES);
@@ -1471,6 +2880,7 @@ var KNOWN_STEP_FIELDS = /* @__PURE__ */ new Set([
   "trigger",
   "option",
   "match",
+  "where",
   "x",
   "y",
   "direction",
@@ -1480,7 +2890,13 @@ var KNOWN_STEP_FIELDS = /* @__PURE__ */ new Set([
   "fullPage",
   "expect",
   "retry",
-  "retryDelay"
+  "retryDelay",
+  "from",
+  "to",
+  "name",
+  "state",
+  "kind",
+  "windowMs"
 ]);
 function resolveAction(name) {
   if (VALID_ACTIONS.includes(name)) {
@@ -1553,6 +2969,11 @@ function checkFieldType(value, rule) {
         return `expected boolean or "auto", got ${typeof value}`;
       }
       return null;
+    case "object":
+      if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return `expected object, got ${Array.isArray(value) ? "array" : typeof value}`;
+      }
+      return null;
     default: {
       const _exhaustive = rule.type;
       return `unknown type: ${_exhaustive}`;
@@ -1916,6 +3337,10 @@ async function grantAudioPermissions(cdp, origin) {
   await cdp.send("Page.addScriptToEvaluateOnNewDocument", {
     source: PERMISSIONS_OVERRIDE_SCRIPT
   });
+  await cdp.send("Runtime.evaluate", {
+    expression: PERMISSIONS_OVERRIDE_SCRIPT,
+    awaitPromise: false
+  });
 }
 var PERMISSIONS_OVERRIDE_SCRIPT = `
 (function() {
@@ -3189,6 +4614,24 @@ Content-Type: ${contentType}\r
   parts.push(data);
 }
 
+// src/utils/json.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function stringifyUnknown(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return Object.prototype.toString.call(value);
+  }
+}
+
 // src/cdp/transport.ts
 function createTransport(wsUrl, options = {}) {
   const { timeout = 3e4 } = options;
@@ -3292,8 +4735,12 @@ function getReadyStateString(state) {
 
 // src/cdp/client.ts
 async function createCDPClient(wsUrl, options = {}) {
-  const { debug = false, timeout = 3e4 } = options;
+  const { timeout = 3e4 } = options;
   const transport = await createTransport(wsUrl, { timeout });
+  return buildCDPClient(transport, options);
+}
+function buildCDPClient(transport, options = {}) {
+  const { debug = false, timeout = 3e4 } = options;
   let messageId = 0;
   let currentSessionId;
   let connected = true;
@@ -3303,7 +4750,19 @@ async function createCDPClient(wsUrl, options = {}) {
   transport.onMessage((raw) => {
     let msg;
     try {
-      msg = JSON.parse(raw);
+      const parsed = JSON.parse(raw);
+      if (!isRecord(parsed)) {
+        if (debug) console.error("[CDP] Ignoring non-object message:", raw);
+        return;
+      }
+      if ("id" in parsed && typeof parsed["id"] === "number") {
+        msg = parsed;
+      } else if ("method" in parsed && typeof parsed["method"] === "string") {
+        msg = parsed;
+      } else {
+        if (debug) console.error("[CDP] Ignoring invalid message shape:", raw);
+        return;
+      }
     } catch {
       if (debug) console.error("[CDP] Failed to parse message:", raw);
       return;
@@ -3318,7 +4777,8 @@ async function createCDPClient(wsUrl, options = {}) {
         pending.delete(response.id);
         clearTimeout(request.timer);
         if (response.error) {
-          request.reject(new CDPError(response.error));
+          const error = typeof response.error === "string" ? { code: -32e3, message: response.error } : response.error;
+          request.reject(new CDPError(error));
         } else {
           request.resolve(response.result);
         }
@@ -3416,6 +4876,9 @@ async function createCDPClient(wsUrl, options = {}) {
     onAny(handler) {
       anyEventHandlers.add(handler);
     },
+    offAny(handler) {
+      anyEventHandlers.delete(handler);
+    },
     async close() {
       connected = false;
       await transport.close();
@@ -3431,6 +4894,9 @@ async function createCDPClient(wsUrl, options = {}) {
     get sessionId() {
       return currentSessionId;
     },
+    setSessionId(sessionId) {
+      currentSessionId = sessionId;
+    },
     get isConnected() {
       return connected;
     }
@@ -4666,6 +6132,9 @@ var Page = class {
   brokenFrame = null;
   /** Last matched selector from findElement (for selectorUsed tracking) */
   _lastMatchedSelector;
+  _lastActionCoordinates = null;
+  _lastActionBoundingBox = null;
+  _lastActionTargetMetadata = null;
   /** Last snapshot for stale ref recovery */
   lastSnapshot;
   /** Audio input controller (lazy-initialized) */
@@ -4697,6 +6166,76 @@ var Page = class {
   getLastMatchedSelector() {
     return this._lastMatchedSelector;
   }
+  async getActionTargetMetadata(identifiers) {
+    try {
+      const objectId = identifiers.objectId ?? (identifiers.nodeId ? await this.resolveObjectId(identifiers.nodeId) : void 0);
+      if (!objectId) return null;
+      const response = await this.cdp.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: `function() {
+          const tagName = this.tagName?.toLowerCase?.() || '';
+          const inputType =
+            tagName === 'input' && typeof this.type === 'string' ? this.type.toLowerCase() : '';
+          const autocomplete =
+            typeof this.autocomplete === 'string' ? this.autocomplete.toLowerCase() : '';
+          return { tagName, inputType, autocomplete };
+        }`,
+        returnByValue: true
+      });
+      return response.result.value ?? null;
+    } catch {
+      return null;
+    }
+  }
+  async getElementPosition(identifiers) {
+    try {
+      const { quads } = await this.cdp.send(
+        "DOM.getContentQuads",
+        identifiers
+      );
+      if (quads?.length > 0) {
+        const q = quads[0];
+        const minX = Math.min(q[0], q[2], q[4], q[6]);
+        const maxX = Math.max(q[0], q[2], q[4], q[6]);
+        const minY = Math.min(q[1], q[3], q[5], q[7]);
+        const maxY = Math.max(q[1], q[3], q[5], q[7]);
+        return {
+          center: { x: (minX + maxX) / 2, y: (minY + maxY) / 2 },
+          bbox: { x: minX, y: minY, width: maxX - minX, height: maxY - minY }
+        };
+      }
+    } catch {
+    }
+    if (identifiers.nodeId) {
+      const box = await this.getBoxModel(identifiers.nodeId);
+      if (box) {
+        return {
+          center: { x: box.content[0] + box.width / 2, y: box.content[1] + box.height / 2 },
+          bbox: { x: box.content[0], y: box.content[1], width: box.width, height: box.height }
+        };
+      }
+    }
+    return null;
+  }
+  setLastActionPosition(coords, bbox) {
+    this._lastActionCoordinates = coords;
+    this._lastActionBoundingBox = bbox;
+  }
+  getLastActionCoordinates() {
+    return this._lastActionCoordinates;
+  }
+  getLastActionBoundingBox() {
+    return this._lastActionBoundingBox;
+  }
+  getLastActionTargetMetadata() {
+    return this._lastActionTargetMetadata;
+  }
+  /** Reset position tracking (call before each executor step) */
+  resetLastActionPosition() {
+    this._lastActionCoordinates = null;
+    this._lastActionBoundingBox = null;
+    this._lastActionTargetMetadata = null;
+  }
   /**
    * Initialize the page (enable required CDP domains)
    */
@@ -4864,6 +6403,14 @@ var Page = class {
           const quad = quads[0];
           clickX = (quad[0] + quad[2] + quad[4] + quad[6]) / 4;
           clickY = (quad[1] + quad[3] + quad[5] + quad[7]) / 4;
+          const minX = Math.min(quad[0], quad[2], quad[4], quad[6]);
+          const maxX = Math.max(quad[0], quad[2], quad[4], quad[6]);
+          const minY = Math.min(quad[1], quad[3], quad[5], quad[7]);
+          const maxY = Math.max(quad[1], quad[3], quad[5], quad[7]);
+          this.setLastActionPosition(
+            { x: clickX, y: clickY },
+            { x: minX, y: minY, width: maxX - minX, height: maxY - minY }
+          );
         } else {
           throw new Error("No quads");
         }
@@ -4872,6 +6419,10 @@ var Page = class {
         if (!box) throw new Error("Could not get element position");
         clickX = box.content[0] + box.width / 2;
         clickY = box.content[1] + box.height / 2;
+        this.setLastActionPosition(
+          { x: clickX, y: clickY },
+          { x: box.content[0], y: box.content[1], width: box.width, height: box.height }
+        );
       }
       const hitTargetCoordinates = this.currentFrame ? void 0 : { x: clickX, y: clickY };
       const HIT_TARGET_RETRIES = 3;
@@ -4922,13 +6473,20 @@ var Page = class {
         if (options.optional) return false;
         throw e;
       }
+      const fillPos = await this.getElementPosition({ nodeId: element.nodeId });
+      if (fillPos) this.setLastActionPosition(fillPos.center, fillPos.bbox);
       const tagInfo = await this.cdp.send("Runtime.callFunctionOn", {
         objectId,
         functionDeclaration: `function() {
-            return { tagName: this.tagName?.toLowerCase() || '', inputType: (this.type || '').toLowerCase() };
+            return {
+              tagName: this.tagName?.toLowerCase() || '',
+              inputType: (this.type || '').toLowerCase(),
+              autocomplete: typeof this.autocomplete === 'string' ? this.autocomplete.toLowerCase() : '',
+            };
           }`,
         returnByValue: true
       });
+      this._lastActionTargetMetadata = tagInfo.result.value;
       const { tagName, inputType } = tagInfo.result.value;
       const specialInputTypes = /* @__PURE__ */ new Set([
         "date",
@@ -5010,6 +6568,9 @@ var Page = class {
         if (options.optional) return false;
         throw e;
       }
+      const typePos = await this.getElementPosition({ nodeId: element.nodeId });
+      if (typePos) this.setLastActionPosition(typePos.center, typePos.bbox);
+      this._lastActionTargetMetadata = await this.getActionTargetMetadata({ objectId });
       await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
       for (const char of text) {
         const def = US_KEYBOARD[char];
@@ -5089,6 +6650,9 @@ var Page = class {
         if (options.optional) return false;
         throw e;
       }
+      const selectPos = await this.getElementPosition({ nodeId: element.nodeId });
+      if (selectPos) this.setLastActionPosition(selectPos.center, selectPos.bbox);
+      this._lastActionTargetMetadata = await this.getActionTargetMetadata({ objectId });
       const metadata = await this.getNativeSelectMetadata(objectId, values);
       if (!metadata.isSelect) {
         throw new Error("select() target must be a native <select> element");
@@ -5225,6 +6789,8 @@ var Page = class {
         if (options.optional) return false;
         throw e;
       }
+      const checkPos = await this.getElementPosition({ nodeId: element.nodeId });
+      if (checkPos) this.setLastActionPosition(checkPos.center, checkPos.bbox);
       const before = await this.cdp.send("Runtime.callFunctionOn", {
         objectId: object.objectId,
         functionDeclaration: "function() { return !!this.checked; }",
@@ -5273,6 +6839,8 @@ var Page = class {
         if (options.optional) return false;
         throw e;
       }
+      const uncheckPos = await this.getElementPosition({ nodeId: element.nodeId });
+      if (uncheckPos) this.setLastActionPosition(uncheckPos.center, uncheckPos.bbox);
       const isRadio = await this.cdp.send(
         "Runtime.callFunctionOn",
         {
@@ -5328,6 +6896,8 @@ var Page = class {
         throw new ElementNotFoundError(selector, hints);
       }
       const objectId = await this.resolveObjectId(element.nodeId);
+      const submitPos = await this.getElementPosition({ nodeId: element.nodeId });
+      if (submitPos) this.setLastActionPosition(submitPos.center, submitPos.bbox);
       const isFormElement = await this.cdp.send(
         "Runtime.callFunctionOn",
         {
@@ -5424,6 +6994,8 @@ var Page = class {
       const hints = await generateHints(this, selectorList, "focus");
       throw new ElementNotFoundError(selector, hints);
     }
+    const focusPos = await this.getElementPosition({ nodeId: element.nodeId });
+    if (focusPos) this.setLastActionPosition(focusPos.center, focusPos.bbox);
     await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
     return true;
   }
@@ -5459,6 +7031,14 @@ var Page = class {
           const quad = quads[0];
           x = (quad[0] + quad[2] + quad[4] + quad[6]) / 4;
           y = (quad[1] + quad[3] + quad[5] + quad[7]) / 4;
+          const minX = Math.min(quad[0], quad[2], quad[4], quad[6]);
+          const maxX = Math.max(quad[0], quad[2], quad[4], quad[6]);
+          const minY = Math.min(quad[1], quad[3], quad[5], quad[7]);
+          const maxY = Math.max(quad[1], quad[3], quad[5], quad[7]);
+          this.setLastActionPosition(
+            { x, y },
+            { x: minX, y: minY, width: maxX - minX, height: maxY - minY }
+          );
         } else {
           throw new Error("No quads");
         }
@@ -5470,6 +7050,10 @@ var Page = class {
         }
         x = box.content[0] + box.width / 2;
         y = box.content[1] + box.height / 2;
+        this.setLastActionPosition(
+          { x, y },
+          { x: box.content[0], y: box.content[1], width: box.width, height: box.height }
+        );
       }
       await this.cdp.send("Input.dispatchMouseEvent", {
         type: "mouseMoved",
@@ -5495,6 +7079,8 @@ var Page = class {
       if (options.optional) return false;
       throw new ElementNotFoundError(selector);
     }
+    const scrollPos = await this.getElementPosition({ nodeId: element.nodeId });
+    if (scrollPos) this.setLastActionPosition(scrollPos.center, scrollPos.bbox);
     await this.scrollIntoView(element.nodeId);
     return true;
   }
@@ -6256,7 +7842,7 @@ var Page = class {
       return {
         role,
         name,
-        value: value !== void 0 ? String(value) : void 0,
+        value: value !== void 0 ? stringifyUnknown(value) : void 0,
         ref,
         children: children.length > 0 ? children : void 0,
         disabled,
@@ -6318,7 +7904,7 @@ var Page = class {
           selector,
           disabled,
           checked,
-          value: value !== void 0 ? String(value) : void 0
+          value: value !== void 0 ? stringifyUnknown(value) : void 0
         });
       }
     }
@@ -6788,7 +8374,7 @@ var Page = class {
    */
   formatConsoleArgs(args) {
     return args.map((arg) => {
-      if (arg.value !== void 0) return String(arg.value);
+      if (arg.value !== void 0) return stringifyUnknown(arg.value);
       if (arg.description) return arg.description;
       return "[object]";
     }).join(" ");
@@ -7577,6 +9163,25 @@ var Browser = class _Browser {
     this.cdp = cdp;
     this.providerSession = providerSession;
   }
+  /**
+   * Create a Browser from an existing CDPClient (used by daemon fast-path).
+   * The caller is responsible for the CDP connection lifecycle.
+   */
+  static fromCDP(cdp, sessionInfo) {
+    const providerSession = {
+      wsUrl: sessionInfo.wsUrl,
+      sessionId: sessionInfo.sessionId,
+      async close() {
+      }
+    };
+    const provider = {
+      name: sessionInfo.provider ?? "daemon",
+      async createSession() {
+        return providerSession;
+      }
+    };
+    return new _Browser(cdp, provider, providerSession, { provider: "generic" });
+  }
   /**
    * Connect to a browser instance
    */