minimal-agent 0.13.0 → 0.14.0

package/src/tools/webbrowser/browserDaemon.js

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { dirname, isAbsolute } from 'node:path';
-import { resolveAgentBrowserPath, resolveBundledChromium, resolveSystemBrowser } from './agentBrowserPath.js';
+import { resolveAgentBrowserPath, resolveBundledChromium, resolveSystemBrowser, } from './agentBrowserPath.js';
 import { browserGlobalArgs, runBounded, sessionArgs, spawnRunner, } from './browser.js';
 /** Daemon 启动（拉起 Chrome + CDP 就绪）总预算：超时即掐断并抛可操作错误，绝不无限挂。 */
 export const DAEMON_BRINGUP_TIMEOUT_MS = 45_000;
@@ -50,17 +50,7 @@ export async function reclaimStaleDaemons(deps = {}) {
         const root = dir.toLowerCase().replace(/'/g, "''");
         const ps = 
         // (a) 本 App 路径下的 agent-browser daemon + 其 Chrome 子树。
-        `Get-CimInstance Win32_Process -Filter "Name='agent-browser.exe'" | ` +
-            `Where-Object { $_.ExecutablePath -and $_.ExecutablePath.ToLower().StartsWith('${root}') } | ` +
-            `ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }; ` +
-            // (b) 真孤儿 agent-browser Chrome（父进程已死）。daemon 崩溃后残留、上面的 agent-browser 树
-            //     够不着，堆积起来会把新 daemon 的 Chrome 拉起拖到几十秒（实测 18 棵孤儿 → 卡 43s；
-            //     清空后同一启动仅 1s）。**只杀父进程已不在的孤儿**，绝不误伤有活父进程的正常浏览器
-            //     （安装版 App 的活浏览器父 agent-browser 健在 → 不匹配，天然豁免）。
-            `$alive=@{}; Get-CimInstance Win32_Process | ForEach-Object { $alive[[int]$_.ProcessId]=$true }; ` +
-            `Get-CimInstance Win32_Process -Filter "Name='chrome.exe'" | ` +
-            `Where-Object { ($_.CommandLine -match 'agent-browser-chrome' -or $_.CommandLine -match '\\.minimal-agent.{0,40}profiles') -and -not $alive.ContainsKey([int]$_.ParentProcessId) } | ` +
-            `ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }`;
+        `Get-CimInstance Win32_Process -Filter "Name='agent-browser.exe'" | Where-Object { $_.ExecutablePath -and $_.ExecutablePath.ToLower().StartsWith('${root}') } | ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }; $alive=@{}; Get-CimInstance Win32_Process | ForEach-Object { $alive[[int]$_.ProcessId]=$true }; Get-CimInstance Win32_Process -Filter "Name='chrome.exe'" | Where-Object { ($_.CommandLine -match 'agent-browser-chrome' -or $_.CommandLine -match '\\.minimal-agent.{0,40}profiles') -and -not $alive.ContainsKey([int]$_.ParentProcessId) } | ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }`;
         await exec('powershell', ['-NoProfile', '-NonInteractive', '-Command', ps]);
     }
     else {
@@ -94,6 +84,17 @@ export async function ensureDaemon(sessionName = 'minimal-agent', opts = {}, dep
     const bin = await deps.resolveBin();
     if (!bin)
         throw new Error('未找到 agent-browser 可执行文件');
+    if (opts.forceRestart) {
+        // The shipped wrapper may launch a daemon from a different resolved
+        // global path. In that case executable-prefix process cleanup is
+        // intentionally conservative and cannot see the daemon. Ask the
+        // session manager to close its own browser first, then apply the scoped
+        // process cleanup as a second line of defense.
+        await deps
+            .runner(bin, [...sessionArgs(sessionName), 'close', '--all'], opts.signal)
+            .catch(() => undefined);
+        await reclaimStaleDaemons(opts.reclaim);
+    }
     const status = await readStatus(bin, sessionName, { signal: opts.signal }, deps);
     if (status.port && status.connected) {
         ports.set(sessionName, status.port);
@@ -143,10 +144,17 @@ export async function ensureDaemon(sessionName = 'minimal-agent', opts = {}, dep
             ]);
             if (ac.signal.aborted)
                 throw bringUpError();
-            if (opened.code !== 0 && browserRuntimeMissing(`${opened.stderr}\n${opened.stdout}`)) {
+            if (opened.code !== 0 &&
+                browserRuntimeMissing(`${opened.stderr}\n${opened.stdout}`)) {
                 const chromium = resolveBundledChromium();
                 if (chromium) {
-                    opened = await run([...globals, '--executable-path', chromium, 'open', 'about:blank']);
+                    opened = await run([
+                        ...globals,
+                        '--executable-path',
+                        chromium,
+                        'open',
+                        'about:blank',
+                    ]);
                 }
                 else {
                     const installed = await run(['install']);

package/src/tools/webbrowser/browserDaemon.ts

@@ -1,13 +1,17 @@
 import { spawn } from 'node:child_process';
 import { dirname, isAbsolute } from 'node:path';
 
-import { resolveAgentBrowserPath, resolveBundledChromium, resolveSystemBrowser } from './agentBrowserPath.js';
 import {
+  resolveAgentBrowserPath,
+  resolveBundledChromium,
+  resolveSystemBrowser,
+} from './agentBrowserPath.js';
+import {
+  type AgentBrowserRunner,
   browserGlobalArgs,
   runBounded,
   sessionArgs,
   spawnRunner,
-  type AgentBrowserRunner,
 } from './browser.js';
 
 export interface BrowserDaemonInfo {
@@ -30,6 +34,8 @@ export interface EnsureDaemonOptions {
   signal?: AbortSignal;
   timeoutMs?: number;
   reclaim?: ReclaimDeps;
+  /** Forcefully rebuild a browser whose CDP endpoint has gone stale. */
+  forceRestart?: boolean;
 }
 
 /**
@@ -78,7 +84,9 @@ export interface ReclaimDeps {
  * 或系统上别处的 agent-browser 用法（对标 scripts/dev-browser.ts::reclaimStalePort）。无法作用域限定
  * （PATH 上裸二进制 / 没装）时保守放弃，不做全局杀。幂等、best-effort（失败静默）。
  */
-export async function reclaimStaleDaemons(deps: ReclaimDeps = {}): Promise<void> {
+export async function reclaimStaleDaemons(
+  deps: ReclaimDeps = {},
+): Promise<void> {
   const platform = deps.platform ?? process.platform;
   const exec = deps.exec ?? realReclaimExec;
   const resolveDir =
@@ -94,17 +102,7 @@ export async function reclaimStaleDaemons(deps: ReclaimDeps = {}): Promise<void>
     const root = dir.toLowerCase().replace(/'/g, "''");
     const ps =
       // (a) 本 App 路径下的 agent-browser daemon + 其 Chrome 子树。
-      `Get-CimInstance Win32_Process -Filter "Name='agent-browser.exe'" | ` +
-      `Where-Object { $_.ExecutablePath -and $_.ExecutablePath.ToLower().StartsWith('${root}') } | ` +
-      `ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }; ` +
-      // (b) 真孤儿 agent-browser Chrome（父进程已死）。daemon 崩溃后残留、上面的 agent-browser 树
-      //     够不着，堆积起来会把新 daemon 的 Chrome 拉起拖到几十秒（实测 18 棵孤儿 → 卡 43s；
-      //     清空后同一启动仅 1s）。**只杀父进程已不在的孤儿**，绝不误伤有活父进程的正常浏览器
-      //     （安装版 App 的活浏览器父 agent-browser 健在 → 不匹配，天然豁免）。
-      `$alive=@{}; Get-CimInstance Win32_Process | ForEach-Object { $alive[[int]$_.ProcessId]=$true }; ` +
-      `Get-CimInstance Win32_Process -Filter "Name='chrome.exe'" | ` +
-      `Where-Object { ($_.CommandLine -match 'agent-browser-chrome' -or $_.CommandLine -match '\\.minimal-agent.{0,40}profiles') -and -not $alive.ContainsKey([int]$_.ParentProcessId) } | ` +
-      `ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }`;
+      `Get-CimInstance Win32_Process -Filter "Name='agent-browser.exe'" | Where-Object { $_.ExecutablePath -and $_.ExecutablePath.ToLower().StartsWith('${root}') } | ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }; $alive=@{}; Get-CimInstance Win32_Process | ForEach-Object { $alive[[int]$_.ProcessId]=$true }; Get-CimInstance Win32_Process -Filter "Name='chrome.exe'" | Where-Object { ($_.CommandLine -match 'agent-browser-chrome' -or $_.CommandLine -match '\\.minimal-agent.{0,40}profiles') -and -not $alive.ContainsKey([int]$_.ParentProcessId) } | ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }`;
     await exec('powershell', ['-NoProfile', '-NonInteractive', '-Command', ps]);
   } else {
     // unix：按可执行路径前缀 pkill agent-browser（其 Chrome 子进程随之收尾）。unix 孤儿会被
@@ -121,7 +119,9 @@ function parsePort(text: string): number | null {
 }
 
 function browserRuntimeMissing(text: string): boolean {
-  return /browser\s+(?:not found|was not found)|chrom(?:e|ium).*(?:not found|missing)|executable.*(?:not found|does not exist)|run ['\"]?agent-browser install/i.test(text);
+  return /browser\s+(?:not found|was not found)|chrom(?:e|ium).*(?:not found|missing)|executable.*(?:not found|does not exist)|run ['\"]?agent-browser install/i.test(
+    text,
+  );
 }
 
 export { browserRuntimeMissing as _browserRuntimeMissing };
@@ -153,7 +153,23 @@ export async function ensureDaemon(
 ): Promise<BrowserDaemonInfo> {
   const bin = await deps.resolveBin();
   if (!bin) throw new Error('未找到 agent-browser 可执行文件');
-  const status = await readStatus(bin, sessionName, { signal: opts.signal }, deps);
+  if (opts.forceRestart) {
+    // The shipped wrapper may launch a daemon from a different resolved
+    // global path. In that case executable-prefix process cleanup is
+    // intentionally conservative and cannot see the daemon. Ask the
+    // session manager to close its own browser first, then apply the scoped
+    // process cleanup as a second line of defense.
+    await deps
+      .runner(bin, [...sessionArgs(sessionName), 'close', '--all'], opts.signal)
+      .catch(() => undefined);
+    await reclaimStaleDaemons(opts.reclaim);
+  }
+  const status = await readStatus(
+    bin,
+    sessionName,
+    { signal: opts.signal },
+    deps,
+  );
   if (status.port && status.connected) {
     ports.set(sessionName, status.port);
     return { sessionName, streamPort: status.port, alreadyRunning: true };
@@ -202,18 +218,30 @@ export async function ensureDaemon(
         'about:blank',
       ]);
       if (ac.signal.aborted) throw bringUpError();
-      if (opened.code !== 0 && browserRuntimeMissing(`${opened.stderr}\n${opened.stdout}`)) {
+      if (
+        opened.code !== 0 &&
+        browserRuntimeMissing(`${opened.stderr}\n${opened.stdout}`)
+      ) {
         const chromium = resolveBundledChromium();
         if (chromium) {
-          opened = await run([...globals, '--executable-path', chromium, 'open', 'about:blank']);
+          opened = await run([
+            ...globals,
+            '--executable-path',
+            chromium,
+            'open',
+            'about:blank',
+          ]);
         } else {
           const installed = await run(['install']);
-          if (installed.code === 0) opened = await run([...globals, 'open', 'about:blank']);
+          if (installed.code === 0)
+            opened = await run([...globals, 'open', 'about:blank']);
         }
         if (ac.signal.aborted) throw bringUpError();
       }
       if (opened.code !== 0) {
-        throw new Error((opened.stderr || opened.stdout || '浏览器启动失败').trim());
+        throw new Error(
+          (opened.stderr || opened.stdout || '浏览器启动失败').trim(),
+        );
       }
       const streamPort = await waitForStreamPort(sessionName, 10_000, deps);
       ports.set(sessionName, streamPort);
@@ -235,7 +263,12 @@ export async function stopDaemon(
   const bin = await deps.resolveBin();
   ports.delete(sessionName);
   if (bin) {
-    await runBounded(bin, [...sessionArgs(sessionName), 'close'], { timeoutMs: STATUS_TIMEOUT_MS }, deps.runner);
+    await runBounded(
+      bin,
+      [...sessionArgs(sessionName), 'close'],
+      { timeoutMs: STATUS_TIMEOUT_MS },
+      deps.runner,
+    );
   }
   // 优雅 close 之外再 tree-kill 一遍本 App 路径下的残留：崩溃/close 不彻底时仍杜绝临时 profile
   // 孤儿 Chrome 堆积（实测同时存活 ≥2 棵孤儿 Chrome 树的根因）。

package/src/tools/webbrowser/browserFrames.js

@@ -0,0 +1,47 @@
+/** Fixed, read-only expression for observing nested same-origin frame trees. */
+export const FRAME_INFO_EXPRESSION = `(() => { const walk = (doc, parentId = '', path = '') => Array.from(doc.querySelectorAll('iframe,frame')).flatMap((el, index) => { const id = 'dom-frame-' + (path ? path + '-' : '') + index; const item = { id, ...(parentId ? { parentId } : {}), url: el.src || '', name: el.name || undefined }; try { return [item, ...walk(el.contentDocument, id, id.replace('dom-frame-', ''))]; } catch { return [item]; } }); return walk(document); })()`;
+/** Normalize the recursive, browser-owned frame tree returned by CDP. */
+export function normalizeFrameTree(value) {
+    const frames = [];
+    const walk = (node, parentId) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const item = node;
+        if (typeof item.frame?.id !== 'string' || !item.frame.id)
+            return;
+        const id = item.frame.id;
+        frames.push({
+            id,
+            ...(parentId ? { parentId } : {}),
+            url: typeof item.frame.url === 'string' ? item.frame.url : '',
+            ...(typeof item.frame.name === 'string' && item.frame.name
+                ? { name: item.frame.name }
+                : {}),
+        });
+        for (const child of item.childFrames ?? [])
+            walk(child, id);
+    };
+    walk(value);
+    return frames;
+}
+export function normalizeFrameInfo(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item) => {
+        if (!item || typeof item !== 'object')
+            return [];
+        const frame = item;
+        if (typeof frame.id !== 'string' || typeof frame.url !== 'string')
+            return [];
+        return [
+            {
+                id: frame.id,
+                url: frame.url,
+                ...(typeof frame.parentId === 'string'
+                    ? { parentId: frame.parentId }
+                    : {}),
+                ...(typeof frame.name === 'string' ? { name: frame.name } : {}),
+            },
+        ];
+    });
+}

package/src/tools/webbrowser/browserFrames.ts

@@ -0,0 +1,54 @@
+export type BrowserFrameInfo = {
+  id: string;
+  parentId?: string;
+  url: string;
+  name?: string;
+};
+
+/** Fixed, read-only expression for observing nested same-origin frame trees. */
+export const FRAME_INFO_EXPRESSION = `(() => { const walk = (doc, parentId = '', path = '') => Array.from(doc.querySelectorAll('iframe,frame')).flatMap((el, index) => { const id = 'dom-frame-' + (path ? path + '-' : '') + index; const item = { id, ...(parentId ? { parentId } : {}), url: el.src || '', name: el.name || undefined }; try { return [item, ...walk(el.contentDocument, id, id.replace('dom-frame-', ''))]; } catch { return [item]; } }); return walk(document); })()`;
+
+/** Normalize the recursive, browser-owned frame tree returned by CDP. */
+export function normalizeFrameTree(value: unknown): BrowserFrameInfo[] {
+  const frames: BrowserFrameInfo[] = [];
+  const walk = (node: unknown, parentId?: string): void => {
+    if (!node || typeof node !== 'object') return;
+    const item = node as {
+      frame?: { id?: unknown; url?: unknown; name?: unknown };
+      childFrames?: unknown[];
+    };
+    if (typeof item.frame?.id !== 'string' || !item.frame.id) return;
+    const id = item.frame.id;
+    frames.push({
+      id,
+      ...(parentId ? { parentId } : {}),
+      url: typeof item.frame.url === 'string' ? item.frame.url : '',
+      ...(typeof item.frame.name === 'string' && item.frame.name
+        ? { name: item.frame.name }
+        : {}),
+    });
+    for (const child of item.childFrames ?? []) walk(child, id);
+  };
+  walk(value);
+  return frames;
+}
+
+export function normalizeFrameInfo(value: unknown): BrowserFrameInfo[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    if (!item || typeof item !== 'object') return [];
+    const frame = item as Record<string, unknown>;
+    if (typeof frame.id !== 'string' || typeof frame.url !== 'string')
+      return [];
+    return [
+      {
+        id: frame.id,
+        url: frame.url,
+        ...(typeof frame.parentId === 'string'
+          ? { parentId: frame.parentId }
+          : {}),
+        ...(typeof frame.name === 'string' ? { name: frame.name } : {}),
+      },
+    ];
+  });
+}

package/src/tools/webbrowser/browserInteractionResolver.js

@@ -0,0 +1,17 @@
+export function resolveInteractionStrategy(target) {
+    if (target.locator?.by === 'ax')
+        return 'ax';
+    if (target.locator?.by === 'role' ||
+        target.locator?.by === 'label' ||
+        target.locator?.by === 'text' ||
+        target.locator?.by === 'placeholder' ||
+        target.locator?.by === 'testid')
+        return 'role-locator';
+    if (target.locator || target.selector)
+        return 'playwright-locator';
+    if (target.node_id !== undefined)
+        return 'dom-cua';
+    if (target.x !== undefined && target.y !== undefined)
+        return 'visual-coordinate';
+    return 'cdp';
+}

package/src/tools/webbrowser/browserInteractionResolver.ts

@@ -0,0 +1,40 @@
+/**
+ * Deterministic interaction strategy selection shared by batch results and
+ * future adapters. MCP/WebMCP is intentionally absent: this project uses the
+ * visible supervised browser and falls back through its strongest local
+ * representation.
+ */
+export type BrowserInteractionStrategy =
+  | 'ax'
+  | 'role-locator'
+  | 'playwright-locator'
+  | 'dom-cua'
+  | 'visual-coordinate'
+  | 'cdp';
+
+export type BrowserInteractionTarget = {
+  locator?: { by?: string };
+  selector?: string;
+  node_id?: number;
+  x?: number;
+  y?: number;
+};
+
+export function resolveInteractionStrategy(
+  target: BrowserInteractionTarget,
+): BrowserInteractionStrategy {
+  if (target.locator?.by === 'ax') return 'ax';
+  if (
+    target.locator?.by === 'role' ||
+    target.locator?.by === 'label' ||
+    target.locator?.by === 'text' ||
+    target.locator?.by === 'placeholder' ||
+    target.locator?.by === 'testid'
+  )
+    return 'role-locator';
+  if (target.locator || target.selector) return 'playwright-locator';
+  if (target.node_id !== undefined) return 'dom-cua';
+  if (target.x !== undefined && target.y !== undefined)
+    return 'visual-coordinate';
+  return 'cdp';
+}

package/src/tools/webbrowser/browserLocator.js

@@ -0,0 +1,140 @@
+/**
+ * Browser locators shared by BrowserBatch and future visible-DOM adapters.
+ *
+ * This deliberately emits a small, self-contained browser expression instead
+ * of retaining DOM node handles.  A locator is resolved again for every step,
+ * so a navigation or React re-render cannot silently reuse a stale element.
+ */
+const quote = (value) => JSON.stringify(value);
+/** Build an expression returning `Element[]` in the selected document. */
+export function buildLocatorExpression(locator, selector, rootExpression = 'document') {
+    if (selector) {
+        return `Array.from(${rootExpression}.querySelectorAll(${quote(selector)}))`;
+    }
+    if (!locator)
+        throw new Error('step requires selector or locator');
+    if (locator.by === 'ax') {
+        throw new Error('AX locator must be resolved against the live accessibility tree first');
+    }
+    const root = locator.within
+        ? `${buildLocatorExpression(locator.within, undefined, rootExpression)}.flatMap((scope) => Array.from(scope.querySelectorAll('*')))`
+        : `Array.from(${rootExpression}.querySelectorAll('*'))`;
+    const value = quote(locator.value);
+    const exact = locator.exact === true;
+    const compare = (expression, expected = value) => exact
+        ? `${expression}.trim()===${expected}`
+        : `${expression}.includes(${expected})`;
+    let predicate;
+    switch (locator.by) {
+        case 'css':
+            return applyFilters(`Array.from(${rootExpression}.querySelectorAll(${value}))`, locator);
+        case 'role': {
+            const name = locator.name ? quote(locator.name) : value;
+            const nameCompare = locator.name
+                ? `(function(name){return ${exact ? `name.trim()===${name}` : `name.includes(${name})`};})(__name)`
+                : 'true';
+            predicate = `(__role===${value}&&${nameCompare})`;
+            break;
+        }
+        case 'label':
+            predicate = `Array.from(__el.labels||[]).some((label)=>${compare("(label.textContent||'')")})`;
+            break;
+        case 'placeholder':
+            predicate = compare(`__el.getAttribute('placeholder')||''`);
+            break;
+        case 'alt':
+            predicate = compare(`__el.getAttribute('alt')||''`);
+            break;
+        case 'title':
+            predicate = compare(`__el.getAttribute('title')||''`);
+            break;
+        case 'testid':
+            predicate = compare(`__el.getAttribute('data-testid')||''`);
+            break;
+        case 'text':
+            predicate = `(!__el.children.length&&${compare("(__el.textContent||'')")})`;
+            break;
+    }
+    const expression = `(() => {
+    const __accessibleName = (el) => {
+      const labelled = el.getAttribute('aria-label');
+      if (labelled) return labelled;
+      const ids = (el.getAttribute('aria-labelledby')||'').split(/\\s+/).filter(Boolean);
+      if (ids.length) return ids.map((id)=>${rootExpression}.getElementById(id)?.textContent||'').join(' ').trim();
+      if (el.labels?.length) return Array.from(el.labels).map((label)=>label.textContent||'').join(' ').trim();
+      return (el.innerText||el.textContent||'').trim();
+    };
+    const __implicitRole = (el) => {
+      const explicit = el.getAttribute('role');
+      if (explicit) return explicit;
+      const tag = el.tagName.toLowerCase();
+      if (tag === 'button') return 'button';
+      if (tag === 'a' && el.hasAttribute('href')) return 'link';
+      if (tag === 'textarea') return 'textbox';
+      if (tag === 'select') return 'combobox';
+      if (tag === 'input') {
+        const type = (el.getAttribute('type')||'text').toLowerCase();
+        if (type === 'checkbox') return 'checkbox';
+        if (type === 'radio') return 'radio';
+        if (type === 'button' || type === 'submit' || type === 'reset') return 'button';
+        return 'textbox';
+      }
+      return '';
+    };
+    return ${root}.filter((__el) => {
+      const __role = __implicitRole(__el);
+      const __name = __accessibleName(__el);
+      return ${predicate};
+    });
+  })()`;
+    const filtered = applyFilters(expression, locator);
+    const framePath = locator.frame ?? locator.framePath ?? locator.frame_path;
+    if (!framePath?.length)
+        return filtered;
+    // Same-origin frame traversal is explicit.  Cross-origin frames cannot be
+    // inspected through Runtime.evaluate and must be handled by a backend that
+    // can attach to the child target; never pretend the parent matched instead.
+    let frameRoot = rootExpression;
+    for (const frame of framePath) {
+        const frameSelector = frame.by === 'css'
+            ? quote(frame.value)
+            : quote(`iframe[title*="${frame.value.replaceAll('"', '\\"')}"]`);
+        frameRoot = `(() => { const frame = ${frameRoot}.querySelector(${frameSelector}); if (!frame || !frame.contentDocument) throw new Error('frameLocator could not resolve a same-origin iframe'); return frame.contentDocument; })()`;
+    }
+    return buildLocatorExpression({
+        ...locator,
+        frame: undefined,
+        framePath: undefined,
+        frame_path: undefined,
+        frameId: undefined,
+        frame_id: undefined,
+    }, selector, frameRoot);
+}
+function applyFilters(expression, locator) {
+    const filters = [];
+    if (locator.has_text)
+        filters.push(`(__el.textContent||'').includes(${quote(locator.has_text)})`);
+    return filters.length
+        ? `Array.from(${expression}).filter((__el)=>${filters.join('&&')})`
+        : expression;
+}
+export function buildTargetExpression(locator, selector) {
+    const elements = buildLocatorExpression(locator, selector);
+    const strict = locator?.strict !== false;
+    const nth = locator?.nth ?? 0;
+    return `(() => {
+    const __matches = ${elements}.filter((__candidate) => {
+      const __style = getComputedStyle(__candidate);
+      const __rect = __candidate.getBoundingClientRect();
+      return __style.display!=='none' && __style.visibility!=='hidden' && __style.pointerEvents!=='none' && (!!__rect.width || !!__rect.height);
+    });
+    if (!__matches.length) throw new Error('Locator matched no elements');
+    if (__matches.length > 1 && ${strict}) throw new Error('Locator matched '+__matches.length+' elements; use nth or strict:false');
+    const __el = __matches[${nth}];
+    if (!__el) throw new Error('Locator nth is outside the matched elements');
+    const __style = getComputedStyle(__el);
+    const __rect = __el.getBoundingClientRect();
+    if (__style.display==='none'||__style.visibility==='hidden'||__style.pointerEvents==='none'||(!__rect.width&&!__rect.height)) throw new Error('Locator matched a hidden element');
+    return __el;
+  })()`;
+}