@weapp-vite/miniprogram-automator 1.2.23 → 1.4.0

package/dist/index.mjs

@@ -1,31 +1,49 @@
+import { OPERATION_TIMEOUT_CODE, OperationLifecycle, classifyOperationError, isRecoverableOperationError, readWechatLoginState } from "./operation.mjs";
 import { randomUUID } from "node:crypto";
 import net from "node:net";
 import process from "node:process";
-import { spawn } from "node:child_process";
 import path from "node:path";
 import { EventEmitter } from "node:events";
 import { createDebug } from "obug";
 import WebSocket from "ws";
+import { stripVTControlCharacters } from "node:util";
 import fs from "node:fs/promises";
 import os from "node:os";
+import { spawn } from "node:child_process";
 import { decodeQrCodeFromBase64, renderTerminalQrCode } from "@weapp-vite/qr";
 import { Buffer } from "node:buffer";
 //#region src/internal/compat/async.ts
 /**
 * @file 异步控制工具。
 */
-/** sleep 的方法封装。 */
-function sleep$1(timeout) {
-	return new Promise((resolve) => setTimeout(resolve, timeout));
+/** 可取消的延迟，取消时释放自身计时器。 */
+function sleep$1(timeout, signal) {
+	signal?.throwIfAborted();
+	return new Promise((resolve, reject) => {
+		let timer;
+		function abort() {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", abort);
+			reject(signal?.reason);
+		}
+		timer = setTimeout(() => {
+			signal?.removeEventListener("abort", abort);
+			resolve();
+		}, timeout);
+		signal?.addEventListener("abort", abort, { once: true });
+	});
 }
-/** waitUntil 的方法封装。 */
-async function waitUntil(condition, timeout = 0, interval = 250) {
-	const startTime = Date.now();
+/** 条件轮询受同一个单调时钟 deadline 与取消信号约束。 */
+async function waitUntil(condition, timeout = 0, interval = 250, signal) {
+	const deadlineAt = timeout ? performance.now() + timeout : Number.POSITIVE_INFINITY;
 	while (true) {
+		signal?.throwIfAborted();
 		const value = await condition();
+		signal?.throwIfAborted();
 		if (value) return value;
-		if (timeout && Date.now() - startTime >= timeout) throw new Error(`Wait timed out after ${timeout} ms`);
-		await sleep$1(interval);
+		const remaining = deadlineAt - performance.now();
+		if (remaining <= 0) throw new Error(`Wait timed out after ${timeout} ms`);
+		await sleep$1(Math.min(interval, remaining), signal);
 	}
 }
 //#endregion
@@ -218,6 +236,304 @@ function cmpVersion(versionA, versionB) {
 	return 0;
 }
 //#endregion
+//#region src/componentCaller/runtime.ts
+/** 在同一个 Runtime 上下文持有真实 caller，不转用其他 ContextManager 的 token。 */
+function createComponentCallerSession(expected, observerTimeout) {
+	const root = this;
+	const adapter = root.__glassEaselAdapter__;
+	const environment = adapter?.getEnv?.();
+	if (typeof environment?.getAdapterPage !== "function") throw new TypeError("Component caller backend selection is unavailable");
+	if (environment.getAdapterPage(expected.pageId)) return {
+		backend: "glass-easel",
+		dispose: () => ({
+			state: "disposed",
+			added: false,
+			removed: false
+		})
+	};
+	const bridge = root.WeixinJSBridge;
+	if (!bridge || typeof bridge.addSubscribeListener !== "function" || typeof bridge.removeSubscribeListener !== "function" || !adapter || typeof adapter.getVirtualDOM !== "function") throw new Error("Exact component caller bridge is unavailable");
+	const add = bridge.addSubscribeListener;
+	const remove = bridge.removeSubscribeListener;
+	const subscribe = bridge.subscribe;
+	const virtualDOM = adapter.getVirtualDOM();
+	const exparser = virtualDOM?.getExparser?.();
+	if (typeof virtualDOM?.getNodeById !== "function" || typeof virtualDOM.getNodeId !== "function" || typeof virtualDOM.getPageId !== "function" || typeof exparser?.Element?.getMethodCaller !== "function") throw new TypeError("Exact component caller mapping is unavailable");
+	let state = "created";
+	let caller;
+	let node;
+	let virtualId;
+	let added = false;
+	let removed = false;
+	let totalInvocations = 0;
+	let matchingInvocations = 0;
+	let timer;
+	const errors = [];
+	const eventName = "exparserComponentInvoker";
+	function identitiesMatch() {
+		return root.WeixinJSBridge === bridge && root.__glassEaselAdapter__ === adapter && bridge.subscribe === subscribe && bridge.addSubscribeListener === add && bridge.removeSubscribeListener === remove && adapter.getVirtualDOM() === virtualDOM && virtualDOM.getExparser() === exparser;
+	}
+	function snapshot() {
+		return {
+			state,
+			added,
+			removed,
+			totalInvocations,
+			matchingInvocations,
+			errors: [...errors],
+			identitiesMatch: identitiesMatch()
+		};
+	}
+	function listener(message, sender) {
+		totalInvocations += 1;
+		if (state !== "armed" && state !== "resolved") return;
+		if (message?.method !== "resolveComponentCaller") return;
+		matchingInvocations += 1;
+		try {
+			const args = message.params;
+			if (matchingInvocations !== 1 || !Array.isArray(args) || args.length !== 1 || args[0] === null || typeof args[0] !== "object" || Array.isArray(args[0])) throw new Error("Component caller resolver payload is ambiguous");
+			const params = args[0];
+			const id = params.nodeId;
+			if (!Number.isSafeInteger(message.callbackId) || message.callbackId <= 0 || sender !== expected.pageId || params.webviewId !== expected.pageId || !(typeof id === "string" && id.length > 0 || Number.isSafeInteger(id) && id >= 0)) throw new Error("Component caller resolver identity disagrees");
+			if (!identitiesMatch()) throw new Error("Component caller bridge identity changed");
+			const resolvedNode = virtualDOM.getNodeById(id, expected.pageId);
+			if (!resolvedNode || virtualDOM.getNodeId(resolvedNode, expected.pageId) !== id || virtualDOM.getPageId(resolvedNode) !== expected.pageId) throw new Error("Component caller virtual node identity disagrees");
+			const resolvedCaller = exparser.Element.getMethodCaller(resolvedNode);
+			if (!resolvedCaller || !["object", "function"].includes(typeof resolvedCaller)) throw new Error("Component caller is unavailable");
+			virtualId = id;
+			node = resolvedNode;
+			caller = resolvedCaller;
+			state = "resolved";
+		} catch (error) {
+			errors.push(error instanceof Error ? error.message : String(error));
+			state = "failed";
+		}
+	}
+	function removeListener() {
+		if (added && !removed) {
+			remove.call(bridge, eventName, listener);
+			removed = true;
+		}
+		if (timer !== void 0) {
+			clearTimeout(timer);
+			timer = void 0;
+		}
+	}
+	function dispose() {
+		try {
+			removeListener();
+			state = "disposed";
+		} finally {
+			caller = void 0;
+			node = void 0;
+			virtualId = void 0;
+		}
+		return {
+			state,
+			added,
+			removed,
+			totalInvocations,
+			matchingInvocations,
+			errors: [...errors]
+		};
+	}
+	return {
+		backend: "exparser",
+		arm() {
+			if (state !== "created") throw new Error("Component caller observer cannot be armed twice");
+			state = "armed";
+			timer = setTimeout(() => {
+				try {
+					dispose();
+				} catch (error) {
+					errors.push(error instanceof Error ? error.message : String(error));
+					state = "failed";
+				}
+			}, observerTimeout);
+			added = true;
+			add.call(bridge, eventName, listener);
+			return snapshot();
+		},
+		snapshot,
+		disarm() {
+			removeListener();
+			if (state !== "resolved" || matchingInvocations !== 1 || errors.length || !identitiesMatch()) throw new Error(`Exact component caller resolution failed: ${JSON.stringify(snapshot())}`);
+			state = "ready";
+			return snapshot();
+		},
+		invoke(method, args) {
+			if (state !== "ready" || !removed || errors.length || !identitiesMatch()) throw new Error("Component caller is not ready for a single invocation");
+			const pages = typeof getCurrentPages === "function" ? getCurrentPages() : [];
+			if (pages[pages.length - 1]?.__wxWebviewId__ !== expected.pageId || virtualDOM.getNodeById(virtualId, expected.pageId) !== node || virtualDOM.getNodeId(node, expected.pageId) !== virtualId || virtualDOM.getPageId(node) !== expected.pageId || exparser.Element.getMethodCaller(node) !== caller) throw new Error("Component caller changed before invocation");
+			state = "dispatched";
+			return caller[method](...args);
+		},
+		dispose
+	};
+}
+//#endregion
+//#region src/componentCaller/index.ts
+const queues = /* @__PURE__ */ new WeakMap();
+const blocked = /* @__PURE__ */ new WeakMap();
+const owners = /* @__PURE__ */ new WeakMap();
+const TIMEOUT = 2500;
+/** 关闭连接前确认全部自有 listener 已移除；失败时保留 token 与可重试的所有权。 */
+function cleanupComponentCallers(connection) {
+	const pending = owners.get(connection);
+	if (!pending?.size) return;
+	return (async () => {
+		const errors = [];
+		for (const owner of [...pending]) try {
+			await owner.cleanup();
+		} catch (error) {
+			errors.push(error);
+		}
+		if (errors.length) throw new AggregateError(errors, "Component caller cleanup remains incomplete", { cause: errors[0] });
+		blocked.delete(connection);
+	})();
+}
+function result(response) {
+	if (response.exceptionDetails) throw new Error(response.exceptionDetails.text ?? "Component caller Runtime exception", { cause: response.exceptionDetails });
+	if (!response.result) throw new Error("Component caller Runtime result is missing");
+	return response.result;
+}
+function serializeArguments(args) {
+	const payload = JSON.parse(stringify({ params: { args } }));
+	return JSON.stringify(payload.params.args);
+}
+/** 保持原 SDK 的 returnByValue 解包，不等待业务返回的 Promise。 */
+async function unwrap(connection, remote) {
+	if (remote.subtype === "null") return null;
+	if (remote.type === "undefined") return;
+	if (remote.value !== void 0) return remote.value;
+	if (remote.unserializableValue) {
+		const value = remote.unserializableValue;
+		if (/^-?\d+n$/.test(value)) return BigInt(value.slice(0, -1));
+		if ([
+			"NaN",
+			"Infinity",
+			"-Infinity",
+			"-0"
+		].includes(value)) return Number(value);
+		throw new Error(`Unsupported component return value: ${value}`);
+	}
+	if (remote.objectId) try {
+		const converted = await connection.send("App.CDPCommand", {
+			domain: "Runtime",
+			method: "callFunctionOn",
+			params: {
+				objectId: remote.objectId,
+				functionDeclaration: "function () { try { return JSON.stringify(this) } catch { return String(this) } }",
+				returnByValue: true
+			}
+		}, { timeout: TIMEOUT });
+		if (converted.result?.value !== void 0) try {
+			return JSON.parse(converted.result.value);
+		} catch {
+			return converted.result.value;
+		}
+	} catch {}
+	return remote.description ?? `[${remote.type}]`;
+}
+async function invoke(connection, target, method, args, native) {
+	let token;
+	let owner;
+	const errors = [];
+	let cleanupFailed = false;
+	let nativeBackend = false;
+	let value;
+	const cdp = async (domain, command, params) => {
+		return await connection.send("App.CDPCommand", {
+			domain,
+			method: command,
+			params
+		}, { timeout: TIMEOUT });
+	};
+	const wrapper = async (body) => result(await cdp("Runtime", "callFunctionOn", {
+		objectId: token,
+		functionDeclaration: `function () { return ${body} }`,
+		arguments: [],
+		returnByValue: true
+	}));
+	try {
+		if (!Number.isSafeInteger(target.nodeId) || target.nodeId < 0 || !Number.isSafeInteger(target.pageId)) throw new Error("Invalid component caller native target");
+		if ((await connection.send("App.getCurrentPage", {}, { timeout: TIMEOUT })).pageId !== target.pageId) throw new Error("Component caller target is not on the current page");
+		const created = result(await cdp("Runtime", "evaluate", {
+			expression: `(${createComponentCallerSession.toString()})(${JSON.stringify(target)}, 10000)`,
+			returnByValue: false
+		}));
+		if (!created.objectId) throw new Error("Component caller session has no owned Runtime token");
+		token = created.objectId;
+		let cleaning;
+		let disposed = false;
+		let released = false;
+		owner = { cleanup() {
+			cleaning ??= (async () => {
+				if (released) return;
+				if (!disposed) {
+					const snapshot = (await wrapper("this.dispose()")).value;
+					if (snapshot?.state !== "disposed" || snapshot.added && !snapshot.removed) throw new Error("Component caller listener removal was not confirmed");
+					disposed = true;
+				}
+				await cdp("Runtime", "releaseObject", { objectId: token });
+				released = true;
+				owners.get(connection)?.delete(owner);
+			})().catch((error) => {
+				cleaning = void 0;
+				throw error;
+			});
+			return cleaning;
+		} };
+		let pending = owners.get(connection);
+		if (!pending) {
+			pending = /* @__PURE__ */ new Set();
+			owners.set(connection, pending);
+		}
+		pending.add(owner);
+		const backend = (await wrapper("this.backend")).value;
+		if (backend === "glass-easel") nativeBackend = true;
+		else if (backend === "exparser") {
+			const argumentSource = serializeArguments(args);
+			await wrapper("this.arm()");
+			await cdp("WxComponent", "resolveComponentCaller", { nodeId: target.nodeId });
+			await wrapper("this.disarm()");
+			value = await unwrap(connection, await wrapper(`this.invoke(${JSON.stringify(method)}, ${argumentSource})`));
+		} else throw new Error("Unknown component caller backend");
+	} catch (error) {
+		errors.push(error);
+	} finally {
+		if (owner) try {
+			await owner.cleanup();
+		} catch (error) {
+			errors.push(error);
+			cleanupFailed = true;
+		}
+	}
+	if (cleanupFailed) blocked.set(connection, new Error("Component caller cleanup failed; reconnect before invoking another component", { cause: errors[0] }));
+	if (errors.length === 1) throw errors[0];
+	if (errors.length) throw new AggregateError(errors, "Component caller invocation and cleanup failed", { cause: errors[0] });
+	if (nativeBackend) {
+		if (!native) throw new Error("Native component backend requires the original protocol");
+		return await native();
+	}
+	return value;
+}
+/** 同一连接串行观察 resolver，避免多个组件误认彼此的桥接消息。 */
+async function invokeComponentMethod(connection, target, method, args, native) {
+	const pending = (queues.get(connection) ?? Promise.resolve()).then(async () => {
+		const failure = blocked.get(connection);
+		if (failure) throw failure;
+		return await invoke(connection, target, method, args, native);
+	});
+	const settled = pending.then(() => {}, () => {});
+	queues.set(connection, settled);
+	try {
+		return await pending;
+	} finally {
+		if (queues.get(connection) === settled) queues.delete(connection);
+	}
+}
+//#endregion
 //#region src/pageRouteSnapshot.ts
 const ROUTE_ELEMENT_SNAPSHOT_TIMEOUT = 5e3;
 const ROUTE_ELEMENT_SNAPSHOT_EMPTY_RETRIES = 2;
@@ -437,6 +753,14 @@ async function readRouteElementSnapshot(connection, route, query, selector, inde
 }
 //#endregion
 //#region src/Element.ts
+function normalizeTouchOptions(options) {
+	const { changeTouches, ...payload } = options;
+	const changedTouches = options.changedTouches ?? changeTouches;
+	return changedTouches === void 0 ? payload : {
+		...payload,
+		changedTouches
+	};
+}
 const ELEMENT_QUERY_TIMEOUT = 2500;
 const ELEMENT_WXML_TIMEOUT = 8e3;
 /** Element 的实现。 */
@@ -542,16 +866,26 @@ var Element = class Element {
 		await this.send("Element.triggerEvent", payload);
 	}
 	async touchstart(options = {}) {
-		await this.send("Element.touchstart", options);
+		await this.send("Element.touchstart", normalizeTouchOptions(options));
 	}
 	async touchmove(options = {}) {
-		await this.send("Element.touchmove", options);
+		await this.send("Element.touchmove", normalizeTouchOptions(options));
 	}
 	async touchend(options = {}) {
-		await this.send("Element.touchend", options);
+		await this.send("Element.touchend", normalizeTouchOptions(options));
 	}
 	async dispatchEvent(options) {
-		await this.send("Element.dispatchEvent", options);
+		const payload = normalizeTouchOptions(options);
+		if (!payload.$ && !payload.detail && (payload.eventName === "touchstart" || payload.eventName === "touchmove" || payload.eventName === "touchend") && (payload.touches !== void 0 || payload.changedTouches !== void 0)) {
+			const { eventName, ...touchOptions } = payload;
+			await this.send(`Element.${eventName}`, touchOptions);
+			return;
+		}
+		const { detail, ...event } = payload;
+		await this.send("Element.dispatchEvent", detail === void 0 ? event : {
+			...event,
+			eventData: detail
+		});
 	}
 	async _property(name) {
 		return await this.getter(name, "getProperties", "properties");
@@ -733,6 +1067,18 @@ var CustomElement = class extends Element {
 		return (await this.send("Element.getData", payload)).data;
 	}
 	async callMethod(method, ...args) {
+		if (this.connection.prefersComponentCallerBridge) {
+			const nodeId = this.nodeId === null ? NaN : Number(this.nodeId);
+			return await invokeComponentMethod(this.connection, {
+				nodeId,
+				pageId: this.pageId
+			}, method, args, async () => {
+				return (await this.send("Element.callMethod", {
+					method,
+					args
+				})).result;
+			});
+		}
 		return (await this.send("Element.callMethod", {
 			method,
 			args
@@ -811,6 +1157,9 @@ var ContextElement = class extends Element {
 /** Transport 的实现。 */
 var Transport = class extends EventEmitter {
 	ws;
+	closed = false;
+	terminating = false;
+	closing;
 	constructor(ws) {
 		super();
 		this.ws = ws;
@@ -818,6 +1167,7 @@ var Transport = class extends EventEmitter {
 			this.emit("message", typeof data === "string" ? data : data.toString());
 		});
 		ws.on("close", () => {
+			this.closed = true;
 			this.emit("close");
 		});
 	}
@@ -825,7 +1175,36 @@ var Transport = class extends EventEmitter {
 		this.ws.send(message);
 	}
 	close() {
-		this.ws.close();
+		if (this.closing) return this.closing;
+		if (this.closed || this.ws.readyState === 3) return this.closing = Promise.resolve();
+		this.closing = new Promise((resolve, reject) => {
+			let timer;
+			const finish = () => {
+				clearTimeout(timer);
+				this.off("close", finish);
+				resolve();
+			};
+			timer = setTimeout(() => {
+				this.off("close", finish);
+				reject(Object.assign(/* @__PURE__ */ new Error("DevTools websocket did not close within 2000ms"), { code: "DEVTOOLS_DISCONNECT_TIMEOUT" }));
+			}, 2e3);
+			this.once("close", finish);
+			try {
+				if (!this.terminating) {
+					this.terminating = true;
+					this.ws.terminate();
+				}
+			} catch (error) {
+				this.terminating = false;
+				clearTimeout(timer);
+				this.off("close", finish);
+				reject(error);
+			}
+		}).catch((error) => {
+			this.closing = void 0;
+			throw error;
+		});
+		return this.closing;
 	}
 };
 //#endregion
@@ -840,13 +1219,22 @@ const CONNECT_TIMEOUT = 3e4;
 /** Page frame 定向消息失效、需要切换到 App-service Page 协议的 DevTools 版本。 */
 const APP_SERVICE_PAGE_PROTOCOL_VERSIONS = /* @__PURE__ */ new Set(["2.01.2510290"]);
 /** 仅页面方法调用失效的版本，元素查询仍保留原生组件作用域。 */
-const APP_SERVICE_PAGE_METHOD_VERSIONS = /* @__PURE__ */ new Set(["2.02.2608070", "2.02.2609231"]);
+const APP_SERVICE_PAGE_METHOD_VERSIONS = /* @__PURE__ */ new Set([
+	"2.02.2608070",
+	"2.02.2608080",
+	"2.02.2609231",
+	"2.02.2610082",
+	"2.02.2610092"
+]);
 /** Connection 的实现。 */
 var Connection = class Connection extends EventEmitter {
 	transport;
+	disposed = false;
+	disposing;
 	callbacks = /* @__PURE__ */ new Map();
 	useAppServicePageProtocol = false;
 	useAppServicePageMethod = false;
+	useComponentCallerBridge = false;
 	constructor(transport) {
 		super();
 		this.transport = transport;
@@ -854,6 +1242,7 @@ var Connection = class Connection extends EventEmitter {
 		transport.on("close", this.onClose);
 	}
 	send(method, params = {}, options = {}) {
+		if (this.disposed) return Promise.reject(/* @__PURE__ */ new Error(closeErrTip));
 		const id = uuid();
 		const payload = stringify({
 			id,
@@ -877,21 +1266,59 @@ var Connection = class Connection extends EventEmitter {
 			});
 			try {
 				this.transport.send(payload);
-			} catch {
+			} catch (cause) {
 				clearTimeout(timeout);
 				this.callbacks.delete(id);
-				reject(/* @__PURE__ */ new Error(closeErrTip));
+				reject(new Error(closeErrTip, { cause }));
 			}
 		});
 	}
 	dispose() {
-		this.transport.close();
+		if (this.disposing) return this.disposing;
+		let resolve;
+		let reject;
+		this.disposing = new Promise((done, fail) => {
+			resolve = done;
+			reject = fail;
+		}).catch((error) => {
+			this.disposing = void 0;
+			throw error;
+		});
+		const cleanup = cleanupComponentCallers(this);
+		if (cleanup) cleanup.then(() => this.closeTransport(resolve, reject), reject);
+		else this.closeTransport(resolve, reject);
+		return this.disposing;
+	}
+	closeTransport(resolve, reject) {
+		const errors = [];
+		try {
+			this.onClose();
+		} catch (error) {
+			errors.push(error);
+		}
+		this.transport.off("message", this.onMessage);
+		this.transport.off("close", this.onClose);
+		const finish = () => {
+			if (errors.length === 1) reject(errors[0]);
+			else if (errors.length) reject(new AggregateError(errors, "Connection close notification and transport cleanup failed", { cause: errors[0] }));
+			else resolve();
+		};
+		try {
+			Promise.resolve(this.transport.close()).then(finish, (error) => {
+				errors.push(error);
+				finish();
+			});
+		} catch (error) {
+			errors.push(error);
+			finish();
+		}
 	}
 	/** 根据 DevTools 版本选择稳定的 Page 协议实现。 */
 	configureToolInfo(info) {
 		const version = String(info.version ?? "");
 		this.useAppServicePageProtocol = APP_SERVICE_PAGE_PROTOCOL_VERSIONS.has(version);
 		this.useAppServicePageMethod = this.useAppServicePageProtocol || APP_SERVICE_PAGE_METHOD_VERSIONS.has(version);
+		this.useComponentCallerBridge = version === "2.02.2608080" && info.SDKVersion === "3.17.5";
 	}
 	get prefersAppServicePageProtocol() {
 		return this.useAppServicePageProtocol;
@@ -900,6 +1327,10 @@ var Connection = class Connection extends EventEmitter {
 	get prefersAppServicePageMethod() {
 		return this.useAppServicePageMethod;
 	}
+	/** 仅为实测存在跨上下文 token 错绑的 IDE 与基础库启用真实 caller 桥接。 */
+	get prefersComponentCallerBridge() {
+		return this.useComponentCallerBridge;
+	}
 	onMessage = (message) => {
 		debugProtocol(`${dateFormat("yyyy-mm-dd HH:MM:ss:l")} ◀ RECV ${message}`);
 		const { id, method, error, result, params } = JSON.parse(message);
@@ -912,47 +1343,87 @@ var Connection = class Connection extends EventEmitter {
 		this.callbacks.delete(id);
 		clearTimeout(callback.timeout);
 		if (error) {
-			callback.reject(new Error(error.message || closeErrTip));
+			const message = typeof error.message === "string" ? error.message : error.message === void 0 ? closeErrTip : JSON.stringify(error.message);
+			callback.reject(new Error(message, { cause: error }));
 			return;
 		}
 		callback.resolve(result);
 	};
 	onClose = () => {
+		if (this.disposed) return;
+		this.disposed = true;
 		for (const callback of this.callbacks.values()) {
 			clearTimeout(callback.timeout);
 			callback.reject(/* @__PURE__ */ new Error(closeErrTip));
 		}
 		this.callbacks.clear();
+		this.emit("close");
 	};
-	static create(url, timeout = CONNECT_TIMEOUT) {
+	static create(url, timeout = CONNECT_TIMEOUT, signal) {
+		signal?.throwIfAborted();
 		return new Promise((resolve, reject) => {
 			const ws = new WebSocket(url);
 			let settled = false;
-			const timer = setTimeout(() => {
+			let timer;
+			let onAbort;
+			let onOpen;
+			let onClose;
+			function cleanup() {
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
+				ws.off("open", onOpen);
+				ws.off("close", onClose);
+			}
+			function fail(error) {
 				if (settled) return;
 				settled = true;
-				ws.close();
-				reject(/* @__PURE__ */ new Error(`Timed out connecting to DevTools websocket ${url} after ${timeout}ms`));
-			}, timeout);
-			ws.on("open", () => {
+				cleanup();
+				ws.terminate();
+				reject(error);
+			}
+			onAbort = () => {
+				fail(signal?.reason);
+			};
+			onClose = () => {
+				fail(/* @__PURE__ */ new Error("DevTools websocket closed before handshake completed"));
+			};
+			onOpen = () => {
 				if (settled) return;
 				settled = true;
-				clearTimeout(timer);
+				cleanup();
 				resolve(new Connection(new Transport(ws)));
-			});
-			ws.on("error", (error) => {
-				if (settled) return;
-				settled = true;
-				clearTimeout(timer);
-				reject(error);
-			});
+			};
+			timer = setTimeout(() => fail(/* @__PURE__ */ new Error(`Timed out connecting to DevTools websocket ${url} after ${timeout}ms`)), timeout);
+			ws.on("open", onOpen);
+			ws.on("error", fail);
+			ws.on("close", onClose);
+			signal?.addEventListener("abort", onAbort, { once: true });
+			if (signal?.aborted) onAbort();
 		});
 	}
 };
 //#endregion
 //#region src/headless.ts
 async function launchHeadlessAutomator(options) {
-	return await (await import("./launch-CSjvON-f.mjs")).launch({ projectPath: options.projectPath });
+	return await (await import("./launch-ElaGbFxh.mjs")).launch({ projectPath: options.projectPath });
+}
+//#endregion
+//#region src/launcher/diagnostics.ts
+/** 将本次 CLI 的有界输出附到原始错误，避免泄露登录票据及账号参数。 */
+function attachCliDiagnostics(error, state, secrets = []) {
+	const original = error instanceof Error ? error : new Error("Failed to launch WeChat DevTools", { cause: error });
+	if (original.cliOutput !== void 0) return original;
+	let output = stripVTControlCharacters(state.output).trim();
+	for (const secret of secrets.filter(Boolean).sort((a, b) => b.length - a.length)) output = output.split(secret).join("[redacted]");
+	output = output.replace(/(authorization["']?\s*[:=]\s*["']?)(?:Bearer|Basic)\s+[^\s"',;}]+/gi, "$1[redacted]");
+	output = output.replace(/((?:--)?(?:auto-account|account|ticket|access[_-]?token|refresh[_-]?token|token|authorization)["']?\s*(?:[:=]\s*|\s))(["']?)([^\s"',;}]+)\2/gi, "$1[redacted]");
+	if (!output) return original;
+	const truncated = state.outputTruncated || output.length > 32768;
+	output = output.slice(-32768);
+	const target = Object.isExtensible(original) ? original : new Error(original.message, { cause: original });
+	target.cliOutput = output;
+	target.message += `\ncli output${truncated ? " (truncated; last 32768 characters)" : ""}:\n${output}`;
+	return target;
 }
 //#endregion
 //#region src/launcher/portLease.ts
@@ -978,7 +1449,7 @@ function isProcessAlive(pid) {
 	}
 }
 async function removePortLock(leasePath) {
-	await fs.rm(leasePath, { force: true }).catch(() => {});
+	await fs.rm(leasePath, { force: true });
 }
 async function removeStalePortLock(leasePath) {
 	try {
@@ -1010,14 +1481,18 @@ async function createPortLock(port) {
 	return leasePath;
 }
 function createLease(port, leasePath) {
-	let released = false;
+	let releasing;
 	return {
 		path: leasePath,
 		port,
-		release: async () => {
-			if (released) return;
-			released = true;
-			if (leasePath) await removePortLock(leasePath);
+		release: () => {
+			releasing ??= (async () => {
+				if (leasePath) await removePortLock(leasePath);
+			})().catch((error) => {
+				releasing = void 0;
+				throw error;
+			});
+			return releasing;
 		}
 	};
 }
@@ -1064,7 +1539,10 @@ async function enableAutomatorViaHttp(options) {
 	if (options.account) endpoint.searchParams.set("account", options.account);
 	if (options.ticket) endpoint.searchParams.set("ticket", options.ticket);
 	if (options.trustProject) endpoint.searchParams.set("trustProject", "true");
-	const response = await fetch(endpoint, { redirect: "follow" });
+	const response = await fetch(endpoint, {
+		redirect: "follow",
+		signal: options.signal
+	});
 	const body = await response.text();
 	if (!response.ok) throw new Error(`WeChat DevTools HTTP automator fallback failed with status ${response.status}`);
 	let result;
@@ -1073,6 +1551,7 @@ async function enableAutomatorViaHttp(options) {
 	} catch {
 		throw new Error("WeChat DevTools HTTP automator fallback returned invalid JSON");
 	}
+	if (result && typeof result === "object" && "code" in result && Number(result.code) === 10) throw Object.assign(/* @__PURE__ */ new Error("DEVTOOLS_LOGIN_REQUIRED: need re-login"), { code: 10 });
 	if (result && typeof result === "object" && "autoPort" in result) {
 		const autoPort = Number(result.autoPort);
 		if (!Number.isInteger(autoPort) || autoPort <= 0 || autoPort > 65535) throw new Error("WeChat DevTools HTTP automator fallback returned invalid autoPort");
@@ -1106,8 +1585,231 @@ function resolveWechatDevtoolsBootstrapArgs(args) {
 	return bootstrapArgs;
 }
 //#endregion
+//#region src/launcher/process.ts
+const WINDOWS_BATCH_CLI_RE = /\.(?:bat|cmd)$/i;
+function shouldUseWindowsCommandShell(cliPath) {
+	return isWindows && WINDOWS_BATCH_CLI_RE.test(cliPath);
+}
+function escapeWindowsCmdArg(arg) {
+	const escaped = arg.replace(/"/g, "\"\"").replace(/%/g, "%%");
+	return /[\s"&<>^|()]/.test(arg) ? `"${escaped}"` : escaped;
+}
+function resolveWindowsBatchSpawn(cliPath, args) {
+	return {
+		file: process.env.ComSpec || "cmd.exe",
+		args: [
+			"/d",
+			"/s",
+			"/c",
+			`"${[cliPath, ...args].map(escapeWindowsCmdArg).join(" ")}"`
+		]
+	};
+}
+/** 只持有本次 CLI 子进程句柄；退出后不通过旧 PID 查找或终止宿主。 */
+function spawnWechatCli(cliPath, args, cwd, scope) {
+	scope.throwIfAborted();
+	const state = {
+		error: null,
+		success: false,
+		exited: false,
+		output: "",
+		outputTruncated: false
+	};
+	const bootstrapArgs = resolveWechatDevtoolsBootstrapArgs(args);
+	const target = shouldUseWindowsCommandShell(cliPath) ? resolveWindowsBatchSpawn(cliPath, bootstrapArgs) : {
+		file: cliPath,
+		args: bootstrapArgs
+	};
+	const child = spawn(target.file, target.args, {
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		cwd: cwd || void 0,
+		...shouldUseWindowsCommandShell(cliPath) ? {
+			windowsHide: true,
+			windowsVerbatimArguments: true
+		} : {}
+	});
+	let released;
+	const release = () => {
+		if (!released) released = new Promise((resolve) => {
+			if (state.exited || !child.pid || child.exitCode !== null || child.signalCode !== null) {
+				resolve();
+				return;
+			}
+			child.once("close", () => resolve());
+			child.kill("SIGKILL");
+		});
+		return released;
+	};
+	const disown = scope.own(release, "cli-process");
+	child.on("error", (error) => {
+		state.error = error;
+	});
+	const output = (chunk) => {
+		const combined = state.output + String(chunk);
+		state.outputTruncated ||= combined.length > 32768;
+		state.output = combined.slice(-32768);
+	};
+	child.stdout?.on("data", output);
+	child.stderr?.on("data", output);
+	child.on("exit", (code, signal) => {
+		disown();
+		state.exited = true;
+		if (code !== 0 || signal) state.error = /* @__PURE__ */ new Error(`DevTools cli exited unexpectedly with code ${code ?? "null"}${signal ? ` and signal ${signal}` : ""}`);
+		else state.success = true;
+	});
+	child.unref();
+	return Object.assign(state, { release });
+}
+//#endregion
 //#region package.json
-var version = "1.2.23";
+var version = "1.4.0";
+//#endregion
+//#region src/appServiceHeap.ts
+function isRecord$1(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function unsupported$1(reason) {
+	return {
+		status: "unsupported",
+		source: "appservice-cdp-runtime",
+		reason
+	};
+}
+/** 只读取 AppService 当前 V8 堆，不调用 GC，也不把协议故障或空响应当成零内存。 */
+async function readAppServiceHeapUsage(send, options = {}) {
+	const timeout = options.timeout ?? 2500;
+	if (!Number.isFinite(timeout) || timeout <= 0) throw new TypeError("AppService heap timeout must be finite and positive");
+	let response;
+	try {
+		response = await send("App.CDPCommand", {
+			domain: "Runtime",
+			method: "getHeapUsage",
+			params: {}
+		}, { timeout });
+	} catch (error) {
+		if (error instanceof Error && (error.message === "appservice App.CDPCommand unimplemented" || error.message === "Method not implemented.")) return unsupported$1("protocol-unimplemented");
+		if (error instanceof Error && error.message === "'Runtime.getHeapUsage' wasn't found") return unsupported$1("method-not-found");
+		throw error;
+	}
+	if (isRecord$1(response) && isRecord$1(response.error) && response.error.code === -32601) return unsupported$1("method-not-found");
+	if (!isRecord$1(response) || response.error || response.exceptionDetails || typeof response.usedSize !== "number" || !Number.isFinite(response.usedSize) || response.usedSize < 0 || typeof response.totalSize !== "number" || !Number.isFinite(response.totalSize) || response.totalSize < response.usedSize) throw new Error("Invalid AppService Runtime.getHeapUsage response: expected finite non-negative usedSize <= totalSize");
+	return {
+		status: "available",
+		source: "appservice-cdp-runtime",
+		usedSize: response.usedSize,
+		totalSize: response.totalSize
+	};
+}
+//#endregion
+//#region src/cdp/index.ts
+/** 单个连接共享 CDP 启用状态与订阅；不创建额外 WebSocket。 */
+var CDPController = class {
+	connection;
+	send;
+	enabling;
+	enabled = false;
+	stopped = false;
+	subscriptions = /* @__PURE__ */ new Set();
+	session;
+	constructor(connection, send) {
+		this.connection = connection;
+		this.send = send;
+		connection.on("close", this.stop);
+		this.session = {
+			enable: (options) => this.enable(options),
+			sendCommand: (domain, method, params = {}, options) => this.request("App.CDPCommand", {
+				domain,
+				method,
+				params
+			}, options),
+			listProtocol: (options) => this.request("App.CDPListProtocol", {}, options),
+			onEvent: (listener) => this.onEvent(listener)
+		};
+	}
+	enable(options) {
+		if (this.stopped) return Promise.reject(/* @__PURE__ */ new Error("CDP connection closed"));
+		try {
+			this.validateTimeout(options);
+		} catch (error) {
+			return Promise.reject(error);
+		}
+		if (!this.enabling) {
+			let pending;
+			try {
+				pending = this.send("App.CDPEnable", {}, options);
+			} catch (error) {
+				pending = Promise.reject(error);
+			}
+			this.enabling = pending.then((result) => {
+				this.enabled = true;
+				return result;
+			}, (error) => {
+				this.enabling = void 0;
+				throw error;
+			});
+		}
+		if (options?.timeout === void 0) return this.enabling;
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`Timed out enabling CDP within ${options.timeout}ms`)), options.timeout);
+			this.enabling.then(resolve, reject).finally(() => clearTimeout(timer));
+		});
+	}
+	/** 日志显式刷新时重新注册事件通道，兼容 AppService 重载。 */
+	refresh(options) {
+		if (this.enabled) {
+			this.enabled = false;
+			this.enabling = void 0;
+		}
+		return this.enable(options);
+	}
+	stop = () => {
+		this.stopped = true;
+		this.enabled = false;
+		this.enabling = void 0;
+		this.connection.off("close", this.stop);
+		for (const unsubscribe of this.subscriptions) unsubscribe();
+	};
+	async request(method, params, options) {
+		this.validateTimeout(options);
+		const startedAt = Date.now();
+		await this.enable(options);
+		if (this.stopped) throw new Error("CDP connection closed");
+		if (options?.timeout === void 0) return await this.send(method, params);
+		const timeout = options.timeout - (Date.now() - startedAt);
+		if (timeout <= 0) throw new Error(`Timed out executing ${method} within ${options.timeout}ms`);
+		return await this.send(method, params, { timeout });
+	}
+	validateTimeout(options) {
+		if (options?.timeout !== void 0 && (!Number.isFinite(options.timeout) || options.timeout <= 0)) throw new RangeError("CDP timeout must be finite and positive");
+	}
+	onEvent(listener) {
+		if (this.stopped) throw new Error("CDP connection closed");
+		const receive = (payload) => {
+			listener(payload.domain, payload.event, payload.params);
+		};
+		const unsubscribe = () => {
+			this.connection.off("App.CDPEvent", receive);
+			this.subscriptions.delete(unsubscribe);
+		};
+		this.subscriptions.add(unsubscribe);
+		this.connection.on("App.CDPEvent", receive);
+		return unsubscribe;
+	}
+};
+const controllers = /* @__PURE__ */ new WeakMap();
+/** 一个协议连接仅拥有一份 CDP 状态，包括被不同 MiniProgram 包装的连接。 */
+function getCDPController(connection, send) {
+	let controller = controllers.get(connection);
+	if (!controller) {
+		controller = new CDPController(connection, send);
+		controllers.set(connection, controller);
+	}
+	return controller;
+}
 //#endregion
 //#region src/Native.ts
 /** Native 的实现。 */
@@ -1158,6 +1860,25 @@ var Native = class extends EventEmitter {
 	}
 };
 //#endregion
+//#region src/navigation/query.ts
+/** 仅核对请求显式携带的参数，保留宿主附加参数及其原始编码形式。 */
+function matchesRouteQuery(actual, expected) {
+	const expectedKeys = Object.keys(expected);
+	if (!expectedKeys.length) return true;
+	if (!actual || typeof actual !== "object" || Array.isArray(actual)) return false;
+	const query = actual;
+	return expectedKeys.every((key) => {
+		if (!Object.prototype.hasOwnProperty.call(query, key) || query[key] == null) return false;
+		const value = String(query[key]);
+		if (value === expected[key]) return true;
+		try {
+			return decodeURIComponent(value) === expected[key];
+		} catch {
+			return false;
+		}
+	});
+}
+//#endregion
 //#region src/pageRouteFallback.ts
 function normalizeFallbackIdPart(value) {
 	return encodeURIComponent(value).replace(/%/g, "_");
@@ -2422,7 +3143,7 @@ function isPluginNavigationUrl(value) {
 }
 function matchesRouteChange(options) {
 	const normalizedCurrentPath = normalizeRoutePath(options.currentPath);
-	if (!options.expectedRoute || normalizedCurrentPath === options.expectedRoute) return true;
+	if (!options.expectedRoute || normalizedCurrentPath === options.expectedRoute) return matchesRouteQuery(options.currentQuery, options.expectedQuery);
 	if (!isPluginNavigationUrl(options.requestedUrl) || !isPluginPath(options.currentPath)) return false;
 	return normalizedCurrentPath !== normalizeRoutePath(options.previousPath);
 }
@@ -2456,16 +3177,21 @@ var MiniProgram = class extends EventEmitter {
 	logEnabling;
 	structuredLogs = false;
 	structuredConsole;
+	cdp;
 	pageMap = /* @__PURE__ */ new Map();
 	nativeIns;
+	disconnecting;
+	closing;
 	constructor(connection) {
 		super();
 		this.connection = connection;
+		this.cdp = getCDPController(connection, (method, params, options) => this.send(method, params, options));
 		this.structuredConsole = new StructuredConsole((method, params, options) => this.send(method, params, options), (entry) => this.emit("console", entry));
 		connection.on("App.CDPEvent", this.structuredConsole.receive);
 		connection.on("App.logAdded", this.onLogAdded);
 		connection.on("App.bindingCalled", this.onBindingCalled);
 		connection.on("App.exceptionThrown", this.onExceptionThrown);
+		connection.on("close", this.stopSubscriptions);
 	}
 	async pageStack() {
 		const { pageStack } = await this.send("App.getPageStack");
@@ -2600,22 +3326,34 @@ var MiniProgram = class extends EventEmitter {
 		}, sendOptions);
 		return result;
 	}
+	/** 探测并读取 AppService JS 堆；明确不支持时返回原因，连接故障与无效响应继续抛出。 */
+	async getAppServiceHeapUsage(options = {}) {
+		return await readAppServiceHeapUsage((method, params, sendOptions) => this.send(method, params, sendOptions), options);
+	}
 	async pageScrollTo(scrollTop) {
 		await this.callWxMethod("pageScrollTo", {
 			scrollTop,
 			duration: 0
 		});
 	}
-	async close() {
-		try {
-			await withTimeout(this.send("App.exit"), CLOSE_STEP_TIMEOUT);
-		} catch {}
-		await sleep(1e3);
-		try {
-			await withTimeout(this.send("Tool.close"), CLOSE_STEP_TIMEOUT);
-		} catch {} finally {
-			this.disconnect();
-		}
+	close() {
+		this.closing ??= (async () => {
+			try {
+				try {
+					await withTimeout(this.send("App.exit"), CLOSE_STEP_TIMEOUT);
+				} catch {}
+				await sleep(1e3);
+				try {
+					await withTimeout(this.send("Tool.close"), CLOSE_STEP_TIMEOUT);
+				} catch {}
+			} finally {
+				await this.disconnect();
+			}
+		})().catch((error) => {
+			this.closing = void 0;
+			throw error;
+		});
+		return this.closing;
 	}
 	async remote(auto = false) {
 		const { qrCode } = await this.send("Tool.enableRemoteDebug", { auto });
@@ -2628,9 +3366,23 @@ var MiniProgram = class extends EventEmitter {
 		});
 	}
 	disconnect() {
-		this.structuredConsole.stop();
-		this.connection.dispose();
+		if (this.disconnecting) return this.disconnecting;
+		this.stopSubscriptions();
+		this.disconnecting = Promise.resolve(this.connection.dispose()).catch((error) => {
+			this.disconnecting = void 0;
+			throw error;
+		});
+		return this.disconnecting;
 	}
+	stopSubscriptions = () => {
+		this.structuredConsole.stop();
+		this.cdp.stop();
+		this.connection.off("App.CDPEvent", this.structuredConsole.receive);
+		this.connection.off("App.logAdded", this.onLogAdded);
+		this.connection.off("App.bindingCalled", this.onBindingCalled);
+		this.connection.off("App.exceptionThrown", this.onExceptionThrown);
+		this.connection.off("close", this.stopSubscriptions);
+	};
 	/** 等待已接收的结构化日志完成 Error 属性检查并发布。 */
 	async flushConsole() {
 		await this.structuredConsole.flush();
@@ -2655,7 +3407,12 @@ var MiniProgram = class extends EventEmitter {
 			let cdpMethod = this.structuredLogs ? "App.CDPEnable" : "App.CDPCommand";
 			try {
 				if (this.structuredLogs) {
-					await request(cdpMethod);
+					if (timeout === void 0) await this.cdp.refresh();
+					else {
+						const remaining = timeout - (Date.now() - startedAt);
+						if (remaining <= 0) throw new Error(`Timed out enabling console logging within ${timeout}ms`);
+						await this.cdp.refresh({ timeout: remaining });
+					}
 					cdpMethod = "App.CDPCommand";
 				}
 				await request("App.CDPCommand", {
@@ -2695,7 +3452,7 @@ var MiniProgram = class extends EventEmitter {
 		if (sdkVersion !== "dev" && cmpVersion(sdkVersion, "2.7.3") < 0) throw new Error(`SDKVersion is currently ${sdkVersion}, while automator(${version}) requires at least version 2.7.3`);
 	}
 	/**
-	* @description 等待小程序 App 域协议可用，避免返回半就绪自动化会话。
+	* @description 等待原生协议返回真实页面标识和路径，避免返回半就绪自动化会话。
 	*/
 	async waitForAppReady(timeout = APP_READY_TIMEOUT) {
 		const startedAt = Date.now();
@@ -2703,13 +3460,15 @@ var MiniProgram = class extends EventEmitter {
 		while (Date.now() - startedAt < timeout) {
 			const remainingTimeout = timeout - (Date.now() - startedAt);
 			try {
-				await this.send("App.captureScreenshot", {}, { timeout: Math.min(APP_READY_PROBE_TIMEOUT, remainingTimeout) });
-				return;
+				const page = await this.send("App.getCurrentPage", {}, { timeout: Math.min(APP_READY_PROBE_TIMEOUT, remainingTimeout) });
+				if (page && typeof page === "object" && "pageId" in page && typeof page.pageId === "number" && Number.isSafeInteger(page.pageId) && page.pageId >= 0 && "path" in page && typeof page.path === "string" && page.path.trim()) return;
+				lastError = /* @__PURE__ */ new Error("App.getCurrentPage returned no ready page with a valid pageId and path");
 			} catch (error) {
+				if (!isCurrentPageProtocolTimeout(error) && !isPageMetaMissingError(error) && !isCurrentFrameTimedOutError(error)) throw error;
 				lastError = error;
-				const remainingAfterProbe = timeout - (Date.now() - startedAt);
-				if (remainingAfterProbe > 0) await sleep(Math.min(APP_READY_POLL_DELAY, remainingAfterProbe));
 			}
+			const remainingAfterProbe = timeout - (Date.now() - startedAt);
+			if (remainingAfterProbe > 0) await sleep(Math.min(APP_READY_POLL_DELAY, remainingAfterProbe));
 		}
 		throw lastError instanceof Error ? lastError : /* @__PURE__ */ new Error(`Timed out waiting App domain readiness after ${timeout}ms`);
 	}
@@ -2800,9 +3559,11 @@ var MiniProgram = class extends EventEmitter {
 				logChangeRouteDebug(`poll method=${method} url=${url ?? "<none>"} current=${page?.path ?? "<none>"}`);
 				if (matchesRouteChange({
 					currentPath: page?.path,
+					currentQuery: page?.query,
 					previousPath: currentPage?.path,
 					requestedUrl: url,
-					expectedRoute
+					expectedRoute,
+					expectedQuery: expectedRouteQuery
 				})) {
 					logChangeRouteDebug(`ready method=${method} url=${url ?? "<none>"} current=${page?.path ?? "<none>"}`);
 					return page;
@@ -2819,9 +3580,11 @@ var MiniProgram = class extends EventEmitter {
 					logChangeRouteDebug(`stack method=${method} url=${url ?? "<none>"} current=${stackTop.path}`);
 					if (matchesRouteChange({
 						currentPath: stackTop.path,
+						currentQuery: stackTop.query,
 						previousPath: currentPage?.path,
 						requestedUrl: url,
-						expectedRoute
+						expectedRoute,
+						expectedQuery: expectedRouteQuery
 					})) {
 						logChangeRouteDebug(`stack-ready method=${method} url=${url ?? "<none>"} current=${stackTop.path}`);
 						return stackTop;
@@ -2917,6 +3680,11 @@ var MiniProgram = class extends EventEmitter {
 		}
 		throw lastError;
 	}
+	/** 返回当前连接共享的 CDP 调试入口。 */
+	CDP() {
+		return this.cdp.session;
+	}
+	/** 发送原始自动化协议，沿用连接的请求超时及清理契约。 */
 	async send(method, params = {}, options) {
 		return options ? await this.connection.send(method, params, options) : await this.connection.send(method, params);
 	}
@@ -3120,7 +3888,7 @@ var SmartappApp = class {
 		return [];
 	}
 	async close() {
-		this.miniProgram?.disconnect();
+		await this.miniProgram?.disconnect();
 	}
 };
 //#endregion
@@ -3198,8 +3966,8 @@ var SmartappDevice = class {
 		return false;
 	}
 	async close() {
-		await this.driver.close?.();
-		this.driver.miniProgram?.disconnect();
+		const errors = (await Promise.allSettled([Promise.resolve().then(() => this.driver.close?.()), Promise.resolve().then(() => this.driver.miniProgram?.disconnect())])).filter((result) => result.status === "rejected").map((result) => result.reason);
+		if (errors.length) throw new AggregateError(errors, "Smartapp device cleanup failed");
 	}
 };
 //#endregion
@@ -3364,40 +4132,36 @@ const VERSION_CHECK_TIMEOUT = 3e4;
 const AUTOMATOR_LAUNCH_RETRIES = 3;
 const DEFAULT_RUNTIME_PROVIDER_ENV = "WEAPP_VITE_AUTOMATOR_RUNTIME_PROVIDER";
 const LEGACY_RUNTIME_PROVIDER_ENV = "WEAPP_VITE_E2E_RUNTIME_PROVIDER";
-const EXTENSION_CONTEXT_INVALIDATED_RE = /Extension context invalidated/i;
-const RETRYABLE_LAUNCH_PORT_RE = /Wait timed out after \d+ ms|Failed connecting to ws:\/\/127\.0\.0\.1:\d+|Failed connecting to devtools websocket endpoint|Failed to launch wechat web devTools, please make sure cliPath is correctly specified/i;
-const WINDOWS_BATCH_CLI_RE = /\.(?:bat|cmd)$/i;
 let localhostListenPatched = false;
-function isExtensionContextInvalidatedError(error) {
-	return error instanceof Error && EXTENSION_CONTEXT_INVALIDATED_RE.test(error.message);
-}
-function isRetryableAutomatorPortLaunchError(error) {
-	return error instanceof Error && RETRYABLE_LAUNCH_PORT_RE.test(error.message);
-}
 function retainPortLeaseUntilSessionClose(miniProgram, portLease) {
-	let released = false;
+	let released;
 	const release = async () => {
-		if (released) return;
-		released = true;
-		await portLease.release();
+		released ??= portLease.release().catch((error) => {
+			released = void 0;
+			throw error;
+		});
+		await released;
 	};
 	const target = miniProgram;
 	const rawClose = target.close;
 	const rawDisconnect = target.disconnect;
 	if (typeof rawClose !== "function" && typeof rawDisconnect !== "function") return false;
-	if (typeof rawDisconnect === "function") target.disconnect = function disconnectWithPortLeaseRelease() {
-		try {
-			return rawDisconnect.call(this);
-		} finally {
-			release();
-		}
-	};
+	if (typeof rawDisconnect === "function") {
+		let disconnecting;
+		target.disconnect = function disconnectWithPortLeaseRelease() {
+			disconnecting ??= (async () => {
+				await rawDisconnect.call(this);
+				await release();
+			})().catch((error) => {
+				disconnecting = void 0;
+				throw error;
+			});
+			return disconnecting;
+		};
+	}
 	if (typeof rawClose === "function") target.close = async function closeWithPortLeaseRelease() {
-		try {
-			return await rawClose.call(this);
-		} finally {
-			await release();
-		}
+		await rawClose.call(this);
+		await release();
 	};
 	return true;
 }
@@ -3418,25 +4182,6 @@ function patchNetListenToLoopback() {
 		return rawListen.apply(this, args);
 	};
 }
-/** IConnectOptions 的类型定义。 */
-function shouldUseWindowsCommandShell(cliPath) {
-	return isWindows && WINDOWS_BATCH_CLI_RE.test(cliPath);
-}
-function escapeWindowsCmdArg(arg) {
-	const escaped = arg.replace(/"/g, "\"\"").replace(/%/g, "%%");
-	return /[\s"&<>^|()]/.test(arg) ? `"${escaped}"` : escaped;
-}
-function resolveWindowsBatchSpawn(cliPath, args) {
-	return {
-		file: process.env.ComSpec || "cmd.exe",
-		args: [
-			"/d",
-			"/s",
-			"/c",
-			`"${[cliPath, ...args].map(escapeWindowsCmdArg).join(" ")}"`
-		]
-	};
-}
 function resolveRuntimeProvider(options) {
 	return options.runtimeProvider || process.env[DEFAULT_RUNTIME_PROVIDER_ENV] || process.env[LEGACY_RUNTIME_PROVIDER_ENV] || "devtools";
 }
@@ -3449,88 +4194,88 @@ var Launcher = class {
 			return await launchHeadlessAutomator({ projectPath: options.projectPath });
 		}
 		patchNetListenToLoopback();
-		if (options.port) return await this.launchWechatDevtools(options);
-		let lastError = null;
-		for (let attempt = 1; attempt <= AUTOMATOR_LAUNCH_RETRIES; attempt += 1) try {
-			return await this.launchWechatDevtools(options);
-		} catch (error) {
-			lastError = error;
-			if (!isRetryableAutomatorPortLaunchError(error) || attempt === AUTOMATOR_LAUNCH_RETRIES) throw error;
-		}
-		throw lastError instanceof Error ? lastError : new Error(String(lastError));
+		return await new OperationLifecycle(options.timeout ?? DEFAULT_TIMEOUT, "automator launch", options.signal).run(async (scope) => {
+			const attempts = options.port ? 1 : AUTOMATOR_LAUNCH_RETRIES;
+			for (let attempt = 1;; attempt += 1) {
+				scope.attempt();
+				try {
+					return await scope.step(() => this.launchWechatDevtools(options, scope));
+				} catch (error) {
+					scope.recordFailure(error);
+					scope.throwIfAborted();
+					if (error instanceof AggregateError || !isRecoverableOperationError(error) || attempt >= attempts) throw error;
+				}
+			}
+		});
 	}
-	async launchWechatDevtools(options) {
-		const { cliPath = await this.resolveCliPath(), timeout = DEFAULT_TIMEOUT, projectConfig = {}, ticket = "", cwd = "", account = "", trustProject = false } = options;
-		let { args = [], projectPath } = options;
-		const portLease = await acquireAutomatorPortLease(options.port);
+	async launchWechatDevtools(options, scope) {
+		const { cliPath = await scope.step(() => this.resolveCliPath(), { stage: "resolve-cli" }), projectConfig = {}, ticket = "", cwd = "", account = "", trustProject = false } = options;
+		const { args = [], projectPath } = options;
+		const portLease = await scope.step(() => acquireAutomatorPortLease(options.port), {
+			stage: "port-lease",
+			disposeLate: (lease) => lease.release()
+		});
+		const rawReleaseLease = portLease.release.bind(portLease);
+		let releasedLease;
+		portLease.release = () => releasedLease ??= rawReleaseLease().catch((error) => {
+			releasedLease = void 0;
+			throw error;
+		});
+		const connectionTasks = [];
+		const disconnectingConnections = /* @__PURE__ */ new WeakMap();
+		const disconnectConnection = (program) => {
+			const pending = disconnectingConnections.get(program);
+			if (pending) return pending;
+			const closing = Promise.resolve(program.disconnect?.()).catch((error) => {
+				disconnectingConnections.delete(program);
+				throw error;
+			});
+			disconnectingConnections.set(program, closing);
+			return closing;
+		};
+		const releaseConnectionsAndLease = async () => {
+			const results = await Promise.allSettled(connectionTasks);
+			const errors = (await Promise.allSettled(results.map((result) => result.status === "fulfilled" ? disconnectConnection(result.value) : Promise.resolve()))).filter((result) => result.status === "rejected").map((result) => result.reason);
+			if (errors.length) throw new AggregateError(errors, "Automator connections did not finish closing; port lease retained");
+			await portLease.release();
+		};
+		const disownLease = scope.own(releaseConnectionsAndLease, "port-lease");
 		let releasePortLeaseOnExit = true;
+		let releaseChild = async () => {};
+		let diagnoseFailure = (error) => error;
+		let failure;
+		let failed = false;
+		let result;
 		try {
 			const port = portLease.port;
 			if (!cliPath) throw new Error("Wechat web devTools not found, please specify cliPath option");
 			if (isWindows && endWith(cliPath, ".exe")) throw new Error("cliPath is not correct, it's usually named as 'cli' or 'cli.bat'");
 			if (!projectPath) throw new Error("projectPath is not provided");
 			const resolvedProjectPath = isRelative(projectPath) ? path.resolve(projectPath) : projectPath;
-			if (isRelative(projectPath)) projectPath = resolvedProjectPath;
-			if (!await import("node:fs/promises").then((fs) => fs.access(resolvedProjectPath).then(() => true).catch(() => false))) throw new Error(`Project path ${resolvedProjectPath} doesn't exist`);
-			if (!isEmpty(projectConfig)) await this.extendProjectConfig(projectConfig, resolvedProjectPath);
-			let processError = null;
-			let processExitCode = null;
-			let processSignal = null;
-			let successfulCliExitSettled = false;
+			if (!await scope.step(() => import("node:fs/promises").then((fs) => fs.access(resolvedProjectPath).then(() => true).catch(() => false)), { stage: "project" })) throw new Error(`Project path ${resolvedProjectPath} doesn't exist`);
+			if (!isEmpty(projectConfig)) await scope.step(() => this.extendProjectConfig(projectConfig, resolvedProjectPath), { stage: "project-config" });
+			scope.throwIfAborted();
 			let httpFallbackAttempted = false;
 			let httpFallbackError = null;
 			let targetPort = port;
-			const cliOutput = [];
-			args = resolveWechatDevtoolsBootstrapArgs(args);
-			try {
-				const spawnTarget = shouldUseWindowsCommandShell(cliPath) ? resolveWindowsBatchSpawn(cliPath, args) : {
-					file: cliPath,
-					args
-				};
-				const child = spawn(spawnTarget.file, spawnTarget.args, {
-					stdio: [
-						"ignore",
-						"pipe",
-						"pipe"
-					],
-					cwd: cwd || void 0,
-					...shouldUseWindowsCommandShell(cliPath) ? {
-						windowsHide: true,
-						windowsVerbatimArguments: true
-					} : {}
-				});
-				child.on("error", (error) => {
-					processError = error;
-				});
-				child.stdout?.on("data", (chunk) => {
-					cliOutput.push(String(chunk));
-				});
-				child.stderr?.on("data", (chunk) => {
-					cliOutput.push(String(chunk));
-				});
-				child.on("exit", (code, signal) => {
-					processExitCode = code;
-					processSignal = signal;
-					if (code !== 0 || signal) processError = /* @__PURE__ */ new Error(`DevTools cli exited unexpectedly with code ${code ?? "null"}${signal ? ` and signal ${signal}` : ""}`);
-					else successfulCliExitSettled = true;
-				});
-				child.unref();
-			} catch (error) {
-				processError = error;
-			}
+			const cli = spawnWechatCli(cliPath, args, cwd, scope);
+			diagnoseFailure = (error) => attachCliDiagnostics(error, cli, [ticket, account]);
+			releaseChild = cli.release;
 			let miniProgram = null;
 			let lastConnectError = null;
-			const readinessStartedAt = Date.now();
-			const resolveRemainingTimeout = () => Math.max(0, timeout - (Date.now() - readinessStartedAt));
-			await waitUntil(async () => {
+			const resolveRemainingTimeout = () => scope.remainingMs();
+			await scope.step(() => waitUntil(async () => {
+				scope.throwIfAborted();
 				try {
-					if (processError) return true;
-					if (successfulCliExitSettled && !httpFallbackAttempted) {
-						const servicePort = extractWechatDevtoolsServicePort(cliOutput.join("\n"));
+					if (cli.error) return true;
+					if (cli.success && readWechatLoginState(cli.output) === false) throw Object.assign(/* @__PURE__ */ new Error("DEVTOOLS_LOGIN_REQUIRED: need re-login"), { code: 10 });
+					if (cli.success && !httpFallbackAttempted) {
+						const servicePort = extractWechatDevtoolsServicePort(cli.output);
 						if (servicePort) {
 							httpFallbackAttempted = true;
 							try {
 								targetPort = await enableAutomatorViaHttp({
+									signal: scope.signal,
 									account,
 									autoPort: port,
 									projectPath: resolvedProjectPath,
@@ -3546,43 +4291,68 @@ var Launcher = class {
 					}
 					const connectTimeout = resolveRemainingTimeout();
 					if (connectTimeout <= 0) return false;
-					const candidate = await this.connectTool({
-						timeout: Math.min(3e3, connectTimeout),
-						wsEndpoint: `ws://127.0.0.1:${targetPort}`
+					const candidate = await scope.step(() => {
+						const connecting = this.connectTool({
+							signal: scope.signal,
+							timeout: Math.min(3e3, connectTimeout),
+							wsEndpoint: `ws://127.0.0.1:${targetPort}`
+						});
+						connectionTasks.push(connecting);
+						return connecting;
+					}, {
+						stage: "websocket",
+						disposeLate: disconnectConnection
 					});
+					let releasedCandidate;
+					const releaseCandidate = () => {
+						return releasedCandidate ??= disconnectConnection(candidate).catch((error) => {
+							releasedCandidate = void 0;
+							throw error;
+						});
+					};
+					const disownCandidate = scope.own(releaseCandidate, "websocket");
 					try {
 						const checkVersionTimeout = resolveRemainingTimeout();
 						if (checkVersionTimeout <= 0) {
-							candidate.disconnect();
+							await scope.step(releaseCandidate);
 							return false;
 						}
-						await candidate.checkVersion(Math.min(VERSION_CHECK_TIMEOUT, checkVersionTimeout));
+						await scope.step(() => candidate.checkVersion(Math.min(VERSION_CHECK_TIMEOUT, checkVersionTimeout)), { stage: "version" });
 						if (typeof candidate.waitForAppReady === "function") {
 							const appReadyTimeout = resolveRemainingTimeout();
 							if (appReadyTimeout <= 0) {
-								candidate.disconnect();
+								await scope.step(releaseCandidate);
 								return false;
 							}
-							await candidate.waitForAppReady(appReadyTimeout);
+							await scope.step(() => candidate.waitForAppReady(appReadyTimeout), { stage: "app-ready" });
 						}
 					} catch (error) {
-						candidate.disconnect();
+						try {
+							await scope.step(releaseCandidate);
+						} catch (cleanupError) {
+							if (cleanupError !== error) throw new AggregateError([error, cleanupError], "Automator validation and connection cleanup failed", { cause: error });
+							throw error;
+						}
+						disownCandidate();
 						lastConnectError = error;
-						if (isExtensionContextInvalidatedError(error)) return false;
+						if (isRecoverableOperationError(error)) return false;
 						throw error;
 					}
 					miniProgram = candidate;
 					return true;
 				} catch (error) {
 					lastConnectError = error;
+					scope.recordFailure(error);
+					scope.throwIfAborted();
+					if (error instanceof AggregateError || !isRecoverableOperationError(error)) throw error;
 					return false;
 				}
-			}, timeout, 1e3);
+			}, scope.remainingMs(), 1e3, scope.signal), { stage: "readiness" });
 			if (!miniProgram) {
 				if (httpFallbackError) throw httpFallbackError;
-				if (processError) throw new Error("Failed to launch wechat web devTools, please make sure cliPath is correctly specified");
+				if (cli.error) throw new Error("Failed to launch wechat web devTools, please make sure cliPath is correctly specified", { cause: cli.error });
 				if (lastConnectError) throw lastConnectError;
-				if (processExitCode !== null || processSignal) throw new Error("Failed to launch wechat web devTools, please make sure http port is open");
+				if (cli.exited) throw new Error("Failed to launch wechat web devTools, please make sure http port is open");
 				throw new Error("Failed connecting to devtools websocket endpoint");
 			}
 			const resolvedMiniProgram = miniProgram;
@@ -3592,33 +4362,47 @@ var Launcher = class {
 				wsEndpoint: `ws://127.0.0.1:${targetPort}`
 			});
 			releasePortLeaseOnExit = !retainPortLeaseUntilSessionClose(resolvedMiniProgram, portLease);
-			await sleep$1(5e3);
-			return resolvedMiniProgram;
-		} finally {
-			if (releasePortLeaseOnExit) await portLease.release();
+			if (!releasePortLeaseOnExit) disownLease();
+			result = resolvedMiniProgram;
+		} catch (error) {
+			failed = true;
+			failure = diagnoseFailure(error);
 		}
+		const cleanupErrors = [];
+		try {
+			await scope.step(releaseChild);
+		} catch (error) {
+			if (!failed || error !== failure) cleanupErrors.push(error);
+		}
+		if (releasePortLeaseOnExit) try {
+			await scope.step(releaseConnectionsAndLease);
+			disownLease();
+		} catch (error) {
+			if ((!failed || error !== failure) && !cleanupErrors.includes(error)) cleanupErrors.push(error);
+		}
+		if (cleanupErrors.length) {
+			if (failed) throw new AggregateError([failure, ...cleanupErrors], "Automator launch and resource cleanup failed", { cause: failure });
+			throw new AggregateError(cleanupErrors, "Automator launch resource cleanup failed");
+		}
+		if (failed) throw failure;
+		return result;
 	}
 	async connect(options) {
 		if (normalizePlatform(options.platform) === "swan") return await new SwanLauncher().connect(options);
-		const timeout = options.timeout ?? DEFAULT_TIMEOUT;
-		const deadlineAt = performance.now() + timeout;
-		const miniProgram = await this.connectTool({
-			...options,
-			timeout
-		});
-		try {
-			const remaining = Math.ceil(deadlineAt - performance.now());
-			if (remaining <= 0) throw new Error(`Timed out connecting to automator after ${timeout}ms`);
-			await miniProgram.checkVersion(remaining);
+		return await new OperationLifecycle(options.timeout ?? DEFAULT_TIMEOUT, "automator connect", options.signal).run(async (scope) => {
+			scope.attempt();
+			const miniProgram = await scope.step(() => this.connectTool({
+				...options,
+				signal: scope.signal,
+				timeout: scope.remainingMs()
+			}), {
+				stage: "websocket",
+				disposeLate: (program) => program.disconnect()
+			});
+			scope.own(() => miniProgram.disconnect(), "websocket");
+			await scope.step(() => miniProgram.checkVersion(scope.remainingMs()), { stage: "version" });
 			return miniProgram;
-		} catch (error) {
-			try {
-				miniProgram.disconnect();
-			} catch (cleanupError) {
-				throw new AggregateError([error, cleanupError], "Automator connection and cleanup both failed", { cause: error });
-			}
-			throw error;
-		}
+		});
 	}
 	async extendProjectConfig(projectConfig, projectPath) {
 		const projectConfigPath = path.resolve(projectPath, "project.config.json");
@@ -3630,9 +4414,9 @@ var Launcher = class {
 	}
 	async connectTool(options) {
 		try {
-			return new MiniProgram(await Connection.create(options.wsEndpoint, options.timeout));
-		} catch {
-			throw new Error(`Failed connecting to ${options.wsEndpoint}, check if target project window is opened with automation enabled`);
+			return new MiniProgram(await Connection.create(options.wsEndpoint, options.timeout, options.signal));
+		} catch (cause) {
+			throw new Error(`Failed connecting to ${options.wsEndpoint}, check if target project window is opened with automation enabled`, { cause });
 		}
 	}
 	async resolveCliPath() {
@@ -3674,4 +4458,4 @@ var Automator = class {
 */
 const SmartappAutomator = smartappAutomatorRuntime;
 //#endregion
-export { Automator, Connection, ContextElement, CustomElement, Element, InputElement, Launcher, MiniProgram, MovableViewElement, Native, Page, ScrollViewElement, SliderElement, SmartappAutomator, SwiperElement, SwitchElement, TextareaElement, Transport, decodeQrCode, extractPluginId, isPluginPath, normalizePlatform, printQrCode };
+export { Automator, Connection, ContextElement, CustomElement, Element, InputElement, Launcher, MiniProgram, MovableViewElement, Native, OPERATION_TIMEOUT_CODE, OperationLifecycle, Page, ScrollViewElement, SliderElement, SmartappAutomator, SwiperElement, SwitchElement, TextareaElement, Transport, acquireAutomatorPortLease, classifyOperationError, decodeQrCode, extractPluginId, isPluginPath, isRecoverableOperationError, normalizePlatform, printQrCode, readWechatLoginState };