@pyrokine/mcp-chrome 2.3.2 → 2.4.0

package/dist/tools/target-diagnostics.js

@@ -0,0 +1,85 @@
+import { sanitizeErrorMessage } from '../core/error-sanitizer.js';
+const MAX_CANDIDATES = 10;
+const MAX_LOCATOR_TEXT = 500;
+const MAX_CANDIDATE_TEXT = 160;
+const MAX_DIAGNOSTIC_TIMEOUT_MS = 1000;
+export class TargetTimeoutError extends Error {
+    context;
+    code = 'TARGET_TIMEOUT';
+    suggestion = '请检查 locator、frame 和 nth，或根据候选摘要调整目标；连接不可用时先恢复 Extension';
+    constructor(context) {
+        super(`等待目标元素超时 (${context.timeout}ms)`);
+        this.context = context;
+        this.name = 'TargetTimeoutError';
+    }
+    toJSON() {
+        return { error: { code: this.code, message: this.message, suggestion: this.suggestion, context: this.context } };
+    }
+}
+function targetType(target) {
+    return Object.keys(target).find((key) => key !== 'nth') ?? 'unknown';
+}
+function boundedTarget(target) {
+    return Object.fromEntries(Object.entries(target).map(([key, value]) => [
+        key,
+        typeof value === 'string' ? value.slice(0, MAX_LOCATOR_TEXT) : value,
+    ]));
+}
+export function summarizeTargetCandidates(candidates) {
+    return candidates.slice(0, MAX_CANDIDATES).map((candidate) => ({
+        ...(typeof candidate.tag === 'string' ? { tag: candidate.tag.slice(0, 40) } : {}),
+        ...(typeof candidate.text === 'string' ? { text: candidate.text.slice(0, MAX_CANDIDATE_TEXT) } : {}),
+        ...(candidate.rect ? { rect: candidate.rect } : {}),
+    }));
+}
+async function collectPageCandidates(unifiedSession, timeout) {
+    try {
+        const candidates = await unifiedSession.evaluate(`(() => Array.from(document.querySelectorAll('input, textarea, select, button, a, [role], [contenteditable="true"]'))
+                .slice(0, ${MAX_CANDIDATES})
+                .map((el) => {
+                    const rect = el.getBoundingClientRect();
+                    return {
+                        tag: el.tagName.toLowerCase(),
+                        id: el.id || undefined,
+                        role: el.getAttribute('role') || undefined,
+                        label: (el.getAttribute('aria-label') || el.getAttribute('placeholder') || '').slice(0, 80),
+                        text: (el.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, ${MAX_CANDIDATE_TEXT}),
+                        visible: rect.width > 0 && rect.height > 0,
+                        disabled: Boolean(el.disabled) || el.getAttribute('aria-disabled') === 'true',
+                        bounds: {x: rect.x, y: rect.y, width: rect.width, height: rect.height}
+                    };
+                }))()`, undefined, Math.min(Math.max(timeout ?? MAX_DIAGNOSTIC_TIMEOUT_MS, 1), MAX_DIAGNOSTIC_TIMEOUT_MS));
+        return { candidates };
+    }
+    catch (error) {
+        return {
+            candidates: [],
+            diagnosticError: sanitizeErrorMessage(error).slice(0, 500),
+        };
+    }
+}
+export async function buildTargetDiagnostics(unifiedSession, target, options) {
+    const state = unifiedSession.getState();
+    const knownCandidates = options.candidates ? summarizeTargetCandidates(options.candidates) : [];
+    const pageCandidates = knownCandidates.length > 0
+        ? { candidates: knownCandidates }
+        : await collectPageCandidates(unifiedSession, options.timeout);
+    return {
+        locator: boundedTarget(target),
+        targetType: targetType(target),
+        nth: options.nth,
+        currentUrl: state?.url?.slice(0, 500),
+        tabId: unifiedSession.getCurrentTargetId(),
+        managed: state?.managed ?? false,
+        frame: options.frame,
+        matchCount: options.matchCount,
+        candidates: pageCandidates.candidates,
+        lastLocatorState: options.lastState,
+        timeout: options.timeout,
+        mode: unifiedSession.getMode(),
+        connection: unifiedSession.isExtensionConnected() ? 'connected' : 'unavailable',
+        ...(options.lastError ? { lastError: sanitizeErrorMessage(options.lastError).slice(0, 500) } : {}),
+        ...(pageCandidates.diagnosticError ? { diagnosticError: pageCandidates.diagnosticError } : {}),
+    };
+}
+//# sourceMappingURL=target-diagnostics.js.map

package/dist/tools/target-diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-diagnostics.js","sourceRoot":"","sources":["../../src/tools/target-diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/tools/wait.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../src/tools/wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAwoBxE;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CASxD"}
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../src/tools/wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AA4lBxE;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CASxD"}

package/dist/tools/wait.js

@@ -8,40 +8,19 @@
  * - idle: 等待网络空闲
  */
 import { z } from 'zod';
-import { formatErrorResponse, formatResponse, getSession, getUnifiedSession, TimeoutError } from '../core/index.js';
+import { formatErrorResponse, getSession, getUnifiedSession, TimeoutError } from '../core/index.js';
 import { DEFAULT_TIMEOUT } from '../core/types.js';
+import { withDiagnosticsResponse } from './diagnostics.js';
 import { targetToFindParams, targetZodSchema } from './schema.js';
+import { buildTargetDiagnostics, TargetTimeoutError } from './target-diagnostics.js';
 /** 轮询间隔（毫秒） */
 const POLL_INTERVAL = 100;
 const NAVIGATION_SNAPSHOT_TIMEOUT = 1000;
-async function captureDiagnosticsStart(unifiedSession) {
-    await unifiedSession.enableConsole();
-    await unifiedSession.enableNetwork();
-    const consoleLogs = await unifiedSession.getConsoleLogs();
-    const network = await unifiedSession.getNetworkRequests();
-    return { consoleCount: consoleLogs.length, networkCount: network.length };
-}
-async function captureDiagnosticsDelta(unifiedSession, start) {
-    const consoleLogs = await unifiedSession.getConsoleLogs();
-    const network = await unifiedSession.getNetworkRequests();
-    return {
-        console: consoleLogs
-            .slice(start.consoleCount)
-            .filter((item) => ['error', 'warning', 'warn'].includes(item.level))
-            .slice(-20),
-        failedRequests: network
-            .slice(start.networkCount)
-            .filter((item) => item.errorText || (item.status !== undefined && item.status >= 400))
-            .slice(-20),
-    };
-}
-async function withDiagnostics(unifiedSession, enabled, action) {
-    const start = enabled ? await captureDiagnosticsStart(unifiedSession) : undefined;
-    const result = await action();
-    if (start) {
-        result.diagnostics = await captureDiagnosticsDelta(unifiedSession, start);
+async function sleepWithinBudget(startedAt, timeout, interval) {
+    const remaining = timeout - (Date.now() - startedAt);
+    if (remaining > 0) {
+        await new Promise((resolve) => setTimeout(resolve, Math.min(interval, remaining)));
     }
-    return result;
 }
 async function getExtensionNavigationSnapshot(unifiedSession, timeout = NAVIGATION_SNAPSHOT_TIMEOUT) {
     const targetId = unifiedSession.getCurrentTargetId();
@@ -117,9 +96,9 @@ async function handleWait(args) {
                             };
                         }
                         const state = args.state ?? 'visible';
-                        return formatResponse(await withDiagnostics(unifiedSession, args.diagnostics, async () => {
+                        return withDiagnosticsResponse(unifiedSession, args.diagnostics, async () => {
                             if (mode === 'extension') {
-                                await waitForElementExtension(unifiedSession, args.target, state, timeout);
+                                await waitForElementExtension(unifiedSession, args.target, state, timeout, args.frame);
                             }
                             else {
                                 const session = getSession();
@@ -131,94 +110,86 @@ async function handleWait(args) {
                                 state,
                                 mode,
                             };
-                        }));
+                        });
                     }
                     case 'navigation': {
-                        const diagnosticsStart = args.diagnostics
-                            ? await captureDiagnosticsStart(unifiedSession)
-                            : undefined;
-                        if (mode === 'extension') {
-                            const navStart = Date.now();
-                            let navCompleted = false;
-                            let navLastError = null;
-                            let initialUrl = null;
-                            let initialTitle = null;
-                            let sawLoading = false;
-                            let navUrl = null;
-                            let navTitle = null;
-                            try {
-                                const initial = await getExtensionNavigationSnapshot(unifiedSession, Math.min(timeout, NAVIGATION_SNAPSHOT_TIMEOUT));
-                                if (unifiedSession.isExtensionConnected()) {
-                                    initialUrl = initial.url;
-                                    initialTitle = initial.title;
-                                    sawLoading = initial.readyState !== 'complete';
+                        return withDiagnosticsResponse(unifiedSession, args.diagnostics, async () => {
+                            if (mode === 'extension') {
+                                const navStart = Date.now();
+                                let navCompleted = false;
+                                let navLastError = null;
+                                let initialUrl = null;
+                                let initialTitle = null;
+                                let sawLoading = false;
+                                let navUrl = null;
+                                let navTitle = null;
+                                try {
+                                    const initial = await getExtensionNavigationSnapshot(unifiedSession, Math.min(timeout, NAVIGATION_SNAPSHOT_TIMEOUT));
+                                    if (unifiedSession.isExtensionConnected()) {
+                                        initialUrl = initial.url;
+                                        initialTitle = initial.title;
+                                        sawLoading = initial.readyState !== 'complete';
+                                    }
                                 }
-                            }
-                            catch (err) {
-                                sawLoading = true;
-                                navLastError = err instanceof Error ? err : new Error(String(err));
-                            }
-                            while (!navCompleted && Date.now() - navStart < timeout) {
-                                if (!unifiedSession.isExtensionConnected()) {
-                                    navLastError = new Error('Extension 未连接');
-                                    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
-                                    continue;
+                                catch (err) {
+                                    sawLoading = true;
+                                    navLastError = err instanceof Error ? err : new Error(String(err));
                                 }
-                                try {
-                                    const remaining = timeout - (Date.now() - navStart);
-                                    const pageInfo = await getExtensionNavigationSnapshot(unifiedSession, Math.min(remaining, NAVIGATION_SNAPSHOT_TIMEOUT));
+                                while (!navCompleted && Date.now() - navStart < timeout) {
                                     if (!unifiedSession.isExtensionConnected()) {
-                                        navLastError = new Error('Extension 在查询导航状态期间断开');
-                                        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
+                                        navLastError = new Error('Extension 未连接');
+                                        await sleepWithinBudget(navStart, timeout, POLL_INTERVAL);
                                         continue;
                                     }
-                                    if (pageInfo.readyState !== 'complete') {
-                                        sawLoading = true;
-                                    }
-                                    else {
-                                        const changed = (initialUrl !== null && pageInfo.url !== initialUrl) ||
-                                            (initialTitle !== null && pageInfo.title !== initialTitle);
-                                        if (sawLoading || changed || initialUrl === null) {
-                                            navUrl = pageInfo.url;
-                                            navTitle = pageInfo.title;
-                                            navCompleted = true;
-                                            break;
+                                    try {
+                                        const remaining = timeout - (Date.now() - navStart);
+                                        const pageInfo = await getExtensionNavigationSnapshot(unifiedSession, Math.min(remaining, NAVIGATION_SNAPSHOT_TIMEOUT));
+                                        if (!unifiedSession.isExtensionConnected()) {
+                                            navLastError = new Error('Extension 在查询导航状态期间断开');
+                                            await sleepWithinBudget(navStart, timeout, POLL_INTERVAL);
+                                            continue;
+                                        }
+                                        if (pageInfo.readyState !== 'complete') {
+                                            sawLoading = true;
+                                        }
+                                        else {
+                                            const changed = (initialUrl !== null && pageInfo.url !== initialUrl) ||
+                                                (initialTitle !== null && pageInfo.title !== initialTitle);
+                                            if (sawLoading || changed || initialUrl === null) {
+                                                navUrl = pageInfo.url;
+                                                navTitle = pageInfo.title;
+                                                navCompleted = true;
+                                                break;
+                                            }
                                         }
                                     }
+                                    catch (err) {
+                                        navLastError = err instanceof Error ? err : new Error(String(err));
+                                    }
+                                    await sleepWithinBudget(navStart, timeout, POLL_INTERVAL);
                                 }
-                                catch (err) {
-                                    navLastError = err instanceof Error ? err : new Error(String(err));
+                                if (!navCompleted) {
+                                    const msg = `等待导航完成超时 (${timeout}ms)`;
+                                    throw new TimeoutError(navLastError ? `${msg}: ${navLastError.message}` : msg);
                                 }
-                                await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
+                                return {
+                                    success: true,
+                                    waited: 'navigation',
+                                    url: navUrl,
+                                    title: navTitle,
+                                    mode,
+                                };
                             }
-                            if (!navCompleted) {
-                                const msg = `等待导航完成超时 (${timeout}ms)`;
-                                throw new TimeoutError(navLastError ? `${msg}: ${navLastError.message}` : msg);
-                            }
-                            return formatResponse({
+                            const session = getSession();
+                            await waitForNavigation(session, timeout);
+                            const sessionState = session.getState();
+                            return {
                                 success: true,
                                 waited: 'navigation',
-                                url: navUrl,
-                                title: navTitle,
+                                url: sessionState?.url,
+                                title: sessionState?.title,
                                 mode,
-                                ...(diagnosticsStart
-                                    ? { diagnostics: await captureDiagnosticsDelta(unifiedSession, diagnosticsStart) }
-                                    : {}),
-                            });
-                        }
-                        // CDP 模式
-                        const session = getSession();
-                        await waitForNavigation(session, timeout);
-                        const sessionState = session.getState();
-                        return formatResponse({
-                            success: true,
-                            waited: 'navigation',
-                            url: sessionState?.url,
-                            title: sessionState?.title,
-                            mode,
-                            ...(diagnosticsStart
-                                ? { diagnostics: await captureDiagnosticsDelta(unifiedSession, diagnosticsStart) }
-                                : {}),
+                            };
                         });
                     }
                     case 'time': {
@@ -238,66 +209,66 @@ async function handleWait(args) {
                                 isError: true,
                             };
                         }
-                        await new Promise((resolve) => setTimeout(resolve, args.ms));
-                        return formatResponse({
-                            success: true,
-                            waited: 'time',
-                            ms: args.ms,
+                        return withDiagnosticsResponse(unifiedSession, args.diagnostics, async () => {
+                            await new Promise((resolve) => setTimeout(resolve, args.ms));
+                            return {
+                                success: true,
+                                waited: 'time',
+                                ms: args.ms,
+                            };
                         });
                     }
                     case 'idle': {
-                        const diagnosticsStart = args.diagnostics
-                            ? await captureDiagnosticsStart(unifiedSession)
-                            : undefined;
-                        if (mode === 'extension') {
-                            // Extension 模式：readyState complete + DOM mutation 静默检测
-                            const idleStart = Date.now();
-                            const quietPeriod = args.ms ?? 500;
-                            let idleCompleted = false;
-                            let idleLastError = null;
-                            // Phase 1: 等待 readyState === 'complete'
-                            while (Date.now() - idleStart < timeout) {
-                                if (!unifiedSession.isExtensionConnected()) {
-                                    idleLastError = new Error('Extension 未连接');
-                                    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
-                                    continue;
-                                }
-                                try {
-                                    const remaining = timeout - (Date.now() - idleStart);
-                                    const readyState = await unifiedSession.evaluate('document.readyState', undefined, remaining);
+                        return withDiagnosticsResponse(unifiedSession, args.diagnostics, async () => {
+                            if (mode === 'extension') {
+                                // Extension 模式：readyState complete + DOM mutation 静默检测
+                                const idleStart = Date.now();
+                                const quietPeriod = args.ms ?? 500;
+                                let idleCompleted = false;
+                                let idleLastError = null;
+                                // Phase 1: 等待 readyState === 'complete'
+                                while (Date.now() - idleStart < timeout) {
                                     if (!unifiedSession.isExtensionConnected()) {
-                                        idleLastError = new Error('Extension 在 evaluate 期间断开');
-                                        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
+                                        idleLastError = new Error('Extension 未连接');
+                                        await sleepWithinBudget(idleStart, timeout, POLL_INTERVAL);
                                         continue;
                                     }
-                                    if (readyState === 'complete') {
-                                        idleCompleted = true;
-                                        break;
+                                    try {
+                                        const remaining = timeout - (Date.now() - idleStart);
+                                        const readyState = await unifiedSession.evaluate('document.readyState', undefined, remaining);
+                                        if (!unifiedSession.isExtensionConnected()) {
+                                            idleLastError = new Error('Extension 在 evaluate 期间断开');
+                                            await sleepWithinBudget(idleStart, timeout, POLL_INTERVAL);
+                                            continue;
+                                        }
+                                        if (readyState === 'complete') {
+                                            idleCompleted = true;
+                                            break;
+                                        }
+                                    }
+                                    catch (err) {
+                                        idleLastError = err instanceof Error ? err : new Error(String(err));
                                     }
+                                    await sleepWithinBudget(idleStart, timeout, POLL_INTERVAL);
                                 }
-                                catch (err) {
-                                    idleLastError = err instanceof Error ? err : new Error(String(err));
+                                if (!idleCompleted) {
+                                    const msg = `等待页面加载超时 (${timeout}ms)`;
+                                    throw new TimeoutError(idleLastError ? `${msg}: ${idleLastError.message}` : msg);
                                 }
-                                await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
-                            }
-                            if (!idleCompleted) {
-                                const msg = `等待页面加载超时 (${timeout}ms)`;
-                                throw new TimeoutError(idleLastError ? `${msg}: ${idleLastError.message}` : msg);
-                            }
-                            // Phase 2: DOM mutation 静默检测
-                            // 注入 MutationObserver，等待 quietPeriod 毫秒内无 DOM 变更
-                            const mutationRemaining = timeout - (Date.now() - idleStart);
-                            const scriptTimeout = mutationRemaining - POLL_INTERVAL;
-                            if (scriptTimeout > quietPeriod) {
-                                try {
-                                    const domStable = await new Promise((resolve, reject) => {
-                                        let settled = false;
-                                        const timer = setTimeout(() => {
-                                            settled = true;
-                                            resolve(false);
-                                        }, scriptTimeout);
-                                        unifiedSession
-                                            .evaluate(`(function(quietMs, timeoutMs) {
+                                // Phase 2: DOM mutation 静默检测
+                                // 注入 MutationObserver，等待 quietPeriod 毫秒内无 DOM 变更
+                                const mutationRemaining = timeout - (Date.now() - idleStart);
+                                const scriptTimeout = mutationRemaining - POLL_INTERVAL;
+                                if (scriptTimeout > quietPeriod) {
+                                    try {
+                                        const domStable = await new Promise((resolve, reject) => {
+                                            let settled = false;
+                                            const timer = setTimeout(() => {
+                                                settled = true;
+                                                resolve(false);
+                                            }, scriptTimeout);
+                                            unifiedSession
+                                                .evaluate(`(function(quietMs, timeoutMs) {
                                                     return new Promise(function(resolve) {
                                                         var target = document.documentElement || document.body;
                                                         if (!target) {
@@ -342,58 +313,50 @@ async function handleWait(args) {
                                                         setTimeout(check, quietMs);
                                                     });
                                                 })`, undefined, mutationRemaining, [quietPeriod, scriptTimeout])
-                                            .then((value) => {
-                                            if (settled) {
-                                                return;
-                                            }
-                                            settled = true;
-                                            clearTimeout(timer);
-                                            resolve(value);
-                                        })
-                                            .catch((err) => {
-                                            if (settled) {
-                                                return;
-                                            }
-                                            settled = true;
-                                            clearTimeout(timer);
-                                            reject(err);
+                                                .then((value) => {
+                                                if (settled) {
+                                                    return;
+                                                }
+                                                settled = true;
+                                                clearTimeout(timer);
+                                                resolve(value);
+                                            })
+                                                .catch((err) => {
+                                                if (settled) {
+                                                    return;
+                                                }
+                                                settled = true;
+                                                clearTimeout(timer);
+                                                reject(err);
+                                            });
                                         });
-                                    });
-                                    if (!domStable) {
-                                        throw new TimeoutError(`等待页面 idle 超时 (${timeout}ms): DOM 未达到 ${quietPeriod}ms 静默`);
+                                        if (!domStable) {
+                                            throw new TimeoutError(`等待页面 idle 超时 (${timeout}ms): DOM 未达到 ${quietPeriod}ms 静默`);
+                                        }
+                                        return {
+                                            success: true,
+                                            waited: 'idle',
+                                            domStable,
+                                            mode,
+                                        };
                                     }
-                                    return formatResponse({
-                                        success: true,
-                                        waited: 'idle',
-                                        domStable,
-                                        mode,
-                                        ...(diagnosticsStart
-                                            ? {
-                                                diagnostics: await captureDiagnosticsDelta(unifiedSession, diagnosticsStart),
-                                            }
-                                            : {}),
-                                    });
-                                }
-                                catch (err) {
-                                    if (err instanceof TimeoutError) {
-                                        throw err;
+                                    catch (err) {
+                                        if (err instanceof TimeoutError) {
+                                            throw err;
+                                        }
+                                        const message = err instanceof Error ? err.message : String(err);
+                                        throw new TimeoutError(`等待页面 idle 超时 (${timeout}ms): ${message}`);
                                     }
-                                    const message = err instanceof Error ? err.message : String(err);
-                                    throw new TimeoutError(`等待页面 idle 超时 (${timeout}ms): ${message}`);
                                 }
+                                throw new TimeoutError(`等待页面 idle 超时 (${timeout}ms): 剩余时间不足以完成 ${quietPeriod}ms DOM 静默检测`);
                             }
-                            throw new TimeoutError(`等待页面 idle 超时 (${timeout}ms): 剩余时间不足以完成 ${quietPeriod}ms DOM 静默检测`);
-                        }
-                        // CDP 模式
-                        const session = getSession();
-                        await waitForNetworkIdle(session, timeout);
-                        return formatResponse({
-                            success: true,
-                            waited: 'idle',
-                            mode,
-                            ...(diagnosticsStart
-                                ? { diagnostics: await captureDiagnosticsDelta(unifiedSession, diagnosticsStart) }
-                                : {}),
+                            const session = getSession();
+                            await waitForNetworkIdle(session, timeout);
+                            return {
+                                success: true,
+                                waited: 'idle',
+                                mode,
+                            };
                         });
                     }
                     default:
@@ -422,27 +385,38 @@ async function handleWait(args) {
 /**
  * Extension 模式：等待元素
  */
-async function waitForElementExtension(unifiedSession, target, state, timeout) {
+async function waitForElementExtension(unifiedSession, target, state, timeout, frame) {
     const startTime = Date.now();
     const retryDelay = POLL_INTERVAL;
     const { selector, text, xpath, nth: nthParam } = targetToFindParams(target);
     const nth = nthParam ?? 0;
     let lastError = null;
+    let matchCount = 0;
+    let candidates = [];
     while (true) {
         const elapsed = Date.now() - startTime;
         if (elapsed >= timeout) {
-            const msg = `等待元素 ${JSON.stringify(target)} 状态 ${state} 超时 (${timeout}ms)`;
-            throw new TimeoutError(lastError ? `${msg}: ${lastError.message}` : msg);
+            throw new TargetTimeoutError(await buildTargetDiagnostics(unifiedSession, target, {
+                nth,
+                timeout,
+                frame,
+                matchCount,
+                lastState: state,
+                lastError,
+                candidates,
+            }));
         }
         // 未连接时跳过 find()，避免阻塞超出用户 timeout
         if (!unifiedSession.isExtensionConnected()) {
             lastError = new Error('Extension 未连接');
-            await new Promise((resolve) => setTimeout(resolve, retryDelay));
+            await sleepWithinBudget(startTime, timeout, retryDelay);
             continue;
         }
         try {
             const remaining = timeout - elapsed;
             const elements = await unifiedSession.find(selector, text, xpath, remaining);
+            matchCount = elements.length;
+            candidates = elements;
             const found = elements.length > nth;
             switch (state) {
                 case 'attached':
@@ -481,12 +455,12 @@ async function waitForElementExtension(unifiedSession, target, state, timeout) {
             if (err instanceof Error &&
                 /Request timeout|Failed to send|disconnect|未连接|stopped|replaced/i.test(err.message)) {
                 lastError = err;
-                await new Promise((resolve) => setTimeout(resolve, retryDelay));
+                await sleepWithinBudget(startTime, timeout, retryDelay);
                 continue;
             }
             throw err;
         }
-        await new Promise((resolve) => setTimeout(resolve, retryDelay));
+        await sleepWithinBudget(startTime, timeout, retryDelay);
     }
 }
 /**
@@ -544,7 +518,7 @@ async function waitForElement(session, target, state, timeout) {
             }
             // 继续等待
         }
-        await new Promise((resolve) => setTimeout(resolve, retryDelay));
+        await sleepWithinBudget(startTime, timeout, retryDelay);
     }
     throw new TimeoutError(`等待元素 ${JSON.stringify(target)} 状态 ${state} 超时 (${timeout}ms)`);
 }