@xbrowser/cli 1.11.0 → 1.13.0

package/dist/chunk-HD4FX2N5.js

@@ -0,0 +1,1255 @@
+import {
+  createRuleEngine,
+  launch
+} from "./chunk-T2CNKWPV.js";
+import {
+  errMsg
+} from "./chunk-GDKLH7ZY.js";
+
+// src/browser.ts
+import { randomUUID } from "crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+// src/cdp-interceptor/proxy.ts
+import { WebSocketServer, WebSocket } from "ws";
+
+// src/cdp-interceptor/logger.ts
+function createLogger(config) {
+  const buffer = [];
+  const MAX_BUFFER = 2e3;
+  return {
+    info(message, meta) {
+      if (!config.enableLogging) return;
+      const ts = (/* @__PURE__ */ new Date()).toISOString();
+      if (meta) {
+        console.log(`[CDPInterceptor ${ts}] ${message}`, JSON.stringify(meta));
+      } else {
+        console.log(`[CDPInterceptor ${ts}] ${message}`);
+      }
+    },
+    log(method, direction, sessionId, payload, decision) {
+      const entry = {
+        timestamp: Date.now(),
+        direction,
+        sessionId,
+        method,
+        payload: sanitizePayload(payload),
+        decision: decision ?? void 0
+      };
+      if (config.enableLogging) {
+        buffer.push(entry);
+        if (buffer.length > MAX_BUFFER) buffer.shift();
+        const tag = decision ? decision.action === "block" ? "\u{1F6AB}BLOCK" : decision.action === "transform" ? "\u{1F504}XFMR" : "\u2705" : "  ";
+        const reason = decision ? ` [${decision.severity}] ${decision.reason}` : "";
+        console.log(`[CDP] ${tag} ${direction} ${method}${reason}`);
+      }
+      return entry;
+    },
+    getRecent(count) {
+      return buffer.slice(-count);
+    },
+    flush() {
+      buffer.length = 0;
+    }
+  };
+}
+function sanitizePayload(payload) {
+  if (typeof payload !== "object" || payload === null) return { raw: String(payload) };
+  const obj = payload;
+  const cleaned = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === "data" && typeof value === "string" && value.length > 200) {
+      cleaned[key] = `<binary: ${value.length} chars>`;
+    } else if (key === "expression" && typeof value === "string" && value.length > 500) {
+      cleaned[key] = value.substring(0, 500) + "...";
+    } else {
+      cleaned[key] = value;
+    }
+  }
+  return cleaned;
+}
+
+// src/cdp-interceptor/advisor.ts
+function formatBlockMessage(decision, method) {
+  const adv = advise(decision, method);
+  const lines = [
+    `[CDP-FIREWALL-BLOCK] rule=${decision.ruleId}`,
+    `method=${method}`,
+    `reason=${decision.reason}`,
+    `suggestion=${decision.suggestion ?? adv.detail}`
+  ];
+  if (adv.codeExample) {
+    lines.push(`code-example=`);
+    lines.push(adv.codeExample);
+  }
+  return lines.join("\n");
+}
+function advise(decision, originalMethod) {
+  const baseAdvice = getBaseAdvice(decision, originalMethod);
+  return {
+    ruleId: decision.ruleId,
+    title: baseAdvice.title,
+    detail: decision.suggestion ?? baseAdvice.detail,
+    codeExample: baseAdvice.codeExample
+  };
+}
+function getBaseAdvice(decision, method) {
+  switch (decision.ruleId) {
+    case "dom-mutation":
+      return {
+        title: "Direct DOM property mutation blocked",
+        detail: `Your ${method} call tried to set a DOM property directly. In React/Vue/Angular, this bypasses the framework's virtual DOM completely meaning onChange/onInput never fires. The website CAN detect this mismatch as automation.`,
+        codeExample: [
+          "# \u274C BLOCKED \u2014 what you tried to do:",
+          `page.evaluate(\`el.value = 'hello'\`)  # triggers isTrusted=false`,
+          "",
+          "# \u2705 USE INSTEAD \u2014 proper CDP input dispatch:",
+          "page.fill('#selector', 'hello')           # Playwright: dispatches input+change events",
+          "page.type('#selector', 'hello', {delay})  # Playwright: real keystrokes",
+          "page.locator('#selector').fill('hello')   # Playwright: recommended API"
+        ].join("\n")
+      };
+    case "mouse-trajectory":
+      return {
+        title: "Unnatural mouse trajectory blocked",
+        detail: `Your ${method} sequence formed a perfectly linear path. Human hands have micro-tremors (1-3px variation at any point along the arc), acceleration curves, and never draw straight lines between distant points.`,
+        codeExample: [
+          "# \u274C BLOCKED \u2014 linear interpolation:",
+          "for i in range(20):",
+          "    page.mouse.move(x0 + (x1-x0)*(i/20), y0 + (y1-y0)*(i/20))",
+          "",
+          "# \u2705 USE INSTEAD \u2014 Bezier curves with overshoot:",
+          '# Use "ghost-cursor" or similar library',
+          "from ghost_cursor import path_to",
+          "path_to(page, (x1, y1))"
+        ].join("\n")
+      };
+    case "input-keystroke":
+      if (method === "Input.insertText") {
+        return {
+          title: "Input.insertText detected (logged, not blocked)",
+          detail: "Input.insertText bypasses native keyDown\u2192keyPress\u2192input\u2192keyUp events. Playwright uses this internally for page.fill(). Logged for observability."
+        };
+      }
+      return {
+        title: "Unnatural keystroke timing blocked",
+        detail: `Your ${method} calls have unnaturally constant timing (e.g., exact 50ms intervals). Human typing always has variation (CV > 0.2).`,
+        codeExample: [
+          "# \u274C BLOCKED \u2014 exact constant delay:",
+          "page.type('#input', 'hello', {delay: 50})  # every keystroke exactly 50ms apart",
+          "",
+          "# \u2705 USE INSTEAD \u2014 variable delay (human-like):",
+          "page.fill('#input', 'hello')               # recommended, dispatches events properly",
+          "# OR: type with randomized delay",
+          "page.type('#input', 'hello', {delay: 50 + Math.floor(Math.random() * 80)})"
+        ].join("\n")
+      };
+    case "automation-signals":
+      return {
+        title: "Browser automation marker detected",
+        detail: `Your ${method} call accessed a property/marker that anti-crawler systems check to detect automation. These markers (navigator.webdriver, window.__playwright, etc.) are the #1 detection vector.`,
+        codeExample: [
+          "# \u274C BLOCKED \u2014 don't check for automation markers:",
+          "navigator.webdriver      # NEVER check this",
+          "window.__playwright      # NEVER check this",
+          "chrome.runtime           # NEVER check this",
+          "",
+          "# \u2705 Just go about your business normally.",
+          "# Anti-detection is handled by the CDP firewall automatically."
+        ].join("\n")
+      };
+    case "fingerprinting":
+      return {
+        title: "Browser fingerprinting API access blocked",
+        detail: `Your ${method} call accessed a known fingerprinting API. These APIs (canvas.toDataURL, WebGL getParameter, AudioContext, etc.) are used by anti-crawler systems to build a unique device fingerprint.`,
+        codeExample: [
+          "# \u274C BLOCKED \u2014 fingerprinting vector:",
+          "canvas.toDataURL()                        # returns unique browser hash",
+          'gl.getParameter(gl.VENDOR)                # returns "SwiftShader" in headless',
+          "screen.availWidth - screen.availHeight    # no OS chrome in headless",
+          "",
+          "# \u2705 Avoid accessing these APIs. They are only used for fingerprinting."
+        ].join("\n")
+      };
+    case "event-simulation":
+      return {
+        title: "Synthetic event simulation blocked",
+        detail: `Your ${method} call simulated user interaction via el.click() or dispatchEvent(new Event(...)). These produce isTrusted=false events, which are 100% detectable by any anti-crawler that checks isTrusted on critical events.`,
+        codeExample: [
+          "# \u274C BLOCKED \u2014 synthetic events (isTrusted=false):",
+          "el.click()                                 # isTrusted=false",
+          'el.dispatchEvent(new Event("click"))       # isTrusted=false',
+          "el.focus()                                 # isTrusted=false",
+          "",
+          "# \u2705 USE INSTEAD \u2014 CDP-level input dispatch (isTrusted=true):",
+          "page.click(selector)                       # uses Input.dispatchMouseEvent",
+          "page.fill(selector, value)                 # dispatches real input events"
+        ].join("\n")
+      };
+    case "emulation-override":
+      return {
+        title: "CDP emulation override blocked",
+        detail: `Your ${method} call overrides browser behavior in a way that creates detectable inconsistencies. Anti-crawler systems cross-check multiple sources (e.g., navigator.userAgent vs HTTP User-Agent header) to catch these mismatches.`,
+        codeExample: [
+          "# \u274C BLOCKED \u2014 detectable emulation override:",
+          "Emulation.setUserAgentOverride(...)        # JS vs HTTP header mismatch",
+          "Emulation.setGeolocationOverride(...)       # IP geo vs overridden geo mismatch",
+          "Emulation.setDeviceMetricsOverride(...)     # matchMedia vs actual viewport",
+          "",
+          "# \u2705 These are handled automatically by the CDP firewall.",
+          "# Do NOT call them manually."
+        ].join("\n")
+      };
+    case "network-anomaly":
+      return {
+        title: "Network anomaly detected",
+        detail: `Your ${method} call triggered a network pattern that is characteristic of scrapers: blocking URLs, clearing caches, or intercepting requests.`,
+        codeExample: [
+          "# \u274C BLOCKED \u2014 scraper optimization:",
+          "Network.clearBrowserCache()                # natural users never do this",
+          'Network.setBlockedURLs(["*fonts*"])        # blocking resources is detectable',
+          "Fetch.enable()                             # MITM-style interception",
+          "",
+          "# \u2705 Let the browser manage its own cache and network normally."
+        ].join("\n")
+      };
+    case "page-lifecycle":
+      return {
+        title: "Suspicious page lifecycle pattern blocked",
+        detail: `Your ${method} call reveals an unnatural page interaction sequence: navigating too fast, taking screenshots before the page renders, or generating PDFs (a telltale scraper giveaway).`,
+        codeExample: [
+          "# \u274C BLOCKED \u2014 unnatural lifecycle:",
+          "page.goto(url); page.pdf()                 # PDF = scraper giveaway",
+          "page.goto(url); page.screenshot() <500ms   # screenshot before render",
+          "page.goto(url) 3x in <100ms               # rapid navigation barrage",
+          "",
+          "# \u2705 Add proper waits between actions:",
+          'page.goto(url, {waitUntil: "networkidle"})',
+          'page.waitForSelector("body")',
+          "page.screenshot()                          # after rendering"
+        ].join("\n")
+      };
+    default:
+      return {
+        title: decision.reason,
+        detail: decision.suggestion ?? `The CDP call "${method}" was blocked by rule "${decision.ruleId}".`
+      };
+  }
+}
+
+// src/cdp-interceptor/proxy.ts
+function makeCompoundId(cdpSessionId, rawSessionId) {
+  return `${cdpSessionId ?? "nil"}::${rawSessionId ?? "nil"}`;
+}
+var CDPInterceptorProxy = class {
+  wss = null;
+  engine;
+  config;
+  logger;
+  started = false;
+  stats = {
+    totalMessages: 0,
+    blockedMessages: 0,
+    transformedMessages: 0,
+    passedMessages: 0,
+    byRule: {}
+  };
+  constructor(config) {
+    this.config = config;
+    this.engine = createRuleEngine(config.rules);
+    this.logger = createLogger({
+      enableLogging: config.enableLogging ?? true,
+      logDir: config.logDir
+    });
+  }
+  /** The port the proxy is listening on (only valid after start()) */
+  get port() {
+    const addr = this.wss?.address();
+    if (addr && typeof addr === "object") return addr.port;
+    return 0;
+  }
+  /** Start the proxy server */
+  async start() {
+    if (this.started) return this.port;
+    return new Promise((resolve, reject) => {
+      this.wss = new WebSocketServer({ port: this.config.listenPort ?? 0 }, () => {
+        const port = this.port;
+        this.engine.start();
+        this.started = true;
+        this.logger.info("CDP interceptor proxy started", { port, endpoint: this.config.cdpEndpoint });
+        resolve(port);
+      });
+      this.wss.on("error", reject);
+      this.wss.on("connection", (clientWs, _req) => {
+        this.handleConnection(clientWs);
+      });
+    });
+  }
+  /** Stop the proxy server */
+  async stop() {
+    this.engine.stop();
+    this.logger.flush();
+    this.started = false;
+    return new Promise((resolve) => {
+      if (!this.wss) return resolve();
+      this.wss.close(() => resolve());
+      this.wss = null;
+    });
+  }
+  /** Get accumulated statistics */
+  getStats() {
+    return { ...this.stats };
+  }
+  /** Get recent log entries (for inspection) */
+  getRecentLogs(count = 50) {
+    return this.logger.getRecent(count);
+  }
+  // ── Connection handling ──────────────────────────────────────
+  handleConnection(clientWs) {
+    let browserWs = null;
+    let isAlive = true;
+    const pendingMessages = [];
+    browserWs = new WebSocket(this.config.cdpEndpoint);
+    clientWs.on("message", (raw) => {
+      if (browserWs && browserWs.readyState === WebSocket.OPEN) {
+        this.handleClientMessage(clientWs, browserWs, raw);
+      } else {
+        pendingMessages.push(raw);
+      }
+    });
+    browserWs.on("open", () => {
+      for (const buf of pendingMessages) {
+        this.handleClientMessage(clientWs, browserWs, buf);
+      }
+      pendingMessages.length = 0;
+    });
+    browserWs.on("error", (err) => {
+      this.logger.info("Browser WebSocket error", { error: String(err) });
+    });
+    browserWs.on("close", (code, reason) => {
+      if (isAlive && clientWs.readyState === WebSocket.OPEN) {
+        this.logger.info("Browser WS closed, closing client", { code, reason: String(reason) });
+        clientWs.close();
+      }
+    });
+    browserWs.on("message", (raw) => {
+      this.handleBrowserMessage(clientWs, browserWs, raw);
+    });
+    const cleanup = () => {
+      isAlive = false;
+      if (browserWs && browserWs.readyState === WebSocket.OPEN) {
+        browserWs.close();
+      }
+    };
+    clientWs.on("close", cleanup);
+    clientWs.on("error", cleanup);
+    browserWs.on("close", () => {
+      if (isAlive && clientWs.readyState === WebSocket.OPEN) {
+        clientWs.close();
+      }
+    });
+    browserWs.on("error", cleanup);
+  }
+  // ── Message processing ───────────────────────────────────────
+  handleClientMessage(clientWs, browserWs, raw) {
+    const msg = this.parseMessage(raw);
+    if (!msg) return;
+    this.stats.totalMessages++;
+    if (!("method" in msg)) {
+      browserWs.send(raw.toString());
+      return;
+    }
+    const request = msg;
+    const ctx = {
+      method: request.method,
+      params: request.params ?? {},
+      sessionId: makeCompoundId("_cdpSession" in browserWs ? browserWs._cdpSession : void 0, request.sessionId),
+      direction: "client\u2192browser"
+    };
+    const decision = this.engine.evaluate(ctx);
+    this.logger.log(ctx.method, "client\u2192browser", ctx.sessionId, { method: ctx.method, params: ctx.params }, decision);
+    if (decision) {
+      this.recordDecision(decision);
+    }
+    if (decision?.action === "block") {
+      const blockMsg = formatBlockMessage(decision, ctx.method);
+      const errorResponse = {
+        id: request.id,
+        error: {
+          code: decision.errorCode ?? -32e3,
+          message: blockMsg
+        },
+        sessionId: request.sessionId
+      };
+      this.stats.blockedMessages++;
+      console.error(`
+${blockMsg}
+`);
+      clientWs.send(JSON.stringify(errorResponse));
+      return;
+    }
+    if (decision?.action === "transform" && decision.transformedParams) {
+      const transformed = { ...request, params: decision.transformedParams };
+      this.stats.transformedMessages++;
+      browserWs.send(JSON.stringify(transformed));
+      return;
+    }
+    this.stats.passedMessages++;
+    browserWs.send(raw.toString());
+  }
+  handleBrowserMessage(clientWs, _browserWs, raw) {
+    const msg = this.parseMessage(raw);
+    if (!msg) {
+      clientWs.send(raw.toString());
+      return;
+    }
+    if ("method" in msg) {
+      const event = msg;
+      const ctx = {
+        method: event.method,
+        params: event.params ?? {},
+        sessionId: event.sessionId ?? "browser",
+        direction: "browser\u2192client"
+      };
+      const decision = this.engine.evaluate(ctx);
+      if (decision?.action === "block") {
+        return;
+      }
+    }
+    clientWs.send(raw.toString());
+  }
+  // ── Utilities ────────────────────────────────────────────────
+  parseMessage(raw) {
+    try {
+      return JSON.parse(raw.toString());
+    } catch {
+      return null;
+    }
+  }
+  recordDecision(decision) {
+    if (!this.stats.byRule[decision.ruleId]) {
+      this.stats.byRule[decision.ruleId] = { matched: 0, blocked: 0, transformed: 0 };
+    }
+    this.stats.byRule[decision.ruleId].matched++;
+    if (decision.action === "block") {
+      this.stats.byRule[decision.ruleId].blocked++;
+    } else if (decision.action === "transform") {
+      this.stats.byRule[decision.ruleId].transformed++;
+    }
+  }
+};
+
+// src/utils/cdp.ts
+async function fetchNoProxy(url) {
+  const savedProxy = {
+    http_proxy: process.env.http_proxy,
+    https_proxy: process.env.https_proxy,
+    HTTP_PROXY: process.env.HTTP_PROXY,
+    HTTPS_PROXY: process.env.HTTPS_PROXY,
+    all_proxy: process.env.all_proxy,
+    ALL_PROXY: process.env.ALL_PROXY
+  };
+  for (const key of Object.keys(savedProxy)) delete process.env[key];
+  try {
+    return await fetch(url);
+  } finally {
+    for (const [key, val] of Object.entries(savedProxy)) {
+      if (val !== void 0) process.env[key] = val;
+    }
+  }
+}
+async function resolveCDPEndpoint(raw) {
+  if (raw === "auto") {
+    const ports = [9222, 9221, 9223, 9224];
+    for (const port of ports) {
+      try {
+        const httpResp = await fetchNoProxy(`http://localhost:${port}/json/version`);
+        if (httpResp.ok) {
+          const data = await httpResp.json();
+          if (data.webSocketDebuggerUrl) {
+            return data.webSocketDebuggerUrl;
+          }
+        }
+      } catch {
+      }
+    }
+    throw new Error(
+      `Could not auto-discover CDP endpoint. Tried ports: ${ports.join(", ")}.
+\u53EF\u80FD\u539F\u56E0\uFF1A\u6CA1\u6709 Chrome \u4EE5 --remote-debugging-port \u542F\u52A8\u3002
+\u89E3\u51B3\u65B9\u6CD5\uFF1A
+  1. \u542F\u52A8 Chrome: google-chrome --remote-debugging-port=9222
+  2. \u6216\u7528 cdp-tunnel: npx cdp-tunnel setup
+  3. \u6216\u6307\u5B9A\u7AEF\u53E3: --cdp <port>`
+    );
+  }
+  if (/^\d+$/.test(raw)) {
+    const port = raw;
+    const httpResp = await fetchNoProxy(`http://localhost:${port}/json/version`);
+    const data = await httpResp.json();
+    if (!data.webSocketDebuggerUrl) {
+      throw new Error(`Could not discover CDP endpoint from localhost:${port}`);
+    }
+    return data.webSocketDebuggerUrl;
+  }
+  if (raw.startsWith("http://") || raw.startsWith("https://")) {
+    try {
+      const httpResp = await fetchNoProxy(`${raw}/json/version`);
+      const data = await httpResp.json();
+      if (!data.webSocketDebuggerUrl) {
+        throw new Error(`Could not discover CDP endpoint from ${raw}`);
+      }
+      return data.webSocketDebuggerUrl;
+    } catch (error) {
+      console.warn(`Failed to fetch WebSocket URL from ${raw}, using endpoint directly: ${error instanceof Error ? error.message : String(error)}`);
+      return raw;
+    }
+  }
+  return raw;
+}
+
+// src/browser.ts
+import { SessionStore } from "@dyyz1993/xcli-core";
+function logSessionEvent(event, details) {
+  const ts = (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").substring(0, 19);
+  const pid = process.pid;
+  console.error(`[SESSION] ${ts} [PID:${pid}] ${event} | ${details}`);
+}
+var SESSION_DIR = join(homedir(), ".xbrowser", "sessions");
+function sessionFile(name) {
+  return join(SESSION_DIR, `${name}.json`);
+}
+function ensureSessionDir() {
+  mkdirSync(SESSION_DIR, { recursive: true });
+}
+var sessions = new SessionStore();
+var _sharedBrowser = null;
+var _sharedCdpProxy = null;
+var IDLE_TIMEOUT_MS = (process.env.XBROWSER_IDLE_TIMEOUT ? parseInt(process.env.XBROWSER_IDLE_TIMEOUT, 10) : 30) * 60 * 1e3;
+var idleTimer = null;
+function resetIdleTimer() {
+  if (idleTimer) clearTimeout(idleTimer);
+  idleTimer = setTimeout(async () => {
+    const now = Date.now();
+    let allIdle = true;
+    const idleSessions = [];
+    for (const s of sessions) {
+      if (now - s.lastActivityAt < IDLE_TIMEOUT_MS) {
+        allIdle = false;
+      } else {
+        idleSessions.push(`${s.name}(${(now - s.lastActivityAt) / 1e3}s idle)`);
+      }
+    }
+    if (allIdle && (sessions.size > 0 || _sharedBrowser)) {
+      logSessionEvent("idle_timeout", `Sessions idle for >${IDLE_TIMEOUT_MS / 6e4}min. Sessions: ${idleSessions.join(", ") || "all"}. Calling destroyBrowser()`);
+      await destroyBrowser().catch(() => {
+      });
+    }
+  }, IDLE_TIMEOUT_MS);
+  if (idleTimer && typeof idleTimer.unref === "function") {
+    idleTimer.unref();
+  }
+}
+function touchSession(id) {
+  const s = sessions.get(id);
+  if (s) s.lastActivityAt = Date.now();
+  resetIdleTimer();
+}
+process.on("exit", () => {
+  for (const session of sessions.list()) {
+    if (session.isCDP) {
+      logSessionEvent("process_exit", `Session "${session.name}": CDP connection (not closing external browser).`);
+    } else {
+      logSessionEvent("process_exit", `Session "${session.name}": Closing self-launched browser.`);
+      try {
+        session.browser?.close();
+      } catch {
+      }
+    }
+  }
+  if (_sharedBrowser) {
+    logSessionEvent("process_exit", "Closing shared browser (self-launched only, external CDP is safe).");
+    try {
+      _sharedBrowser.close();
+    } catch {
+    }
+    _sharedBrowser = null;
+  }
+  if (_sharedCdpProxy) {
+    try {
+      _sharedCdpProxy.stop();
+    } catch {
+    }
+    _sharedCdpProxy = null;
+  }
+  sessions.clear();
+});
+async function getCDPTargets(cdpEndpoint) {
+  try {
+    const ep = String(cdpEndpoint);
+    let host = "localhost";
+    let port = "9222";
+    if (ep.startsWith("http://") || ep.startsWith("https://")) {
+      const u = new URL(ep);
+      host = u.hostname;
+      port = u.port || "9222";
+    } else if (/^\d+$/.test(ep)) {
+      port = ep;
+    }
+    const url = `http://${host}:${port}/json/list`;
+    const resp = await fetch(url);
+    return await resp.json();
+  } catch {
+    return [];
+  }
+}
+async function findTargetPage(cdpEndpoint, target) {
+  const targets = await getCDPTargets(cdpEndpoint);
+  const pages = targets.filter((t) => t.url && !t.url.startsWith("about:blank") && !t.url.startsWith("chrome://") && !t.url.startsWith("chrome-untrusted://") && !t.url.startsWith("chrome-error://"));
+  const byId = pages.find((t) => t.id === target);
+  if (byId) return { pageId: byId.id, wsUrl: byId.webSocketDebuggerUrl, title: byId.title, url: byId.url };
+  const lowerTarget = target.toLowerCase();
+  const byTitle = pages.find((t) => t.title && t.title.toLowerCase().includes(lowerTarget));
+  if (byTitle) return { pageId: byTitle.id, wsUrl: byTitle.webSocketDebuggerUrl, title: byTitle.title, url: byTitle.url };
+  const byUrl = pages.find((t) => t.url.toLowerCase().includes(lowerTarget));
+  if (byUrl) return { pageId: byUrl.id, wsUrl: byUrl.webSocketDebuggerUrl, title: byUrl.title, url: byUrl.url };
+  return null;
+}
+function resolveLaunchOpts(ctx) {
+  if (ctx.cdpEndpoint) {
+    return { cdpEndpoint: ctx.cdpEndpoint };
+  }
+  return { headless: true };
+}
+var CHROMIUM_CANDIDATES = [
+  "/Applications/Chromium.app/Contents/MacOS/Chromium",
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/usr/bin/chromium-browser",
+  "/usr/bin/chromium",
+  "/usr/bin/google-chrome"
+];
+function discoverChromiumPath() {
+  for (const p of CHROMIUM_CANDIDATES) {
+    if (existsSync(p)) return p;
+  }
+  return void 0;
+}
+async function createBrowser(options) {
+  if (options?.cdpEndpoint) {
+    const realEndpoint = await resolveCDPEndpoint(options.cdpEndpoint);
+    if (options.intercept) {
+      const config = typeof options.intercept === "object" ? { ...options.intercept, cdpEndpoint: realEndpoint } : { cdpEndpoint: realEndpoint };
+      _sharedCdpProxy = new CDPInterceptorProxy(config);
+      const proxyPort = await _sharedCdpProxy.start();
+      console.error(`[CDP Interceptor] Proxy running on ws://localhost:${proxyPort}, forwarding to ${realEndpoint}`);
+      const { browser: browser3 } = await launch({ cdpEndpoint: `ws://localhost:${proxyPort}` });
+      return browser3;
+    }
+    const { browser: browser2 } = await launch({ cdpEndpoint: realEndpoint });
+    await browser2.discoverContexts().catch((err) => {
+      console.error(`[browser] discoverContexts failed: ${errMsg(err)}`);
+    });
+    return browser2;
+  }
+  const executablePath = options?.executablePath || process.env.XBROWSER_CHROMIUM_PATH || discoverChromiumPath();
+  const { browser } = await launch({ executablePath, headless: options?.headless ?? true });
+  return browser;
+}
+async function getBrowser(options) {
+  if (_sharedBrowser) return _sharedBrowser;
+  _sharedBrowser = await createBrowser(options);
+  if (options?.cdpEndpoint && options.intercept) {
+  }
+  return _sharedBrowser;
+}
+function findSession(name) {
+  return sessions.find(name);
+}
+function getSessionById(id) {
+  return sessions.get(id);
+}
+function setActivePage(session, page) {
+  session.page = page;
+  session.lastActivityAt = Date.now();
+}
+function saveSessionDiskMeta(name, data) {
+  ensureSessionDir();
+  const file = sessionFile(name);
+  let existing = {};
+  try {
+    existing = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+  }
+  Object.assign(existing, data, { name });
+  writeFileSync(file, JSON.stringify(existing, null, 2));
+}
+function readSessionDiskMeta(name) {
+  const file = sessionFile(name);
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function deleteSessionDiskMeta(name) {
+  const file = sessionFile(name);
+  try {
+    unlinkSync(file);
+  } catch {
+  }
+}
+async function isSessionPageAlive(session) {
+  const page = session.page;
+  if (!page || typeof page.evaluate !== "function") return false;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      await Promise.race([
+        page.evaluate("1"),
+        new Promise((_, reject) => setTimeout(() => reject(new Error("liveness probe timeout")), 1500))
+      ]);
+      return true;
+    } catch {
+      await new Promise((r) => setTimeout(r, 400));
+    }
+  }
+  return false;
+}
+async function findOrRestoreSession(name, cdpEndpoint) {
+  const inMem = findSession(name);
+  if (inMem) {
+    if (await isSessionPageAlive(inMem)) return inMem;
+    logSessionEvent("stale_session", `name="${name}" \u2014 page \u63A2\u9488\u5931\u8D25\uFF08\u6D4F\u89C8\u5668\u53EF\u80FD\u5DF2\u91CD\u542F\uFF09\uFF0C\u5C31\u5730\u91CD\u5EFA`);
+    try {
+      await closeSessionByName(name);
+    } catch {
+    }
+  }
+  const meta = readSessionDiskMeta(name);
+  if (!meta) return void 0;
+  const ep = cdpEndpoint || meta.cdpEndpoint;
+  if (!ep) return void 0;
+  try {
+    const b = await createBrowser({ cdpEndpoint: ep });
+    await new Promise((r) => setTimeout(r, 500));
+    let contexts = b.contexts();
+    if (contexts.length === 0) {
+      await new Promise((r) => setTimeout(r, 500));
+      contexts = b.contexts();
+    }
+    const context = contexts[0] || await b.newContext();
+    const savedUrl = meta.conversationUrl || meta.url;
+    const targetHostname = savedUrl ? (() => {
+      try {
+        return new URL(savedUrl).hostname;
+      } catch {
+        return "";
+      }
+    })() : "";
+    let page = null;
+    let fallbackPage = null;
+    for (const ctx of contexts) {
+      const pages = ctx.pages();
+      for (const p of pages) {
+        const pUrl = p.url();
+        if (pUrl && pUrl !== "about:blank" && !pUrl.startsWith("chrome://") && !pUrl.startsWith("chrome-untrusted://") && !pUrl.startsWith("chrome-error://")) {
+          if (targetHostname && pUrl.includes(targetHostname)) {
+            page = p;
+            break;
+          }
+          if (!fallbackPage) {
+            fallbackPage = p;
+          }
+        }
+      }
+      if (page) break;
+    }
+    page = page || fallbackPage;
+    if (!page) {
+      const targets = await getCDPTargets(ep);
+      const matchTarget = targets.find(
+        (t) => t.url && t.url !== "about:blank" && !t.url.startsWith("chrome://") && !t.url.startsWith("chrome-untrusted://") && !t.url.startsWith("chrome-error://") && (targetHostname ? t.url.includes(targetHostname) : true)
+      );
+      if (matchTarget && matchTarget.url) {
+        page = await context.newPage();
+        await page.goto(matchTarget.url, { waitUntil: "domcontentloaded", timeout: 15e3 }).catch(() => {
+        });
+      }
+    }
+    if (!page) {
+      const pages = context.pages();
+      page = pages.length > 0 ? pages[0] : await context.newPage();
+    }
+    try {
+      await Promise.race([
+        page.evaluate(() => true),
+        new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 3e3))
+      ]);
+    } catch {
+      console.log(`[Session] "${name}" restored page unresponsive, creating fresh session`);
+      deleteSessionDiskMeta(name);
+      return void 0;
+    }
+    const targetUrl = meta.conversationUrl || meta.url;
+    if (targetUrl && page.url() !== targetUrl) {
+      try {
+        if (!page.url().includes(new URL(targetUrl).hostname)) {
+          await page.goto(targetUrl, { waitUntil: "domcontentloaded", timeout: 3e4 }).catch(() => {
+          });
+        }
+      } catch {
+      }
+    }
+    const session = {
+      id: meta.id || randomUUID(),
+      name,
+      context,
+      page,
+      browser: b,
+      createdAt: meta.createdAt || (/* @__PURE__ */ new Date()).toISOString(),
+      lastActivityAt: Date.now(),
+      isCDP: true,
+      cdpEndpoint: ep
+    };
+    for (const existingSession of sessions.list()) {
+      if (existingSession.name === name) {
+        logSessionEvent("remove_stale", `Removing stale session name="${name}" id="${existingSession.id}" during restore`);
+        sessions.removeById(existingSession.id);
+      }
+    }
+    sessions.set(session);
+    resetIdleTimer();
+    await installNetworkCapture(page, name);
+    return session;
+  } catch (e) {
+    console.error(`[Session Restore] Failed for "${name}":`, errMsg(e));
+    deleteSessionDiskMeta(name);
+    return void 0;
+  }
+}
+async function createEphemeralContext(options) {
+  if (options?.cdpEndpoint) {
+    const endpoint = await resolveCDPEndpoint(options.cdpEndpoint);
+    const { browser: b2 } = await launch({ cdpEndpoint: endpoint });
+    const contexts = b2.contexts();
+    const ctx = contexts[0] || await b2.newContext();
+    const allPages = ctx.pages();
+    const existingPages = allPages.filter((p) => {
+      const url = p.url();
+      return url !== "about:blank" && !url.startsWith("chrome://") && !url.startsWith("chrome-untrusted://") && !url.startsWith("chrome-error://");
+    });
+    const page2 = existingPages.length > 0 ? existingPages[0] : allPages.length > 0 ? allPages[0] : await ctx.newPage();
+    resetIdleTimer();
+    ephemeralConnections.set(page2, b2);
+    return { context: ctx, page: page2 };
+  }
+  const b = await getBrowser(options);
+  const context = await b.newContext();
+  const page = await context.newPage();
+  resetIdleTimer();
+  return { context, page };
+}
+var ephemeralConnections = /* @__PURE__ */ new WeakMap();
+async function closeEphemeralContext(context) {
+  try {
+    const pages = context.pages();
+    for (const p of pages) {
+      const conn = ephemeralConnections.get(p);
+      if (conn) {
+        ephemeralConnections.delete(p);
+        await conn.close();
+        break;
+      }
+    }
+    await context.close();
+  } catch {
+  }
+  if (sessions.size === 0 && idleTimer) {
+    clearTimeout(idleTimer);
+    idleTimer = null;
+  }
+}
+function getAllSessions() {
+  return sessions.list();
+}
+async function installNetworkCapture(page, sessionName) {
+  if (process.env.XBROWSER_DAEMON_WORKER !== "1") return;
+  const { networkStore } = await import("./network-store-XGZ25FFC.js");
+  const requestData = /* @__PURE__ */ new Map();
+  const responseMeta = /* @__PURE__ */ new Map();
+  const xbPage = page;
+  xbPage.on("request", (params) => {
+    try {
+      const p = params;
+      requestData.set(p.requestId, {
+        method: p.request.method,
+        headers: p.request.headers,
+        postData: p.request.postData ?? null,
+        resourceType: p.type
+      });
+    } catch {
+    }
+  });
+  xbPage.on("response", (params) => {
+    try {
+      const p = params;
+      responseMeta.set(p.requestId, {
+        status: p.response.status,
+        url: p.response.url,
+        headers: p.response.headers,
+        mimeType: p.response.mimeType,
+        type: p.type
+      });
+    } catch {
+    }
+  });
+  xbPage.on("requestfinished", async (params) => {
+    try {
+      const p = params;
+      const meta = responseMeta.get(p.requestId);
+      if (!meta) return;
+      const req = requestData.get(p.requestId);
+      const method = req?.method ?? "GET";
+      const contentType = meta.headers["content-type"] || meta.headers["Content-Type"] || "";
+      const resourceType = req?.resourceType ?? meta.type;
+      const requestHeaders = req?.headers ?? {};
+      let requestBody = void 0;
+      const isPostLike = ["POST", "PATCH", "PUT"].includes(method);
+      if (isPostLike && requestHeaders["content-type"]?.includes("application/json")) {
+        const postData = req?.postData;
+        if (postData) {
+          try {
+            requestBody = JSON.parse(postData);
+          } catch {
+            requestBody = postData;
+          }
+        }
+      }
+      let responseBody = void 0;
+      let size = 0;
+      const isJsonish = contentType.includes("json") || contentType.includes("javascript") || contentType.includes("text/");
+      if (isJsonish) {
+        try {
+          const bodyResult = await xbPage._cdpSend(
+            "Network.getResponseBody",
+            { requestId: p.requestId }
+          );
+          const text = bodyResult.body ?? "";
+          size = text.length;
+          if (size <= 10240) {
+            try {
+              responseBody = JSON.parse(text);
+            } catch {
+              responseBody = text.slice(0, 200);
+            }
+          }
+        } catch {
+        }
+      } else {
+        try {
+          const bodyResult = await xbPage._cdpSend(
+            "Network.getResponseBody",
+            { requestId: p.requestId }
+          );
+          size = bodyResult.body?.length ?? 0;
+        } catch {
+          size = 0;
+        }
+      }
+      networkStore.add(sessionName, {
+        timestamp: Date.now(),
+        method,
+        url: meta.url,
+        path: new URL(meta.url).pathname,
+        status: meta.status,
+        contentType,
+        size,
+        headers: meta.headers,
+        body: responseBody,
+        requestHeaders,
+        requestBody,
+        resourceType
+      });
+      requestData.delete(p.requestId);
+      responseMeta.delete(p.requestId);
+    } catch {
+    }
+  });
+}
+async function createSession(name, url, options) {
+  const existing = findSession(name);
+  if (existing) {
+    logSessionEvent("replace_session", `name="${name}" id="${existing.id}" \u2014 closing existing session before creating new one`);
+    await closeSessionByName(name);
+  }
+  const b = await createBrowser(options);
+  const isCDP = !!options?.cdpEndpoint;
+  let context;
+  let page;
+  if (isCDP) {
+    const targetHostname = url ? (() => {
+      try {
+        return new URL(url).hostname;
+      } catch {
+        return "";
+      }
+    })() : "";
+    const isRealPageUrl = (u) => !!u && u !== "about:blank" && !u.startsWith("chrome://") && !u.startsWith("chrome-untrusted://") && !u.startsWith("chrome-error://");
+    const resolvePageUrl = async (p) => {
+      const u = p.url();
+      if (u && u !== "about:blank") return u;
+      try {
+        return await p.evaluate("location.href");
+      } catch {
+        return u ?? "";
+      }
+    };
+    const pollStart = Date.now();
+    for (; ; ) {
+      const ctxs = b.contexts();
+      let hostHit = false;
+      let anyHit = false;
+      for (const ctx of ctxs) {
+        for (const p of ctx.pages()) {
+          const u = await resolvePageUrl(p);
+          if (!isRealPageUrl(u)) continue;
+          anyHit = true;
+          if (targetHostname && u.includes(targetHostname)) {
+            hostHit = true;
+            break;
+          }
+        }
+        if (hostHit) break;
+      }
+      if (process.env.XB_DEBUG_SESSION_POLL) {
+        console.error(`[poll] t=${Date.now() - pollStart}ms ctxs=${ctxs.length} hostHit=${hostHit} anyHit=${anyHit}`);
+      }
+      if (hostHit) break;
+      if (anyHit && Date.now() - pollStart >= 2e3) break;
+      if (Date.now() - pollStart >= 5e3) break;
+      await new Promise((r) => setTimeout(r, 200));
+    }
+    let contexts = b.contexts();
+    if (contexts.length === 0) {
+      await new Promise((r) => setTimeout(r, 500));
+      contexts = b.contexts();
+    }
+    context = contexts[0] || await b.newContext();
+    let targetPage = null;
+    if (targetHostname) {
+      for (const ctx of contexts) {
+        const pages = ctx.pages();
+        for (const p of pages) {
+          const pUrl = await resolvePageUrl(p);
+          if (isRealPageUrl(pUrl) && pUrl.includes(targetHostname)) {
+            targetPage = p;
+            break;
+          }
+        }
+        if (targetPage) break;
+      }
+    }
+    if (!targetPage) {
+      for (const ctx of contexts) {
+        const pages = ctx.pages();
+        for (const p of pages) {
+          const pUrl = await resolvePageUrl(p);
+          if (isRealPageUrl(pUrl)) {
+            targetPage = p;
+            break;
+          }
+        }
+        if (targetPage) break;
+      }
+    }
+    if (!targetPage && options?.cdpEndpoint) {
+      const targets = await getCDPTargets(options.cdpEndpoint);
+      const matchTarget = targets.find(
+        (t) => t.url && t.url !== "about:blank" && !t.url.startsWith("chrome://") && !t.url.startsWith("chrome-untrusted://") && !t.url.startsWith("chrome-error://") && (url ? t.url.includes(new URL(url).hostname) : true)
+      );
+      if (matchTarget && matchTarget.url) {
+        targetPage = await context.newPage();
+        await targetPage.goto(matchTarget.url, { waitUntil: "domcontentloaded", timeout: 15e3 }).catch(() => {
+        });
+      }
+    }
+    if (!targetPage) {
+      const pages = context.pages();
+      if (pages.length > 0) {
+        targetPage = pages[0];
+      } else {
+        targetPage = await context.newPage();
+      }
+    }
+    page = targetPage;
+  } else {
+    context = await b.newContext({ viewport: { width: 1920, height: 1080 } });
+    page = await context.newPage();
+  }
+  if (url && page.url() !== url) {
+    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 15e3 }).catch(() => {
+    });
+  }
+  const session = {
+    id: randomUUID(),
+    name,
+    context,
+    page,
+    browser: b,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    lastActivityAt: Date.now(),
+    isCDP,
+    cdpEndpoint: options?.cdpEndpoint
+  };
+  sessions.set(session);
+  logSessionEvent("create_session", `name="${name}" id="${session.id}" url="${url || "(no url)"}" isCDP=${isCDP} cdpEndpoint=${options?.cdpEndpoint || "(none)"}`);
+  resetIdleTimer();
+  await installNetworkCapture(page, name);
+  return session;
+}
+async function closeSessionByName(name) {
+  for (const session of sessions) {
+    if (session.name === name || session.id === name) {
+      logSessionEvent("close_session", `name="${session.name}" id="${session.id}" url="${session.page.url()}"`);
+      if (session.isCDP) {
+        if (session.browser) {
+          await session.browser.close().catch(() => {
+          });
+        }
+      } else {
+        await session.context.close();
+        if (session.browser) {
+          await session.browser.close().catch(() => {
+          });
+        }
+      }
+      sessions.removeById(session.id);
+      const file2 = sessionFile(session.name);
+      try {
+        unlinkSync(file2);
+      } catch {
+      }
+      try {
+        const { networkStore, commandLogStore } = await import("./network-store-XGZ25FFC.js");
+        networkStore.clear(session.name);
+        commandLogStore.clear(session.name);
+      } catch {
+      }
+      try {
+        const { SessionRecorder } = await import("./session-recorder-3BEVWHOK.js");
+        SessionRecorder.cleanup(session.name);
+      } catch {
+      }
+      return true;
+    }
+  }
+  const file = sessionFile(name);
+  try {
+    unlinkSync(file);
+  } catch {
+  }
+  return false;
+}
+async function closeAllSessions() {
+  const names = sessions.list().map((s) => `${s.name}(${s.page.url()})`).join(", ");
+  if (names) logSessionEvent("close_all_sessions", `Closing ${sessions.size} sessions: ${names}`);
+  for (const session of sessions.list()) {
+    try {
+      if (session.isCDP) {
+        if (session.browser) {
+          await session.browser.close().catch(() => {
+          });
+        }
+      } else {
+        await session.context.close();
+        if (session.browser) {
+          await session.browser.close().catch(() => {
+          });
+        }
+      }
+      sessions.removeById(session.id);
+    } catch {
+      sessions.removeById(session.id);
+    }
+  }
+}
+async function destroyBrowser() {
+  logSessionEvent("destroy_browser", `Sessions count: ${sessions.size}. Clearing idle timer and closing all sessions.`);
+  if (idleTimer) {
+    clearTimeout(idleTimer);
+    idleTimer = null;
+  }
+  await closeAllSessions();
+  if (_sharedBrowser) {
+    await _sharedBrowser.close().catch(() => {
+    });
+    _sharedBrowser = null;
+  }
+  if (_sharedCdpProxy) {
+    await _sharedCdpProxy.stop().catch(() => {
+    });
+    _sharedCdpProxy = null;
+  }
+}
+function resetForTesting() {
+  sessions.clear();
+  _sharedBrowser = null;
+  _sharedCdpProxy = null;
+  try {
+    for (const f of readdirSync(SESSION_DIR)) {
+      unlinkSync(join(SESSION_DIR, f));
+    }
+  } catch {
+  }
+}
+async function ensureProcessCanExit() {
+  if (idleTimer) {
+    clearTimeout(idleTimer);
+    idleTimer = null;
+  }
+  for (const session of sessions.list()) {
+    if (session.browser) {
+      if (session.isCDP) {
+      } else {
+        await session.browser.close().catch(() => {
+        });
+      }
+    }
+  }
+  sessions.clear();
+  if (_sharedBrowser) {
+    await _sharedBrowser.close().catch(() => {
+    });
+    _sharedBrowser = null;
+  }
+  if (_sharedCdpProxy) {
+    await _sharedCdpProxy.stop().catch(() => {
+    });
+    _sharedCdpProxy = null;
+  }
+}
+
+export {
+  resolveCDPEndpoint,
+  touchSession,
+  findTargetPage,
+  resolveLaunchOpts,
+  createBrowser,
+  getBrowser,
+  findSession,
+  getSessionById,
+  setActivePage,
+  saveSessionDiskMeta,
+  readSessionDiskMeta,
+  deleteSessionDiskMeta,
+  findOrRestoreSession,
+  createEphemeralContext,
+  closeEphemeralContext,
+  getAllSessions,
+  createSession,
+  closeSessionByName,
+  closeAllSessions,
+  destroyBrowser,
+  resetForTesting,
+  ensureProcessCanExit
+};