dsh-mobile 0.3.0 → 0.3.2

package/lib/index.mjs

@@ -11,7 +11,7 @@ import { createSocket } from "node:dgram";
 import { homedir, hostname, networkInterfaces } from "node:os";
 import { createServer as createServer$1, request } from "node:http";
 import { createServer as createServer$2 } from "node:https";
-import { Transform } from "node:stream";
+import { Transform, finished } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { createGzip, gzip } from "node:zlib";
 import Bonjour from "bonjour-service";
@@ -1250,14 +1250,33 @@ const EXTENSION_LIMITS = Object.freeze({
 });
 /** A misbehaving host activation must not wedge the local watcher forever. */
 const HOST_ACTIVATION_TIMEOUT_MS = 5e3;
-async function withActivationTimeout(promise, id) {
+/** The previous Host outlives the hidden-page refresh interval and one timed refresh. */
+const RETIRED_GENERATION_TTL_MS = 6e5;
+/** Extension teardown is advisory and must never stop watcher progress. */
+const HOST_TEARDOWN_TIMEOUT_MS = 2e3;
+async function withActivationTimeout(promise, id, signal) {
 	let timer;
+	let onAbort;
 	try {
-		return await Promise.race([promise, new Promise((_, reject) => {
-			timer = setTimeout(() => reject(new MobileExtensionError("host_load_timeout", `extension ${id} activation timed out`, 500)), HOST_ACTIVATION_TIMEOUT_MS);
-		})]);
+		return await Promise.race([
+			promise,
+			new Promise((_, reject) => {
+				timer = setTimeout(() => reject(new MobileExtensionError("host_load_timeout", `extension ${id} activation timed out`, 500)), HOST_ACTIVATION_TIMEOUT_MS);
+			}),
+			new Promise((_, reject) => {
+				const abort = () => {
+					reject(new MobileExtensionError("host_activation_closed", `extension ${id} activation is closed`, 409));
+				};
+				if (signal.aborted) abort();
+				else {
+					onAbort = abort;
+					signal.addEventListener("abort", abort, { once: true });
+				}
+			})
+		]);
 	} finally {
 		if (timer !== void 0) clearTimeout(timer);
+		if (onAbort !== void 0) signal.removeEventListener("abort", onAbort);
 	}
 }
 /** A controlled business failure returned by an extension action or route. */
@@ -1346,21 +1365,92 @@ async function optionalFile(root, name, maximum, field) {
 }
 async function optionalBytes(root, name, maximum, field) {
 	const path = await optionalFile(root, name, maximum, field);
-	return path === void 0 ? Buffer.alloc(0) : readFile(path);
+	return path === void 0 ? void 0 : readFile(path);
+}
+function assertRealPathWithin(rootReal, targetReal, field) {
+	const relation = relative(rootReal, targetReal);
+	if (relation === "" || relation.startsWith("..") || isAbsolute(relation)) throw new MobileExtensionError("invalid_extension_path", `${field} escapes extension directory`);
+}
+async function realExtensionRoot(directory) {
+	const root = resolve(directory);
+	const info = await lstat(root);
+	if (!info.isDirectory() || info.isSymbolicLink()) throw new MobileExtensionError("invalid_extension", "extension directory must be real");
+	return realpath(root);
+}
+async function assetSnapshot(extensionRootReal) {
+	const assetsPath = join(extensionRootReal, "assets");
+	let assetsInfo;
+	try {
+		assetsInfo = await lstat(assetsPath);
+	} catch (error) {
+		if (error.code === "ENOENT") return /* @__PURE__ */ new Map();
+		throw error;
+	}
+	if (!assetsInfo.isDirectory() || assetsInfo.isSymbolicLink()) throw new MobileExtensionError("invalid_extension", "assets must be a real directory");
+	const assetsReal = await realpath(assetsPath);
+	assertRealPathWithin(extensionRootReal, assetsReal, "assets");
+	const snapshots = /* @__PURE__ */ new Map();
+	const visit = async (directoryReal, prefix) => {
+		assertRealPathWithin(extensionRootReal, directoryReal, "asset directory");
+		const handle = await opendir(directoryReal);
+		const entries = [];
+		try {
+			for await (const entry of handle) entries.push(entry);
+		} finally {
+			await handle.close().catch(() => void 0);
+		}
+		entries.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+		for (const entry of entries) {
+			const path = join(directoryReal, entry.name);
+			const info = await lstat(path);
+			if (info.isSymbolicLink()) throw new MobileExtensionError("invalid_extension_path", "asset escapes extension directory");
+			const targetReal = await realpath(path);
+			assertRealPathWithin(extensionRootReal, targetReal, "asset");
+			const key = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+			if (info.isDirectory()) {
+				await visit(targetReal, key);
+				continue;
+			}
+			if (!info.isFile() || info.size > EXTENSION_LIMITS.asset) throw new MobileExtensionError("invalid_extension", "asset must be a regular file within its size limit");
+			const body = await readFile(targetReal);
+			snapshots.set(key, Object.freeze({
+				body,
+				digest: createHash("sha256").update(body).digest("hex"),
+				name: entry.name
+			}));
+		}
+	};
+	await visit(assetsReal, "");
+	return snapshots;
 }
 async function extensionFingerprint(directory) {
-	const manifestFile = await regularFile$1(join(directory, "extension.json"), EXTENSION_LIMITS.manifest, "extension.json");
+	const root = await realExtensionRoot(directory);
+	const manifestFile = await regularFile$1(join(root, "extension.json"), EXTENSION_LIMITS.manifest, "extension.json");
 	const manifestBody = await readFile(manifestFile.path);
 	const manifest = parseExtensionManifest(JSON.parse(manifestBody.toString("utf8")));
-	if (manifest.id !== basename(resolve(directory))) throw new MobileExtensionError("invalid_manifest", "extension id must match its directory name");
-	const [host, script, style] = await Promise.all([
-		optionalBytes(directory, "host.mjs", EXTENSION_LIMITS.script, "host.mjs"),
-		optionalBytes(directory, "mobile.js", EXTENSION_LIMITS.script, "mobile.js"),
-		optionalBytes(directory, "mobile.css", EXTENSION_LIMITS.css, "mobile.css")
+	if (manifest.id !== basename(root)) throw new MobileExtensionError("invalid_manifest", "extension id must match its directory name");
+	const [host, script, style, assets] = await Promise.all([
+		optionalBytes(root, "host.mjs", EXTENSION_LIMITS.script, "host.mjs"),
+		optionalBytes(root, "mobile.js", EXTENSION_LIMITS.script, "mobile.js"),
+		optionalBytes(root, "mobile.css", EXTENSION_LIMITS.css, "mobile.css"),
+		assetSnapshot(root)
 	]);
+	const digest = createHash("sha256").update(`manifest:${manifestBody.byteLength}:`).update(createHash("sha256").update(manifestBody).digest());
+	for (const [name, body] of [
+		["host", host],
+		["script", script],
+		["style", style]
+	]) {
+		digest.update(`\0${name}:${body?.byteLength ?? -1}:`);
+		if (body !== void 0) digest.update(createHash("sha256").update(body).digest());
+	}
+	for (const [name, asset] of assets) digest.update(`\0asset:${Buffer.byteLength(name)}:${name}:${asset.body.byteLength}:${asset.digest}`);
 	return {
 		manifest,
-		digest: createHash("sha256").update(manifestBody).update(host).update(script).update(style).digest("hex")
+		digest: digest.digest("hex"),
+		assets,
+		...script === void 0 ? {} : { scriptBody: script },
+		...style === void 0 ? {} : { styleBody: style }
 	};
 }
 function routeKey(route) {
@@ -1415,20 +1505,49 @@ function validateDefinition(definition) {
 		...routes.length === 0 ? {} : { routes: Object.freeze(routes) }
 	});
 }
-function combineSignals(first, second) {
-	if (first.aborted || second.aborted) return AbortSignal.abort(first.aborted ? first.reason : second.reason);
-	return AbortSignal.any([first, second]);
+function combineSignalLifetime(first, second) {
+	if (first.aborted || second.aborted) {
+		const aborted = new AbortController();
+		aborted.abort(first.aborted ? first.reason : second.reason);
+		return {
+			signal: aborted.signal,
+			cleanup: () => void 0
+		};
+	}
+	const controller = new AbortController();
+	const cleanup = () => {
+		first.removeEventListener("abort", abortFirst);
+		second.removeEventListener("abort", abortSecond);
+	};
+	const abortFirst = () => {
+		cleanup();
+		controller.abort(first.reason);
+	};
+	const abortSecond = () => {
+		cleanup();
+		controller.abort(second.reason);
+	};
+	first.addEventListener("abort", abortFirst, { once: true });
+	second.addEventListener("abort", abortSecond, { once: true });
+	return {
+		signal: controller.signal,
+		cleanup
+	};
 }
 /** Host registry and service consumed by both npm plugins and local extensions. */
 var MobileAccessService = class extends Service {
 	registered = /* @__PURE__ */ new Map();
 	local = /* @__PURE__ */ new Map();
+	retired = /* @__PURE__ */ new Map();
 	failures = /* @__PURE__ */ new Map();
-	contentHash = "";
+	contentListeners = /* @__PURE__ */ new Set();
+	contentHash = createHash("sha256").update("").digest("hex");
 	localRoot;
 	localContext;
 	localTimer;
 	localRefreshing;
+	localRefreshAbort;
+	localLifecycle = 0;
 	localClosed = true;
 	constructor(ctx) {
 		super(ctx, "mobileAccess");
@@ -1454,9 +1573,21 @@ var MobileAccessService = class extends Service {
 	contentDigest() {
 		return this.contentHash;
 	}
+	/** Subscribe to committed extension generation changes. */
+	onContentChanged(listener) {
+		this.contentListeners.add(listener);
+		return () => {
+			this.contentListeners.delete(listener);
+		};
+	}
 	updateContentHash() {
 		const parts = [...[...this.registered.values()].map((entry) => entry.definition.id), ...[...this.local.values()].map((active) => `${active.manifest.id}:${active.digest}`)];
-		this.contentHash = createHash("sha256").update(parts.sort().join("|")).digest("hex");
+		const next = createHash("sha256").update(parts.sort().join("|")).digest("hex");
+		if (next === this.contentHash) return;
+		this.contentHash = next;
+		for (const listener of this.contentListeners) try {
+			listener();
+		} catch {}
 	}
 	/** Return the current client-facing manifest, deterministically sorted by id. */
 	manifest() {
@@ -1470,8 +1601,9 @@ var MobileAccessService = class extends Service {
 		});
 		for (const active of this.local.values()) entries.set(active.manifest.id, {
 			...active.manifest,
-			...active.scriptFile === void 0 ? {} : { scriptUrl: `/mobile-access/extensions/${active.manifest.id}/mobile.js` },
-			...active.styleFile === void 0 ? {} : { styleUrl: `/mobile-access/extensions/${active.manifest.id}/mobile.css` },
+			generation: active.digest,
+			...active.scriptBody === void 0 ? {} : { scriptUrl: `/mobile-access/extensions/${active.manifest.id}/mobile.js?generation=${active.digest}` },
+			...active.styleBody === void 0 ? {} : { styleUrl: `/mobile-access/extensions/${active.manifest.id}/mobile.css?generation=${active.digest}` },
 			assetsUrl: `/mobile-access/extensions/${active.manifest.id}/assets/`
 		});
 		return [...entries.values()].sort((left, right) => left.id.localeCompare(right.id));
@@ -1484,49 +1616,52 @@ var MobileAccessService = class extends Service {
 		});
 	}
 	/** Locate one active extension. */
-	extension(id) {
+	extension(id, generation) {
+		if (generation !== void 0) {
+			const current = this.local.get(id);
+			if (current?.digest === generation) return current;
+			const previous = this.retired.get(id)?.active;
+			return previous?.digest === generation ? previous : void 0;
+		}
 		return this.local.get(id) ?? this.registered.get(id)?.definition;
 	}
 	/** Return the active local generation signal for gateway cancellation wiring. */
-	signal(id) {
-		return this.local.get(id)?.controller.signal;
+	signal(id, generation) {
+		const extension = this.extension(id, generation);
+		return extension !== void 0 && "host" in extension ? extension.controller.signal : void 0;
 	}
 	/** Read a local client entry after validating that it remains inside its directory. */
-	async readClientFile(id, kind, signal) {
+	async readClientFile(id, kind, signal, generation) {
 		signal?.throwIfAborted();
-		const active = this.local.get(id);
-		if (active === void 0) throw new MobileExtensionError("extension_not_found", "extension not found", 404);
-		const path = kind === "script" ? active.scriptFile : active.styleFile;
-		if (path === void 0) throw new MobileExtensionError("extension_asset_not_found", "extension asset not found", 404);
-		const file = await regularFile$1(path, kind === "script" ? EXTENSION_LIMITS.script : EXTENSION_LIMITS.css, kind);
-		const body = await readFile(file.path, { signal });
+		const selected = this.extension(id, generation);
+		const active = selected !== void 0 && "host" in selected ? selected : void 0;
+		if (active === void 0) throw new MobileExtensionError("extension_generation_not_found", "extension generation not found", 404);
+		const snapshot = kind === "script" ? active.scriptBody : active.styleBody;
+		if (snapshot === void 0) throw new MobileExtensionError("extension_asset_not_found", "extension asset not found", 404);
+		const body = Buffer.from(snapshot);
 		return {
 			body,
 			digest: createHash("sha256").update(body).digest("hex")
 		};
 	}
-	/** Read a local static asset after containment and size checks. */
-	async readAsset(id, assetPath, signal) {
+	/** Read a generation-pinned static asset from its validated snapshot. */
+	async readAsset(id, assetPath, signal, generation) {
 		signal?.throwIfAborted();
-		const active = this.local.get(id);
-		if (active === void 0) throw new MobileExtensionError("extension_not_found", "extension not found", 404);
-		let file;
-		try {
-			file = await containedPath(join(active.directory, "assets"), assetPath, EXTENSION_LIMITS.asset, "asset");
-		} catch (error) {
-			if (error.code === "ENOENT") throw new MobileExtensionError("extension_asset_not_found", "extension asset not found", 404);
-			throw error;
-		}
-		const body = await readFile(file.path, { signal });
+		const selected = this.extension(id, generation);
+		const active = selected !== void 0 && "host" in selected ? selected : void 0;
+		if (active === void 0) throw new MobileExtensionError("extension_generation_not_found", "extension generation not found", 404);
+		const normalized = normalizeRelativePath(assetPath, "asset");
+		const asset = active.assets.get(normalized);
+		if (asset === void 0) throw new MobileExtensionError("extension_asset_not_found", "extension asset not found", 404);
 		return {
-			body,
-			digest: createHash("sha256").update(body).digest("hex"),
-			name: basename(file.path)
+			body: Buffer.from(asset.body),
+			digest: asset.digest,
+			name: asset.name
 		};
 	}
 	/** Invoke one action after parsing its input and binding the request lifetime. */
-	async invoke(id, actionName, input, context) {
-		const extension = this.extension(id);
+	async invoke(id, actionName, input, context, generation) {
+		const extension = this.extension(id, generation);
 		if (extension === void 0) throw new MobileExtensionError("extension_not_found", "extension not found", 404);
 		const action = ("host" in extension ? extension.host : extension).actions?.[actionName];
 		if (action === void 0) throw new MobileExtensionError("action_not_found", "action not found", 404);
@@ -1536,7 +1671,8 @@ var MobileAccessService = class extends Service {
 		} catch {
 			throw new MobileExtensionError("invalid_action_input", "action input is invalid", 400);
 		}
-		const signal = "host" in extension ? combineSignals(extension.controller.signal, context.signal) : context.signal;
+		const lifetime = "host" in extension ? combineSignalLifetime(extension.controller.signal, context.signal) : void 0;
+		const signal = lifetime?.signal ?? context.signal;
 		try {
 			return await action.run({
 				...context,
@@ -1545,39 +1681,53 @@ var MobileAccessService = class extends Service {
 		} catch (error) {
 			if (error instanceof MobileExtensionError) throw error;
 			throw new MobileExtensionError("extension_failed", "extension action failed", 500);
+		} finally {
+			lifetime?.cleanup();
 		}
 	}
 	/** Match one route and invoke it with a generation-bound abort signal. */
-	async route(id, method, pathname, request) {
-		const extension = this.extension(id);
+	async route(id, method, pathname, request, generation) {
+		const extension = this.extension(id, generation);
 		if (extension === void 0) throw new MobileExtensionError("extension_not_found", "extension not found", 404);
 		const route = ("host" in extension ? extension.host : extension).routes?.find((candidate) => {
 			if (candidate.method !== method) return false;
 			return (candidate.kind ?? "exact") === "exact" ? candidate.path === pathname : pathname === candidate.path || pathname.startsWith(`${candidate.path}/`);
 		});
 		if (route === void 0) throw new MobileExtensionError("route_not_found", "route not found", 404);
+		const lifetime = "host" in extension ? combineSignalLifetime(extension.controller.signal, request.signal) : void 0;
+		let releaseLifetime = true;
 		try {
-			const routeRequest = "host" in extension ? {
+			const routeRequest = lifetime === void 0 ? request : {
 				...request,
-				signal: combineSignals(extension.controller.signal, request.signal)
-			} : request;
+				signal: lifetime.signal
+			};
 			const result = await route.handle(routeRequest);
 			if (result === null || typeof result !== "object" || typeof result.body !== "string" && !(result.body instanceof Uint8Array) && !isReadable(result.body)) throw new MobileExtensionError("invalid_route_response", "extension returned an invalid response", 500);
+			if (lifetime !== void 0 && isReadable(result.body)) {
+				releaseLifetime = false;
+				releaseSignalLifetimeWhenStreamSettles(result.body, lifetime.cleanup);
+			}
 			return result;
 		} catch (error) {
 			if (error instanceof MobileExtensionError) throw error;
 			throw new MobileExtensionError("extension_failed", "extension route failed", 500);
+		} finally {
+			if (releaseLifetime) lifetime?.cleanup();
 		}
 	}
 	/** Start the local directory watcher; an absent directory is intentionally inert. */
 	async startLocal(root, context) {
-		if (this.localRoot !== void 0 && resolve(this.localRoot) !== resolve(root)) await this.stopLocal();
+		const targetRoot = resolve(root);
+		if (this.localRoot !== void 0 && resolve(this.localRoot) !== targetRoot) await this.stopLocal();
 		if (this.localTimer !== void 0) clearInterval(this.localTimer);
-		this.localRoot = resolve(root);
+		const lifecycle = ++this.localLifecycle;
+		this.localRoot = targetRoot;
 		this.localContext = context;
 		this.localClosed = false;
 		await mkdir(this.localRoot, { recursive: true });
+		if (this.localClosed || this.localLifecycle !== lifecycle || this.localRoot !== targetRoot || this.localContext !== context) return;
 		await this.refreshLocal();
+		if (this.localClosed || this.localLifecycle !== lifecycle || this.localRoot !== targetRoot || this.localContext !== context) return;
 		this.localTimer = setInterval(() => {
 			this.refreshLocal();
 		}, 2e3);
@@ -1586,23 +1736,43 @@ var MobileAccessService = class extends Service {
 	/** Stop the watcher and abort every local host generation. */
 	async stopLocal() {
 		this.localClosed = true;
+		const lifecycle = ++this.localLifecycle;
 		if (this.localTimer !== void 0) clearInterval(this.localTimer);
 		this.localTimer = void 0;
-		const previous = [...this.local.values()];
+		const refreshing = this.localRefreshing;
+		this.localRefreshAbort?.abort();
+		const previous = [...this.local.values(), ...[...this.retired.values()].map((entry) => entry.active)];
+		this.local.clear();
+		for (const entry of this.retired.values()) clearTimeout(entry.timer);
+		this.retired.clear();
+		this.failures.clear();
+		this.updateContentHash();
+		await Promise.allSettled([abortAndDisposeLocal(previous), ...refreshing === void 0 ? [] : [refreshing]]);
+		if (this.localLifecycle !== lifecycle) return;
+		const late = [...this.local.values(), ...[...this.retired.values()].map((entry) => entry.active)];
 		this.local.clear();
+		for (const entry of this.retired.values()) clearTimeout(entry.timer);
+		this.retired.clear();
 		this.failures.clear();
-		await disposeLocal(previous);
+		this.updateContentHash();
+		await abortAndDisposeLocal(late);
+		if (this.localTimer !== void 0) clearInterval(this.localTimer);
+		this.localTimer = void 0;
 	}
 	/** Refresh all local extensions atomically; failures keep the previous snapshot. */
 	refreshLocal() {
 		if (this.localRefreshing !== void 0) return this.localRefreshing;
-		this.localRefreshing = this.stageAndCommit().finally(() => {
-			this.localRefreshing = void 0;
+		const controller = new AbortController();
+		this.localRefreshAbort = controller;
+		const refreshing = this.stageAndCommit(controller.signal).finally(() => {
+			if (this.localRefreshing === refreshing) this.localRefreshing = void 0;
+			if (this.localRefreshAbort === controller) this.localRefreshAbort = void 0;
 		});
-		return this.localRefreshing;
+		this.localRefreshing = refreshing;
+		return refreshing;
 	}
-	async stageAndCommit() {
-		if (this.localClosed || this.localRoot === void 0 || this.localContext === void 0) return;
+	async stageAndCommit(signal) {
+		if (this.localClosed || signal.aborted || this.localRoot === void 0 || this.localContext === void 0) return;
 		let names = [];
 		try {
 			const directory = await opendir(this.localRoot);
@@ -1620,19 +1790,29 @@ var MobileAccessService = class extends Service {
 		let failingName = "local";
 		try {
 			for (const name of names) {
+				signal.throwIfAborted();
 				failingName = name;
 				const directory = join(this.localRoot, name);
 				const fingerprint = await extensionFingerprint(directory);
-				const previous = this.local.get(fingerprint.manifest.id);
-				if (previous?.directory === resolve(directory) && previous.digest === fingerprint.digest) staged.push(previous);
+				const current = this.local.get(fingerprint.manifest.id);
+				const retired = this.retired.get(fingerprint.manifest.id)?.active;
+				const previous = current?.digest === fingerprint.digest ? current : retired?.digest === fingerprint.digest ? retired : void 0;
+				if (previous?.digest === fingerprint.digest) staged.push(previous);
 				else {
-					const fresh = await loadLocalExtension(directory, this.localContext, fingerprint);
+					const fresh = await loadLocalExtension(directory, this.localContext, fingerprint, signal);
+					try {
+						signal.throwIfAborted();
+						if ((await extensionFingerprint(directory)).digest !== fingerprint.digest) throw new MobileExtensionError("extension_changed_during_activation", `extension ${fingerprint.manifest.id} changed during activation`, 409);
+					} catch (error) {
+						await abortAndDisposeLocal([fresh]);
+						throw error;
+					}
 					staged.push(fresh);
 					stagedFresh.push(fresh);
 				}
 			}
-			if (this.localClosed || this.localRoot === void 0 || this.localContext === void 0) {
-				await disposeLocal(stagedFresh);
+			if (this.localClosed || signal.aborted || this.localRoot === void 0 || this.localContext === void 0) {
+				await abortAndDisposeLocal(stagedFresh);
 				return;
 			}
 			const duplicate = /* @__PURE__ */ new Set();
@@ -1641,42 +1821,106 @@ var MobileAccessService = class extends Service {
 				duplicate.add(entry.manifest.id);
 			}
 			const previous = [...this.local.values()];
+			for (const entry of staged) {
+				const retired = this.retired.get(entry.manifest.id);
+				if (retired?.active === entry) {
+					clearTimeout(retired.timer);
+					this.retired.delete(entry.manifest.id);
+				}
+			}
+			const stagedIds = new Set(staged.map((entry) => entry.manifest.id));
+			const removed = [];
+			for (const entry of previous) {
+				if (staged.includes(entry)) continue;
+				if (stagedIds.has(entry.manifest.id)) {
+					this.retire(entry);
+					continue;
+				}
+				removed.push(entry);
+				const retired = this.retired.get(entry.manifest.id);
+				if (retired !== void 0) {
+					clearTimeout(retired.timer);
+					this.retired.delete(entry.manifest.id);
+					removed.push(retired.active);
+				}
+			}
 			this.local.clear();
 			for (const entry of staged) this.local.set(entry.manifest.id, entry);
 			for (const entry of staged) this.failures.delete(entry.manifest.id);
 			for (const name of names) this.failures.delete(name);
 			for (const failure of this.failures.keys()) if (failure !== "local" && !names.includes(failure)) this.failures.delete(failure);
 			this.failures.delete("local");
-			await disposeLocal(previous.filter((entry) => !staged.includes(entry)));
+			if (removed.length > 0) abortAndDisposeLocal(removed);
 			this.updateContentHash();
 		} catch (error) {
-			await disposeLocal(stagedFresh);
+			await abortAndDisposeLocal(stagedFresh);
+			if (this.localClosed || signal.aborted) return;
 			const message = error instanceof Error ? error.message : String(error);
 			this.failures.set(failingName, message);
 			if (!(error instanceof MobileExtensionError)) this.ctx.logger.warn(error instanceof Error ? error : new Error(String(error)));
 		}
 	}
+	retire(active) {
+		const previous = this.retired.get(active.manifest.id);
+		if (previous?.active === active) return;
+		if (previous !== void 0) {
+			clearTimeout(previous.timer);
+			this.retired.delete(active.manifest.id);
+			abortAndDisposeLocal([previous.active]);
+		}
+		const timer = setTimeout(() => {
+			if (this.retired.get(active.manifest.id)?.active !== active) return;
+			this.retired.delete(active.manifest.id);
+			abortAndDisposeLocal([active]);
+		}, RETIRED_GENERATION_TTL_MS);
+		timer.unref();
+		this.retired.set(active.manifest.id, {
+			active,
+			timer
+		});
+	}
 };
 function isReadable(value) {
 	return value !== null && typeof value === "object" && typeof value.pipe === "function";
 }
-async function disposeLocal(entries) {
+function releaseSignalLifetimeWhenStreamSettles(stream, cleanup) {
+	let stopObserving;
+	stopObserving = finished(stream, () => {
+		stopObserving?.();
+		cleanup();
+	});
+}
+function invokeCleanups(cleanups) {
+	const pending = [];
+	for (const cleanup of [...cleanups].reverse()) try {
+		pending.push(Promise.resolve(cleanup()));
+	} catch {}
+	return pending;
+}
+async function settleBounded(pending, timeoutMs) {
+	if (pending.length === 0) return;
+	let timer;
+	await Promise.race([Promise.allSettled(pending), new Promise((resolveTimeout) => {
+		timer = setTimeout(resolveTimeout, timeoutMs);
+	})]);
+	if (timer !== void 0) clearTimeout(timer);
+}
+async function abortAndDisposeLocal(entries) {
+	const pending = [];
 	for (const entry of entries) {
 		entry.controller.abort();
-		for (const cleanup of [...entry.cleanups].reverse()) try {
-			await cleanup();
-		} catch {}
+		pending.push(...invokeCleanups(entry.cleanups));
 	}
+	await settleBounded(pending, HOST_TEARDOWN_TIMEOUT_MS);
 }
-async function loadLocalExtension(directory, context, known) {
-	const root = resolve(directory);
-	const rootStat = await lstat(root);
-	if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new MobileExtensionError("invalid_extension", "extension directory must be real");
+async function loadLocalExtension(directory, context, known, parentSignal) {
+	const root = await realExtensionRoot(directory);
 	const manifestFile = await regularFile$1(join(root, "extension.json"), EXTENSION_LIMITS.manifest, "extension.json");
 	const manifest = known?.manifest ?? parseExtensionManifest(JSON.parse(await readFile(manifestFile.path, "utf8")));
 	if (manifest.id !== basename(root)) throw new MobileExtensionError("invalid_manifest", "extension id must match its directory name");
-	const scriptFile = await optionalFile(root, "mobile.js", EXTENSION_LIMITS.script, "mobile.js");
-	const styleFile = await optionalFile(root, "mobile.css", EXTENSION_LIMITS.css, "mobile.css");
+	const scriptBody = known === void 0 ? await optionalFile(root, "mobile.js", EXTENSION_LIMITS.script, "mobile.js").then((path) => path === void 0 ? void 0 : readFile(path)) : known.scriptBody;
+	const styleBody = known === void 0 ? await optionalFile(root, "mobile.css", EXTENSION_LIMITS.css, "mobile.css").then((path) => path === void 0 ? void 0 : readFile(path)) : known.styleBody;
+	const assets = known?.assets ?? await assetSnapshot(root);
 	const hostFile = await optionalFile(root, "host.mjs", EXTENSION_LIMITS.script, "host.mjs");
 	const controller = new AbortController();
 	const actions = {};
@@ -1684,43 +1928,60 @@ async function loadLocalExtension(directory, context, known) {
 	const cleanups = [];
 	const pendingEffects = [];
 	let activationOpen = true;
+	const onParentAbort = () => {
+		controller.abort(parentSignal?.reason);
+	};
+	if (parentSignal?.aborted === true) onParentAbort();
+	else parentSignal?.addEventListener("abort", onParentAbort, { once: true });
+	const ensureActivationOpen = () => {
+		if (!activationOpen || controller.signal.aborted) throw new MobileExtensionError("host_activation_closed", `extension ${manifest.id} activation is closed`, 409);
+	};
 	const api = {
 		manifest,
 		context,
 		schema: z,
 		signal: controller.signal,
 		action(name, spec) {
+			ensureActivationOpen();
 			if (actions[name] !== void 0) throw new MobileExtensionError("duplicate_action", `duplicate action ${name}`);
 			actions[name] = spec;
 		},
 		route(spec) {
+			ensureActivationOpen();
 			routes.push(spec);
 		},
 		effect(setup) {
+			ensureActivationOpen();
 			const result = setup();
 			if (result instanceof Promise) pendingEffects.push(result.then(async (cleanup) => {
 				if (typeof cleanup !== "function") return;
 				if (activationOpen) cleanups.push(cleanup);
 				else await cleanup();
 			}));
-			else if (typeof result === "function") cleanups.push(result);
+			else if (typeof result === "function") {
+				if (activationOpen) cleanups.push(result);
+				else Promise.resolve(result()).catch(() => void 0);
+			}
 		}
 	};
 	try {
 		const activate = async () => {
+			controller.signal.throwIfAborted();
 			if (hostFile !== void 0) {
 				const digest = createHash("sha256").update(await readFile(hostFile)).digest("hex");
+				controller.signal.throwIfAborted();
 				let imported;
 				try {
 					imported = await import(`${pathToFileURL(hostFile).href}?dsh_generation=${digest}`);
 				} catch {
 					throw new MobileExtensionError("host_load_failed", `could not load ${manifest.id}/host.mjs`, 500);
 				}
+				controller.signal.throwIfAborted();
 				if (imported.default !== void 0) await imported.default(api);
 			}
 			await Promise.all(pendingEffects);
 		};
-		await withActivationTimeout(activate(), manifest.id);
+		await withActivationTimeout(activate(), manifest.id, controller.signal);
 		const host = validateDefinition({
 			...manifest,
 			actions,
@@ -1731,8 +1992,9 @@ async function loadLocalExtension(directory, context, known) {
 		return Object.freeze({
 			manifest,
 			directory: root,
-			...scriptFile === void 0 ? {} : { scriptFile },
-			...styleFile === void 0 ? {} : { styleFile },
+			...scriptBody === void 0 ? {} : { scriptBody },
+			...styleBody === void 0 ? {} : { styleBody },
+			assets,
 			host,
 			controller,
 			cleanups: Object.freeze(cleanups),
@@ -1740,12 +2002,12 @@ async function loadLocalExtension(directory, context, known) {
 		});
 	} catch (error) {
 		activationOpen = false;
-		await withActivationTimeout(Promise.allSettled(pendingEffects), manifest.id).catch(() => void 0);
 		controller.abort();
-		for (const cleanup of [...cleanups].reverse()) try {
-			await cleanup();
-		} catch {}
+		const cleanupPromises = invokeCleanups(cleanups.splice(0));
+		await settleBounded([...pendingEffects, ...cleanupPromises], HOST_TEARDOWN_TIMEOUT_MS);
 		throw error;
+	} finally {
+		parentSignal?.removeEventListener("abort", onParentAbort);
 	}
 }
 /** Construct the service in a Cordis plugin without importing DSH internals. */
@@ -1772,6 +2034,8 @@ const UPSTREAM_AUTH_REFRESH_MARGIN_MS = 6e4;
 const UPSTREAM_COOKIE_PAIR = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+=[\x21-\x3A\x3C-\x7E]*$/u;
 const CUSTOM_STYLE_FALLBACK = "/* Add mobile overrides in the DSH home mobile-access/mobile.css file. */\n";
 const CUSTOM_SCRIPT_FALLBACK = "window.dshMobile?.register(() => undefined)\n";
+const EXTENSION_CHANGE_POLL_MS = 2e3;
+const EXTENSION_EVENT_HEARTBEAT_MS = 15e3;
 const MOBILE_CLIENT_MODULE = "dsh-mobile";
 const CONNECTION_MODULE = "@deepseek-ai/dsh-client-connection";
 const RUNTIME_MODULE = "@deepseek-ai/dsh-client-runtime";
@@ -2247,6 +2511,7 @@ function discoveryBroadcastTargets(cidrs) {
 function extensionTarget(pathname) {
 	const prefix = `${AUTH_PREFIX}/extensions`;
 	if (pathname === prefix || pathname === `${prefix}/` || pathname === `${prefix}/manifest`) return { kind: "manifest" };
+	if (pathname === `${prefix}/events`) return { kind: "events" };
 	if (!pathname.startsWith(`${prefix}/`)) return void 0;
 	const parts = pathname.slice(prefix.length + 1).split("/");
 	const id = parts.shift();
@@ -2276,12 +2541,21 @@ function extensionTarget(pathname) {
 		path: `/${parts.join("/")}`.replace(/\/{2,}/gu, "/")
 	};
 }
+const EXTENSION_GENERATION_HEADER = "x-dsh-mobile-extension-generation";
+function extensionGeneration(value) {
+	if (value === void 0) return void 0;
+	if (!/^[a-f\d]{64}$/u.test(value)) throw new HttpError(400, "invalid_extension_generation");
+	return value;
+}
 function mobileBootBatchKey(pathname) {
 	return new RegExp(`^${MOBILE_BOOT_BATCH_PREFIX.replaceAll("/", "\\/")}([a-f\\d]{64})\\.js$`, "u").exec(pathname)?.[1];
 }
-async function readBoundedBody(request, maximum) {
+function assertBoundedContentLength(request, maximum) {
 	const declared = request.headers["content-length"];
 	if (declared !== void 0 && (!/^\d+$/u.test(declared) || Number(declared) > maximum)) throw new HttpError(413, "payload_too_large");
+}
+async function readBoundedBody(request, maximum) {
+	assertBoundedContentLength(request, maximum);
 	const chunks = [];
 	let total = 0;
 	for await (const chunk of request) {
@@ -2343,6 +2617,11 @@ var MobileAccessGateway = class {
 	activeRequests = /* @__PURE__ */ new Map();
 	activeWebSockets = /* @__PURE__ */ new Map();
 	mobileBootBatches = /* @__PURE__ */ new Map();
+	extensionEventListeners = /* @__PURE__ */ new Set();
+	extensionEventRevision = 0;
+	extensionChangeTimer;
+	extensionChangeTask;
+	legacyCustomDigest = "";
 	upstreamCookie;
 	upstreamCookieExpiresAt = 0;
 	upstreamCookieTask;
@@ -2352,6 +2631,7 @@ var MobileAccessGateway = class {
 	started = false;
 	closeTask;
 	removeSessionListener;
+	removeExtensionContentListener;
 	renewLimiter;
 	constructor(config, store, extensions, upstreamAuthenticatedUrl) {
 		this.config = config;
@@ -2373,6 +2653,9 @@ var MobileAccessGateway = class {
 		this.removeSessionListener = this.access.onSessionEnded((authorization) => {
 			this.abortSessionResources(authorization.sessionKey);
 		});
+		this.removeExtensionContentListener = this.extensions?.onContentChanged(() => {
+			this.broadcastExtensionChange();
+		}) ?? (() => void 0);
 	}
 	/** Initialize durable state, validate TLS, and bind the externally reachable listener. */
 	async start() {
@@ -2440,6 +2723,11 @@ var MobileAccessGateway = class {
 			this.listenerPort = address.port;
 			this.policy = new RequestTrustPolicy(this.config.authorities, address.port, this.config.allowedCidrs, this.tlsEnabled);
 			if (this.config.discovery) await this.startDiscovery(address.port);
+			await this.pollLegacyCustomChanges();
+			this.extensionChangeTimer = setInterval(() => {
+				this.pollLegacyCustomChanges();
+			}, EXTENSION_CHANGE_POLL_MS);
+			this.extensionChangeTimer.unref();
 		} catch (error) {
 			await this.closeFailedStart();
 			throw error;
@@ -2499,6 +2787,9 @@ var MobileAccessGateway = class {
 		}), "utf8");
 	}
 	async closeFailedStart() {
+		if (this.extensionChangeTimer !== void 0) clearInterval(this.extensionChangeTimer);
+		this.extensionChangeTimer = void 0;
+		this.removeExtensionContentListener();
 		if (this.discoveryTimer !== void 0) clearInterval(this.discoveryTimer);
 		this.discoveryTimer = void 0;
 		await this.closeBonjour();
@@ -2859,6 +3150,11 @@ var MobileAccessGateway = class {
 	async handleExtensionRequest(targetInfo, target, request, response, authorization) {
 		const extensions = this.extensions;
 		if (extensions === void 0) throw new HttpError(404, "not_found");
+		if (targetInfo.kind === "events") {
+			if (request.method !== "GET" || target.search !== "") throw new HttpError(request.method === "GET" ? 400 : 405, request.method === "GET" ? "bad_request" : "method_not_allowed");
+			this.openExtensionEventStream(request, response, authorization);
+			return;
+		}
 		if (targetInfo.kind === "manifest") {
 			if (request.method !== "GET" && request.method !== "HEAD") throw new HttpError(405, "method_not_allowed");
 			const operation = this.allocateRequest(authorization, response, {});
@@ -2906,9 +3202,10 @@ var MobileAccessGateway = class {
 		}
 		if (targetInfo.kind === "script" || targetInfo.kind === "style" || targetInfo.kind === "asset") {
 			if (request.method !== "GET" && request.method !== "HEAD") throw new HttpError(405, "method_not_allowed");
+			const generation = extensionGeneration(new URLSearchParams(target.search).get("generation") ?? void 0);
 			const operation = this.allocateRequest(authorization, response, {});
 			try {
-				const file = targetInfo.kind === "script" ? await extensions.readClientFile(targetInfo.id, "script", operation.signal) : targetInfo.kind === "style" ? await extensions.readClientFile(targetInfo.id, "style", operation.signal) : await extensions.readAsset(targetInfo.id, targetInfo.path ?? "", operation.signal);
+				const file = targetInfo.kind === "script" ? await extensions.readClientFile(targetInfo.id, "script", operation.signal, generation) : targetInfo.kind === "style" ? await extensions.readClientFile(targetInfo.id, "style", operation.signal, generation) : await extensions.readAsset(targetInfo.id, targetInfo.path ?? "", operation.signal, generation);
 				if (headerValue(request.headers, "if-none-match") === file.digest) {
 					setSecurityHeaders(response, this.tlsEnabled);
 					response.writeHead(304);
@@ -2931,23 +3228,26 @@ var MobileAccessGateway = class {
 		}
 		if (targetInfo.kind === "action") {
 			if (request.method !== "POST") throw new HttpError(405, "method_not_allowed");
-			const body = await readJsonObject(request, 1048576);
+			const maximum = 1048576;
+			assertBoundedContentLength(request, maximum);
+			const generation = extensionGeneration(headerValue(request.headers, EXTENSION_GENERATION_HEADER));
 			const operation = this.allocateRequest(authorization, response, {});
 			const abort = new AbortController();
 			response.once("close", () => {
 				abort.abort();
 			});
-			const generationSignal = extensions.signal(targetInfo.id);
+			const generationSignal = extensions.signal(targetInfo.id, generation);
 			const onGenerationAbort = () => {
 				abort.abort();
 				if (!response.destroyed) response.destroy();
 			};
 			generationSignal?.addEventListener("abort", onGenerationAbort, { once: true });
 			try {
+				const body = await readJsonObject(request, maximum);
 				const result = await extensions.invoke(targetInfo.id, targetInfo.action, body, {
 					signal: abort.signal,
 					deviceId: authorization.deviceId
-				});
+				}, generation);
 				let serialized;
 				try {
 					serialized = Buffer.from(JSON.stringify(result));
@@ -2973,19 +3273,22 @@ var MobileAccessGateway = class {
 				"PATCH",
 				"DELETE"
 			].includes(method)) throw new HttpError(405, "method_not_allowed");
-			const body = method === "GET" || method === "HEAD" ? Buffer.alloc(0) : await readBoundedBody(request, this.config.maxBodyBytes);
+			const hasBody = method !== "GET" && method !== "HEAD";
+			if (hasBody) assertBoundedContentLength(request, this.config.maxBodyBytes);
+			const generation = extensionGeneration(headerValue(request.headers, EXTENSION_GENERATION_HEADER));
 			const operation = this.allocateRequest(authorization, response, {});
 			const abort = new AbortController();
 			response.once("close", () => {
 				abort.abort();
 			});
-			const generationSignal = extensions.signal(targetInfo.id);
+			const generationSignal = extensions.signal(targetInfo.id, generation);
 			const onGenerationAbort = () => {
 				abort.abort();
 				if (!response.destroyed) response.destroy();
 			};
 			generationSignal?.addEventListener("abort", onGenerationAbort, { once: true });
 			try {
+				const body = hasBody ? await readBoundedBody(request, this.config.maxBodyBytes) : Buffer.alloc(0);
 				const parsed = new URL(target.raw, this.address().origin);
 				const routeRequest = {
 					method,
@@ -2996,7 +3299,7 @@ var MobileAccessGateway = class {
 					signal: abort.signal,
 					deviceId: authorization.deviceId
 				};
-				const result = await extensions.route(targetInfo.id, method, targetInfo.path, routeRequest);
+				const result = await extensions.route(targetInfo.id, method, targetInfo.path, routeRequest, generation);
 				await this.sendExtensionResponse(response, result, request.method === "HEAD");
 			} finally {
 				generationSignal?.removeEventListener("abort", onGenerationAbort);
@@ -3382,6 +3685,66 @@ var MobileAccessGateway = class {
 			socket.upstream.destroy();
 		}
 	}
+	broadcastExtensionChange() {
+		if (this.closing) return;
+		this.extensionEventRevision += 1;
+		for (const listener of this.extensionEventListeners) listener(this.extensionEventRevision);
+	}
+	pollLegacyCustomChanges() {
+		if (this.extensionChangeTask !== void 0) return this.extensionChangeTask;
+		const digestFile = async (path, fallback) => {
+			try {
+				const info = await stat(path);
+				if (!info.isFile() || info.size > 262144) return `invalid:${String(info.size)}:${String(info.mtimeMs)}`;
+				return createHash("sha256").update(await readFile(path)).digest("hex");
+			} catch (error) {
+				if (error.code === "ENOENT") return createHash("sha256").update(fallback).digest("hex");
+				return `error:${String(error.code ?? "unknown")}`;
+			}
+		};
+		const task = Promise.all([digestFile(this.config.customScriptFile, CUSTOM_SCRIPT_FALLBACK), digestFile(this.config.customCssFile, CUSTOM_STYLE_FALLBACK)]).then((parts) => {
+			const next = createHash("sha256").update(parts.join("|")).digest("hex");
+			if (this.legacyCustomDigest !== "" && next !== this.legacyCustomDigest) this.broadcastExtensionChange();
+			this.legacyCustomDigest = next;
+		}).finally(() => {
+			if (this.extensionChangeTask === task) this.extensionChangeTask = void 0;
+		});
+		this.extensionChangeTask = task;
+		return task;
+	}
+	openExtensionEventStream(request, response, authorization) {
+		const operation = this.allocateRequest(authorization, response, {});
+		let closed = false;
+		let heartbeat;
+		const close = () => {
+			if (closed) return;
+			closed = true;
+			if (heartbeat !== void 0) clearInterval(heartbeat);
+			this.extensionEventListeners.delete(send);
+			request.removeListener("aborted", close);
+			response.removeListener("close", close);
+			operation.release();
+		};
+		const send = (revision) => {
+			if (closed || response.destroyed || response.writableEnded) return;
+			response.write(`id: ${String(revision)}\nevent: extensions-changed\ndata: {\"revision\":${String(revision)}}\n\n`);
+		};
+		setSecurityHeaders(response, this.tlsEnabled);
+		response.writeHead(200, {
+			"Content-Type": "text/event-stream; charset=utf-8",
+			"Cache-Control": "no-store",
+			Connection: "keep-alive",
+			"X-Accel-Buffering": "no"
+		});
+		response.write("retry: 2000\n: ready\n\n");
+		this.extensionEventListeners.add(send);
+		heartbeat = setInterval(() => {
+			if (!closed && !response.destroyed && !response.writableEnded) response.write(": heartbeat\n\n");
+		}, EXTENSION_EVENT_HEARTBEAT_MS);
+		heartbeat.unref();
+		request.once("aborted", close);
+		response.once("close", close);
+	}
 	async readUpgradeResponse(upstream, expectedAccept) {
 		return new Promise((resolve, reject) => {
 			let buffer = Buffer.alloc(0);
@@ -3629,6 +3992,9 @@ var MobileAccessGateway = class {
 	}
 	async performClose() {
 		this.closing = true;
+		if (this.extensionChangeTimer !== void 0) clearInterval(this.extensionChangeTimer);
+		this.extensionChangeTimer = void 0;
+		this.removeExtensionContentListener();
 		this.upstreamAuthRequest?.destroy();
 		this.upstreamAuthRequest = void 0;
 		this.removeSessionListener();
@@ -3816,10 +4182,12 @@ const REMOTE_ERROR_GUIDANCE = Object.freeze({
 	cpolar_exited: "点击“重新连接”；仍失败时复制诊断报告。",
 	gateway_start_failed: "确认 DSH 正在运行后重新连接。"
 });
-function check(id, status, label, detail, action) {
+function check(id, status, reason, label, detail, action, facts) {
 	return Object.freeze({
 		id,
 		status,
+		reason,
+		...facts === void 0 ? {} : { facts: Object.freeze(facts) },
 		label,
 		detail,
 		...action === void 0 ? {} : { action }
@@ -3935,24 +4303,42 @@ async function collectConnectionDiagnostics(snapshot, probes = {}) {
 	const checks = [];
 	const remoteProbe = snapshot.remote.running && snapshot.remote.state === "ready" && snapshot.remote.origin !== void 0 ? (probes.remote ?? defaultRemoteProbe)(snapshot.remote.origin) : Promise.resolve({ state: "not-applicable" });
 	const [firewall, remoteObservation] = await Promise.all([(probes.firewall ?? defaultFirewallProbe())(snapshot.lan.port), remoteProbe]);
-	checks.push(check("versions", "ok", "版本兼容", `插件 ${DSH_MOBILE_VERSION}，DSH ${snapshot.dshVersion}，Android App 最低 ${MINIMUM_ANDROID_APP_VERSION}。`));
-	if (snapshot.lan.networkError !== void 0) checks.push(check("network", "error", "局域网网卡", "已保存的网卡当前不可用。", "重新运行 dsh-mobile setup。"));
-	else if (snapshot.lan.configuredInterface !== void 0) checks.push(check("network", "ok", "局域网网卡", `正在跟随 ${snapshot.lan.interfaceName ?? snapshot.lan.configuredInterface}。`));
-	else checks.push(check("network", "info", "局域网网卡", "当前使用固定网络配置。"));
-	if (snapshot.lan.running && snapshot.lan.origin !== void 0) checks.push(check("lan", "ok", "局域网网关", `已监听 ${maskLanOrigin(snapshot.lan.origin)}，配对入口可用。`));
-	else checks.push(check("lan", "info", "局域网网关", "当前未开启。", "需要手机直连时开启局域网访问。"));
-	if (firewall.state === "ready") checks.push(check("firewall", "ok", "Windows 防火墙", "局域网 TCP 与发现规则已启用。"));
-	else if (firewall.state === "missing") checks.push(check("firewall", "warning", "Windows 防火墙", "未找到完整的局域网放行规则。", "以管理员身份重新运行 dsh-mobile setup。"));
-	else if (firewall.state === "unknown") checks.push(check("firewall", "info", "Windows 防火墙", "系统未允许插件读取防火墙状态。", "若手机找不到电脑，以管理员身份重新运行 setup。"));
-	if (!snapshot.remote.running || snapshot.remote.state === "off") checks.push(check("remote", "info", "远程通道", "当前未启用。"));
+	checks.push(check("versions", "ok", "versions-current", "版本兼容", `插件 ${DSH_MOBILE_VERSION}，DSH ${snapshot.dshVersion}，Android App 最低 ${MINIMUM_ANDROID_APP_VERSION}。`));
+	if (snapshot.lan.networkError !== void 0) checks.push(check("network", "error", "network-unavailable", "局域网网卡", "已保存的网卡当前不可用。", "重新运行 dsh-mobile setup。"));
+	else if (snapshot.lan.configuredInterface !== void 0) {
+		const interfaceName = snapshot.lan.interfaceName ?? snapshot.lan.configuredInterface;
+		checks.push(check("network", "ok", "network-interface", "局域网网卡", `正在跟随 ${interfaceName}。`, void 0, { interfaceName }));
+	} else checks.push(check("network", "info", "network-fixed", "局域网网卡", "当前使用固定网络配置。"));
+	if (snapshot.lan.running && snapshot.lan.origin !== void 0) {
+		const endpointSuffix = maskLanOrigin(snapshot.lan.origin);
+		checks.push(check("lan", "ok", "lan-ready", "局域网网关", `已监听 ${endpointSuffix}，配对入口可用。`, void 0, { endpointSuffix }));
+	} else checks.push(check("lan", "info", "lan-off", "局域网网关", "当前未开启。", "需要手机直连时开启局域网访问。"));
+	if (firewall.state === "ready") checks.push(check("firewall", "ok", "firewall-ready", "Windows 防火墙", "局域网 TCP 与发现规则已启用。"));
+	else if (firewall.state === "missing") checks.push(check("firewall", "warning", "firewall-missing", "Windows 防火墙", "未找到完整的局域网放行规则。", "以管理员身份重新运行 dsh-mobile setup。"));
+	else if (firewall.state === "unknown") checks.push(check("firewall", "info", "firewall-unknown", "Windows 防火墙", "系统未允许插件读取防火墙状态。", "若手机找不到电脑，以管理员身份重新运行 setup。"));
+	if (!snapshot.remote.running || snapshot.remote.state === "off") checks.push(check("remote", "info", "remote-off", "远程通道", "当前未启用。", void 0, { provider: snapshot.remote.provider }));
 	else if (snapshot.remote.state === "ready" && snapshot.remote.origin !== void 0) {
-		if (remoteObservation.state === "ready") checks.push(check("remote", "ok", "远程通道", `${snapshot.remote.provider} 公共地址 ${remoteSuffix(snapshot.remote.origin)} 可达，往返约 ${String(remoteObservation.latencyMs ?? 0)} ms。`));
-		else if (remoteObservation.state === "rate-limited") checks.push(check("remote", "warning", "远程通道", "公共地址可达，但本次检查观察到服务限流。", "稍后重试；旧会话会按需加载以减少流量。"));
-		else if (snapshot.remote.provider === "tailscale" && remoteObservation.fakeIp === true) checks.push(check("remote", "error", "远程通道", "Tailscale 地址被当前 VPN 或 DNS 代理接管，但 TLS 链路未建立。", "切换 VPN 节点或代理模式；仍失败时改用 cpolar。"));
-		else checks.push(check("remote", "error", "远程通道", "提供方显示已就绪，但公共地址暂不可达。", "点击“重新连接”；仍失败时检查提供方状态。"));
-	} else if (snapshot.remote.state === "starting" || snapshot.remote.state === "connecting" || snapshot.remote.state === "needs-login") checks.push(check("remote", "warning", "远程通道", snapshot.remote.state === "needs-login" ? "等待完成 Tailscale 登录。" : "仍在建立连接。", snapshot.remote.state === "needs-login" ? "返回远程页继续登录。" : "等待片刻后重新检查。"));
-	else checks.push(check("remote", "error", "远程通道", `连接未建立（${snapshot.remote.errorCode ?? snapshot.remote.state}）。`, REMOTE_ERROR_GUIDANCE[snapshot.remote.errorCode ?? ""] ?? "返回远程页点击“重新连接”。"));
-	checks.push(check("phone-network", "info", "手机网络", "电脑无法判断路由器是否隔离了手机。", "局域网仍失败时，确认手机与电脑在同一网络，并关闭访客网络或 AP 隔离。"));
+		const endpointSuffix = remoteSuffix(snapshot.remote.origin);
+		const facts = {
+			provider: snapshot.remote.provider,
+			endpointSuffix,
+			...remoteObservation.latencyMs === void 0 ? {} : { latencyMs: remoteObservation.latencyMs }
+		};
+		if (remoteObservation.state === "ready") checks.push(check("remote", "ok", "remote-ready", "远程通道", `${snapshot.remote.provider} 公共地址 ${endpointSuffix} 可达，往返约 ${String(remoteObservation.latencyMs ?? 0)} ms。`, void 0, facts));
+		else if (remoteObservation.state === "rate-limited") checks.push(check("remote", "warning", "remote-rate-limited", "远程通道", "公共地址可达，但本次检查观察到服务限流。", "稍后重试；旧会话会按需加载以减少流量。", facts));
+		else if (snapshot.remote.provider === "tailscale" && remoteObservation.fakeIp === true) checks.push(check("remote", "error", "remote-fake-ip", "远程通道", "Tailscale 地址被当前 VPN 或 DNS 代理接管，但 TLS 链路未建立。", "切换 VPN 节点或代理模式；仍失败时改用 cpolar。", facts));
+		else checks.push(check("remote", "error", "remote-unreachable", "远程通道", "提供方显示已就绪，但公共地址暂不可达。", "点击“重新连接”；仍失败时检查提供方状态。", facts));
+	} else if (snapshot.remote.state === "starting" || snapshot.remote.state === "connecting" || snapshot.remote.state === "needs-login") {
+		const needsLogin = snapshot.remote.state === "needs-login";
+		checks.push(check("remote", "warning", needsLogin ? "remote-needs-login" : "remote-connecting", "远程通道", needsLogin ? "等待完成 Tailscale 登录。" : "仍在建立连接。", needsLogin ? "返回远程页继续登录。" : "等待片刻后重新检查。", { provider: snapshot.remote.provider }));
+	} else {
+		const controllerCode = snapshot.remote.errorCode ?? snapshot.remote.state;
+		checks.push(check("remote", "error", "remote-controller-error", "远程通道", `连接未建立（${controllerCode}）。`, REMOTE_ERROR_GUIDANCE[controllerCode] ?? "返回远程页点击“重新连接”。", {
+			provider: snapshot.remote.provider,
+			controllerCode
+		}));
+	}
+	checks.push(check("phone-network", "info", "phone-network-unknown", "手机网络", "电脑无法判断路由器是否隔离了手机。", "局域网仍失败时，确认手机与电脑在同一网络，并关闭访客网络或 AP 隔离。"));
 	const overall = checks.some((entry) => entry.status === "error") ? "error" : checks.some((entry) => entry.status === "warning") ? "attention" : "ok";
 	const summary = overall === "ok" ? "连接基础检查正常。" : overall === "attention" ? "发现需要留意的项目。" : "发现会影响连接的问题。";
 	const report = [
@@ -4002,7 +4388,7 @@ const MOBILE_CUSTOMIZATION_GUIDE = `你在为用户定制 DSH Mobile 的手机
    - mobile.js：手机端脚本，用 window.dshMobile.define({ apiVersion:1, id:'<id>', activate(api) { ... } })，activate 返回清理函数
    - mobile.css：手机端样式（可选）
    - assets/：手机端静态资源（可选）
-   - mobile.js 里用 api.host.invoke('动作名', 输入) 调 host.mjs 的 action，api.host.fetch('/路由路径') 调 route
+   - mobile.js 里用 api.host.invoke('动作名', 输入) 调 host.mjs 的 action，api.host.fetch('/路由路径') 调 route，api.host.assetUrl('相对路径') 生成与当前版本绑定的资源地址
    - 也可以先用命令生成模板：dsh plugin --profile web exec dsh-mobile extension create <id> --name "<名称>"，再在模板上改
 
 安全约束：