@xbrowser/cli 1.10.0 → 1.11.0

package/dist/cli.js

@@ -22,7 +22,7 @@ import {
   forwardSessionList,
   forwardViewerCheckSelector,
   version
-} from "./chunk-YMUSHPU4.js";
+} from "./chunk-WHPBNUKB.js";
 import {
   buildViewerUrl
 } from "./chunk-3OD76SUE.js";
@@ -35,7 +35,7 @@ import {
 } from "./chunk-Q2DFJQGS.js";
 import {
   SessionRecorder
-} from "./chunk-4452SPFI.js";
+} from "./chunk-NODRQGOK.js";
 import {
   addKnownIssue,
   getKnowledgePath,
@@ -59,7 +59,7 @@ import {
   resolveLaunchOpts,
   saveSessionDiskMeta,
   setActivePage
-} from "./chunk-NITFVWWS.js";
+} from "./chunk-JEDP4PJW.js";
 import "./chunk-TNEN6VQ2.js";
 import {
   errMsg
@@ -67,7 +67,7 @@ import {
 import {
   detectAntiBot,
   formatDetectionMessage
-} from "./chunk-INTQPBYF.js";
+} from "./chunk-JKVUFP3G.js";
 import {
   NPM_REGISTRY_URL,
   NPM_SCOPE,
@@ -460,14 +460,23 @@ var CAPTCHA_SELECTORS = {
   generic: '#captcha, .captcha-container, [class*="captcha"]'
 };
 async function detectCaptcha(page) {
-  for (const [type, selector] of Object.entries(CAPTCHA_SELECTORS)) {
-    const el = await page.$(selector);
-    if (el) {
-      const iframeUrl = await el.getAttribute("src").catch(() => void 0);
-      return { type, selector, iframeUrl: iframeUrl || void 0 };
-    }
-  }
-  return null;
+  const hit = await page.evaluate(`
+    (function() {
+      var S = ${JSON.stringify(CAPTCHA_SELECTORS)};
+      for (var type in S) {
+        var sel = S[type];
+        var el;
+        try { el = document.querySelector(sel); } catch (e) { continue; }
+        if (el) {
+          var url = el.getAttribute && el.getAttribute('src');
+          return { type: type, selector: sel, iframeUrl: url || undefined };
+        }
+      }
+      return null;
+    })()
+  `).catch(() => null);
+  if (!hit) return null;
+  return { type: hit.type, selector: hit.selector, iframeUrl: hit.iframeUrl || void 0 };
 }
 async function waitForCaptchaSolved(page, captchaInfo, timeoutMs = 18e4) {
   const startTime = Date.now();
@@ -518,12 +527,24 @@ var clickCommand = registerCommand({
     let detectedNewPage;
     let cleanup;
     if (ctx.browserContext?.on) {
+      const targetIdOf = (p2) => p2._targetId;
+      let targetIdsBefore;
+      try {
+        targetIdsBefore = new Set(ctx.browserContext.pages().map(targetIdOf));
+      } catch {
+        targetIdsBefore = /* @__PURE__ */ new Set();
+      }
       const pagePromise = new Promise((resolve10) => {
         const timer = setTimeout(() => {
           ctx.browserContext.off("page", handler);
           resolve10(void 0);
         }, 3e3);
         const handler = (page2) => {
+          if (targetIdsBefore.has(targetIdOf(page2))) return;
+          try {
+            if ((page2.url?.() ?? "") === "about:blank") return;
+          } catch {
+          }
           clearTimeout(timer);
           ctx.browserContext.off("page", handler);
           resolve10(page2);
@@ -924,9 +945,11 @@ var mouseCommand = registerCommand({
         await ctx.page.mouse.move(p.x, p.y, { steps: p.steps || 1 });
         break;
       case "down":
+        await ctx.page.mouse.move(p.x, p.y);
         await ctx.page.mouse.down({ button });
         break;
       case "up":
+        await ctx.page.mouse.move(p.x, p.y);
         await ctx.page.mouse.up({ button });
         break;
       case "click":
@@ -945,10 +968,11 @@ import { z as z7 } from "zod";
 import { ok as ok7, normalizeTips as normalizeTips2 } from "@dyyz1993/xcli-core";
 var evaluateCommand = registerCommand({
   name: "eval",
-  description: "Evaluate JavaScript expression in the browser",
+  description: "Evaluate JavaScript expression in the browser (--frame <url-substring> \u53EF\u5B9A\u5411\u5230 iframe \u4E0A\u4E0B\u6587\uFF0C\u8DE8\u57DF iframe \u4EA6\u53EF)",
   scope: "page",
   parameters: z7.object({
-    expression: z7.string()
+    expression: z7.string(),
+    frame: z7.string().optional().describe("\u5728 URL \u542B\u6B64\u5B50\u4E32\u7684 iframe \u91CC\u6267\u884C\uFF08\u540C\u8FDB\u7A0B\u7528 contextId\uFF0C\u8DE8\u57DF OOPIF \u7528 Target auto-attach\uFF09")
   }),
   handler: async (p, ctx) => {
     const engine = createRuleEngine();
@@ -960,7 +984,7 @@ var evaluateCommand = registerCommand({
       direction: "client\u2192browser"
     });
     engine.stop();
-    const result = await ctx.page.evaluate(p.expression);
+    const result = p.frame ? await ctx.page.evaluateInFrame(p.frame, p.expression) : await ctx.page.evaluate(p.expression);
     const response = ok7({ result });
     if (decision && decision.severity === "danger") {
       response.tips = normalizeTips2([`${decision.suggestion}`]);
@@ -5448,6 +5472,11 @@ async function handleSwitch(p, pages, ctx) {
   const targetPage = pages[p.index];
   await targetPage.bringToFront().catch(() => {
   });
+  for (let i = 0; i < 5; i++) {
+    const okProbe = await targetPage.evaluate("1").then(() => true, () => false);
+    if (okProbe) break;
+    await new Promise((r) => setTimeout(r, 300));
+  }
   const session = ctx.sessionId ? getSessionById(ctx.sessionId) : void 0;
   if (session) {
     setActivePage(session, targetPage);
@@ -5871,7 +5900,7 @@ function describeSelector(strategy, value, name) {
 // src/context.ts
 function attachDetectAntiBot(ctx) {
   ctx.detectAntiBot = async (page, config) => {
-    const { detectAntiBot: detectAntiBot2 } = await import("./anti-bot-DR56Y63V.js");
+    const { detectAntiBot: detectAntiBot2 } = await import("./anti-bot-GTTYNEFB.js");
     return detectAntiBot2(page, config);
   };
 }
@@ -7051,7 +7080,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
   }
   let targetPageOverride = null;
   if (_target && extraOpts?.cdpEndpoint) {
-    const { findTargetPage } = await import("./browser-T3V3JWVH.js");
+    const { findTargetPage } = await import("./browser-Q5APBNF6.js");
     targetPageOverride = await findTargetPage(extraOpts.cdpEndpoint, _target);
     if (!targetPageOverride) {
       return errorResult(`Target "${_target}" not found. Use 'xbrowser targets --cdp ${extraOpts.cdpEndpoint}' to list available pages.`);
@@ -7068,7 +7097,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
     params = result.data;
   }
   if (command.scope !== "cli" && !process.env.XBROWSER_DAEMON_WORKER) {
-    const { forwardExec } = await import("./daemon-client-O6BYVRXV.js");
+    const { forwardExec } = await import("./daemon-client-Y2YSZCGK.js");
     const result = await forwardExec(commandName, params, sessionName, extraOpts?.cdpEndpoint);
     if (result) return result;
   }
@@ -9679,10 +9708,12 @@ var HTML_TAGS = /* @__PURE__ */ new Set([
   "map",
   "area"
 ]);
+var SELECTOR_DSL_PREFIXES = /^(text=|popup-text=|xpath=|role=|css=|chain=)/;
 function normalizeSelector(input) {
   if (!input) return input;
   if (/^[#\.\[\:\/]/.test(input)) return input;
   if (input === "*") return input;
+  if (SELECTOR_DSL_PREFIXES.test(input)) return input;
   if (/[>\s+,~]/.test(input)) return input;
   const tagName = input.match(/^[a-zA-Z][a-zA-Z0-9]*/)?.[0];
   if (tagName && HTML_TAGS.has(tagName.toLowerCase())) return input;
@@ -9857,11 +9888,23 @@ async function handleBrowserCommand(command, args, options, sessionName, mode, c
           output: options.output || options.o || args[0]
         };
         break;
-      case "eval":
+      case "eval": {
         cmdName = "eval";
-        params = { expression: args.join(" ") || options.expression || "" };
-        if (!params.expression) outputError("Usage: xbrowser eval <expression>");
+        const frameVal = options.frame || void 0;
+        const exprParts = [];
+        for (let i = 0; i < args.length; i++) {
+          if (args[i] === "--frame") {
+            i++;
+            continue;
+          }
+          if (args[i].startsWith("--frame=")) continue;
+          exprParts.push(args[i]);
+        }
+        params = { expression: exprParts.join(" ") || options.expression || "" };
+        if (frameVal) params.frame = frameVal;
+        if (!params.expression) outputError("Usage: xbrowser eval <expression> [--frame <url-substring>]");
         break;
+      }
       case "scroll": {
         let direction = "down";
         let distance;
@@ -10564,7 +10607,7 @@ async function handlePlugin(args, options, mode) {
       } catch {
       }
       try {
-        const { daemonPing } = await import("./daemon-client-O6BYVRXV.js");
+        const { daemonPing } = await import("./daemon-client-Y2YSZCGK.js");
         if (await daemonPing()) {
           await fetch("http://localhost:9224/rpc", {
             method: "POST",
@@ -11130,7 +11173,7 @@ async function handleFilter(args, _mode, options) {
   }
 }
 async function handleGeneratePlugin(sessionName, pluginName, outputDir) {
-  const { SessionRecorder: SessionRecorder2 } = await import("./session-recorder-QRZMKFVL.js");
+  const { SessionRecorder: SessionRecorder2 } = await import("./session-recorder-SLDBENVF.js");
   const { readSiteKnowledge: readSiteKnowledge2, toMarkdown } = await import("./site-knowledge-SYC6VCDB.js");
   const { mkdirSync: mkdirSync10, writeFileSync: writeFileSync12 } = await import("fs");
   const { join: join13 } = await import("path");
@@ -12436,6 +12479,9 @@ var HTTPServer = class {
         this.server = null;
         reject(err);
       });
+      server.headersTimeout = 20 * 6e4;
+      server.requestTimeout = 20 * 6e4;
+      server.keepAliveTimeout = 20 * 6e4;
       server.listen(this.port, this.host, () => {
         const addr = server.address();
         if (addr && typeof addr === "object") {
@@ -13071,7 +13117,7 @@ Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
           }
           const needsBrowser = cmdEntry.scope === "page" || cmdEntry.scope === "browser";
           if (needsBrowser && !process.env.XBROWSER_DAEMON_WORKER) {
-            const { forwardPluginExec } = await import("./daemon-client-O6BYVRXV.js");
+            const { forwardPluginExec } = await import("./daemon-client-Y2YSZCGK.js");
             const userTimeout = typeof params.timeout === "number" && params.timeout > 0 ? params.timeout * 1e3 + 3e4 : void 0;
             const result = await forwardPluginExec(`${command}.${subCommand}`, params, sessionName, cdpEndpoint, userTimeout);
             const resultData = result && typeof result === "object" && "data" in result ? result.data : void 0;
@@ -13111,7 +13157,7 @@ Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
               const targetPage = pages[cmdTabIndex];
               await targetPage.bringToFront().catch(() => {
               });
-              const { setActivePage: setActivePage2 } = await import("./browser-T3V3JWVH.js");
+              const { setActivePage: setActivePage2 } = await import("./browser-Q5APBNF6.js");
               setActivePage2(session, targetPage);
             }
           }
@@ -13387,7 +13433,7 @@ async function main() {
     const command = process.argv[2];
     const isLongRunning = command === "preview" || command === "serve";
     if (!isLongRunning) {
-      const { ensureProcessCanExit } = await import("./browser-T3V3JWVH.js");
+      const { ensureProcessCanExit } = await import("./browser-Q5APBNF6.js");
       await ensureProcessCanExit().catch(() => {
       });
       process.exit(process.exitCode || exitCode);

package/dist/{daemon-client-GKEPT4NY.js → daemon-client-MMDRYCF5.js}

@@ -11,6 +11,7 @@ import {
 import "./chunk-KFQGP6VL.js";
 
 // src/client/daemon-client.ts
+import { request as httpRequest } from "http";
 var DAEMON_PORT = 9224;
 var DAEMON_BASE = `http://localhost:${DAEMON_PORT}`;
 var _ensurePromise = null;
@@ -205,7 +206,40 @@ async function forwardRecordSummary(session) {
   return rpcCall("record:summary", { session }, 5e3);
 }
 async function forwardReplay(file, session, slowMo) {
-  return rpcCall("replay", { file, session, slowMo }, 12e4);
+  return longRpcCall("replay", { file, session, slowMo }, 20 * 6e4);
+}
+function longRpcCall(method, params, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const body = JSON.stringify({ method, params });
+    const req = httpRequest(
+      {
+        hostname: "127.0.0.1",
+        port: DAEMON_PORT,
+        path: "/rpc",
+        method: "POST",
+        headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on("end", () => {
+          try {
+            const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+            if (parsed && typeof parsed.error === "string" && Object.keys(parsed).length === 1) {
+              reject(new Error(`Daemon error: ${parsed.error}`));
+            } else {
+              resolve(parsed);
+            }
+          } catch (e) {
+            reject(e instanceof Error ? e : new Error(String(e)));
+          }
+        });
+      }
+    );
+    req.setTimeout(timeoutMs, () => req.destroy(new Error(`replay RPC timeout after ${timeoutMs}ms`)));
+    req.on("error", reject);
+    req.end(body);
+  });
 }
 async function forwardRecordCheckpoint(session, type, hint, selector) {
   return rpcCall("record:checkpoint", { session, type, hint, selector }, 1e4);

package/dist/{daemon-client-O6BYVRXV.js → daemon-client-Y2YSZCGK.js}

@@ -30,7 +30,7 @@ import {
   forwardSessionList,
   forwardViewerCheckSelector,
   isDaemonRunning
-} from "./chunk-YMUSHPU4.js";
+} from "./chunk-WHPBNUKB.js";
 import "./chunk-Q2DFJQGS.js";
 import "./chunk-GDKLH7ZY.js";
 import "./chunk-KFQGP6VL.js";

package/dist/daemon-main.js

@@ -15,7 +15,7 @@ import {
 } from "./chunk-VEDJ5XSQ.js";
 import {
   SessionRecorder
-} from "./chunk-5UGR6MUK.js";
+} from "./chunk-HBHOKZPN.js";
 import {
   closeEphemeralContext,
   closeSessionByName,
@@ -31,8 +31,11 @@ import {
   resolveLaunchOpts,
   saveSessionDiskMeta,
   setActivePage
-} from "./chunk-BAHSRZIX.js";
-import "./chunk-RRBXV7KE.js";
+} from "./chunk-HVPUVVSA.js";
+import "./chunk-XQ4HRPDJ.js";
+import {
+  queryJS
+} from "./chunk-3FWLW7FS.js";
 import "./chunk-TNEN6VQ2.js";
 import {
   errMsg
@@ -40,7 +43,7 @@ import {
 import {
   detectAntiBot,
   formatDetectionMessage
-} from "./chunk-INTQPBYF.js";
+} from "./chunk-JKVUFP3G.js";
 import {
   ScreencastCapturer
 } from "./chunk-BNO7OKO4.js";
@@ -416,14 +419,23 @@ var CAPTCHA_SELECTORS = {
   generic: '#captcha, .captcha-container, [class*="captcha"]'
 };
 async function detectCaptcha(page) {
-  for (const [type, selector] of Object.entries(CAPTCHA_SELECTORS)) {
-    const el = await page.$(selector);
-    if (el) {
-      const iframeUrl = await el.getAttribute("src").catch(() => void 0);
-      return { type, selector, iframeUrl: iframeUrl || void 0 };
-    }
-  }
-  return null;
+  const hit = await page.evaluate(`
+    (function() {
+      var S = ${JSON.stringify(CAPTCHA_SELECTORS)};
+      for (var type in S) {
+        var sel = S[type];
+        var el;
+        try { el = document.querySelector(sel); } catch (e) { continue; }
+        if (el) {
+          var url = el.getAttribute && el.getAttribute('src');
+          return { type: type, selector: sel, iframeUrl: url || undefined };
+        }
+      }
+      return null;
+    })()
+  `).catch(() => null);
+  if (!hit) return null;
+  return { type: hit.type, selector: hit.selector, iframeUrl: hit.iframeUrl || void 0 };
 }
 async function waitForCaptchaSolved(page, captchaInfo, timeoutMs = 18e4) {
   const startTime = Date.now();
@@ -474,12 +486,24 @@ var clickCommand = registerCommand({
     let detectedNewPage;
     let cleanup;
     if (ctx.browserContext?.on) {
+      const targetIdOf = (p2) => p2._targetId;
+      let targetIdsBefore;
+      try {
+        targetIdsBefore = new Set(ctx.browserContext.pages().map(targetIdOf));
+      } catch {
+        targetIdsBefore = /* @__PURE__ */ new Set();
+      }
       const pagePromise = new Promise((resolve) => {
         const timer = setTimeout(() => {
           ctx.browserContext.off("page", handler);
           resolve(void 0);
         }, 3e3);
         const handler = (page2) => {
+          if (targetIdsBefore.has(targetIdOf(page2))) return;
+          try {
+            if ((page2.url?.() ?? "") === "about:blank") return;
+          } catch {
+          }
           clearTimeout(timer);
           ctx.browserContext.off("page", handler);
           resolve(page2);
@@ -880,9 +904,11 @@ var mouseCommand = registerCommand({
         await ctx.page.mouse.move(p.x, p.y, { steps: p.steps || 1 });
         break;
       case "down":
+        await ctx.page.mouse.move(p.x, p.y);
         await ctx.page.mouse.down({ button });
         break;
       case "up":
+        await ctx.page.mouse.move(p.x, p.y);
         await ctx.page.mouse.up({ button });
         break;
       case "click":
@@ -901,10 +927,11 @@ import { z as z7 } from "zod";
 import { ok as ok7, normalizeTips as normalizeTips2 } from "@dyyz1993/xcli-core";
 var evaluateCommand = registerCommand({
   name: "eval",
-  description: "Evaluate JavaScript expression in the browser",
+  description: "Evaluate JavaScript expression in the browser (--frame <url-substring> \u53EF\u5B9A\u5411\u5230 iframe \u4E0A\u4E0B\u6587\uFF0C\u8DE8\u57DF iframe \u4EA6\u53EF)",
   scope: "page",
   parameters: z7.object({
-    expression: z7.string()
+    expression: z7.string(),
+    frame: z7.string().optional().describe("\u5728 URL \u542B\u6B64\u5B50\u4E32\u7684 iframe \u91CC\u6267\u884C\uFF08\u540C\u8FDB\u7A0B\u7528 contextId\uFF0C\u8DE8\u57DF OOPIF \u7528 Target auto-attach\uFF09")
   }),
   handler: async (p, ctx) => {
     const engine = createRuleEngine();
@@ -916,7 +943,7 @@ var evaluateCommand = registerCommand({
       direction: "client\u2192browser"
     });
     engine.stop();
-    const result = await ctx.page.evaluate(p.expression);
+    const result = p.frame ? await ctx.page.evaluateInFrame(p.frame, p.expression) : await ctx.page.evaluate(p.expression);
     const response = ok7({ result });
     if (decision && decision.severity === "danger") {
       response.tips = normalizeTips2([`${decision.suggestion}`]);
@@ -5404,6 +5431,11 @@ async function handleSwitch(p, pages, ctx) {
   const targetPage = pages[p.index];
   await targetPage.bringToFront().catch(() => {
   });
+  for (let i = 0; i < 5; i++) {
+    const okProbe = await targetPage.evaluate("1").then(() => true, () => false);
+    if (okProbe) break;
+    await new Promise((r) => setTimeout(r, 300));
+  }
   const session = ctx.sessionId ? getSessionById(ctx.sessionId) : void 0;
   if (session) {
     setActivePage(session, targetPage);
@@ -5827,7 +5859,7 @@ function describeSelector(strategy, value, name) {
 // src/context.ts
 function attachDetectAntiBot(ctx) {
   ctx.detectAntiBot = async (page, config) => {
-    const { detectAntiBot: detectAntiBot2 } = await import("./anti-bot-DR56Y63V.js");
+    const { detectAntiBot: detectAntiBot2 } = await import("./anti-bot-GTTYNEFB.js");
     return detectAntiBot2(page, config);
   };
 }
@@ -6565,7 +6597,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
   }
   let targetPageOverride = null;
   if (_target && extraOpts?.cdpEndpoint) {
-    const { findTargetPage } = await import("./browser-WQZ3D6AE.js");
+    const { findTargetPage } = await import("./browser-XNU7JQYC.js");
     targetPageOverride = await findTargetPage(extraOpts.cdpEndpoint, _target);
     if (!targetPageOverride) {
       return errorResult(`Target "${_target}" not found. Use 'xbrowser targets --cdp ${extraOpts.cdpEndpoint}' to list available pages.`);
@@ -6582,7 +6614,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
     params = result.data;
   }
   if (command.scope !== "cli" && !process.env.XBROWSER_DAEMON_WORKER) {
-    const { forwardExec } = await import("./daemon-client-GKEPT4NY.js");
+    const { forwardExec } = await import("./daemon-client-MMDRYCF5.js");
     const result = await forwardExec(commandName, params, sessionName, extraOpts?.cdpEndpoint);
     if (result) return result;
   }
@@ -7941,15 +7973,26 @@ function createRPCHandler() {
     const needsPause = INTERACTION_COMMANDS2.has(command) && !!previewWS;
     if (needsPause) await previewWS.pauseScreencast(sessionName);
     let urlBeforeCommand;
+    let preElement;
     try {
       const session = findSession(sessionName);
       urlBeforeCommand = session?.page?.url();
+      const sel = cmdParams.selector || cmdParams.css;
+      if (session?.page && sel && INTERACTION_COMMANDS2.has(command)) {
+        preElement = await session.page.evaluate(`
+          (function() {
+            const el = ${queryJS(sel)};
+            if (!el || typeof window.__xb_describe !== 'function') return null;
+            return window.__xb_describe(el);
+          })()
+        `);
+      }
     } catch {
     }
     try {
       const result = await executeCommand(command, cmdParams, sessionName, { cdpEndpoint: endpoint });
       registerSessionIfNew(sessionName);
-      await injectCommandToRecorder(sessionName, command, cmdParams, urlBeforeCommand);
+      await injectCommandToRecorder(sessionName, command, cmdParams, urlBeforeCommand, preElement);
       return result;
     } finally {
       if (needsPause) await previewWS.resumeScreencast(sessionName).catch(() => {
@@ -8104,7 +8147,7 @@ function createRPCHandler() {
     const limit = params.limit || 50;
     return { session: sessionName, commands: commandLogStore.list(sessionName, { limit }) };
   }
-  async function injectCommandToRecorder(sessionName, command, params, urlBeforeCommand) {
+  async function injectCommandToRecorder(sessionName, command, params, urlBeforeCommand, preElement) {
     const recorder = activeRecorders.get(sessionName);
     if (!recorder) return;
     const COMMAND_ACTION_MAP = {
@@ -8112,33 +8155,48 @@ function createRPCHandler() {
       fill: "cdp-fill",
       click: "cdp-click",
       type: "input",
-      select: "change"
+      select: "change",
+      scroll: "scroll"
     };
     const actionType = COMMAND_ACTION_MAP[command];
     if (!actionType) return;
     const selector = params.selector || params.css;
-    const value = params.value || params.expression;
+    let value = params.value || params.expression;
+    if (value === void 0 || value === "") {
+      value = params.text;
+    }
+    if (command === "scroll") {
+      const dir = params.direction || "down";
+      const dist = params.distance ?? 300;
+      value = `${dir}:${dist}`;
+    }
     let currentUrl = params.url || urlBeforeCommand;
     if (command !== "goto" && urlBeforeCommand && urlBeforeCommand !== "about:blank") {
       currentUrl = urlBeforeCommand;
     }
-    let element;
-    if (selector) {
+    let element = preElement;
+    if (!element && selector) {
       try {
         const session = findSession(sessionName);
         if (session?.page) {
-          element = await session.page.evaluate((sel) => {
-            const el = document.querySelector(sel);
-            if (!el || typeof window.__xb_describe !== "function") return null;
-            return window.__xb_describe(el);
-          }, selector);
+          element = await session.page.evaluate(`
+            (function() {
+              const el = ${queryJS(selector)};
+              if (!el || typeof window.__xb_describe !== 'function') return null;
+              return window.__xb_describe(el);
+            })()
+          `);
         }
       } catch {
       }
     }
     await recorder.recordCommandAction({
       type: actionType,
-      selector,
+      // Prefer the described unique selector so the dedup key matches the
+      // real action signal's key (which uses element.selector). The raw
+      // command selector (e.g. "button") never equals the generated unique
+      // selector, so dedup silently failed before (rec-duel d02/d03).
+      selector: element?.selector || selector,
       value,
       url: currentUrl,
       element
@@ -8348,7 +8406,7 @@ function createRPCHandler() {
     if (isNewFormat) {
       try {
         const replayErrors = [];
-        const { SessionReplayer } = await import("./session-replayer-LJUC4TI7.js");
+        const { SessionReplayer } = await import("./session-replayer-WIUYVN5J.js");
         const replayer = new SessionReplayer({
           page: session.page,
           stepDelay: slowMo * 500,

package/dist/index.d.ts

@@ -173,6 +173,12 @@ interface XBPage {
     }): Promise<void>;
     addInitScript(script: string): Promise<void>;
     discoverFrames(): Promise<XBFrame[]>;
+    /**
+     * 在 URL 含 urlIncludes 的 iframe 上下文中执行表达式。
+     * 同进程 iframe 走 contextId；跨域 OOPIF 走 Target auto-attach。
+     * 绕过页面同源策略（CDP 是调试通道）——跨域嵌入内容读写的唯一路径。
+     */
+    evaluateInFrame<R = unknown>(urlIncludes: string, expression: string): Promise<R>;
     bringToFront(): Promise<void>;
     setExtraHTTPHeaders(headers: Record<string, string>): Promise<void>;
     setOfflineMode(offline: boolean): Promise<void>;
@@ -288,6 +294,7 @@ interface XBMouse {
         button?: 'left' | 'right' | 'middle';
         clickCount?: number;
         delay?: number;
+        stealth?: boolean;
     }): Promise<void>;
     dblclick(x: number, y: number, opts?: {
         button?: 'left' | 'right' | 'middle';
@@ -311,6 +318,7 @@ interface XBKeyboard {
     up(key: string): Promise<void>;
     type(text: string, opts?: {
         delay?: number;
+        stealth?: boolean;
     }): Promise<void>;
     insertText(text: string): Promise<void>;
 }