dsh-browser-view 0.7.0 → 0.7.2

package/lib/index.js

@@ -683,6 +683,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 +713,8 @@ function __walkerCore() {
 		isElementInViewport,
 		describeElement,
 		composedParent,
-		deepChildren
+		deepChildren,
+		isProbablyClickable
 	};
 }
 /** walker 核心的序列化源码(模块加载期取一次;tsdown/vitest 均原样保留)。 */
@@ -1650,7 +1670,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);
@@ -1759,6 +1779,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);
@@ -1838,7 +1891,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 +1935,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 {
@@ -1964,6 +2035,18 @@ function nameSimilar(a, b) {
 * 具备路径防漂移校验与 getByRole 自愈降级能力。
 */
 async function resolveTargetLocator(page, args) {
+	{
+		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);
@@ -2159,6 +2242,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 +2862,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 +2887,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 +2936,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 +2984,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 +3027,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 +3214,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 +3244,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 +3762,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 +3778,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 +3789,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 +4108,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 +4153,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 +4247,24 @@ 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);
+	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 +4273,7 @@ async function typeTool(config, args) {
 			typed: true,
 			editor: true,
 			selector,
+			...ambiguityFields(targetRes),
 			...await pageIdentity(page)
 		};
 	}
@@ -4102,9 +4283,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 +4301,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 +4328,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 +4352,11 @@ 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);
+	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 +4370,7 @@ async function selectTool(config, args) {
 			clear: args.clear === true
 		})).selected,
 		selector: label,
+		...ambiguityFields(targetRes),
 		...await pageIdentity(page)
 	};
 }
@@ -4482,7 +4680,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 +4912,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 +5008,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
@@ -5996,7 +6268,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 +6276,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 +6933,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 +6964,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 +7077,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 +7254,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 +7276,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 +7298,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 +7314,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 +7344,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 +7375,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 +7393,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 +7421,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 +7429,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 +7456,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 +7483,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 +7515,10 @@ function getInteractionTools(config, timeout, stepImpls) {
 						type: "boolean",
 						description: "是否在选择前先清空已有选中项(对于多选下拉，替换而非叠加旧选项)。"
 					},
+					strict: {
+						type: "boolean",
+						description: "多命中即抛错(对齐 Playwright strict)。"
+					},
 					timeoutMs: { type: "integer" }
 				},
 				required: ["option"],
@@ -7185,7 +7531,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 +8199,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 +8239,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 +8300,7 @@ function getTestingTools(config, timeout, stepImpls) {
 					},
 					urlSubstr: {
 						type: "string",
-						description: "URL 子串过滤(list/failed)。"
+						description: "URL 子串过滤(list/failed,大小写不敏感;零命中时附 suggestions 相近 URL 候选,防误判接口未调用)。"
 					},
 					method: {
 						type: "string",
@@ -7985,7 +8343,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: []
 			},

package/lib/types/browser/session.d.ts

@@ -49,7 +49,9 @@ export interface NamedContext {
     createdAt: number;
 }
 export declare function namedContextsOf(): Map<string, NamedContext>;
-/** 把一个已 attach 的页面注册进 profile 标签表并激活,返回分配的 tab id。 */
+/** 把一个已 attach 的页面注册进 profile 标签表并激活,返回分配的 tab id。
+ * 唯一注册路径:同时挂 close 监听幂等摘除外部关闭的页(否则僵尸句柄会永久占用
+ * activeId,所有工具连报 "Target page...closed" 而 tabs list 仍显示存活)。 */
 export declare function registerTabPage(state: ProfileState, page: Page): number;
 /** 新建一个页面(当前 profile 会话未启动时先启动)。 */
 export declare function newPage(config: BrowserConfig): Promise<Page>;
@@ -57,8 +59,9 @@ export declare function newPage(config: BrowserConfig): Promise<Page>;
 export declare function getPage(config: BrowserConfig): Promise<Page>;
 /** 活动页面(可能为 null,不触发启动)。 */
 export declare function activePage(): Page | null;
-/** 投影当前 profile 的标签列表。 */
+/** 投影当前 profile 的标签列表(先摘除僵尸页,附注册时间)。 */
 export declare function tabList(): Promise<{
+    createdAt?: number | undefined;
     id: number;
     url: string;
     title: string;

package/lib/types/browser/tools/interaction.d.ts

@@ -7,6 +7,7 @@ export declare function isBotSensitiveUrl(url: string): boolean;
 export declare function clickTool(config: BrowserConfig, args: Record<string, any>, exec?: ToolRunContext): Promise<{
     url: string;
     title: string;
+    viaBridge?: boolean | undefined;
     effectHint?: string | undefined;
     clicked: string;
     effect: {
@@ -23,6 +24,7 @@ export declare function clickTool(config: BrowserConfig, args: Record<string, an
 } | {
     url: string;
     title: string;
+    viaBridge?: boolean | undefined;
     clicked: string;
 }>;
 export declare function typeTool(config: BrowserConfig, args: Record<string, any>): Promise<{

package/lib/types/browser/tools/navigation.d.ts

@@ -1,5 +1,6 @@
 import type { BrowserConfig } from "../types.js";
 export declare function openTool(configOrArgs: BrowserConfig | Record<string, any>, maybeArgs?: Record<string, any>): Promise<{
+    recovered?: string | undefined;
     url: string;
     title: string;
     status: string;
@@ -90,6 +91,7 @@ export declare function statusTool(): Promise<{
 export declare function tabsTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     action: any;
     tabs: {
+        createdAt?: number | undefined;
         id: number;
         url: string;
         title: string;
@@ -104,11 +106,12 @@ export declare function tabsTool(config: BrowserConfig, args: Record<string, any
         title: string;
     };
     tabs: {
+        createdAt?: number | undefined;
         id: number;
         url: string;
         title: string;
     }[];
-    activeId: number;
+    activeId: number | null;
 }>;
 export declare function profileTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     current: string;

package/lib/types/browser/tools/testing.d.ts

@@ -9,12 +9,13 @@ export declare function waitTool(config: BrowserConfig, args: Record<string, any
 /**
  * 条件检查引擎(测试原语共用)。
  *
- * cond 支持四类(每类内部互斥,取第一个存在的字段):
+ * cond 支持六类(每类内部互斥,取第一个存在的字段):
  *   { selector: "#btn", state: "visible|hidden|attached|detached" }  元素状态(默认 visible)
  *   { url: "正则字符串" }                                            当前 URL 匹配
  *   { text: "子串" }                                                  body 可见文本包含
  *   { count: { selector, op: "eq|gt|gte|lt|lte", value: n } }         元素数量比较
  *   { eval: "JS 表达式" }                                            表达式求值 truthy
+ *   { bridge: { method, args?, expect?/expectContains? } }           页内调用 __DSH_BRIDGE__ 方法并断言返回
  */
 export type TestCondition = Record<string, any>;
 /** 单次检查:返回 { ok, detail }。不抛错,失败时 detail 给出原因。 */
@@ -56,6 +57,7 @@ export declare function networkTool(configOrArgs?: Record<string, any>, maybeArg
     waitMs?: undefined;
     stats?: undefined;
     failed?: undefined;
+    suggestions?: undefined;
 } | {
     matched: import("../session.js").NetworkEntry;
     waitMs: number;
@@ -63,6 +65,7 @@ export declare function networkTool(configOrArgs?: Record<string, any>, maybeArg
     entries?: undefined;
     stats?: undefined;
     failed?: undefined;
+    suggestions?: undefined;
 } | {
     stats: {
         host: string;
@@ -76,13 +79,31 @@ export declare function networkTool(configOrArgs?: Record<string, any>, maybeArg
     matched?: undefined;
     waitMs?: undefined;
     failed?: undefined;
+    suggestions?: undefined;
 } | {
     failed: import("../session.js").NetworkEntry[];
+    suggestions: string[];
     cleared?: undefined;
     entries?: undefined;
     matched?: undefined;
     waitMs?: undefined;
     stats?: undefined;
+} | {
+    failed: import("../session.js").NetworkEntry[];
+    cleared?: undefined;
+    entries?: undefined;
+    matched?: undefined;
+    waitMs?: undefined;
+    stats?: undefined;
+    suggestions?: undefined;
+} | {
+    entries: import("../session.js").NetworkEntry[];
+    suggestions: string[];
+    cleared?: undefined;
+    matched?: undefined;
+    waitMs?: undefined;
+    stats?: undefined;
+    failed?: undefined;
 } | {
     entries: import("../session.js").NetworkEntry[];
     cleared?: undefined;
@@ -90,5 +111,6 @@ export declare function networkTool(configOrArgs?: Record<string, any>, maybeArg
     waitMs?: undefined;
     stats?: undefined;
     failed?: undefined;
+    suggestions?: undefined;
 }>;
 //# sourceMappingURL=testing.d.ts.map

package/lib/types/browser/types.d.ts

@@ -92,6 +92,10 @@ export interface ProfileState {
     activeId: number | null;
     counter: number;
     channel?: string;
+    /** 标签元数据(id → createdAt);随 pages 同步增删,僵尸标签治理用。 */
+    tabMeta?: Map<number, {
+        createdAt: number;
+    }>;
 }
 /** 一次页面下载的记录。 */
 export interface DownloadEntry {
@@ -173,6 +177,8 @@ export interface TargetResolution {
     visibleCount?: number;
     /** 语义定位的备选目标(按打分次序,最多 2 个);点击效果验证无变化时自动换选。 */
     alternates?: Locator[];
+    /** 经 window.__DSH_BRIDGE__.resolveActionTarget 兜底命中(vite-plugin-dsh-bridge 反哺)。 */
+    viaBridge?: boolean;
 }
 /** 录制时采集的选择器指纹(回放自愈的降级候选来源)。 */
 export interface SelectorHint {

package/lib/types/browser/walker.d.ts

@@ -20,6 +20,7 @@ declare function __walkerCore(): {
     };
     composedParent: (el: Element) => Element | null;
     deepChildren: (el: Element) => Element[];
+    isProbablyClickable: (el: Element) => boolean;
 };
 /** walker 核心注入后暴露给 entry 的 API(类型层)。 */
 export type WalkerApi = ReturnType<typeof __walkerCore>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-browser-view",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "DSH 插件:共享 Playwright 浏览器自动化(38 个 browser_* 工具,含 what 意图语义定位(一次调用替代快照→查找→点击)、SoM 标徽看图点击与零命中截图兜底、SPA ref 软失效重锚定、open Shadow DOM 组合树穿透、跨 Frame/IFrame 定位、视口感知动态快照、批量表单智能填充、点击效果验证与定位失败遥测、Playwright 规范代码导出、批处理、视觉回归、选择器自愈、增量快照)+ 人机协作(面板点选教学 browser_pick_element、人工接管等待、敏感操作审批硬拦截、人机混合录制、面板一键重跑)+ CDP 流式推流、拟人化轨迹与高斯击键、全景时光机、企业富控件矩阵。仅依赖 playwright-core。",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,6 +34,7 @@
     "test:enterprise": "tsx scripts/test-dev-server-enterprise.ts",
     "test:energy": "tsx scripts/test-dev-server-energy.ts",
     "test:shadow": "tsx scripts/test-dev-server-shadow.ts",
+    "test:span": "tsx scripts/test-dev-server-clickable-span.ts",
     "test:pick": "tsx scripts/test-panel-pick.ts",
     "dev:server": "tsx scripts/dev-server.ts",
     "verify": "npm run typecheck && npm run lint && npm run test && npm run build",