@xbrowser/cli 1.21.0 → 1.22.0

package/dist/session-replayer-XM5L7LFD.js

@@ -0,0 +1,927 @@
+import {
+  queryAllDeepJS,
+  queryJS
+} from "./chunk-A7NEA4PA.js";
+import "./chunk-KFQGP6VL.js";
+
+// src/recorder/session-replayer.ts
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var HEAL_KB_TTL_DAYS = 30;
+var NATIVE_VALUE_INJECT_TYPES = /* @__PURE__ */ new Set([
+  "color",
+  "date",
+  "datetime-local",
+  "month",
+  "week",
+  "time"
+]);
+var SessionReplayer = class {
+  opts;
+  recording = null;
+  page = null;
+  constructor(opts) {
+    this.opts = {
+      cdpUrl: opts.cdpUrl,
+      page: opts.page,
+      stepDelay: opts.stepDelay ?? 500,
+      stepTimeout: opts.stepTimeout ?? 1e4,
+      onStep: opts.onStep,
+      onError: opts.onError,
+      selfHealing: opts.selfHealing !== false,
+      onHealed: opts.onHealed,
+      healKnowledgeDir: opts.healKnowledgeDir ?? join(homedir(), ".xbrowser", "knowledge"),
+      actionRetry: opts.actionRetry ?? true
+    };
+  }
+  /** Load a recording from a file path or parsed JSON */
+  async load(source) {
+    if (typeof source === "string") {
+      const fs = await import("fs");
+      const raw = fs.readFileSync(source, "utf8");
+      this.recording = JSON.parse(raw);
+    } else {
+      this.recording = source;
+    }
+  }
+  /** Run the full replay */
+  async run() {
+    if (!this.recording) throw new Error("No recording loaded. Call load() first.");
+    const { startKeepAwake } = await import("./keep-awake-M4KJS4B4.js");
+    const keepAwake = startKeepAwake();
+    try {
+      return await this._runInner();
+    } finally {
+      keepAwake.dispose();
+    }
+  }
+  async _runInner() {
+    if (!this.recording) throw new Error("No recording loaded. Call load() first.");
+    if (this.opts.page) {
+      this.page = this.opts.page;
+    } else if (this.opts.cdpUrl) {
+      const { launch } = await import("./cdp-driver-DC7EIUG5.js");
+      const { browser } = await launch({ cdpEndpoint: this.opts.cdpUrl });
+      let contexts = browser.contexts();
+      for (let i = 0; i < 10 && contexts.length === 0; i++) {
+        await new Promise((r) => setTimeout(r, 500));
+        contexts = browser.contexts();
+      }
+      const context = contexts[0];
+      if (!context) throw new Error("No browser context available");
+      const pages = context.pages();
+      this.page = pages[0];
+    }
+    if (!this.page) throw new Error("No page available. Provide cdpUrl or page.");
+    const actions = this.dedupAdjacentActions(this.recording.actions);
+    let success = 0;
+    let failed = 0;
+    let skipped = 0;
+    let retried = 0;
+    const healedDetails = [];
+    for (let i = 0; i < actions.length; i++) {
+      const action = actions[i];
+      this.opts.onStep?.(action, i, actions.length);
+      const pagesBefore = this.listContextPages();
+      const prevOnHealed = this.opts.onHealed;
+      this.opts.onHealed = (a, strategy, idx) => {
+        healedDetails.push({ index: i, strategy });
+        prevOnHealed?.(a, strategy, idx);
+      };
+      try {
+        if (action.trajectory) {
+          await this.replayTrajectory(action.trajectory);
+        }
+        try {
+          await this.replayAction(action);
+        } catch (e) {
+          if (this.opts.actionRetry === false || action.type === "navigation" || action.type === "goto") {
+            throw e;
+          }
+          retried++;
+          await new Promise((r) => setTimeout(r, 1200));
+          await this.replayAction(action);
+        }
+        if (action.type !== "resize" && action.type !== "clipboard" && action.type !== "visibility") {
+          try {
+            await this.page.waitForLoadState("domcontentloaded", this.opts.stepTimeout);
+          } catch {
+          }
+        }
+        success++;
+        if (action.type === "click" || action.type === "cdp-click") {
+          const pagesAfter = this.listContextPages();
+          if (pagesAfter && pagesBefore && pagesAfter.length > pagesBefore.length) {
+            const newest = pagesAfter[pagesAfter.length - 1];
+            await newest.bringToFront().catch(() => {
+            });
+            this.page = newest;
+          }
+        }
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        this.opts.onError?.(action, err, i);
+        failed++;
+      } finally {
+        this.opts.onHealed = prevOnHealed;
+      }
+      if (i < actions.length - 1) {
+        await new Promise((r) => setTimeout(r, this.opts.stepDelay));
+      }
+    }
+    return {
+      success,
+      failed,
+      skipped,
+      retried,
+      healed: healedDetails.length,
+      healedDetails
+    };
+  }
+  /** Replay a single action */
+  /** Pages of the replayer page's context (best-effort; null if unavailable). */
+  listContextPages() {
+    try {
+      const ctx = this.page.context?.();
+      const pages = ctx?.pages?.();
+      return Array.isArray(pages) ? pages : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Replay-time adjacent dedup (rec-duel d02/d03/d05).
+   *
+   * The recorder can emit both the real action signal AND the injected cdp
+   * command action for a single interaction when the signal flush lags behind
+   * the recorder-side dedup window (heavy snapshot capture slows polling).
+   * Replaying both executes the interaction twice. Filter here: an action is
+   * skipped when a nearby (≤15s apart) earlier action matches on
+   * type-normalized key (selector + text) AND coordinates agree — either side
+   * lacks coords (cdp actions carry none) or both are within 30px. Two real
+   * clicks on the same element at different spots (canvas buttons) survive.
+   */
+  dedupAdjacentActions(actions) {
+    const normType = (t) => t === "cdp-click" ? "click" : t === "cdp-fill" ? "input" : t;
+    const generic = (a) => (a.type === "click" || a.type === "dblclick" || a.type === "contextmenu") && (a.element?.selector === "html" || a.element?.selector === "body");
+    const keyOf = (a) => `${normType(a.type)}|${a.element?.selector || ""}|${a.element?.text || ""}`;
+    const coordsOf = (a) => typeof a.x === "number" && typeof a.y === "number" ? { x: a.x, y: a.y } : null;
+    const near = (p, q) => Math.abs(p.x - q.x) <= 30 && Math.abs(p.y - q.y) <= 30;
+    const lastKept = /* @__PURE__ */ new Map();
+    return actions.filter((a) => {
+      if (generic(a)) return false;
+      const key = keyOf(a);
+      const c = coordsOf(a);
+      const recent = lastKept.get(key) || [];
+      const dup = recent.some((e) => {
+        if (Math.abs(a.timestamp - e.ts) > 2500) return false;
+        if (!c || !e.c) return true;
+        return near(c, e.c);
+      });
+      if (dup) return false;
+      recent.push({ ts: a.timestamp, c });
+      lastKept.set(key, recent);
+      return true;
+    });
+  }
+  async replayAction(action) {
+    const page = this.page;
+    const timeout = this.opts.stepTimeout;
+    switch (action.type) {
+      // Proactive sensing actions are observations, not user actions — skip
+      // them during replay (they don't represent anything the user did).
+      case "popup_appear":
+      case "discovered_filters":
+        return;
+      case "navigation":
+        await page.goto(action.url, { waitUntil: "load", timeout });
+        break;
+      case "goto":
+        await page.goto(action.url, { waitUntil: "load", timeout });
+        break;
+      case "click":
+      case "cdp-click": {
+        const selector = await this.resolveAndWait(action);
+        if (typeof action.x === "number" && typeof action.y === "number") {
+          const hit = await page.evaluate(`
+            (function() {
+              const el = ${queryJS(selector)};
+              if (!el) return false;
+              const r = el.getBoundingClientRect();
+              return ${action.x} >= r.x - 2 && ${action.x} <= r.x + r.width + 2
+                  && ${action.y} >= r.y - 2 && ${action.y} <= r.y + r.height + 2;
+            })()
+          `).catch(() => false);
+          if (hit) {
+            await page.mouse.click(action.x, action.y, { stealth: true });
+            break;
+          }
+        }
+        await page.click(selector, { timeout });
+        break;
+      }
+      case "scroll": {
+        const [dir, distStr] = (action.value || "down:300").split(":");
+        const dist = Number(distStr) || 300;
+        const sign = dir === "up" ? -1 : dir === "left" ? 0 : 1;
+        const selector = await this.resolveAndWait(action).catch(() => void 0);
+        if (selector) {
+          await page.evaluate(`
+            (function() {
+              const el = ${queryJS(selector)};
+              if (el) el.scrollTop += ${sign * dist};
+            })()
+          `).catch(() => {
+          });
+        } else {
+          await page.evaluate(`window.scrollBy(0, ${sign * dist})`).catch(() => {
+          });
+        }
+        break;
+      }
+      case "input": {
+        const selector = await this.resolveAndWait(action);
+        if (action.element?.type && NATIVE_VALUE_INJECT_TYPES.has(action.element.type)) {
+          await page.evaluate(`
+            (function() {
+              var el = ${queryJS(selector)};
+              if (!el) return;
+              el.value = ${JSON.stringify(action.value ?? "")};
+              el.dispatchEvent(new Event('input', { bubbles: true }));
+              el.dispatchEvent(new Event('change', { bubbles: true }));
+            })()
+          `);
+          break;
+        }
+        await page.fill(selector, action.value ?? "", { timeout });
+        break;
+      }
+      case "cdp-fill": {
+        const selector = await this.resolveAndWait(action);
+        if (action.element?.type && NATIVE_VALUE_INJECT_TYPES.has(action.element.type)) {
+          await page.evaluate(`
+            (function() {
+              var el = ${queryJS(selector)};
+              if (!el) return;
+              el.value = ${JSON.stringify(action.value ?? "")};
+              el.dispatchEvent(new Event('input', { bubbles: true }));
+              el.dispatchEvent(new Event('change', { bubbles: true }));
+            })()
+          `);
+          break;
+        }
+        await page.fill(selector, action.value ?? "", { timeout });
+        break;
+      }
+      case "change": {
+        const selector = await this.resolveAndWait(action);
+        if (action.value) {
+          await page.selectOption(selector, action.value);
+        }
+        break;
+      }
+      case "filechooser": {
+        const selector = await this.resolveAndWait(action);
+        const files = this.resolveFiles(action);
+        if (files.length > 0) {
+          await page.setInputFiles(selector, files);
+        }
+        break;
+      }
+      case "drop": {
+        const selector = await this.resolveAndWait(action);
+        const files = this.resolveFiles(action);
+        if (files.length > 0) {
+          await page.dropFiles(selector, files[0]);
+        }
+        break;
+      }
+      case "keydown": {
+        const key = action.key ?? "";
+        if (key === "Enter" || key === "Tab" || key === "Escape") {
+          await page.keyboard.press(key);
+        } else if (key === "Backspace") {
+          await page.keyboard.press("Backspace");
+        } else if (key === "Delete") {
+          await page.keyboard.press("Delete");
+        } else if (key.startsWith("Arrow")) {
+          await page.keyboard.press(key);
+        } else if (key.includes("+")) {
+          await page.keyboard.press(key.replace("Meta", "Meta").replace("Ctrl", "Control"));
+        }
+        break;
+      }
+      case "dblclick": {
+        const selector = await this.resolveAndWait(action).catch(() => "");
+        if (selector) {
+          await page.dblclick(selector, { timeout });
+        } else if (action.x !== void 0 && action.y !== void 0) {
+          await page.mouse.dblclick(action.x, action.y);
+        }
+        break;
+      }
+      case "contextmenu": {
+        const selector = await this.resolveAndWait(action).catch(() => "");
+        if (selector) {
+          await page.click(selector, { button: "right", timeout });
+        } else if (action.x !== void 0 && action.y !== void 0) {
+          await page.mouse.click(action.x, action.y, { button: "right" });
+        }
+        break;
+      }
+      case "hover": {
+        const selector = await this.resolveAndWait(action);
+        if (selector) {
+          await page.hover(selector);
+        }
+        const firstPopup = action.hoverContext?.appeared?.[0];
+        if (firstPopup?.selector) {
+          try {
+            await page.waitForSelector(firstPopup.selector, {
+              state: "visible",
+              timeout: 1e3
+            });
+          } catch {
+          }
+        }
+        break;
+      }
+      case "drag": {
+        if (action.drag) {
+          const { fromX, fromY, toX, toY } = action.drag;
+          await page.mouse.move(fromX, fromY);
+          await page.mouse.down();
+          const steps = 5;
+          for (let i = 1; i <= steps; i++) {
+            await page.mouse.move(
+              fromX + (toX - fromX) * i / steps,
+              fromY + (toY - fromY) * i / steps
+            );
+            await new Promise((r) => setTimeout(r, 30));
+          }
+          await page.mouse.up();
+        }
+        break;
+      }
+      case "resize": {
+        break;
+      }
+      case "clipboard": {
+        break;
+      }
+      case "touch": {
+        if (action.touch) {
+          const { touchType, touches } = action.touch;
+          if (touchType === "start" && touches.length > 0) {
+            await page.mouse.move(touches[0].x, touches[0].y);
+            await page.mouse.down();
+          } else if (touchType === "end" && touches.length > 0) {
+            await page.mouse.move(touches[0].x, touches[0].y);
+            await page.mouse.up();
+          }
+        }
+        break;
+      }
+      case "focus": {
+        const selector = await this.resolveAndWait(action);
+        if (action.focus?.focusType === "focus") {
+          await page.locator(selector).focus();
+        }
+        break;
+      }
+      case "visibility": {
+        break;
+      }
+      case "submit": {
+        const selector = await this.resolveAndWait(action);
+        await page.evaluate((sel) => {
+          const form = document.querySelector(sel);
+          if (!form) return;
+          if (typeof form.requestSubmit === "function") {
+            form.requestSubmit();
+          } else {
+            form.dispatchEvent(new Event("submit", { bubbles: true, cancelable: true }));
+          }
+        }, selector);
+        break;
+      }
+      case "scroll": {
+        await page.evaluate(() => {
+          window.scrollBy(action.scrollX ?? 0, action.scrollY ?? 0);
+        });
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  /** Replay a mouse trajectory (smooth movement between actions) */
+  async replayTrajectory(trajectory) {
+    const page = this.page;
+    const { points } = trajectory;
+    if (!points || points.length < 2) return;
+    for (let i = 0; i < points.length; i++) {
+      const { x, y, dt } = points[i];
+      if (dt > 0) {
+        await new Promise((r) => setTimeout(r, Math.min(dt, 200)));
+      }
+      await page.mouse.move(x, y);
+    }
+  }
+  /**
+   * S202: 自愈选择器解析——主选择器失败后，生成语义备选并逐级尝试。
+   *
+   * Fallback chain:
+   *   1. Primary selector + textFallback + tag (existing)
+   *   2. Partial id match (extract stable substring from original id)
+   *   3. Type-based (input[type=text] etc — survives id/class/name mutations)
+   *   4. Tag + positional (form input:nth-of-type(N))
+   *   5. Text content match (visible text contains a stable substring)
+   */
+  async healResolve(action, primaryFailed) {
+    const page = this.page;
+    const el = action.element;
+    const timeout = Math.min(this.opts.stepTimeout, 5e3);
+    const domain = this.pageDomain(action);
+    if (this.opts.healKnowledgeDir) {
+      const known = this.lookupHealKnowledge(domain, primaryFailed[0] ?? "");
+      if (known) {
+        try {
+          await page.waitForSelector(known.healed, { state: "visible", timeout: Math.min(timeout, 2e3) });
+          const verdict = await this.verifyHealHit(action, known.healed);
+          if (verdict !== "hard") {
+            this.bumpHealKnowledge(domain, primaryFailed[0] ?? "");
+            return { selector: known.healed, strategy: "known-heal" };
+          }
+          this.forgetHealKnowledge(domain, primaryFailed[0] ?? "");
+        } catch {
+          this.forgetHealKnowledge(domain, primaryFailed[0] ?? "");
+        }
+      }
+    }
+    const coreId = this.extractSemanticCore(primaryFailed[0] || "");
+    const tagName = el?.tag || "input";
+    const candidates = [];
+    if (coreId) {
+      candidates.push({ sel: `[id*="${coreId}"]`, strategy: "partial-id" });
+    }
+    if (coreId) {
+      candidates.push({ sel: `[name*="${coreId}"]`, strategy: "partial-name" });
+    }
+    if (coreId) {
+      candidates.push({ sel: `[placeholder*="${coreId}"]`, strategy: "partial-placeholder" });
+    }
+    if (coreId) {
+      candidates.push({ sel: `[aria-label*="${coreId}"]`, strategy: "aria-label" });
+      candidates.push({ sel: `[data-testid*="${coreId}"]`, strategy: "data-testid" });
+    }
+    if (coreId && primaryFailed[0]?.trimStart().startsWith(".")) {
+      candidates.push({ sel: `[class*="${coreId}"]`, strategy: "partial-class" });
+    }
+    const anchorText = (el?.text || "").trim().replace(/"/g, "");
+    const isTextBearer = tagName === "button" || tagName === "a" || el?.role === "button" || el?.role === "link";
+    if (anchorText && isTextBearer) {
+      candidates.push({
+        sel: `xpath=//*[contains(normalize-space(.), "${anchorText}")][self::${tagName} or self::a or self::button or @role="button" or @role="link"]`,
+        strategy: "text-anchor"
+      });
+    }
+    const labelText = (el?.labelText || "").trim().replace(/"/g, "");
+    if (labelText) {
+      candidates.push({
+        sel: `xpath=//label[contains(normalize-space(.), "${labelText}")]//${tagName}`,
+        strategy: "label-anchor"
+      });
+      candidates.push({
+        sel: `xpath=//${tagName}[@id=(//label[contains(normalize-space(.), "${labelText}")]/@for)]`,
+        strategy: "label-for-anchor"
+      });
+    }
+    const rowText = (el?.rowText || "").trim().replace(/"/g, "");
+    if (rowText) {
+      candidates.push({
+        sel: `xpath=//tr[contains(normalize-space(.), "${rowText}")]//${tagName}`,
+        strategy: "row-anchor"
+      });
+      candidates.push({
+        sel: `xpath=//li[contains(normalize-space(.), "${rowText}")]//${tagName}`,
+        strategy: "row-anchor"
+      });
+    }
+    if (el?.type) {
+      candidates.push({ sel: `${tagName}[type="${el.type}"]`, strategy: "meta-type" });
+    }
+    if (el?.placeholder) {
+      candidates.push({ sel: `[placeholder="${el.placeholder}"]`, strategy: "meta-placeholder" });
+    }
+    if (el?.ariaLabel) {
+      candidates.push({ sel: `[aria-label="${el.ariaLabel}"]`, strategy: "meta-aria" });
+    }
+    const typeMap = {
+      username: "text",
+      password: "password",
+      email: "email",
+      search: "search",
+      phone: "tel",
+      url: "url"
+    };
+    if (typeMap[coreId]) {
+      candidates.push({ sel: `${tagName}[type="${typeMap[coreId]}"]`, strategy: "type-based" });
+    }
+    const uniqueTags = ["textarea", "select"];
+    if (uniqueTags.includes(tagName)) {
+      candidates.push({ sel: tagName, strategy: "tag-unique" });
+    }
+    const ord = el?.ordinal;
+    if (ord && ord.formNth > 0 && ord.tagNth > 0) {
+      candidates.push({
+        sel: `form:nth-of-type(${ord.formNth}) ${tagName}:nth-of-type(${ord.tagNth})`,
+        strategy: "ordinal"
+      });
+    }
+    candidates.push({ sel: `form ${tagName}:first-of-type`, strategy: "tag-first" });
+    candidates.push({ sel: `form ${tagName}`, strategy: "tag-in-form" });
+    const blindPositional = /* @__PURE__ */ new Set(["tag-first", "tag-in-form"]);
+    const inList = (c) => !!c.sel && c.sel !== primaryFailed[0];
+    const semanticList = candidates.filter((c) => inList(c) && !blindPositional.has(c.strategy));
+    const blindList = candidates.filter((c) => inList(c) && blindPositional.has(c.strategy));
+    const tryProbe = async (list) => {
+      const probeSels = [...new Set(list.map((c) => c.sel))];
+      if (probeSels.length === 0) return null;
+      const probeExprs = JSON.stringify(probeSels.map((s) => queryAllDeepJS(s)));
+      const metaJson = JSON.stringify({
+        type: el?.type ?? null,
+        placeholder: el?.placeholder ?? null,
+        text: (el?.text || "").trim(),
+        labelText: (el?.labelText || "").trim(),
+        size: el?.size ?? null
+      });
+      const probeSrc = `
+        (function() {
+          var sels = ${JSON.stringify(probeSels)};
+          var meta = ${metaJson};
+          var pairs = ${probeExprs};
+          function pathOf(m) {
+            var root = m.getRootNode ? m.getRootNode() : null;
+            if (root && root.nodeType !== 9) return null; // \u9634\u5F71/iframe\u2014\u2014\u8DEF\u5F84\u4E0D\u8DE8\u754C\uFF0C\u9000\u56DE\u539F\u9009\u62E9\u5668
+            var parts = [];
+            var cur = m;
+            while (cur && cur !== document.body) {
+              var parent = cur.parentElement;
+              if (!parent) return null;
+              var same = Array.prototype.filter.call(parent.children, function(c) { return c.tagName === cur.tagName; });
+              parts.unshift(cur.tagName.toLowerCase() + ':nth-of-type(' + (same.indexOf(cur) + 1) + ')');
+              cur = parent;
+            }
+            return parts.length ? parts.join(' > ') : null;
+          }
+          function scoreMatch(m) {
+            var mt = m.getAttribute ? m.getAttribute('type') : null;
+            var mp = m.getAttribute ? m.getAttribute('placeholder') : null;
+            var mtext = (String(m.value ?? '') || m.textContent || '').trim().slice(0, 80);
+            if (meta.type && mt && mt !== meta.type) return -1;
+            if (meta.placeholder && mp && mp !== meta.placeholder) return -1;
+            var s = 10;
+            if (meta.text && mtext && mtext.indexOf(meta.text) === -1) s = 1;
+            if (meta.labelText) {
+              var label = '';
+              try {
+                var lb = m.closest ? m.closest('label') : null;
+                if (lb) label = (lb.textContent || '').trim();
+              } catch (e) {}
+              if (label && label.indexOf(meta.labelText) !== -1) s += 2;
+            }
+            if (meta.size) {
+              var r = m.getBoundingClientRect();
+              if (r.width > 0 && r.height > 0) {
+                var dw = Math.abs(r.width - meta.size.w) / Math.max(meta.size.w, 1);
+                var dh = Math.abs(r.height - meta.size.h) / Math.max(meta.size.h, 1);
+                if (dw <= 0.4 && dh <= 0.4) s += 1;
+              }
+            }
+            return s;
+          }
+          var best = null;
+          for (var i = 0; i < sels.length; i++) {
+            var matches = [];
+            try { matches = (new Function('return (' + pairs[i] + ')'))() || []; } catch (e) { continue; }
+            var cap = Math.min(matches.length, 20);
+            var candBest = null;
+            for (var k = 0; k < cap; k++) {
+              var m = matches[k];
+              if (!m) continue;
+              var sc = scoreMatch(m);
+              if (sc < 0) continue;
+              if (!candBest || sc > candBest.score) {
+                candBest = { score: sc, k: k, soft: sc <= 1 };
+              }
+            }
+            if (candBest && (!best || candBest.score > best.score)) {
+              var pinned = candBest.k > 0 ? pathOf(matches[candBest.k]) : null;
+              if (candBest.k === 0 || pinned) {
+                best = { selIndex: i, k: candBest.k, pinned: pinned, soft: candBest.soft };
+              }
+            }
+          }
+          return best;
+        })()
+      `;
+      let best = null;
+      for (let attempt = 0; attempt < 5; attempt++) {
+        if (attempt > 0) await new Promise((r) => setTimeout(r, 200));
+        best = await page.evaluate(probeSrc).catch((e) => {
+          if (process.env.XBROWSER_HEAL_DEBUG) console.error("[heal] probe evaluate error:", e instanceof Error ? e.message.split("\n")[0] : String(e).slice(0, 200));
+          return null;
+        });
+        if (best) break;
+      }
+      if (!best) return null;
+      const originSel = probeSels[best.selIndex];
+      const finalSel = best.pinned ?? originSel;
+      const strategyName = list.find((c) => c.sel === originSel)?.strategy ?? "probe";
+      if (process.env.XBROWSER_HEAL_DEBUG) {
+        console.error(`[heal] cand=${finalSel} (via ${originSel}) soft=${best.soft}`);
+      }
+      try {
+        await page.waitForSelector(finalSel, { state: "visible", timeout: Math.min(timeout, 1e3) });
+        const needsHitTest = action.type === "click" || action.type === "cdp-click";
+        if (needsHitTest && await this.isClickOccluded(finalSel)) return null;
+        return {
+          kind: best.soft ? "alt" : "hit",
+          hit: { selector: finalSel, strategy: strategyName }
+        };
+      } catch {
+        return null;
+      }
+    };
+    const semanticHit = await tryProbe(semanticList);
+    if (semanticHit?.kind === "hit") return semanticHit.hit;
+    if (typeof action.x === "number" && typeof action.y === "number") {
+      try {
+        const pathSel = await page.evaluate(`
+          (function() {
+            var el = document.elementFromPoint(${action.x}, ${action.y});
+            if (!el || el === document.body || el === document.documentElement) return '';
+            if (el.tagName.toLowerCase() !== ${JSON.stringify(el?.tag ?? "")}) return '';
+            var parts = [];
+            var cur = el;
+            while (cur && cur !== document.body) {
+              var parent = cur.parentElement;
+              if (!parent) break;
+              var same = Array.prototype.filter.call(parent.children, function(c) { return c.tagName === cur.tagName; });
+              parts.unshift(cur.tagName.toLowerCase() + ':nth-of-type(' + (same.indexOf(cur) + 1) + ')');
+              cur = parent;
+            }
+            return parts.length ? parts.join(' > ') : '';
+          })()
+        `);
+        if (pathSel) {
+          await page.waitForSelector(pathSel, { state: "visible", timeout: Math.min(timeout, 1e3) });
+          return { selector: pathSel, strategy: "coords" };
+        }
+      } catch {
+      }
+    }
+    const blindHit = await tryProbe(blindList);
+    if (blindHit?.kind === "hit") return blindHit.hit;
+    const softAlt = semanticHit?.kind === "alt" ? semanticHit.hit : blindHit?.kind === "alt" ? blindHit.hit : null;
+    if (softAlt) return { selector: softAlt.selector, strategy: `${softAlt.strategy}~soft` };
+    throw new Error(`Self-healing exhausted all ${candidates.length} strategies. Primary: ${primaryFailed.join(", ")}`);
+  }
+  /** 从选择器字符串提取语义核心（去掉版本号/前缀/后缀等噪声） */
+  extractSemanticCore(selector) {
+    const idMatch = selector.match(/#([\w-]+)/);
+    if (idMatch) {
+      return idMatch[1].replace(/-v\d+$/, "").replace(/-mut$/, "");
+    }
+    const nameMatch = selector.match(/\[name=["']([\w-]+)["']\]/);
+    if (nameMatch) return nameMatch[1];
+    const phMatch = selector.match(/\[placeholder=["']([\w-]+)["']\]/);
+    if (phMatch) return phMatch[1];
+    const dtMatch = selector.match(/\[data-testid=["']([\w-]+)["']\]/);
+    if (dtMatch) return dtMatch[1];
+    const classMatch = selector.match(/\.([\w-]+)/);
+    if (classMatch) return classMatch[1];
+    return "";
+  }
+  // ── heal 知识库（r10）：heal 一次、同域记住、二次回放零成本 ──
+  pageDomain(action) {
+    try {
+      const u = new URL(action.url || this.page.url());
+      return u.hostname || u.protocol.replace(":", "") || "unknown";
+    } catch {
+      return "unknown";
+    }
+  }
+  healKnowledgeFile(domain) {
+    return join(this.opts.healKnowledgeDir, `heals-${domain}.json`);
+  }
+  readHealFile(file) {
+    try {
+      return JSON.parse(readFileSync(file, "utf8"));
+    } catch {
+      return {};
+    }
+  }
+  lookupHealKnowledge(domain, primary) {
+    if (!primary || !this.opts.healKnowledgeDir) return null;
+    const data = this.readHealFile(this.healKnowledgeFile(domain));
+    const e = data[primary];
+    return e ? { healed: e.healed, strategy: e.strategy } : null;
+  }
+  persistHealKnowledge(action, primary, healed) {
+    if (!this.opts.healKnowledgeDir || !primary || healed.strategy === "known-heal") return;
+    try {
+      const file = this.healKnowledgeFile(this.pageDomain(action));
+      const data = this.readHealFile(file);
+      data[primary] = {
+        healed: healed.selector,
+        strategy: healed.strategy,
+        lastSeen: (/* @__PURE__ */ new Date()).toISOString(),
+        hits: (data[primary]?.hits ?? 0) + 1
+      };
+      const cutoff = Date.now() - HEAL_KB_TTL_DAYS * 864e5;
+      for (const k of Object.keys(data)) {
+        const ts = Date.parse(data[k]?.lastSeen ?? "");
+        if (!(ts >= cutoff)) delete data[k];
+      }
+      mkdirSync(this.opts.healKnowledgeDir, { recursive: true });
+      writeFileSync(file, JSON.stringify(data, null, 2));
+    } catch {
+    }
+  }
+  bumpHealKnowledge(domain, primary) {
+    try {
+      const file = this.healKnowledgeFile(domain);
+      const data = this.readHealFile(file);
+      const e = data[primary];
+      if (!e) return;
+      e.hits += 1;
+      e.lastSeen = (/* @__PURE__ */ new Date()).toISOString();
+      writeFileSync(file, JSON.stringify(data, null, 2));
+    } catch {
+    }
+  }
+  forgetHealKnowledge(domain, primary) {
+    try {
+      const file = this.healKnowledgeFile(domain);
+      const data = this.readHealFile(file);
+      if (!data[primary]) return;
+      delete data[primary];
+      writeFileSync(file, JSON.stringify(data, null, 2));
+    } catch {
+    }
+  }
+  /**
+   * r9: click 类动作遮挡校验——元素"可见"（rect+样式）但被覆盖层（弹窗/
+   * 横幅）盖住时，点击只会落在覆盖层上。elementFromPoint 顶元素非目标
+   * 自身/子孙即判遮挡。视口外（top 为 null）不判定——点击路径会自行滚动。
+   * r17: 阴影边界重定向——elementFromPoint 对阴影内命中点返回宿主，
+   * el.contains 不跨 shadow 边界，需沿 getRootNode().host 攀升做组合树
+   * 祖先判定，否则阴影内元素恒误判遮挡。
+   */
+  async isClickOccluded(selector) {
+    try {
+      return await this.page.evaluate(`
+        (function() {
+          var el = ${queryJS(selector)};
+          if (!el) return true;
+          var r = el.getBoundingClientRect();
+          var top = document.elementFromPoint(r.x + r.width / 2, r.y + r.height / 2);
+          if (!top) return false;
+          function chainReaches(node, stop) {
+            while (node) {
+              if (node === stop) return true;
+              var root = node.getRootNode ? node.getRootNode() : null;
+              if (root && root.host) node = root.host;
+              else node = node.parentNode;
+            }
+            return false;
+          }
+          // \u53CC\u5411\u7EC4\u5408\u6811\u5224\u5B9A\uFF08r17\uFF09\uFF1Atop \u5728 el \u7684\u7EC4\u5408\u5B50\u6811\u5185\uFF08\u547D\u4E2D\u76EE\u6807\u7684\u5B50\u5B59\uFF09\uFF0C
+          // \u6216 el \u5728 top \u7684\u7EC4\u5408\u7956\u5148\u94FE\u4E0A\uFF08\u9634\u5F71\u91CD\u5B9A\u5411\uFF1Atop=\u5BBF\u4E3B\u4EE3\u8868\u5F71\u5B50\u5185\u547D\u4E2D\uFF09
+          var related = chainReaches(top, el) || chainReaches(el, top);
+          return !related;
+        })()
+      `);
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * r7/r8: heal 命中指纹校验——"找对"而非"找到"。
+   * 录制的 type/placeholder/text 与命中元素比对，裁决分三级：
+   *   hard — type/placeholder 正性矛盾（两侧都有值但不等）：判 wrong-target，
+   *          丢弃该候选。文案改版不会动这两个属性，硬拒不会误杀。
+   *   soft — 仅 text 正性矛盾：最常见改版恰恰是文案改版，硬拒会误杀正确
+   *          元素，降级为备选（alt）——全链无干净命中时才启用。
+   *   pass — 无矛盾（元素侧属性缺失不算矛盾；无信号/异常放行）。
+   */
+  async verifyHealHit(action, selector) {
+    const m = action.element;
+    if (!m?.type && !m?.placeholder && !m?.text) return "pass";
+    try {
+      const meta = await this.page.evaluate(`
+        (function() {
+          var el = ${queryJS(selector)};
+          if (!el) return null;
+          return {
+            type: el.getAttribute('type'),
+            placeholder: el.getAttribute('placeholder'),
+            text: (String(el.value ?? '') || el.textContent || '').trim().substring(0, 80),
+          };
+        })()
+      `);
+      if (!meta) return "pass";
+      if (m.type && meta.type && meta.type !== m.type) return "hard";
+      if (m.placeholder && meta.placeholder && meta.placeholder !== m.placeholder) return "hard";
+      const wantText = (m.text || "").trim();
+      if (wantText && meta.text && !meta.text.includes(wantText)) return "soft";
+      return "pass";
+    } catch {
+      return "pass";
+    }
+  }
+  /**
+   * X2: Wait for an element using the best available selector, with
+   * confidence-based fallback support.
+   *
+   * Returns the first matching selector, or throws if none match.
+   * Fallback order:
+   *   1. Primary CSS selector (always tried first)
+   *   2. textFallback selector (used when primary fails — not just for low
+   *      confidence, since high-confidence selectors from dynamic attributes
+   *      like data-spm-anchor-id can also fail on replay)
+   *   3. Tag-based fallback (last resort)
+   */
+  async resolveAndWait(action) {
+    const el = action.element;
+    if (!el) throw new Error("No element metadata");
+    const page = this.page;
+    const timeout = this.opts.stepTimeout;
+    const candidates = [];
+    if (el.selector) candidates.push(el.selector);
+    if (el.textFallback?.selector && !candidates.includes(el.textFallback.selector)) {
+      candidates.push(el.textFallback.selector);
+    }
+    const UNIQUE_TAGS = /* @__PURE__ */ new Set(["textarea", "select"]);
+    if (el.tag && UNIQUE_TAGS.has(el.tag) && !candidates.includes(el.tag)) {
+      candidates.push(el.tag);
+    }
+    if (candidates.length === 0 && this.opts.selfHealing === false) {
+      throw new Error("No selector available for element");
+    }
+    const isClick = action.type === "click" || action.type === "cdp-click";
+    const __dbgT0 = Date.now();
+    const __dbg = (msg) => {
+      if (process.env.XBROWSER_HEAL_DEBUG) console.error(`[resolve ${Math.round(Date.now() - __dbgT0)}ms] ${msg}`);
+    };
+    for (const sel of candidates) {
+      try {
+        await page.waitForSelector(sel, { state: "visible", timeout });
+        if (isClick && await this.isClickOccluded(sel)) {
+          __dbg(`occluded: ${sel}`);
+          continue;
+        }
+        __dbg(`primary hit: ${sel}`);
+        return sel;
+      } catch {
+        __dbg(`primary miss: ${sel}`);
+      }
+    }
+    if (this.opts.selfHealing !== false) {
+      try {
+        const healed = await this.healResolve(action, candidates);
+        this.opts.onHealed?.(action, healed.strategy, candidates.length);
+        this.persistHealKnowledge(action, candidates[0] ?? "", healed);
+        __dbg(`heal hit: ${healed.selector} (${healed.strategy})`);
+        return healed.selector;
+      } catch {
+        __dbg("heal exhausted");
+      }
+    }
+    if (candidates.length === 0) throw new Error("No selector available for element");
+    throw new Error(`Element not found, tried: ${candidates.join(", ")}`);
+  }
+  /** Resolve file payloads from a filechooser action */
+  resolveFiles(action) {
+    if (!action.files?.fileData) return [];
+    return action.files.fileData.filter((f) => f.dataUrl).map((f) => {
+      const match = f.dataUrl.match(/^data:[^;]+;base64,(.+)$/);
+      if (!match) return null;
+      return {
+        name: f.name,
+        mimeType: f.type || "application/octet-stream",
+        buffer: Buffer.from(match[1], "base64")
+      };
+    }).filter((f) => f !== null);
+  }
+  /** Clean up */
+  async close() {
+    this.page = null;
+  }
+};
+export {
+  SessionReplayer
+};