dsh-browser-view 0.7.0 → 0.7.4

package/lib/index.js

@@ -572,12 +572,12 @@ function __walkerCore() {
 		}
 		if (el.id) {
 			const t = document.querySelector(`label[for="${CSS.escape(el.id)}"]`)?.textContent?.trim();
-			if (t) return t.slice(0, 60);
+			if (t) return t.replace(/^[*：:\s]+|[*：:\s]+$/g, "").slice(0, 60);
 		}
 		const wrapLabel = el.closest("label");
 		if (wrapLabel) {
 			const t = wrapLabel.textContent?.trim();
-			if (t) return t.slice(0, 60);
+			if (t) return t.replace(/^[*：:\s]+|[*：:\s]+$/g, "").slice(0, 60);
 		}
 		if ([
 			"checkbox",
@@ -587,17 +587,45 @@ function __walkerCore() {
 			const container = el.closest("label, [class*='wrapper'], [class*='item'], li");
 			if (container) {
 				const t = container.textContent?.trim();
-				if (t) return t.replace(/\s+/g, " ").slice(0, 60);
+				if (t) return t.replace(/\s+/g, " ").replace(/^[*：:\s]+|[*：:\s]+$/g, "").slice(0, 60);
 			}
 		}
 		if ([
 			"textbox",
 			"searchbox",
 			"combobox",
-			"spinbutton"
+			"spinbutton",
+			"slider",
+			"listbox"
 		].includes(role)) {
+			const formItem = el.closest("[class*='form-item'], [class*='form__item'], [class*='form-group'], [role='group']");
+			if (formItem) {
+				const lab = formItem.querySelector("label, [class*='form-item-label'], [class*='form-item__label'], [class*='label']");
+				if (lab) {
+					const t = (lab.getAttribute("title") || lab.textContent || "").trim().replace(/^[*：:\s]+|[*：:\s]+$/g, "");
+					if (t) return t.slice(0, 60);
+				}
+			}
+			const selectHost = el.closest("[class*='select'], [class*='cascader'], [class*='picker']");
+			if (selectHost) {
+				const ph = selectHost.querySelector("[class*='placeholder'], [class*='selection-placeholder']")?.textContent?.trim();
+				if (ph) return ph.slice(0, 60);
+				const selVal = selectHost.querySelector("[class*='selection-item'], [class*='selected-value']")?.textContent?.trim();
+				if (selVal) return selVal.slice(0, 60);
+			}
 			const ph = el.getAttribute("placeholder");
 			if (ph && ph.trim()) return ph.trim().slice(0, 60);
+			const host = selectHost || el;
+			const prevEl = host.previousElementSibling;
+			if (prevEl) {
+				const prevText = (prevEl.textContent || "").trim().replace(/^[*：:\s]+|[*：:\s]+$/g, "");
+				if (prevText && prevText.length <= 30) return prevText.slice(0, 60);
+			}
+			const td = host.closest("td");
+			if (td && td.previousElementSibling) {
+				const tdText = (td.previousElementSibling.textContent || "").trim().replace(/^[*：:\s]+|[*：:\s]+$/g, "");
+				if (tdText && tdText.length <= 30) return tdText.slice(0, 60);
+			}
 		}
 		const text = (el.innerText || el.textContent || "").trim().replace(/\s+/g, " ");
 		if (text) return text.slice(0, 60);
@@ -683,6 +711,25 @@ function __walkerCore() {
 			visible: isVisible(el)
 		};
 	}
+	/** 疑似可点击 generic 元素(自定义组件的 span+click 等):无 ARIA 角色或显式
+	* presentational(presentation/none)但具备 cursor:pointer / onclick 属性 /
+	* tabindex≥0 特征且有非空文本(≤60 字符)。仅供扫描语义消费(what 语义扫描与
+	* SoM 标徽共用,防判定分叉);aria 快照不纳入(避免噪音)——这是记录在案的
+	* 设计分叉,见产品文档 03。 */
+	function isProbablyClickable(el) {
+		const role = roleOf(el);
+		if (role !== "" && role !== "presentation" && role !== "none") return false;
+		const text = (el.innerText || el.textContent || "").trim();
+		if (text === "" || text.length > 60) return false;
+		if (el.hasAttribute("onclick")) return true;
+		const ti = el.tabIndex;
+		if (typeof ti === "number" && ti >= 0) return true;
+		try {
+			return getComputedStyle(el).cursor === "pointer";
+		} catch {
+			return false;
+		}
+	}
 	return {
 		INTERACTIVE,
 		STRUCTURAL,
@@ -694,7 +741,8 @@ function __walkerCore() {
 		isElementInViewport,
 		describeElement,
 		composedParent,
-		deepChildren
+		deepChildren,
+		isProbablyClickable
 	};
 }
 /** walker 核心的序列化源码(模块加载期取一次;tsdown/vitest 均原样保留)。 */
@@ -1356,8 +1404,38 @@ async function executeUniversalSelect(ctx) {
 		const options = await withTimeout(target.locator("option").allTextContents(), probe, "读取原生下拉选项").catch(() => []);
 		throw new Error(`原生下拉无选项 "${want}"; 可用选项: ${options.map((t) => t.trim()).join(" / ")}`);
 	}
-	const hostLocator = target.locator("xpath=ancestor-or-self::*[@role='combobox' or contains(@class, 'select') or contains(@class, 'selector')][last()]");
-	const actualTarget = await hostLocator.count().catch(() => 0) > 0 ? hostLocator.first() : target;
+	let resolvedTarget = target;
+	if (await withTimeout(target.evaluate((el) => {
+		if (el.tagName.toLowerCase() === "label") return true;
+		const cls = typeof el.className === "string" ? el.className : "";
+		if (/(?:form-item|form__item|form-group)/i.test(cls)) return true;
+		if (el.closest("label, [class*='form-item'], [class*='form__item'], [class*='form-group']")) return !el.matches("[role='combobox'], select, [class*='select-selector']");
+		if (!el.matches("[role='combobox'], select, [class*='select'], [class*='selector']")) return true;
+		return false;
+	}), 1500, "探测 label 或非标文本容器").catch(() => false)) {
+		const descendantSelect = target.locator("xpath=.//*[@role='combobox' or self::select or contains(@class, 'select-selector') or contains(@class, 'select')][not(self::label)]").first();
+		if (await descendantSelect.count().catch(() => 0) > 0) resolvedTarget = descendantSelect;
+		else {
+			const forId = await target.getAttribute("for").catch(() => null);
+			if (forId) {
+				const forTarget = page.locator(`[id="${forId.replace(/"/g, "\\\"")}"]`).first();
+				if (await forTarget.count().catch(() => 0) > 0) resolvedTarget = forTarget;
+			} else {
+				const nextSiblingSelect = target.locator("xpath=following-sibling::*[self::select or @role='combobox' or contains(@class, 'select') or contains(@class, 'selector')][1] | following-sibling::*[1]//*[@role='combobox' or self::select or contains(@class, 'select')]").first();
+				if (await nextSiblingSelect.count().catch(() => 0) > 0) resolvedTarget = nextSiblingSelect;
+				else {
+					const tdSiblingSelect = target.locator("xpath=ancestor-or-self::td[1]/following-sibling::td[1]//*[@role='combobox' or self::select or contains(@class, 'select')]").first();
+					if (await tdSiblingSelect.count().catch(() => 0) > 0) resolvedTarget = tdSiblingSelect;
+					else {
+						const siblingSelect = target.locator("xpath=ancestor-or-self::*[contains(@class, 'form-item') or contains(@class, 'form__item') or contains(@class, 'form-group')][1]//*[@role='combobox' or self::select or contains(@class, 'select-selector') or contains(@class, 'select')][not(self::label)] | ..//*[@role='combobox' or self::select or contains(@class, 'select-selector') or contains(@class, 'select')][not(self::label)]").first();
+						if (await siblingSelect.count().catch(() => 0) > 0) resolvedTarget = siblingSelect;
+					}
+				}
+			}
+		}
+	}
+	const hostLocator = resolvedTarget.locator("xpath=ancestor-or-self::*[@role='combobox' or contains(@class, 'select') or contains(@class, 'selector')][last()]");
+	const actualTarget = await hostLocator.count().catch(() => 0) > 0 ? hostLocator.first() : resolvedTarget;
 	if (clear) try {
 		const clearBtn = actualTarget.locator("[class*='clear'], [aria-label*='clear']").first();
 		if (await clearBtn.count().catch(() => 0) > 0 && await clearBtn.isVisible().catch(() => false)) await clearBtn.click({ timeout: 1e3 }).catch(() => {});
@@ -1410,13 +1488,17 @@ async function executeUniversalSelect(ctx) {
 	const optionSelector = "[role='option']:not([style*='height: 0px']):not([class*='empty']), [class*='item-option']:not([class*='empty']), [class*='select-dropdown'] li:not([class*='empty'])";
 	const dropdownSelector = "[role='listbox']:not([style*='display: none']), [class*='select-dropdown']:not([style*='display: none']):not([class*='hidden']), [class*='popper']:not([style*='display: none'])";
 	let options;
+	let targetDropdown = null;
 	if (controlsId) {
 		const parentDropdown = page.locator(`xpath=//*[@id='${controlsId}']/ancestor-or-self::*[contains(@class, 'dropdown') or contains(@class, 'popper') or @role='listbox'][1] | //*[contains(@class, 'dropdown') or @role='listbox'][.//*[@id='${controlsId}']]`);
+		targetDropdown = parentDropdown.first();
 		const visual = parentDropdown.locator(optionSelector).locator("visible=true");
 		options = await visual.count().catch(() => 0) > 0 ? visual : parentDropdown.locator(optionSelector);
 	} else {
-		const activeDropdowns = page.locator(dropdownSelector);
-		const dropdown = await activeDropdowns.count().catch(() => 0) > 1 ? activeDropdowns.last() : activeDropdowns.first();
+		const activeVisualDropdowns = page.locator(dropdownSelector).locator("visible=true");
+		const visualCount = await activeVisualDropdowns.count().catch(() => 0);
+		const dropdown = visualCount > 1 ? activeVisualDropdowns.last() : visualCount === 1 ? activeVisualDropdowns.first() : page.locator(dropdownSelector).last();
+		targetDropdown = dropdown;
 		const visual = dropdown.locator(optionSelector).locator("visible=true");
 		options = await visual.count().catch(() => 0) > 0 ? visual : dropdown.locator(optionSelector);
 	}
@@ -1432,7 +1514,7 @@ async function executeUniversalSelect(ctx) {
 		};
 	})).catch(() => [])).map((e) => e.text || e.title || e.aria).filter(Boolean);
 	if (visibleTexts.length === 0) {
-		const isEmpty = await page.locator("[class*='empty'], [class*='no-data'], [role='status'], [class*='item-empty']").first().isVisible().catch(() => false);
+		const isEmpty = targetDropdown !== null ? await targetDropdown.locator("[class*='empty'], [class*='no-data'], [role='status'], [class*='item-empty']").first().isVisible().catch(() => false) : false;
 		await actualTarget.click({ timeout: 1e3 }).catch(() => {});
 		if (isEmpty) throw new Error(`下拉浮层当前无选项(数据为空态/无可选数据): ${label}`);
 		throw new Error(`点击 ${label} 后未出现下拉选项(选项列表为空态)`);
@@ -1650,7 +1732,7 @@ async function fillFormFieldHelper(page, field, scope) {
 * 多 token(空格/中英混排拆分)按 AND 命中 —— 单 token 行为与旧子串匹配等价。
 */
 const scanInteractive = injectWalker((payload, w) => {
-	const { INTERACTIVE, STRUCTURAL, SKIP_TAGS, roleOf, nameOf, cssPath, isVisible, deepChildren, composedParent } = w;
+	const { INTERACTIVE, STRUCTURAL, SKIP_TAGS, roleOf, nameOf, cssPath, isVisible, deepChildren, composedParent, isProbablyClickable } = w;
 	function resolveScopeRoot(scopeStr) {
 		if (!scopeStr) return document.body;
 		const wantsVisible = /:visible\b/.test(scopeStr);
@@ -1741,6 +1823,7 @@ const scanInteractive = injectWalker((payload, w) => {
 			}
 			const hit = payload.exact ? legacyHit : legacyHit || tokens.length > 0 && tokenHit;
 			if (legacyHit && name !== "" && name.toLowerCase() === q) score += 50;
+			if (payload.preferredRoles && payload.preferredRoles.includes(role)) score += 40;
 			scanned += 1;
 			if (name !== "" && candidates.length < 50) candidates.push({
 				role,
@@ -1759,6 +1842,39 @@ const scanInteractive = injectWalker((payload, w) => {
 			});
 			continue;
 		}
+		if (isVisible(el) && isProbablyClickable(el)) {
+			const text = (el.innerText || el.textContent || "").trim().slice(0, 60);
+			const n = text.toLowerCase();
+			const nStr = n.replace(/\s+/g, "");
+			const legacyHit = payload.exact ? n === q || nStr === qStripped : n.includes(q) || qStripped !== "" && nStr.includes(qStripped);
+			let tokenScore = 0;
+			let tokenHit = true;
+			for (const t of tokens) {
+				const tStr = t.replace(/\s+/g, "");
+				if (n.includes(t) || tStr !== "" && nStr.includes(tStr)) tokenScore += 3;
+				else {
+					tokenHit = false;
+					break;
+				}
+			}
+			if (legacyHit && n === q) tokenScore += 50;
+			const hit = payload.exact ? legacyHit : legacyHit || tokens.length > 0 && tokenHit;
+			if (candidates.length < 50) candidates.push({
+				role: "clickable",
+				name: text,
+				selector: cssPath(el)
+			});
+			if (hit && hits.length < 100) hits.push({
+				role: "clickable",
+				name: text,
+				selector: cssPath(el),
+				text,
+				visible: true,
+				inDialog: dialogSel !== "" ? Boolean(el.closest(dialogSel)) : false,
+				score: (legacyHit ? 100 : 0) + tokenScore - 200,
+				ancestors: ancestorsOf(el)
+			});
+		}
 		for (const c of deepChildren(el)) if (!SKIP_TAGS.has(c.tagName.toLowerCase())) stack.push(c);
 	}
 	hits.sort((a, b) => Number(b.inDialog) - Number(a.inDialog) || b.score - a.score);
@@ -1804,7 +1920,8 @@ async function resolveSemanticTarget(page, what, opts = {}) {
 			exact: opts.exact === true,
 			scope: typeof opts.scope === "string" && opts.scope !== "" ? opts.scope : "",
 			limit: Math.min(Math.max(opts.limit ?? 5, 1), 20),
-			dialogSelector: ACTIVE_DIALOG_SELECTORS
+			dialogSelector: ACTIVE_DIALOG_SELECTORS,
+			preferredRoles: opts.preferredRoles
 		});
 	} catch {
 		return {
@@ -1838,7 +1955,7 @@ async function resolveSemanticTarget(page, what, opts = {}) {
 * 同一 walker 语义。上限 300 条,超出截断(超大页面重锚定按命中部分处理)。
 */
 const scanAllInteractive = injectWalker((payload, w) => {
-	const { INTERACTIVE, SKIP_TAGS, roleOf, nameOf, cssPath, isVisible, isElementInViewport, deepChildren } = w;
+	const { INTERACTIVE, SKIP_TAGS, roleOf, nameOf, cssPath, isVisible, isElementInViewport, deepChildren, isProbablyClickable } = w;
 	const out = [];
 	let truncated = false;
 	const snapScroll = {
@@ -1882,6 +1999,24 @@ const scanAllInteractive = injectWalker((payload, w) => {
 			});
 			continue;
 		}
+		if (out.length < 300 && isVisible(el) && isProbablyClickable(el)) {
+			const text = (el.innerText || el.textContent || "").trim();
+			const rect = el.getBoundingClientRect();
+			out.push({
+				role: "clickable",
+				name: text.slice(0, 60),
+				selector: cssPath(el),
+				...isElementInViewport(el, 0) ? {
+					rect: {
+						x: Math.round(rect.left),
+						y: Math.round(rect.top),
+						w: Math.round(rect.width),
+						h: Math.round(rect.height)
+					},
+					scroll: snapScroll
+				} : {}
+			});
+		}
 		for (const c of deepChildren(el)) if (!SKIP_TAGS.has(c.tagName.toLowerCase())) stack.push(c);
 	}
 	return {
@@ -1963,7 +2098,19 @@ function nameSimilar(a, b) {
 * 自动识别 selector 或 ref；若 ref 标记位于子 Frame，自动绑定到对应子 Frame 上下文。
 * 具备路径防漂移校验与 getByRole 自愈降级能力。
 */
-async function resolveTargetLocator(page, args) {
+async function resolveTargetLocator(page, args, opts = {}) {
+	{
+		const present = [];
+		if (args.ref !== void 0 && args.ref !== "") present.push("ref");
+		if (args.mark !== void 0) present.push("mark");
+		if (typeof args.what === "string" && args.what.trim() !== "") present.push("what");
+		if (args.selector !== void 0 && args.selector !== "") present.push("selector");
+		if ((args.rowText !== void 0 || args.row !== void 0) && present.some((k) => k !== "selector")) {
+			const offending = present.filter((k) => k !== "selector");
+			throw new Error(`定位参数冲突: row/rowText 与 ${offending.join("、")} 不能同时使用(行级定位仅可组合 selector 限定行内目标);在行内按意图找按钮请用 row + action/actionText`);
+		}
+		if (present.length >= 2) throw new Error(`定位参数冲突: 同时传了 ${present.join(" 与 ")} —— ref/mark/what/selector 四选一;若要在容器内语义定位,请用 what + scope(容器选择器)`);
+	}
 	if (args.ref !== void 0 && args.ref !== "") {
 		const ref = String(args.ref);
 		const entry = pageRef(page, ref);
@@ -2141,7 +2288,10 @@ async function resolveTargetLocator(page, args) {
 	}
 	const what = args.what;
 	if (typeof what === "string" && what.trim() !== "" && args.selector === void 0 && args.ref === void 0 && args.mark === void 0 && rowPattern === void 0) {
-		const res = await resolveSemanticTarget(page, what, { scope: typeof args.scope === "string" && args.scope !== "" ? args.scope : void 0 });
+		const res = await resolveSemanticTarget(page, what, {
+			scope: typeof args.scope === "string" && args.scope !== "" ? args.scope : void 0,
+			preferredRoles: opts.preferredRoles
+		});
 		if (!("candidates" in res)) return res;
 		for (const role of [
 			"button",
@@ -2159,6 +2309,29 @@ async function resolveTargetLocator(page, args) {
 				visibleCount: 1
 			};
 		}
+		{
+			const bridgeHit = await withTimeout(page.evaluate(async (q) => {
+				const b = window.__DSH_BRIDGE__;
+				if (b === void 0 || typeof b.resolveActionTarget !== "function") return null;
+				const targets = await b.resolveActionTarget({ query: q });
+				if (!Array.isArray(targets) || targets.length === 0) return null;
+				const t = targets[0];
+				if (t === null || typeof t !== "object" || typeof t.selector !== "string" || t.selector === "") return null;
+				return { selector: t.selector };
+			}, what), 2500, "bridge 兜底").catch(() => null);
+			const bridgeSelector = bridgeHit !== null && typeof bridgeHit === "object" && typeof bridgeHit.selector === "string" && bridgeHit.selector !== "" ? bridgeHit.selector : null;
+			if (bridgeSelector !== null) {
+				const loc = page.locator(bridgeSelector).first();
+				if (await withTimeout(loc.count(), 1500, "bridge 兜底定位").catch(() => 0) > 0) return {
+					locator: loc,
+					container: page,
+					isIFrame: false,
+					matchedCount: 1,
+					visibleCount: 1,
+					viaBridge: true
+				};
+			}
+		}
 		const err = new Error(semanticMissMessage(res));
 		err.semanticMiss = res;
 		err.locationFailure = {
@@ -2756,7 +2929,7 @@ async function launchProfile(name, config) {
 				...options,
 				headless: resolved.headless ?? false
 			});
-			for (const existing of context.pages()) existing.close().catch(() => {});
+			await Promise.race([Promise.all(context.pages().map((p) => p.close().catch(() => {}))), new Promise((r) => setTimeout(r, 3e3))]);
 			state.browser = null;
 			state.context = context;
 			state.persistent = true;
@@ -2781,11 +2954,30 @@ const namedContexts = /* @__PURE__ */ new Map();
 function namedContextsOf() {
 	return namedContexts;
 }
-/** 把一个已 attach 的页面注册进 profile 标签表并激活,返回分配的 tab id。 */
+/** 同步摘除已关闭页面(手动关标签/渲染崩溃的僵尸句柄)。
+* activeId 指向被摘页时置 null 而非自动迁移——静默换页对 click/type 是错页执行,
+* 由 getPage 报错引导显式恢复(switch / browser_open 自愈)。 */
+function pruneClosedPages(state) {
+	for (const [id, page] of state.pages) if (page.isClosed()) {
+		state.pages.delete(id);
+		state.tabMeta?.delete(id);
+		if (state.activeId === id) state.activeId = null;
+	}
+}
+/** 把一个已 attach 的页面注册进 profile 标签表并激活,返回分配的 tab id。
+* 唯一注册路径:同时挂 close 监听幂等摘除外部关闭的页(否则僵尸句柄会永久占用
+* activeId,所有工具连报 "Target page...closed" 而 tabs list 仍显示存活)。 */
 function registerTabPage(state, page) {
 	const id = state.counter++;
 	state.pages.set(id, page);
 	state.activeId = id;
+	(state.tabMeta ??= /* @__PURE__ */ new Map()).set(id, { createdAt: Date.now() });
+	page.on("close", () => {
+		if (!state.pages.has(id)) return;
+		state.pages.delete(id);
+		state.tabMeta?.delete(id);
+		if (state.activeId === id) state.activeId = null;
+	});
 	return id;
 }
 /** 新建一个页面(当前 profile 会话未启动时先启动)。 */
@@ -2811,34 +3003,42 @@ async function newPage(config) {
 async function getPage(config) {
 	const state = stateOf();
 	if (state.browser === null && state.context === null) await launchProfile(currentProfile, config);
+	pruneClosedPages(state);
 	if (state.pages.size === 0) {
 		const page = await newPage(config);
-		const id = state.counter++;
-		state.pages.set(id, page);
-		state.activeId = id;
+		registerTabPage(state, page);
+		return page;
 	}
 	const page = state.pages.get(state.activeId ?? -1);
-	if (page === void 0) throw new Error("dsh-browser: no active page");
+	if (page === void 0) {
+		const err = /* @__PURE__ */ new Error("dsh-browser: 活动标签已关闭或崩溃;请 browser_tabs { action: \"list\" } 查看存活标签并 switch,或 browser_open 打开目标 URL(将自动新建标签)");
+		err.code = "activeTabClosed";
+		throw err;
+	}
 	return page;
 }
 /** 活动页面(可能为 null,不触发启动)。 */
 function activePage() {
 	const state = stateOf();
+	pruneClosedPages(state);
 	return state.pages.get(state.activeId ?? -1) ?? null;
 }
-/** 投影当前 profile 的标签列表。 */
+/** 投影当前 profile 的标签列表(先摘除僵尸页,附注册时间)。 */
 async function tabList() {
 	const state = stateOf();
+	pruneClosedPages(state);
 	const tabs = [];
 	for (const [id, page] of state.pages) {
 		let title = "";
 		try {
 			title = await page.title();
 		} catch {}
+		const createdAt = state.tabMeta?.get(id)?.createdAt;
 		tabs.push({
 			id,
 			url: page.url(),
-			title
+			title,
+			...createdAt !== void 0 ? { createdAt } : {}
 		});
 	}
 	return tabs;
@@ -2851,6 +3051,7 @@ async function closeBrowser() {
 		state.browser = null;
 		state.context = null;
 		state.pages = /* @__PURE__ */ new Map();
+		state.tabMeta?.clear();
 		state.activeId = null;
 		state.counter = 0;
 		try {
@@ -2893,15 +3094,38 @@ async function openTool(configOrArgs, maybeArgs) {
 	const isSingleArg = maybeArgs === void 0;
 	const config = isSingleArg && typeof configOrArgs?.url === "string" ? {} : configOrArgs;
 	const args = isSingleArg ? configOrArgs : maybeArgs;
-	const page = await getPage(config ?? {});
-	await page.goto(String(args.url), {
-		waitUntil: args.waitUntil ?? "domcontentloaded",
-		timeout: args.timeoutMs ?? config?.timeoutMs
+	const state = stateOf();
+	let recovered;
+	const freshPage = async () => {
+		const p = await newPage(config ?? {});
+		registerTabPage(state, p);
+		recovered = "new-tab";
+		return p;
+	};
+	let page = await getPage(config ?? {}).catch(async (e) => {
+		if (e?.code === "activeTabClosed") return freshPage();
+		throw e;
 	});
+	if (page.isClosed()) page = await freshPage();
+	try {
+		await page.goto(String(args.url), {
+			waitUntil: args.waitUntil ?? "domcontentloaded",
+			timeout: args.timeoutMs ?? config?.timeoutMs
+		});
+	} catch (e) {
+		if (recovered === void 0 && /has been closed/.test(String(e?.message ?? e))) {
+			page = await freshPage();
+			await page.goto(String(args.url), {
+				waitUntil: args.waitUntil ?? "domcontentloaded",
+				timeout: args.timeoutMs ?? config?.timeoutMs
+			});
+		} else throw e;
+	}
 	return {
 		url: page.url(),
 		title: await page.title(),
-		status: "ok"
+		status: "ok",
+		...recovered !== void 0 ? { recovered } : {}
 	};
 }
 async function backTool(config) {
@@ -3057,9 +3281,7 @@ async function tabsTool(config, args) {
 		};
 		case "new": {
 			const page = await newPage(config);
-			const id = state.counter++;
-			state.pages.set(id, page);
-			state.activeId = id;
+			const id = registerTabPage(state, page);
 			if (args.url) await page.goto(String(args.url), {
 				waitUntil: args.waitUntil ?? "domcontentloaded",
 				timeout: args.timeoutMs ?? config.timeoutMs
@@ -3089,12 +3311,10 @@ async function tabsTool(config, args) {
 			const id = resolveTabId(args);
 			const page = state.pages.get(id);
 			if (page === void 0) throw new Error(`no tab with id ${id}`);
-			await page.close().catch(() => {});
 			state.pages.delete(id);
-			if (state.activeId === id) {
-				const next = state.pages.keys().next().value;
-				state.activeId = next === void 0 ? null : next;
-			}
+			state.tabMeta?.delete(id);
+			if (state.activeId === id) state.activeId = null;
+			await page.close().catch(() => {});
 			return {
 				action,
 				activeId: state.activeId ?? -1,
@@ -3609,7 +3829,7 @@ const removeSomOverlay = () => {
 	document.getElementById("__dsh_som_overlay__")?.remove();
 };
 const injectSomOverlay = injectWalker((payload, w) => {
-	const { INTERACTIVE, roleOf, nameOf, cssPath, isVisible, isElementInViewport, deepChildren } = w;
+	const { INTERACTIVE, roleOf, nameOf, cssPath, isVisible, isElementInViewport, deepChildren, isProbablyClickable } = w;
 	const marks = [];
 	const snapScroll = {
 		x: window.scrollX,
@@ -3625,6 +3845,7 @@ const injectSomOverlay = injectWalker((payload, w) => {
 			candidates.push(el);
 			return;
 		}
+		if (isVisible(el) && isElementInViewport(el, 0) && isProbablyClickable(el)) candidates.push(el);
 		for (const c of deepChildren(el)) if (c.tagName !== "SCRIPT" && c.tagName !== "STYLE") collect(c);
 	}
 	if (document.body) collect(document.body);
@@ -3635,8 +3856,9 @@ const injectSomOverlay = injectWalker((payload, w) => {
 		const rect = el.getBoundingClientRect();
 		if (rect.width < 8 || rect.height < 8) continue;
 		count += 1;
-		const role = roleOf(el);
-		const name = nameOf(el, role);
+		const realRole = roleOf(el);
+		const role = realRole === "" ? "clickable" : realRole;
+		const name = realRole === "" ? (el.innerText || el.textContent || "").trim().replace(/\s+/g, " ").slice(0, 60) : nameOf(el, realRole);
 		const x = Math.max(0, rect.left);
 		const y = Math.max(0, rect.top);
 		const g = document.createElementNS("http://www.w3.org/2000/svg", "g");
@@ -3953,6 +4175,22 @@ async function humanType(page, text, options = {}) {
 }
 //#endregion
 //#region lib/types/browser/tools/interaction.js
+/** 多命中可见化:解析层 matchedCount/visibleCount 透传到成功返回,>1 附操作指引。
+* 防同名字段静默打进被遮罩的背景元素(背景表单 + Modal 同名字段场景)。 */
+function ambiguityFields(res) {
+	const matched = res.matchedCount;
+	if (matched === void 0) return {};
+	return {
+		matchedCount: matched,
+		...res.visibleCount !== void 0 ? { visibleCount: res.visibleCount } : {},
+		...matched > 1 ? { hint: `命中 ${matched} 个元素(可见 ${res.visibleCount ?? 0}),已操作第 1 个;建议用 scope 限定或 browser_snapshot 取 ref 消歧` } : {}
+	};
+}
+/** strict 模式(对齐 Playwright strict):多命中直接拒绝,要求定位唯一。 */
+function strictReject(args, res) {
+	if (args.strict !== true || (res.matchedCount ?? 0) <= 1) return null;
+	return /* @__PURE__ */ new Error(`strict 模式拒绝多命中: 命中 ${res.matchedCount} 个元素(可见 ${res.visibleCount ?? 0}),要求定位唯一;请用 scope 限定、更特异的 selector 或 browser_snapshot 取 ref`);
+}
 function isBotSensitiveUrl(url) {
 	if (!url) return false;
 	return /login|signin|auth|captcha|challenge|turnstile|security|waf/i.test(url);
@@ -3982,6 +4220,8 @@ async function clickTool(config, args, exec) {
 	}
 	let target = targetRes.locator;
 	const label = String(args.ref ?? args.selector ?? args.mark ?? args.what ?? "");
+	const strictErr = strictReject(args, targetRes);
+	if (strictErr !== null) throw strictErr;
 	target = await liftTargetIfHiddenInput(target);
 	const wantEffect = args.effect === true;
 	let urlBefore = "";
@@ -4074,17 +4314,28 @@ async function clickTool(config, args, exec) {
 			clicked: String(args.ref ?? args.selector ?? args.mark ?? args.what ?? (args.row ? `row: ${args.row}` : "target")),
 			effect,
 			...quiet ? { effectHint: "点击后未观察到任何 DOM/URL/网络变化,可能未生效(被遮挡/事件被吞/前置条件未满足);建议 browser_snapshot 核实或换目标" } : {},
+			...ambiguityFields(targetRes),
+			...targetRes.viaBridge === true ? { viaBridge: true } : {},
 			...await pageIdentity(page)
 		};
 	}
 	return {
 		clicked: String(args.ref ?? args.selector ?? args.mark ?? args.what ?? (args.row ? `row: ${args.row}` : "target")),
+		...ambiguityFields(targetRes),
+		...targetRes.viaBridge === true ? { viaBridge: true } : {},
 		...await pageIdentity(page)
 	};
 }
 async function typeTool(config, args) {
 	const page = await getPage(config);
-	const target = await targetLocator(page, args);
+	const targetRes = await resolveTargetLocator(page, args, { preferredRoles: [
+		"textbox",
+		"searchbox",
+		"spinbutton"
+	] });
+	const target = targetRes.locator;
+	const strictErr = strictReject(args, targetRes);
+	if (strictErr !== null) throw strictErr;
 	const text = String(args.text ?? "");
 	const isHuman = args.humanize === true || args.humanize === void 0 && (config.humanize === true || config.humanize === "auto" && isBotSensitiveUrl(page.url()));
 	if (args.editor === true) {
@@ -4093,6 +4344,7 @@ async function typeTool(config, args) {
 			typed: true,
 			editor: true,
 			selector,
+			...ambiguityFields(targetRes),
 			...await pageIdentity(page)
 		};
 	}
@@ -4102,9 +4354,11 @@ async function typeTool(config, args) {
 			await humanType(page, text, { speed: config.humanizeSpeed });
 		} else await target.fill(text, { timeout: args.timeoutMs ?? config.timeoutMs });
 	} else {
+		const ambiguous = args.strict === true || (targetRes.matchedCount ?? 0) > 1;
 		try {
 			await target.click({ timeout: Math.min(args.timeoutMs ?? config.timeoutMs, 5e3) });
-		} catch {
+		} catch (e) {
+			if (ambiguous) throw new Error(`type 定位目标存在歧义(命中 ${targetRes.matchedCount ?? "?"} 个元素)且首个不可交互,已中止;请用 scope 限定或 browser_snapshot 取 ref 消歧;原始错误: ${e instanceof Error ? e.message : String(e)}`);
 			await target.click({
 				timeout: 2e3,
 				force: true
@@ -4118,6 +4372,7 @@ async function typeTool(config, args) {
 		typed: true,
 		selector: String(args.ref ?? args.selector),
 		submit: args.submit === true,
+		...ambiguityFields(targetRes),
 		...await pageIdentity(page)
 	};
 }
@@ -4144,8 +4399,18 @@ async function pressTool(config, args) {
 			} else warning = "检测到页面存在活动弹窗 [modal: closeOnEsc]，按全局 Escape 可能导致弹窗及其表单被关闭。若需关闭指定元素请传 selector/ref。";
 		}
 	}
-	if (args.selector !== void 0 || args.ref !== void 0 || typeof args.what === "string" && args.what.trim() !== "") await (await targetLocator(page, args)).press(key, { timeout: args.timeoutMs ?? config.timeoutMs });
-	else await page.keyboard.press(key);
+	if (args.selector !== void 0 || args.ref !== void 0 || typeof args.what === "string" && args.what.trim() !== "") {
+		const targetRes = await resolveTargetLocator(page, args);
+		const strictErr = strictReject(args, targetRes);
+		if (strictErr !== null) throw strictErr;
+		await targetRes.locator.press(key, { timeout: args.timeoutMs ?? config.timeoutMs });
+		return {
+			pressed: key,
+			...warning ? { warning } : {},
+			...ambiguityFields(targetRes),
+			...await pageIdentity(page)
+		};
+	} else await page.keyboard.press(key);
 	return {
 		pressed: key,
 		...warning ? { warning } : {},
@@ -4158,8 +4423,15 @@ async function pressTool(config, args) {
 */
 async function selectTool(config, args) {
 	const page = await getPage(config);
-	const target = await targetLocator(page, args);
-	const label = String(args.ref ?? args.selector);
+	const targetRes = await resolveTargetLocator(page, args, { preferredRoles: [
+		"combobox",
+		"select",
+		"listbox"
+	] });
+	const target = targetRes.locator;
+	const strictErr = strictReject(args, targetRes);
+	if (strictErr !== null) throw strictErr;
+	const label = String(args.ref ?? args.selector ?? args.what ?? "");
 	const want = String(args.option ?? "");
 	if (!want) throw new Error("select 需要 option(选项文本)");
 	return {
@@ -4173,6 +4445,7 @@ async function selectTool(config, args) {
 			clear: args.clear === true
 		})).selected,
 		selector: label,
+		...ambiguityFields(targetRes),
 		...await pageIdentity(page)
 	};
 }
@@ -4482,7 +4755,53 @@ async function checkOnce(page, cond) {
 			detail: `eval 执行失败: ${e instanceof Error ? e.message : String(e)}`
 		};
 	}
-	throw new Error("条件无效: 需要 selector/url/text/count/eval 之一");
+	if (cond.bridge !== void 0 && typeof cond.bridge === "object") {
+		const spec = cond.bridge;
+		const method = String(spec.method ?? "");
+		const trunc = (v) => {
+			const s = JSON.stringify(v) ?? String(v);
+			return s.length > 500 ? `${s.slice(0, 500)}…(截断)` : s;
+		};
+		if (method === "") return {
+			ok: false,
+			detail: "bridge 条件需要 method(__DSH_BRIDGE__ 方法名)"
+		};
+		try {
+			const value = await page.evaluate(async (payload) => {
+				const bridge = window.__DSH_BRIDGE__;
+				if (bridge === void 0 || bridge === null) throw new Error("NO_BRIDGE:页面无 __DSH_BRIDGE__(未接入 vite-plugin-dsh-bridge?)");
+				if (typeof bridge[payload.method] !== "function") throw new Error(`NO_BRIDGE:__DSH_BRIDGE__ 无方法 ${payload.method}`);
+				return await bridge[payload.method](...payload.args);
+			}, {
+				method,
+				args: Array.isArray(spec.args) ? spec.args : []
+			});
+			const actual = JSON.parse(JSON.stringify(value ?? null));
+			if (spec.expectContains !== void 0) return (typeof actual === "string" ? actual : JSON.stringify(actual)).includes(String(spec.expectContains)) ? { ok: true } : {
+				ok: false,
+				detail: `[bridge] ${method}() 结果不含 "${spec.expectContains}"(实际: ${trunc(actual)})`
+			};
+			if (spec.expect !== void 0) return JSON.stringify(actual) === JSON.stringify(spec.expect) ? { ok: true } : {
+				ok: false,
+				detail: `[bridge] ${method}() = ${trunc(actual)} ≠ 期望 ${trunc(spec.expect)}`
+			};
+			return actual ? { ok: true } : {
+				ok: false,
+				detail: `[bridge] ${method}() 返回假值: ${trunc(actual)}`
+			};
+		} catch (e) {
+			const msg = e instanceof Error ? e.message : String(e);
+			if (msg.startsWith("NO_BRIDGE:")) return {
+				ok: false,
+				detail: `[bridge] ${msg.slice(10)}`
+			};
+			return {
+				ok: false,
+				detail: `[bridge] ${method}() 执行失败: ${msg}`
+			};
+		}
+	}
+	throw new Error("条件无效: 需要 selector/url/text/count/eval/bridge 之一");
 }
 /** 轮询等待条件成立(intervalMs 步进),返回最后一次检查结果。 */
 async function pollCondition(page, cond, timeoutMs, intervalMs = 500) {
@@ -4668,12 +4987,28 @@ async function visualAssert(config, visual, page, exec) {
 	};
 }
 function matchNetwork(entry, f) {
-	if (f.urlSubstr && !entry.url.includes(String(f.urlSubstr))) return false;
+	if (f.urlSubstr && !entry.url.toLowerCase().includes(String(f.urlSubstr).toLowerCase())) return false;
 	if (f.method && entry.method.toUpperCase() !== String(f.method).toUpperCase()) return false;
 	if (f.status !== void 0 && Number(f.status) !== entry.status) return false;
 	if (f.failedOnly === true && !entry.failed && (entry.status === void 0 || entry.status < 400)) return false;
 	return true;
 }
+/** urlSubstr 零命中时的相近 URL 候选(top5,去重,LCS 打分),与 what 未命中的
+* 候选体验对齐——把"子串写错"与"接口没调"区分开。 */
+function urlSuggestions(entries, substr) {
+	const min = substr.trim().length <= 3 ? 1 : 2;
+	const seen = /* @__PURE__ */ new Set();
+	const scored = [];
+	for (const e of entries) {
+		if (seen.has(e.url)) continue;
+		seen.add(e.url);
+		scored.push({
+			url: e.url,
+			score: lcsScore(substr, e.url)
+		});
+	}
+	return scored.filter((s) => s.score >= min).sort((a, b) => b.score - a.score).slice(0, 5).map((s) => s.url);
+}
 /** 网络记录查询:list / failed / wait / clear。兼容 (args) 与 (config, args) 两种调用签名。 */
 async function networkTool(configOrArgs, maybeArgs) {
 	const args = (maybeArgs !== void 0 ? maybeArgs : configOrArgs) ?? {};
@@ -4748,8 +5083,20 @@ async function networkTool(configOrArgs, maybeArgs) {
 			byStatus: b.byStatus
 		})).sort((a, b) => b.total - a.total) };
 	}
-	if (action === "failed") return { failed: list };
-	if (action === "list") return { entries: list };
+	if (action === "failed") {
+		const suggestions = list.length === 0 && args.urlSubstr ? urlSuggestions(entries, String(args.urlSubstr)) : [];
+		return suggestions.length > 0 ? {
+			failed: list,
+			suggestions
+		} : { failed: list };
+	}
+	if (action === "list") {
+		const suggestions = list.length === 0 && args.urlSubstr ? urlSuggestions(entries, String(args.urlSubstr)) : [];
+		return suggestions.length > 0 ? {
+			entries: list,
+			suggestions
+		} : { entries: list };
+	}
 	throw new Error(`unknown network action: ${action}`);
 }
 //#endregion
@@ -5036,25 +5383,187 @@ function previewHighlight(page, selector, label) {
 	}).catch(() => {});
 }
 /**
+* 常见认证/登录相关的 URL 特征正则，用于防止跳板页提前误判。
+*/
+const AUTH_URL_PATTERN = /login|signin|sign-in|oauth|passport|sso|cas|challenge|captcha|verify|auth\b/i;
+/**
+* 等待人工登录底层执行(独立导出供测试注入 fake page)。
+* 协同机制:
+* 1. 挂起等待期间置入 instruction 至实时画面面板(setPauseInstruction),结束后统一清理;
+* 2. 存活标签感知:感知 context 内所有存活页面,原标签关闭时自动迁移至存活页,新标签出现时通知外层注册;
+* 3. 稳态判定:
+*    - 显式 successSelector / successUrl 优先;
+*    - 缺省时,检测 URL 离开登录页(非 AUTH_URL_PATTERN)、登录密码框消除、或 SPA 内容签名稳态变化,防范跳板页误判与 SPA 弹窗漏判。
+*/
+async function runWaitForLoginOnPage(initialPage, args, onNewPageDetected) {
+	const instruction = typeof args.instruction === "string" && args.instruction.trim() ? args.instruction.trim() : "请在浏览器窗口中完成登录";
+	const timeoutMs = Math.min(Math.max(Number(args.timeoutMs ?? 12e4) || 12e4, 1e3), 6e5);
+	const pollIntervalMs = Math.min(Math.max(Number(args.pollIntervalMs ?? 2e3) || 2e3, 100), 5e3);
+	let currentPage = initialPage;
+	let startUrl = "";
+	try {
+		startUrl = initialPage.url();
+	} catch {}
+	const checkHasPassword = async (p) => {
+		try {
+			return await p.evaluate(() => !!document.querySelector("input[type=\"password\"]"));
+		} catch {
+			return false;
+		}
+	};
+	const getPageSig = async (p) => {
+		try {
+			return await p.evaluate(() => {
+				const body = document.body;
+				return `${location.href}|${body ? body.innerText.length : 0}|${document.querySelectorAll("input,button,a").length}`;
+			});
+		} catch {
+			try {
+				return p.url();
+			} catch {
+				return "";
+			}
+		}
+	};
+	const startHasPassword = await checkHasPassword(initialPage);
+	const startSig = args.successSelector || args.successUrl ? "" : await getPageSig(initialPage);
+	const startedAt = Date.now();
+	let loggedIn = false;
+	let detail = `等待登录超时(${timeoutMs}ms)`;
+	setPauseInstruction(instruction);
+	try {
+		const deadline = startedAt + timeoutMs;
+		while (Date.now() < deadline) {
+			let candidatePages = [];
+			try {
+				const context = typeof currentPage.context === "function" ? currentPage.context() : null;
+				if (context && typeof context.pages === "function") candidatePages = context.pages().filter((p) => {
+					try {
+						return !p.isClosed();
+					} catch {
+						return false;
+					}
+				});
+			} catch {}
+			let isCurrentClosed = false;
+			try {
+				isCurrentClosed = currentPage.isClosed();
+			} catch {
+				isCurrentClosed = true;
+			}
+			if (candidatePages.length > 0) {
+				for (const p of candidatePages) if (p !== currentPage && onNewPageDetected) onNewPageDetected(p);
+				if (isCurrentClosed) {
+					currentPage = candidatePages[candidatePages.length - 1];
+					isCurrentClosed = false;
+				}
+			}
+			try {
+				if (args.successSelector) {
+					const targets = candidatePages.length > 0 ? candidatePages : isCurrentClosed ? [] : [currentPage];
+					for (const p of targets) try {
+						if (await p.locator(String(args.successSelector)).first().isVisible()) {
+							loggedIn = true;
+							currentPage = p;
+							detail = `命中 successSelector: ${args.successSelector}`;
+							break;
+						}
+					} catch {}
+				} else if (args.successUrl) {
+					const re = new RegExp(String(args.successUrl));
+					const targets = candidatePages.length > 0 ? candidatePages : isCurrentClosed ? [] : [currentPage];
+					for (const p of targets) try {
+						const u = p.url();
+						if (re.test(u)) {
+							loggedIn = true;
+							currentPage = p;
+							detail = `命中 successUrl: ${args.successUrl}`;
+							break;
+						}
+					} catch {}
+				} else {
+					const target = !isCurrentClosed ? currentPage : candidatePages[0];
+					if (target) {
+						let curUrl = "";
+						try {
+							curUrl = target.url();
+						} catch {}
+						if (curUrl && curUrl !== "about:blank") {
+							if (curUrl !== startUrl) {
+								if (!AUTH_URL_PATTERN.test(curUrl)) {
+									loggedIn = true;
+									currentPage = target;
+									detail = `URL 离开登录页跳转至 ${curUrl}`;
+								} else {
+									const hasPwd = await checkHasPassword(target);
+									if (startHasPassword && !hasPwd) {
+										loggedIn = true;
+										currentPage = target;
+										detail = `登录密码输入框已消除，页面跳转至 ${curUrl}`;
+									}
+								}
+							} else {
+								const hasPwd = await checkHasPassword(target);
+								if (startHasPassword && !hasPwd) {
+									loggedIn = true;
+									currentPage = target;
+									detail = "登录密码输入框已消除(SPA 登录完成)";
+								} else if (await getPageSig(target) !== startSig && (!startHasPassword || !hasPwd)) {
+									loggedIn = true;
+									currentPage = target;
+									detail = "页面内容签名变更(SPA 登录完成)";
+								}
+							}
+						}
+					}
+				}
+			} catch (e) {
+				detail = `检查登录状态出错: ${e instanceof Error ? e.message : String(e)}`;
+			}
+			if (loggedIn) break;
+			try {
+				await currentPage.waitForTimeout(pollIntervalMs);
+			} catch {
+				await sleep$1(pollIntervalMs);
+			}
+		}
+	} finally {
+		clearPauseInstruction();
+	}
+	return {
+		loggedIn,
+		waitedMs: Date.now() - startedAt,
+		detail,
+		targetPage: currentPage
+	};
+}
+/**
 * 等待人工登录完成(配合 headless:false 使用):agent 打开登录页后调用本工具,
-* 提示用户在浏览器窗口中完成登录(输入/扫码/双因素)。基于通用条件引擎:
-* successSelector / successUrl 指定完成条件,两者都不给则以 URL 跳转视为完成。
-* 超时返回 loggedIn:false(不抛错)。
+* 提示用户在浏览器窗口中完成登录(输入/扫码/双因素)。支持 instruction 提示语
+* 与右下角实时画面面板联动显示横幅,支持多标签感知与 SPA 签名自适应判定。
+* 超时返回 loggedIn:false(附 waitedMs 与 detail,不抛错)。
 */
 async function waitForLoginTool(config, args) {
 	const page = await getPage(config);
-	const startUrl = page.url();
-	let condition;
-	if (args.successSelector) condition = {
-		selector: String(args.successSelector),
-		state: "visible"
-	};
-	else if (args.successUrl) condition = { url: String(args.successUrl) };
-	else condition = { eval: `location.href !== ${JSON.stringify(startUrl)} && location.href !== "about:blank"` };
-	const timeoutMs = Math.min(Math.max(Number(args.timeoutMs ?? 12e4) || 12e4, 5e3), 6e5);
+	const state = stateOf();
+	const result = await runWaitForLoginOnPage(page, args, (newPage) => {
+		if (![...state.pages.values()].includes(newPage)) {
+			attachPage(newPage, profileConfig(config, currentProfile));
+			registerTabPage(state, newPage);
+		}
+	});
+	if (result.targetPage !== page) {
+		for (const [id, p] of state.pages) if (p === result.targetPage) {
+			state.activeId = id;
+			break;
+		}
+	}
+	const identity = await pageIdentity(result.targetPage);
 	return {
-		loggedIn: (await pollCondition(page, condition, timeoutMs, 2e3)).ok,
-		...await pageIdentity(page)
+		loggedIn: result.loggedIn,
+		waitedMs: result.waitedMs,
+		detail: result.detail,
+		...identity
 	};
 }
 /**
@@ -5996,7 +6505,7 @@ function compileToPlaywrightSpec(steps, options = {}) {
 				else if (args.selector) {
 					const state = args.state || "visible";
 					lines.push(`    await page.locator(${JSON.stringify(args.selector)}).waitFor({ state: ${JSON.stringify(state)} });`);
-				}
+				} else if (args.condition?.bridge !== void 0 || args.bridge !== void 0) lines.push(`    // bridge 条件请在接入 vite-plugin-dsh-bridge 的环境手动断言: await __DSH_BRIDGE__.<method>(...)`);
 				break;
 			case "browser_assert": {
 				const sel = args.selector || "body";
@@ -6004,6 +6513,9 @@ function compileToPlaywrightSpec(steps, options = {}) {
 				else if (args.visible !== void 0) {
 					if (args.visible) lines.push(`    await expect(page.locator(${JSON.stringify(sel)})).toBeVisible();`);
 					else lines.push(`    await expect(page.locator(${JSON.stringify(sel)})).toBeHidden();`);
+				} else if (args.condition?.bridge !== void 0 || args.bridge !== void 0) {
+					const bridge = args.condition?.bridge ?? args.bridge;
+					lines.push(`    // bridge 断言请在接入 vite-plugin-dsh-bridge 的环境手动执行: const v = await __DSH_BRIDGE__.${String(bridge?.method ?? "method")}(); expect(v).toBeTruthy();`);
 				}
 				break;
 			}
@@ -6658,7 +7170,7 @@ function getNavigationTools(config, timeout, stepImpls) {
 	return [
 		definePlainTool({
 			name: "browser_open",
-			description: "在共享浏览器中打开一个 URL。之后可用 browser_snapshot 读取页面内容,用 browser_click / browser_type / browser_eval 操作页面,用 browser_screenshot 截图。",
+			description: "在共享浏览器中打开一个 URL。活动标签已关闭或崩溃时自动新建标签重试(返回标 recovered: 'new-tab')。之后可用 browser_snapshot 读取页面内容,用 browser_click / browser_type / browser_eval 操作页面,用 browser_screenshot 截图。",
 			parameters: {
 				type: "object",
 				properties: {
@@ -6689,7 +7201,11 @@ function getNavigationTools(config, timeout, stepImpls) {
 				properties: {
 					url: { type: "string" },
 					title: { type: "string" },
-					status: { type: "string" }
+					status: { type: "string" },
+					recovered: {
+						type: "string",
+						description: "活动标签已死自动换新页时为 'new-tab'。"
+					}
 				},
 				required: [
 					"url",
@@ -6798,7 +7314,7 @@ function getNavigationTools(config, timeout, stepImpls) {
 		}),
 		definePlainTool({
 			name: "browser_tabs",
-			description: "管理浏览器多标签页:list 列出所有标签,new 新建(可选带 url),switch 按 id 或 index 切换,close 关闭指定标签。id 来自 list 结果。",
+			description: "管理浏览器多标签页:list 列出所有标签(每项含 createdAt 注册时间;已关闭的僵尸页自动摘除),new 新建(可选带 url),switch 按 id 或 index 切换,close 关闭指定标签。id 来自 list 结果。",
 			parameters: {
 				type: "object",
 				properties: {
@@ -6975,21 +7491,21 @@ function getInteractionTools(config, timeout, stepImpls) {
 	return [
 		definePlainTool({
 			name: "browser_click",
-			description: "点击页面元素:selector(CSS)、ref(来自 browser_snapshot mode:'aria')、what(意图描述,如 '登录'/'提交订单',页内打分匹配并自动注册 ref)或 mark(SoM 标徽编号,看图定位)四选一。也可通过 row(如 'TASK-1002') 与 action(如 '编辑') 直接定位表格中某行操作按钮。what 零命中时报错并附最相近候选与 SoM 标徽截图。",
+			description: "点击页面元素:selector(CSS)、ref(来自 browser_snapshot mode:'aria')、what(意图描述,如 '登录'/'提交订单',页内打分匹配并自动注册 ref)或 mark(SoM 标徽编号,看图定位)四选一——同时传多个会直接报参数错误;容器内语义定位用 what + scope。也可通过 row(如 'TASK-1002') 与 action(如 '编辑') 直接定位表格中某行操作按钮(row 可组合 selector 限定行内目标)。what 零命中时报错并附最相近候选与 SoM 标徽截图。",
 			parameters: {
 				type: "object",
 				properties: {
 					selector: {
 						type: "string",
-						description: "CSS 选择器。"
+						description: "CSS 选择器(与 ref/mark/what 互斥)。"
 					},
 					ref: {
 						type: "string",
-						description: "aria 快照的 ref(如 'e3');导航后失效。"
+						description: "aria 快照的 ref(如 'e3');导航后失效。与 selector/mark/what 互斥。"
 					},
 					what: {
 						type: "string",
-						description: "意图描述(元素名称/文本,如 '登录'):页内打分语义定位,免快照直达;零命中返回最相近候选。"
+						description: "意图描述(元素名称/文本,如 '登录'):页内打分语义定位,免快照直达;零命中返回最相近候选。与 selector/ref/mark 互斥;容器内定位配合 scope。"
 					},
 					scope: {
 						type: "string",
@@ -6997,11 +7513,11 @@ function getInteractionTools(config, timeout, stepImpls) {
 					},
 					mark: {
 						type: "integer",
-						description: "SoM 标徽编号(browser_screenshot { som: true } 返回 somMarks 的 id);多模态看图定位的落点,导航后失效。"
+						description: "SoM 标徽编号(browser_screenshot { som: true } 返回 somMarks 的 id);多模态看图定位的落点,导航后失效。与 selector/ref/what 互斥。"
 					},
 					row: {
 						type: "string",
-						description: "表格行文本标识，如 'TASK-1002'，用于行级定向操作。"
+						description: "表格行文本标识，如 'TASK-1002'，用于行级定向操作(可组合 selector 限定行内目标,不与 what/ref/mark 同用)。"
 					},
 					action: {
 						type: "string",
@@ -7019,6 +7535,10 @@ function getInteractionTools(config, timeout, stepImpls) {
 						type: "boolean",
 						description: "点击效果验证:收集点击后的 DOM 变化摘要/URL 变化/新增网络请求;what 多候选首击无动静时自动换次候选。"
 					},
+					strict: {
+						type: "boolean",
+						description: "多命中即抛错(对齐 Playwright strict),要求定位唯一;默认 false 操作第 1 个并在返回中提示命中数。"
+					},
 					timeoutMs: { type: "integer" }
 				},
 				additionalProperties: false
@@ -7031,7 +7551,23 @@ function getInteractionTools(config, timeout, stepImpls) {
 					url: { type: "string" },
 					title: { type: "string" },
 					effect: { type: "object" },
-					effectHint: { type: "string" }
+					effectHint: { type: "string" },
+					matchedCount: {
+						type: "integer",
+						description: "选择器命中的元素总数(多命中歧义可见化)。"
+					},
+					visibleCount: {
+						type: "integer",
+						description: "命中元素中的可见数量。"
+					},
+					hint: {
+						type: "string",
+						description: "matchedCount>1 时的消歧指引。"
+					},
+					viaBridge: {
+						type: "boolean",
+						description: "what 未命中时经页面 __DSH_BRIDGE__(vite-plugin-dsh-bridge)兜底命中。"
+					}
 				},
 				required: [
 					"clicked",
@@ -7045,18 +7581,21 @@ function getInteractionTools(config, timeout, stepImpls) {
 		}),
 		definePlainTool({
 			name: "browser_type",
-			description: "向输入框输入文本:selector(CSS)、ref 或 what(意图描述,如 '用户名'/'搜索')定位目标。clear=true 时先清空再输入(推荐用于表单);submit=true 时输入后按回车;editor=true 时适配 Monaco/CodeMirror/富文本编辑器。",
+			description: "向输入框输入文本:selector(CSS)、ref 或 what(意图描述,如 '用户名'/'搜索')三选一定位目标(同时传多个会报参数错误;容器内定位用 what + scope)。clear=true 时先清空再输入(推荐用于表单);submit=true 时输入后按回车;editor=true 时适配 Monaco/CodeMirror/富文本编辑器。",
 			parameters: {
 				type: "object",
 				properties: {
-					selector: { type: "string" },
+					selector: {
+						type: "string",
+						description: "CSS 选择器(与 ref/what 互斥)。"
+					},
 					ref: {
 						type: "string",
-						description: "aria 快照的 ref(如 'e2')。"
+						description: "aria 快照的 ref(如 'e2')。与 selector/what 互斥。"
 					},
 					what: {
 						type: "string",
-						description: "意图描述(元素名称/label/placeholder,如 '用户名'):页内打分语义定位。"
+						description: "意图描述(元素名称/label/placeholder,如 '用户名'):页内打分语义定位。与 selector/ref 互斥;容器内定位配合 scope。"
 					},
 					scope: {
 						type: "string",
@@ -7073,6 +7612,10 @@ function getInteractionTools(config, timeout, stepImpls) {
 						type: "boolean",
 						description: "使用高斯间隔拟人化逐字输入。"
 					},
+					strict: {
+						type: "boolean",
+						description: "多命中即抛错(对齐 Playwright strict);多命中或 strict 时不再 force 降级点击,遮罩拦截会直接暴露。"
+					},
 					delayMs: { type: "integer" },
 					timeoutMs: { type: "integer" }
 				},
@@ -7087,7 +7630,19 @@ function getInteractionTools(config, timeout, stepImpls) {
 					selector: { type: "string" },
 					submit: { type: "boolean" },
 					url: { type: "string" },
-					title: { type: "string" }
+					title: { type: "string" },
+					matchedCount: {
+						type: "integer",
+						description: "选择器命中的元素总数(多命中歧义可见化)。"
+					},
+					visibleCount: {
+						type: "integer",
+						description: "命中元素中的可见数量。"
+					},
+					hint: {
+						type: "string",
+						description: "matchedCount>1 时的消歧指引。"
+					}
 				},
 				required: [
 					"typed",
@@ -7103,7 +7658,7 @@ function getInteractionTools(config, timeout, stepImpls) {
 		}),
 		definePlainTool({
 			name: "browser_press",
-			description: "按键:有 selector 或 ref 时先聚焦该元素再按键(如 'Enter'、'Tab'、'Escape'、'Control+a'),否则在页面级按键。",
+			description: "按键:有 selector、ref 或 what(三选一,互斥)时先聚焦该元素再按键(如 'Enter'、'Tab'、'Escape'、'Control+a'),否则在页面级按键。",
 			parameters: {
 				type: "object",
 				properties: {
@@ -7111,14 +7666,21 @@ function getInteractionTools(config, timeout, stepImpls) {
 						type: "string",
 						description: "按键名(Playwright 键盘键名)。"
 					},
-					selector: { type: "string" },
+					selector: {
+						type: "string",
+						description: "CSS 选择器(与 ref/what 互斥)。"
+					},
 					ref: {
 						type: "string",
-						description: "aria 快照的 ref。"
+						description: "aria 快照的 ref。与 selector/what 互斥。"
 					},
 					what: {
 						type: "string",
-						description: "意图描述:先聚焦该元素再按键(页内打分语义定位)。"
+						description: "意图描述:先聚焦该元素再按键(页内打分语义定位)。与 selector/ref 互斥。"
+					},
+					strict: {
+						type: "boolean",
+						description: "多命中即抛错(对齐 Playwright strict)。"
 					},
 					timeoutMs: { type: "integer" }
 				},
@@ -7131,7 +7693,20 @@ function getInteractionTools(config, timeout, stepImpls) {
 				properties: {
 					pressed: { type: "string" },
 					url: { type: "string" },
-					title: { type: "string" }
+					title: { type: "string" },
+					warning: { type: "string" },
+					matchedCount: {
+						type: "integer",
+						description: "选择器命中的元素总数(多命中歧义可见化)。"
+					},
+					visibleCount: {
+						type: "integer",
+						description: "命中元素中的可见数量。"
+					},
+					hint: {
+						type: "string",
+						description: "matchedCount>1 时的消歧指引。"
+					}
 				},
 				required: [
 					"pressed",
@@ -7145,21 +7720,25 @@ function getInteractionTools(config, timeout, stepImpls) {
 		}),
 		definePlainTool({
 			name: "browser_select",
-			description: "下拉选择原语:原生 <select> 与组件库下拉(antd / element-plus / ARIA listbox)通用。selector 或 ref 指向下拉触发框,option 为选项文本(默认包含匹配,exact=true 精确)。多选下拉传 clear:true 可在选择前先清空旧标签实现替换语义。找不到选项时报错并列出可见选项,无需再 browser_eval 探查。",
+			description: "下拉选择原语:原生 <select> 与组件库下拉(antd / element-plus / ARIA listbox)通用。selector、ref 或 what(三选一,互斥)指向下拉触发框,option 为选项文本(默认包含匹配,exact=true 精确)。多选下拉传 clear:true 可在选择前先清空旧标签实现替换语义。找不到选项时报错并列出可见选项,无需再 browser_eval 探查。",
 			parameters: {
 				type: "object",
 				properties: {
 					selector: {
 						type: "string",
-						description: "下拉触发框的 CSS 选择器(如 #rc_select_1)。"
+						description: "下拉触发框的 CSS 选择器(如 #rc_select_1);与 ref/what 互斥。"
 					},
 					ref: {
 						type: "string",
-						description: "aria 快照的 ref。"
+						description: "aria 快照的 ref。与 selector/what 互斥。"
 					},
 					what: {
 						type: "string",
-						description: "意图描述(下拉的 label/名称,如 '所属部门'):页内打分语义定位触发框。"
+						description: "意图描述(下拉的 label/名称,如 '所属部门'):页内打分语义定位触发框。与 selector/ref 互斥;容器内定位配合 scope。"
+					},
+					scope: {
+						type: "string",
+						description: "配合 what 限定扫描范围的容器选择器。"
 					},
 					option: {
 						type: "string",
@@ -7173,6 +7752,10 @@ function getInteractionTools(config, timeout, stepImpls) {
 						type: "boolean",
 						description: "是否在选择前先清空已有选中项(对于多选下拉，替换而非叠加旧选项)。"
 					},
+					strict: {
+						type: "boolean",
+						description: "多命中即抛错(对齐 Playwright strict)。"
+					},
 					timeoutMs: { type: "integer" }
 				},
 				required: ["option"],
@@ -7185,7 +7768,19 @@ function getInteractionTools(config, timeout, stepImpls) {
 					selected: { type: "string" },
 					selector: { type: "string" },
 					url: { type: "string" },
-					title: { type: "string" }
+					title: { type: "string" },
+					matchedCount: {
+						type: "integer",
+						description: "选择器命中的元素总数(多命中歧义可见化)。"
+					},
+					visibleCount: {
+						type: "integer",
+						description: "命中元素中的可见数量。"
+					},
+					hint: {
+						type: "string",
+						description: "matchedCount>1 时的消歧指引。"
+					}
 				},
 				required: [
 					"selected",
@@ -7841,7 +8436,7 @@ function getTestingTools(config, timeout, stepImpls) {
 		}),
 		definePlainTool({
 			name: "browser_wait_for",
-			description: "通用显式等待(测试同步原语):轮询直到条件成立或超时抛错。condition 格式(可放在 condition 对象内，也可直接平铺于顶层参数): 1) {selector:'#btn', state:'visible|hidden|attached|detached'}; 2) {ref:'e1', state}; 3) {row:'TASK-1002', action:'编辑', state}; 4) {url:'正则'}; 5) {text:'子串'}; 6) {count:{selector,op,value}}; 7) {eval:'JS 表达式' (支持纯表达式或 return 语句)}。用于等页面渲染、等请求完成、等元素出现。",
+			description: "通用显式等待(测试同步原语):轮询直到条件成立或超时抛错。condition 格式(可放在 condition 对象内，也可直接平铺于顶层参数): 1) {selector:'#btn', state:'visible|hidden|attached|detached'}; 2) {ref:'e1', state}; 3) {row:'TASK-1002', action:'编辑', state}; 4) {url:'正则'}; 5) {text:'子串'}; 6) {count:{selector,op,value}}; 7) {eval:'JS 表达式' (支持纯表达式或 return 语句)}; 8) {bridge:{method:'桥方法名', args?:[], expect?:期望值 / expectContains:'子串'}} —— 页内调用 __DSH_BRIDGE__(vite-plugin-dsh-bridge)方法并断言返回(缺省判 truthy;expect 深比较),让桥取数与宿主等待无缝衔接。用于等页面渲染、等请求完成、等元素出现。",
 			parameters: {
 				type: "object",
 				properties: {
@@ -7881,13 +8476,13 @@ function getTestingTools(config, timeout, stepImpls) {
 		}),
 		definePlainTool({
 			name: "browser_assert",
-			description: "结构化断言(测试核心):condition 在 timeoutMs 内成立则通过(条件格式同 browser_wait_for，支持 selector/ref/row+action/url/text/count/eval，亦可直接平铺在顶层参数)。失败时自动截图存证据目录(assert-fail-*.png)并抛错,错误消息含原因与截图路径。另支持视觉回归:传 visual={baseline, threshold?, maxDiffRatio?, mask?} 与基线截图做像素比对(browser_screenshot 的 baseline 建立基线;mask 为忽略的选择器数组,如时钟/广告位),失败时产出当前截图与红标 diff 图。适合断言登录成功、关键元素出现、接口返回、文本正确、页面无视觉回归。",
+			description: "结构化断言(测试核心):condition 在 timeoutMs 内成立则通过(条件格式同 browser_wait_for，支持 selector/ref/row+action/url/text/count/eval/bridge，亦可直接平铺在顶层参数)。bridge 条件 {bridge:{method,args?,expect?/expectContains?}} 页内调用 __DSH_BRIDGE__(vite-plugin-dsh-bridge)方法断言返回——桥取数、宿主断言留证(失败自动截图)。失败时自动截图存证据目录(assert-fail-*.png)并抛错,错误消息含原因与截图路径。另支持视觉回归:传 visual={baseline, threshold?, maxDiffRatio?, mask?} 与基线截图做像素比对(browser_screenshot 的 baseline 建立基线;mask 为忽略的选择器数组,如时钟/广告位),失败时产出当前截图与红标 diff 图。适合断言登录成功、关键元素出现、接口返回、文本正确、页面无视觉回归。",
 			parameters: {
 				type: "object",
 				properties: {
 					condition: {
 						type: "object",
-						description: "断言条件(同 browser_wait_for,另支持 {ref, state})。"
+						description: "断言条件(同 browser_wait_for,另支持 {ref, state} 与 {bridge:{method,args?,expect?}})。"
 					},
 					visual: {
 						type: "object",
@@ -7942,7 +8537,7 @@ function getTestingTools(config, timeout, stepImpls) {
 					},
 					urlSubstr: {
 						type: "string",
-						description: "URL 子串过滤(list/failed)。"
+						description: "URL 子串过滤(list/failed,大小写不敏感;零命中时附 suggestions 相近 URL 候选,防误判接口未调用)。"
 					},
 					method: {
 						type: "string",
@@ -7985,7 +8580,12 @@ function getTestingTools(config, timeout, stepImpls) {
 					},
 					matched: { type: "object" },
 					waitMs: { type: "integer" },
-					cleared: { type: "boolean" }
+					cleared: { type: "boolean" },
+					suggestions: {
+						type: "array",
+						items: { type: "string" },
+						description: "urlSubstr 零命中时的 top5 相近 URL 候选。"
+					}
 				},
 				required: []
 			},
@@ -8010,10 +8610,14 @@ function getCollaborationTools(config, timeout, stepImpls) {
 	return [
 		definePlainTool({
 			name: "browser_wait_for_login",
-			description: "等待人工登录完成。agent 在登录页调用本工具后,提示用户在浏览器窗口中完成登录(有头模式 headless:false 时用户可直接操作;配 userDataDir 登录态会持久化)。成功条件三选一:successSelector(登录后出现的元素,如 '#avatar')或 successUrl(登录后 URL 正则,如 'https://\\\\.app\\\\.example\\\\.com')都不给则 URL 发生变化即视为完成。轮询间隔 2 秒,超时返回 loggedIn:false。",
+			description: "等待人工登录完成。agent 在登录页调用本工具后,提示用户在浏览器窗口中完成登录(有头模式 headless:false 时用户可直接操作;配 userDataDir 登录态会持久化)。支持 instruction 提示语(将显示在右下角实时画面面板);成功条件:优先取 successSelector(登录后出现的元素,如 '#avatar')或 successUrl(登录后 URL 正则);两者未指定时,结合 URL 变化、登录特征消除(密码框等)与页面签名稳态综合判定。轮询间隔 2 秒,超时返回 loggedIn:false(附 waitedMs 与 detail)。",
 			parameters: {
 				type: "object",
 				properties: {
+					instruction: {
+						type: "string",
+						description: "可选:给用户看的提示说明(默认「请在浏览器窗口中完成登录」)。"
+					},
 					timeoutMs: {
 						type: "integer",
 						description: "等待上限(毫秒,默认 120000,上限 600000)。"
@@ -8034,11 +8638,15 @@ function getCollaborationTools(config, timeout, stepImpls) {
 				additionalProperties: false,
 				properties: {
 					loggedIn: { type: "boolean" },
+					waitedMs: { type: "integer" },
+					detail: { type: "string" },
 					url: { type: "string" },
 					title: { type: "string" }
 				},
 				required: [
 					"loggedIn",
+					"waitedMs",
+					"detail",
 					"url",
 					"title"
 				]