@webskill/sdk 0.4.0 → 0.6.0

package/dist/browser.js

@@ -1,6 +1,6 @@
-import { A as parseSkillMarkdown, B as unzipWithLimits, H as verifyManifest, L as resolveInsideRoot, M as readResponseWithLimit, O as messageOf, T as isValidSkillName, V as validateSkills, _ as atomicWriteText, f as SkillDiscovery, h as assertRemoteUrlAllowed, j as parseSkillPackManifest, m as WebSkillError, o as SKILLS_LOCKFILE, r as MANIFEST_EXCLUDED_FILES, s as SKILL_MANIFEST_FILE, u as SKILL_PACK_FILE, v as buildCatalog, w as exportSkills, y as buildManifest } from "./dist-8oQRa8Xz.js";
-import { H as normalizeToolContent, O as bridgeError, R as mergeCatalogEntries, U as normalizeToolError, W as parseBridgeRequest, _ as OpenAiCompatibleClient, d as FsRunSnapshotStore, i as AgentLoop, j as createWebSkillApi, l as FsArtifactStore, o as CapabilityApproval, u as FsMemoryStore, v as ProgressiveRouter, z as networkPolicyLibSource } from "./dist-C-Sh0MDU.js";
-import { n as MockLlmClient } from "./testing-DDCJWvgA.js";
+import { A as parseSkillMarkdown, B as unzipWithLimits, H as verifyManifest, L as resolveInsideRoot, M as readResponseWithLimit, N as readSkillSignature, O as messageOf, T as isValidSkillName, U as verifySkillSignature, V as validateSkills, _ as atomicWriteText, f as SkillDiscovery, h as assertRemoteUrlAllowed, j as parseSkillPackManifest, m as WebSkillError, o as SKILLS_LOCKFILE, r as MANIFEST_EXCLUDED_FILES, s as SKILL_MANIFEST_FILE, u as SKILL_PACK_FILE, v as buildCatalog, w as exportSkills, y as buildManifest } from "./dist-8oQRa8Xz.js";
+import { H as createWebSkillApi, S as ProgressiveRouter, a as AgentLoop, at as normalizeToolContent, c as CapabilityApproval, et as mergeCatalogEntries, h as FsRunSnapshotStore, m as FsMemoryStore, nt as networkPolicyLibSource, o as AnthropicClient, ot as normalizeToolError, p as FsArtifactStore, st as parseBridgeRequest, x as OpenAiCompatibleClient, y as GoogleGenAiClient, z as bridgeError } from "./dist-DusANsrn.js";
+import { n as MockLlmClient } from "./testing-CYTFqkDm.js";
 
 //#region ../browser/dist/index.js
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -63,7 +63,12 @@ var OpfsProvider = class {
 			const name = segments.pop();
 			if (!name) throw new WebSkillError("FS_NOT_FOUND", `Invalid file path: ${p}`);
 			const handle = await (await this.#walkDir(`/${segments.join("/")}`, true)).getFileHandle(name, { create: true });
-			const size = (await handle.getFile()).size;
+			let size = 0;
+			try {
+				size = (await handle.getFile()).size;
+			} catch (e) {
+				if (!isDomException(e, "NotFoundError")) throw e;
+			}
 			const writable = await handle.createWritable({ keepExistingData: true });
 			await writable.write({
 				type: "write",
@@ -371,17 +376,26 @@ self.onmessage = async function (event) {
   }
 };
 `;
-let esbuildPromise;
+/** 按资源地址缓存，而不是全局单例：不同地址必须各自加载，否则先到的实例会顶替后来的配置 */
+const esbuildCache = /* @__PURE__ */ new Map();
 async function loadEsbuild(options) {
-	esbuildPromise ??= (async () => {
-		const mod = await import(
-			/* @vite-ignore */
-			options.esbuildUrl
+	const key = `${options.esbuildUrl}\n${options.wasmUrl ?? ""}`;
+	let pending = esbuildCache.get(key);
+	if (!pending) {
+		pending = (async () => {
+			const mod = await import(
+				/* @vite-ignore */
+				options.esbuildUrl
 );
-		await mod.initialize(options.wasmUrl ? { wasmURL: options.wasmUrl } : {});
-		return mod;
-	})();
-	return esbuildPromise;
+			await mod.initialize(options.wasmUrl ? { wasmURL: options.wasmUrl } : {});
+			return mod;
+		})().catch((e) => {
+			esbuildCache.delete(key);
+			throw e;
+		});
+		esbuildCache.set(key, pending);
+	}
+	return pending;
 }
 async function sha256Hex(data) {
 	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(data));
@@ -400,19 +414,25 @@ var TsTranspiler = class {
 		this.#options = deps.options;
 		this.#cacheDir = deps.cacheDir ?? ".webskill/ts-cache";
 	}
-	/** 返回 JS 源码；转译失败 → TOOL_EXECUTION_FAILED（带 esbuild 诊断） */
+	/** 返回 JS 源码；转译器不可用 → TS_TRANSPILER_UNAVAILABLE，语法错 → TS_TRANSPILE_FAILED */
 	async transpile(scriptPath, source) {
 		const cacheKey = `${this.#cacheDir}/${await sha256Hex(`${scriptPath}\n${source}`)}.js`;
 		if (await this.#fs.exists(cacheKey)) return this.#fs.readText(cacheKey);
+		let esbuild;
+		try {
+			esbuild = await loadEsbuild(this.#options);
+		} catch (e) {
+			throw new WebSkillError("TS_TRANSPILER_UNAVAILABLE", `Failed to load the TypeScript transpiler from "${this.#options.esbuildUrl}": ${messageOf(e)}`, e);
+		}
 		let code;
 		try {
-			code = (await (await loadEsbuild(this.#options)).transform(source, {
+			code = (await esbuild.transform(source, {
 				loader: "ts",
 				target: "es2022",
 				format: "esm"
 			})).code;
 		} catch (e) {
-			throw new WebSkillError("TOOL_EXECUTION_FAILED", `Failed to transpile ${scriptPath}: ${e instanceof Error ? e.message : String(e)}`, e);
+			throw new WebSkillError("TS_TRANSPILE_FAILED", `Failed to transpile ${scriptPath}: ${messageOf(e)}`, e);
 		}
 		await this.#fs.writeText(cacheKey, code);
 		return code;
@@ -461,8 +481,26 @@ async function extractZipWeb(fs, data, destRoot, limits) {
 		else await fs.writeBinary(target, content);
 	}
 }
-const asInstallFailed = (e) => e instanceof WebSkillError && (e.code === "INSTALL_FAILED" || e.code === "TOOL_UNSUPPORTED") ? e : new WebSkillError("INSTALL_FAILED", `Install failed: ${messageOf(e)}`, e);
+/**
+* 验签失败不能被折叠成 INSTALL_FAILED：四种失败的宿主处置完全不同
+* （引导选策略 / 提示重下 / 引导添加密钥 / 安全事件），与 Node 侧同口径。
+*/
+const PRESERVED_INSTALL_CODES = /* @__PURE__ */ new Set([
+	"SIGNATURE_MISSING",
+	"SIGNATURE_MALFORMED",
+	"SIGNATURE_UNTRUSTED_KEY",
+	"SIGNATURE_MISMATCH",
+	"SIGNATURE_UNSUPPORTED"
+]);
+const asInstallFailed = (e) => e instanceof WebSkillError && (e.code === "INSTALL_FAILED" || e.code === "TOOL_UNSUPPORTED" || PRESERVED_INSTALL_CODES.has(e.code)) ? e : new WebSkillError("INSTALL_FAILED", `Install failed: ${messageOf(e)}`, e);
 const lockfilePath = (root) => `${root}/${SKILLS_LOCKFILE}`;
+/** 未注入信任库时的空实现：策略仍然生效，只是没有任何受信公钥 */
+const EMPTY_TRUSTED_KEYS = {
+	list: () => Promise.resolve([]),
+	get: () => Promise.resolve(void 0),
+	add: () => Promise.reject(new WebSkillError("TOOL_UNSUPPORTED", "No trusted key store is configured")),
+	remove: () => Promise.reject(new WebSkillError("TOOL_UNSUPPORTED", "No trusted key store is configured"))
+};
 /**
 * D5：浏览器技能安装（http(s) zip / ArrayBuffer；tar/git/npm → TOOL_UNSUPPORTED）。
 * 流程与 Node 对齐：staging → 解析 name → validateSkills（失败零残留）→ managed root →
@@ -475,12 +513,34 @@ var BrowserSkillManager = class {
 	#fetchImpl;
 	#archiveLimits;
 	#onChanged;
+	#trustedKeys;
+	#unsignedPolicy;
+	#onWarning;
 	constructor(deps) {
 		this.#fs = deps.fs;
 		this.#managedRoot = deps.managedRoot.replace(/\/+$/, "");
 		this.#fetchImpl = deps.fetchImpl;
 		this.#archiveLimits = deps.archiveLimits;
 		this.#onChanged = deps.onChanged;
+		this.#trustedKeys = deps.signature?.trustedKeys ?? EMPTY_TRUSTED_KEYS;
+		this.#unsignedPolicy = deps.signature?.unsigned ?? "warn";
+		this.#onWarning = deps.onWarning;
+	}
+	/**
+	* 安装期验签：manifest 生成之后、提交 swap 之前。失败直接抛出，
+	* 暂存目录由 install 的 finally 清理，不落盘。
+	*/
+	async #verifySignature(skillDir, manifest) {
+		const verdict = await verifySkillSignature({
+			manifest,
+			signature: await readSkillSignature(this.#fs, skillDir),
+			trustedKeys: this.#trustedKeys,
+			policy: { unsigned: this.#unsignedPolicy }
+		});
+		if (verdict.warning !== void 0) this.#onWarning?.({
+			skill: manifest.name,
+			message: verdict.warning
+		});
 	}
 	async install(source, options) {
 		const fs = this.#fs;
@@ -546,6 +606,7 @@ var BrowserSkillManager = class {
 				...version ? { version } : {},
 				source
 			});
+			await this.#verifySignature(finalDir, manifest);
 			targetDir = `${this.#managedRoot}/${name}`;
 			const backupDir = `${stagingRoot}/backup`;
 			const hadPrevious = await fs.exists(targetDir);
@@ -614,6 +675,7 @@ var BrowserSkillManager = class {
 					source
 				});
 				if (manifest.integrity.digest !== entry.digest) throw new WebSkillError("INSTALL_FAILED", `Skill "${entry.name}" digest mismatch: expected ${entry.digest}, got ${manifest.integrity.digest}`);
+				await this.#verifySignature(`${finalRoot}/${entry.name}`, manifest);
 				manifests.push(manifest);
 			}
 			const swapped = [];
@@ -906,7 +968,7 @@ var BrowserWorkerScriptExecutor = class {
 		const [hasJs, hasTs] = await Promise.all([this.#fs.exists(jsPath), this.#fs.exists(tsPath)]);
 		if (hasJs && hasTs) throw new WebSkillError("TOOL_EXECUTION_FAILED", `Script "${scriptName}" is ambiguous: both .ts and .js exist under ${skillRoot}/scripts`);
 		if (hasTs) {
-			if (!this.#transpiler) throw new WebSkillError("TOOL_UNSUPPORTED", `Browser sandbox executes .js only unless TypeScript support is configured ("${scriptName}.ts")`);
+			if (!this.#transpiler) throw new WebSkillError("TOOL_UNSUPPORTED", `Browser sandbox executes .js only unless TypeScript support is configured ("${scriptName}.ts"). Enable it under runtime configuration sandbox.typescript and provide an esbuild-wasm URL.`);
 			return {
 				path: tsPath,
 				source: await this.#transpiler.transpile(tsPath, await this.#fs.readText(tsPath))
@@ -1123,6 +1185,627 @@ function installWebSkillNavigator(config) {
 	nav["webskill"] = api;
 	return api;
 }
+function languageModel() {
+	const candidate = globalThis.LanguageModel;
+	return typeof candidate?.availability === "function" && typeof candidate.create === "function" ? candidate : void 0;
+}
+/** 缺 API 时区分「这个浏览器根本不支持」与「Chromium 但版本/开关没到位」，两者的用户动作不同 */
+function missingReason() {
+	const nav = globalThis.navigator;
+	return nav?.userAgentData?.brands?.some((entry) => /Chromium|Google Chrome/i.test(entry.brand)) === true || /Chrome\//.test(nav?.userAgent ?? "") ? "api-missing" : "unsupported-browser";
+}
+/**
+* 进入模型配置界面时调用（FR-4.7）：不可用时给出具体原因，禁止「选了之后才失败」。
+* 模型还在下载也算不可用——这一轮对话等不到它。
+*/
+async function probeChromeBuiltinAvailability() {
+	const api = languageModel();
+	if (!api) return {
+		available: false,
+		reason: missingReason()
+	};
+	try {
+		return await api.availability() === "available" ? { available: true } : {
+			available: false,
+			reason: "model-not-ready"
+		};
+	} catch {
+		return {
+			available: false,
+			reason: "model-not-ready"
+		};
+	}
+}
+const textOf = (message) => message.content.map((part) => part.type === "text" ? part.text : `[${part.type}]`).join("").trim();
+/** tool 角色 Prompt API 不认识，降级成 user 文本——内置模型本来就不做工具调用 */
+function toInitialPrompt(message) {
+	const text = textOf(message);
+	if (message.role === "assistant") return {
+		role: "assistant",
+		content: text
+	};
+	return {
+		role: "user",
+		content: message.role === "tool" ? `Tool result: ${text}` : text
+	};
+}
+function splitInput(input) {
+	const system = input.messages.filter((m) => m.role === "system").map(textOf).filter((text) => text !== "");
+	const rest = input.messages.filter((m) => m.role !== "system");
+	const last = rest.at(-1);
+	return {
+		initialPrompts: [...system.length > 0 ? [{
+			role: "system",
+			content: system.join("\n\n")
+		}] : [], ...rest.slice(0, -1).map(toInitialPrompt)],
+		prompt: last ? toInitialPrompt(last).content : ""
+	};
+}
+/**
+* 浏览器内置模型客户端（Prompt API）。**不支持工具调用**——`input.tools` 被忽略，
+* 模型只会产出文本，因此技能里的脚本步骤在这一档跑不起来（FR-4.8 要求 UI 标注该限制）。
+* @experimental
+*/
+var ChromeBuiltinLlmClient = class {
+	#temperature;
+	constructor(options = {}) {
+		if (options.temperature !== void 0) this.#temperature = options.temperature;
+	}
+	async #session(input) {
+		const api = languageModel();
+		if (!api) throw new WebSkillError("LLM_UNAVAILABLE", "The Chrome built-in model is not available in this browser (Prompt API missing)");
+		const { initialPrompts, prompt } = splitInput(input);
+		const temperature = input.temperature ?? this.#temperature;
+		return {
+			session: await api.create({
+				...initialPrompts.length > 0 ? { initialPrompts } : {},
+				...temperature !== void 0 ? { temperature } : {},
+				...input.signal ? { signal: input.signal } : {}
+			}),
+			prompt
+		};
+	}
+	async complete(input) {
+		const { session, prompt } = await this.#session(input);
+		try {
+			return { content: [{
+				type: "text",
+				text: await session.prompt(prompt, ...input.signal ? [{ signal: input.signal }] : [])
+			}] };
+		} finally {
+			session.destroy?.();
+		}
+	}
+	async *stream(input) {
+		const { session, prompt } = await this.#session(input);
+		if (!session.promptStreaming) {
+			try {
+				const text = await session.prompt(prompt, ...input.signal ? [{ signal: input.signal }] : []);
+				yield {
+					type: "text-delta",
+					delta: text
+				};
+				yield {
+					type: "done",
+					content: text
+				};
+			} finally {
+				session.destroy?.();
+			}
+			return;
+		}
+		let content = "";
+		try {
+			const reader = session.promptStreaming(prompt, ...input.signal ? [{ signal: input.signal }] : []).getReader();
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				if (value !== void 0 && value !== "") {
+					content += value;
+					yield {
+						type: "text-delta",
+						delta: value
+					};
+				}
+			}
+			yield {
+				type: "done",
+				content
+			};
+		} finally {
+			session.destroy?.();
+		}
+	}
+	async checkAvailability() {
+		return (await probeChromeBuiltinAvailability()).available;
+	}
+};
+/**
+* 配置 → `LlmClient`。收在 SDK 里是为了让下游只跟 `RuntimeConfigStore` 打交道，
+* 不必自己维护「provider → client 类」的映射（设计 04 §5）。
+*/
+function createLlmClient(config) {
+	if (config.provider === "chrome-builtin") return new ChromeBuiltinLlmClient();
+	const common = {
+		...config.baseUrl?.trim() ? { baseUrl: config.baseUrl.trim() } : {},
+		...config.requestTimeoutMs !== void 0 ? { requestTimeoutMs: config.requestTimeoutMs } : {}
+	};
+	const apiKey = config.apiKey?.trim() ?? "";
+	if (config.provider === "anthropic") return new AnthropicClient({
+		...common,
+		apiKey,
+		model: config.model
+	});
+	if (config.provider === "google") return new GoogleGenAiClient({
+		...common,
+		apiKey,
+		model: config.model
+	});
+	return new OpenAiCompatibleClient({
+		...common,
+		...apiKey !== "" ? { apiKey } : {},
+		model: config.model
+	});
+}
+function recognitionCtor() {
+	const scope = globalThis;
+	return scope.SpeechRecognition ?? scope.webkitSpeechRecognition;
+}
+/**
+* 渲染期调用（FR-7.2）：不可用时按钮置灰并说明原因，禁止呈现为可用后才失败。
+*
+* 顺序是刻意的——构造器都不存在时谈安全上下文没有意义；
+* 构造器在但站点是 http，识别一定会被浏览器拒绝，这条原因用户能自己解决。
+* @experimental
+*/
+function checkDictationAvailability() {
+	if (recognitionCtor() === void 0) return {
+		available: false,
+		reason: "api-missing"
+	};
+	if (globalThis.isSecureContext === false) return {
+		available: false,
+		reason: "insecure-context"
+	};
+	return { available: true };
+}
+/** 浏览器的 error 码 → 稳定错误码；权限被拒要单独区分，UI 的降级提示不一样（FR-7.6） */
+function toError(code, message) {
+	if (code === "not-allowed" || code === "service-not-allowed") return new WebSkillError("DICTATION_PERMISSION_DENIED", "Microphone access was denied. Voice input is unavailable until you allow it in the browser.", { reason: code });
+	return new WebSkillError("DICTATION_FAILED", message ?? `Speech recognition failed: ${code}`, { reason: code });
+}
+/**
+* 开始一次语音识别（FR-7.1）。
+*
+* **只能由用户手势调用**（FR-7.3）。设计上的保证是它不进工具列表：
+* agent 拿不到「开始录音」这个动作，因此不存在自主开麦的路径。
+* @experimental
+*/
+function startDictation(options) {
+	const Ctor = recognitionCtor();
+	if (Ctor === void 0) throw new WebSkillError("DICTATION_UNAVAILABLE", "Speech recognition is not available in this browser.");
+	const recognition = new Ctor();
+	recognition.lang = options.lang;
+	recognition.continuous = true;
+	recognition.interimResults = true;
+	/** stop() 之后浏览器仍可能派发一轮回调；这里做一次闸门，保证「停了就不再收结果」 */
+	let stopped = false;
+	recognition.onresult = (event) => {
+		if (stopped) return;
+		let interim = "";
+		for (let index = event.resultIndex; index < event.results.length; index += 1) {
+			const result = event.results[index];
+			if (result === void 0) continue;
+			const text = result[0]?.transcript ?? "";
+			if (text === "") continue;
+			if (result.isFinal) options.onFinal(text);
+			else interim += text;
+		}
+		if (interim !== "") options.onInterim(interim);
+	};
+	recognition.onerror = (event) => {
+		if (stopped) return;
+		if (event.error === "no-speech" || event.error === "aborted") return;
+		options.onError(toError(event.error, event.message));
+	};
+	try {
+		recognition.start();
+	} catch (e) {
+		throw new WebSkillError("DICTATION_UNAVAILABLE", `Speech recognition could not start: ${String(e)}`);
+	}
+	return { stop() {
+		if (stopped) return;
+		stopped = true;
+		recognition.onresult = null;
+		recognition.onerror = null;
+		recognition.onend = null;
+		recognition.stop();
+	} };
+}
+/** 动图无法在不丢帧的前提下走单帧编码管线，超限直接拒绝（裁决 D-2） */
+const UNCOMPRESSABLE_MIME_TYPES = /* @__PURE__ */ new Set(["image/gif"]);
+const QUALITY_STEPS = [
+	.9,
+	.7,
+	.5
+];
+const SCALE_STEP = .75;
+const MAX_ROUNDS = 5;
+/**
+* 把图片压到字节预算内（0.6.0 FR-11.3）。
+* 先逐级降质，仍超限则按长边逐步缩放，最多 5 轮；仍超限抛 `ATTACHMENT_TOO_LARGE`。
+*
+* 编码一律交给平台（`OffscreenCanvas.convertToBlob`），不手写编码器（AGENTS.md §6）。
+* 因此本函数只能在浏览器里用，落在 `@webskill/browser` 而不是 core/runtime（AC-G6）。
+*/
+async function compressImageToBudget(file, maxBytes) {
+	const originalBytes = file.size;
+	if (originalBytes <= maxBytes) return {
+		blob: file,
+		originalBytes,
+		compressedBytes: originalBytes,
+		scaled: false
+	};
+	if (UNCOMPRESSABLE_MIME_TYPES.has(file.type)) throw new WebSkillError("ATTACHMENT_TYPE_REJECTED", `GIF cannot be compressed without dropping animation; the file is ${formatBytes(originalBytes)} which exceeds the ${formatBytes(maxBytes)} limit`);
+	if (typeof createImageBitmap !== "function" || typeof OffscreenCanvas !== "function") throw new WebSkillError("ATTACHMENT_TOO_LARGE", `Image is ${formatBytes(originalBytes)} which exceeds the ${formatBytes(maxBytes)} limit, and this browser cannot re-encode images`);
+	const bitmap = await createImageBitmap(file);
+	try {
+		let width = bitmap.width;
+		let height = bitmap.height;
+		let scaled = false;
+		let best;
+		for (let round = 0; round < MAX_ROUNDS; round += 1) {
+			for (const quality of QUALITY_STEPS) {
+				const blob = await encode(bitmap, width, height, quality);
+				const candidate = {
+					blob,
+					originalBytes,
+					compressedBytes: blob.size,
+					scaled,
+					quality
+				};
+				if (blob.size <= maxBytes) return candidate;
+				if (!best || blob.size < best.compressedBytes) best = candidate;
+			}
+			width = Math.max(1, Math.round(width * SCALE_STEP));
+			height = Math.max(1, Math.round(height * SCALE_STEP));
+			scaled = true;
+		}
+		throw new WebSkillError("ATTACHMENT_TOO_LARGE", `Image is still ${formatBytes(best?.compressedBytes ?? originalBytes)} after compression, which exceeds the ${formatBytes(maxBytes)} limit`);
+	} finally {
+		bitmap.close();
+	}
+}
+async function encode(bitmap, width, height, quality) {
+	const canvas = new OffscreenCanvas(width, height);
+	const ctx = canvas.getContext("2d");
+	if (!ctx) throw new WebSkillError("ATTACHMENT_TOO_LARGE", "Failed to acquire a 2D canvas context for image compression");
+	ctx.drawImage(bitmap, 0, 0, width, height);
+	return canvas.convertToBlob({
+		type: "image/jpeg",
+		quality
+	});
+}
+function formatBytes(bytes) {
+	return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+/** @experimental */
+function isCaptureFailure(result) {
+	return "reason" in result;
+}
+const CAPTURABLE_TAGS = /* @__PURE__ */ new Set([
+	"IMG",
+	"CANVAS",
+	"SVG"
+]);
+/** 只有这三种标签能取像；其余元素连取像入口都不进（FR-12.1，由 T-02-15 守门） @experimental */
+function isCapturableElement(element) {
+	return CAPTURABLE_TAGS.has(element.tagName.toUpperCase());
+}
+function base64Of(bytes) {
+	let binary = "";
+	const chunk = 32768;
+	for (let i = 0; i < bytes.length; i += chunk) binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+	return btoa(binary);
+}
+function splitDataUrl(dataUrl) {
+	const comma = dataUrl.indexOf(",");
+	if (!dataUrl.startsWith("data:") || comma === -1) return void 0;
+	const meta = dataUrl.slice(5, comma);
+	if (!meta.endsWith(";base64")) return void 0;
+	return {
+		mimeType: meta.slice(0, -7),
+		data: dataUrl.slice(comma + 1)
+	};
+}
+/** 压到预算内；压不下去时把失败原因原样上抛给调用方转成 `CaptureFailure` */
+async function toBudget(id, level, blob, maxBytes) {
+	const compressed = await compressImageToBudget(blob, maxBytes);
+	const buffer = await compressed.blob.arrayBuffer();
+	return {
+		id,
+		mimeType: compressed.blob.type === "" ? "application/octet-stream" : compressed.blob.type,
+		data: base64Of(new Uint8Array(buffer)),
+		level,
+		originalBytes: compressed.originalBytes,
+		bytes: compressed.compressedBytes
+	};
+}
+/** L1：`<img>` 取原图字节。跨域且无 CORS 头时 fetch 失败，不改用 canvas 重绘（同样会被污染） */
+async function captureImg(element, id, maxBytes) {
+	const src = element.currentSrc !== "" ? element.currentSrc : element.src;
+	if (src === "") throw new Error("the <img> element has no resolved source");
+	const inline = splitDataUrl(src);
+	if (inline) {
+		const bytes = Uint8Array.from(atob(inline.data), (char) => char.charCodeAt(0));
+		return toBudget(id, "src", new Blob([bytes], { type: inline.mimeType }), maxBytes);
+	}
+	const response = await fetch(src, { mode: "cors" });
+	if (response.type === "opaque") throw new Error("the response is opaque, so its bytes cannot be read");
+	if (!response.ok) throw new Error(`fetching the source returned HTTP ${response.status}`);
+	return toBudget(id, "src", await response.blob(), maxBytes);
+}
+/** L2：`<canvas>` 读回。画布被跨域内容污染时 `toDataURL` 抛 SecurityError，不再兜底（裁决 D-3） */
+async function captureCanvas(element, id, maxBytes) {
+	const parsed = splitDataUrl(element.toDataURL("image/png"));
+	if (parsed === void 0) throw new Error("the canvas produced an unreadable data URL");
+	const bytes = Uint8Array.from(atob(parsed.data), (char) => char.charCodeAt(0));
+	return toBudget(id, "canvas", new Blob([bytes], { type: parsed.mimeType }), maxBytes);
+}
+/** L2：内联 `<svg>` 序列化。SVG 是文本，不进压缩管线——重编码成位图反而丢信息 */
+function captureSvg(element, id, maxBytes) {
+	const markup = new XMLSerializer().serializeToString(element);
+	const data = base64Of(new TextEncoder().encode(markup));
+	const bytes = data.length;
+	if (bytes > maxBytes) throw new Error(`the serialized SVG is ${bytes} bytes, which exceeds the budget`);
+	return {
+		id,
+		mimeType: "image/svg+xml",
+		data,
+		level: "canvas",
+		originalBytes: bytes,
+		bytes
+	};
+}
+/**
+* 取一个元素的图像（0.6.0 FR-12.1）。
+*
+* 按元素类型分派，不做无意义的尝试：`<img>` 只走 L1，`<canvas>` / `<svg>` 只走 L2，
+* 两者互不兜底。失败返回 `CaptureFailure` 而不是抛错——一张图抓不到不该让整次感知失败。
+* @experimental
+*/
+async function captureElementImage(element, options) {
+	const { id, maxBytes } = options;
+	const tag = element.tagName.toUpperCase();
+	if (tag === "IMG") try {
+		return await captureImg(element, id, maxBytes);
+	} catch (e) {
+		return {
+			id,
+			reason: `L1 could not read the image source: ${describeError(e)}`,
+			triedLevels: ["src"]
+		};
+	}
+	if (tag === "CANVAS") try {
+		return await captureCanvas(element, id, maxBytes);
+	} catch (e) {
+		return {
+			id,
+			reason: `L2 could not read the canvas: ${describeError(e)}`,
+			triedLevels: ["canvas"]
+		};
+	}
+	if (tag === "SVG") try {
+		return captureSvg(element, id, maxBytes);
+	} catch (e) {
+		return {
+			id,
+			reason: `L2 could not serialize the SVG: ${describeError(e)}`,
+			triedLevels: ["canvas"]
+		};
+	}
+	return {
+		id,
+		reason: `<${element.tagName.toLowerCase()}> is not a capturable element`,
+		triedLevels: []
+	};
+}
+function describeError(e) {
+	if (e instanceof DOMException && e.name === "SecurityError") return "the canvas is tainted by cross-origin data";
+	if (e instanceof TypeError) return "the request was blocked, most likely by CORS";
+	return e instanceof Error ? e.message : String(e);
+}
+/** 值可能是凭据的输入类型：即便宿主忘了写进 exclude 也不读值 */
+const SECRET_INPUT_TYPES = /* @__PURE__ */ new Set(["password", "hidden"]);
+/** tag → 可访问性角色的最小映射；命中不了就退到 generic，不猜 */
+const ROLE_BY_TAG = {
+	A: "link",
+	BUTTON: "button",
+	CANVAS: "img",
+	H1: "heading",
+	H2: "heading",
+	H3: "heading",
+	H4: "heading",
+	H5: "heading",
+	H6: "heading",
+	IMG: "img",
+	LI: "listitem",
+	NAV: "navigation",
+	OL: "list",
+	P: "paragraph",
+	SELECT: "combobox",
+	SVG: "img",
+	TABLE: "table",
+	TD: "cell",
+	TEXTAREA: "textbox",
+	TH: "columnheader",
+	TR: "row",
+	UL: "list"
+};
+const INPUT_TYPE_ROLE = {
+	button: "button",
+	checkbox: "checkbox",
+	radio: "radio",
+	submit: "button"
+};
+/** 名称与值都截断：一个超长文本节点不该把上下文吃光 */
+const MAX_TEXT = 200;
+const clip = (text) => {
+	const normalized = text.replace(/\s+/g, " ").trim();
+	return normalized.length > MAX_TEXT ? `${normalized.slice(0, MAX_TEXT)}…` : normalized;
+};
+function roleOf(element) {
+	const explicit = element.getAttribute("role");
+	if (explicit !== null && explicit.trim() !== "") return explicit.trim();
+	if (element.tagName === "INPUT") {
+		const type = (element.getAttribute("type") ?? "text").toLowerCase();
+		return INPUT_TYPE_ROLE[type] ?? "textbox";
+	}
+	return ROLE_BY_TAG[element.tagName.toUpperCase()] ?? "generic";
+}
+/** 自身直系文本（不含后代元素的文本）：后代会各自成为节点，重复没有意义 */
+function ownText(element) {
+	let text = "";
+	for (const node of element.childNodes) if (node.nodeType === 3) text += node.nodeValue ?? "";
+	return clip(text);
+}
+function nameOf(element, doc) {
+	const label = element.getAttribute("aria-label");
+	if (label !== null && label.trim() !== "") return clip(label);
+	const labelledBy = element.getAttribute("aria-labelledby");
+	if (labelledBy !== null) {
+		const parts = labelledBy.split(/\s+/).map((id) => doc.getElementById(id)?.textContent ?? "").filter((part) => part.trim() !== "");
+		if (parts.length > 0) return clip(parts.join(" "));
+	}
+	if (element.tagName === "IMG") {
+		const alt = element.getAttribute("alt");
+		if (alt !== null && alt.trim() !== "") return clip(alt);
+	}
+	const own = ownText(element);
+	return own === "" ? void 0 : own;
+}
+function valueOf(element) {
+	if (element.tagName === "INPUT") {
+		const type = (element.getAttribute("type") ?? "text").toLowerCase();
+		if (SECRET_INPUT_TYPES.has(type)) return void 0;
+		const value = element.value;
+		return value === "" ? void 0 : clip(value);
+	}
+	if (element.tagName === "TEXTAREA" || element.tagName === "SELECT") {
+		const value = element.value;
+		return value === "" ? void 0 : clip(value);
+	}
+}
+/**
+* 隐藏节点不进结果：屏幕上看不见的东西，用户没有机会发现它被读走了。
+* jsdom 里 `getComputedStyle` 可用但布局是假的，因此只看显式声明，不看尺寸。
+*/
+function hidden(element, view) {
+	if (element.hasAttribute("hidden")) return true;
+	if (element.getAttribute("aria-hidden") === "true") return true;
+	const inlineStyle = element.getAttribute("style") ?? "";
+	if (/display\s*:\s*none|visibility\s*:\s*hidden/i.test(inlineStyle)) return true;
+	if (view !== null) {
+		const computed = view.getComputedStyle(element);
+		if (computed.display === "none" || computed.visibility === "hidden") return true;
+	}
+	return false;
+}
+/** script / style 的正文是代码，不是页面内容 */
+const SKIPPED_TAGS = /* @__PURE__ */ new Set([
+	"SCRIPT",
+	"STYLE",
+	"NOSCRIPT",
+	"TEMPLATE"
+]);
+function describe(element, excluded, doc, view, targets) {
+	if (excluded.has(element)) return void 0;
+	if (SKIPPED_TAGS.has(element.tagName)) return void 0;
+	if (hidden(element, view)) return void 0;
+	const children = [];
+	for (const child of element.children) {
+		const node = describe(child, excluded, doc, view, targets);
+		if (node !== void 0) children.push(node);
+	}
+	const name = nameOf(element, doc);
+	const value = valueOf(element);
+	const role = roleOf(element);
+	if (role === "generic" && name === void 0 && value === void 0 && children.length === 0) return void 0;
+	const node = {
+		role,
+		...name !== void 0 ? { name } : {},
+		...value !== void 0 ? { value } : {},
+		...children.length > 0 ? { children } : {}
+	};
+	if (targets !== void 0 && isCapturableElement(element)) targets.push({
+		element,
+		node
+	});
+	return node;
+}
+/**
+* DOM 遍历实现（设计 09 §2 的「实现层」）。产出只有角色 / 名称 / 值，
+* **不含任何 HTML 标记、class、data 属性或注释**（FR-10.4）。
+*
+* 判定顺序是先 `include` 取子树再 `exclude` 剪枝：`exclude` 命中的元素连同
+* 其整棵后代一起消失，而不是只去掉那一个节点。
+* @experimental
+*/
+function createDomPerceptionReader(options = {}) {
+	function collect(scope, targets) {
+		const doc = options.document ?? globalThis.document;
+		if (doc === void 0 || scope.include.length === 0) return [];
+		const view = doc.defaultView;
+		const excluded = /* @__PURE__ */ new Set();
+		for (const selector of scope.exclude ?? []) for (const element of doc.querySelectorAll(selector)) excluded.add(element);
+		const roots = [];
+		for (const selector of scope.include) for (const element of doc.querySelectorAll(selector)) if (!roots.includes(element)) roots.push(element);
+		const nodes = [];
+		for (const root of roots) {
+			const node = describe(root, excluded, doc, view, targets);
+			if (node !== void 0) nodes.push(node);
+		}
+		return nodes;
+	}
+	async function readWithImages(scope, capture) {
+		const targets = [];
+		const nodes = collect(scope, targets);
+		const selected = targets.slice(0, capture.maxImages);
+		const images = [];
+		let imageFailures = 0;
+		for (const [index, target] of selected.entries()) {
+			const result = await captureElementImage(target.element, {
+				id: `img-${index + 1}`,
+				maxBytes: capture.maxImageBytes
+			});
+			if (isCaptureFailure(result)) {
+				target.node.imageNote = result.reason;
+				imageFailures += 1;
+				continue;
+			}
+			target.node.imageId = result.id;
+			images.push({
+				id: result.id,
+				mimeType: result.mimeType,
+				data: result.data,
+				level: result.level
+			});
+		}
+		for (const target of targets.slice(capture.maxImages)) target.node.imageNote = "Not captured: the per-message image limit was reached";
+		return {
+			nodes,
+			images,
+			imagesOmitted: targets.length - selected.length,
+			imageFailures
+		};
+	}
+	function read(scope, capture) {
+		if (capture === void 0) return collect(scope, void 0);
+		if (!capture.images || capture.maxImages <= 0) return Promise.resolve({ nodes: collect(scope, void 0) });
+		return readWithImages(scope, capture);
+	}
+	return { read };
+}
 const isRecord = (v) => typeof v === "object" && v !== null;
 const isNonEmptyString = (v) => typeof v === "string" && v !== "";
 /** Worker 侧入站校验：非法消息返回 undefined（忽略） */
@@ -1636,6 +2319,173 @@ var WorkerRuntimeClient = class {
 		}
 	}
 };
+/**
+* 静态加密的 MemoryStore 包装（FR-19.5）。落盘形态：
+* `{ v: 1, iv: base64, ct: base64 }`；每次写入生成新的 12 字节随机 IV
+* ——AES-GCM 下 IV 重用会同时毁掉机密性与完整性，不能复用。
+*
+* 算法与密钥都交给 Web Crypto，本文件不实现任何密码学原语。
+* @experimental
+*/
+const ENVELOPE_VERSION = 1;
+const toBase64 = (bytes) => {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary);
+};
+const allocate = (length) => new Uint8Array(new ArrayBuffer(length));
+const fromBase64 = (text) => {
+	const binary = atob(text);
+	const bytes = allocate(binary.length);
+	for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+	return bytes;
+};
+const encodeUtf8 = (text) => {
+	const bytes = allocate(text.length * 3);
+	const { written } = new TextEncoder().encodeInto(text, bytes);
+	return bytes.subarray(0, written);
+};
+const isEnvelope = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	const record = value;
+	return record["v"] === ENVELOPE_VERSION && typeof record["iv"] === "string" && typeof record["ct"] === "string";
+};
+/**
+* 某条已读出的记忆值是否是密文信封。观测方（如 console）据此决定要不要去取密钥：
+* 加密关着的时候不该为了读一条明文而凭空建出一把密钥。
+* @experimental
+*/
+function isEncryptedMemoryValue(value) {
+	return isEnvelope(value);
+}
+function requireSubtle() {
+	const subtle = globalThis.crypto?.subtle;
+	if (subtle === void 0) throw new WebSkillError("PROFILE_KEY_UNAVAILABLE", "Web Crypto is unavailable, so encrypted memory cannot be read or written. Serve the page over HTTPS or disable encrypted storage.");
+	return subtle;
+}
+/**
+* 用 AES-GCM 包装一个 MemoryStore：值加密后再交给 `inner`，读取时解密。
+* 密钥不可用（未解锁 / 无 Web Crypto）时**拒绝读写并抛结构化错误**，
+* 不静默降级成明文——那会让「已加密」的承诺失效而用户无从察觉。
+*
+* `scopes` 限定加密范围。默认全加密；宿主通常只加密存放个人数据的
+* `user:` 作用域，把运行观测（会话参数历史、技能统计）留作明文供 console 读取。
+* @experimental
+*/
+function createEncryptedMemoryStore(inner, key, options = {}) {
+	const covers = options.scopes ?? (() => true);
+	const requireKey = () => {
+		if (key === void 0) throw new WebSkillError("PROFILE_KEY_UNAVAILABLE", "The encryption key for stored user data is unavailable, so the store refused to read or write.");
+		return key;
+	};
+	const decrypt = async (raw) => {
+		if (raw === void 0 || raw === null) return raw;
+		if (!isEnvelope(raw)) return raw;
+		const plain = await requireSubtle().decrypt({
+			name: "AES-GCM",
+			iv: fromBase64(raw.iv)
+		}, requireKey(), fromBase64(raw.ct));
+		return JSON.parse(new TextDecoder().decode(plain));
+	};
+	const store = {
+		async get(scope, storeKey) {
+			const raw = await inner.get(scope, storeKey);
+			return covers(scope) ? decrypt(raw) : raw;
+		},
+		async set(scope, storeKey, value) {
+			if (!covers(scope)) {
+				await inner.set(scope, storeKey, value);
+				return;
+			}
+			const subtle = requireSubtle();
+			const iv = crypto.getRandomValues(allocate(12));
+			const ct = await subtle.encrypt({
+				name: "AES-GCM",
+				iv
+			}, requireKey(), encodeUtf8(JSON.stringify(value ?? null)));
+			const envelope = {
+				v: ENVELOPE_VERSION,
+				iv: toBase64(iv),
+				ct: toBase64(new Uint8Array(ct))
+			};
+			await inner.set(scope, storeKey, envelope);
+		},
+		async delete(scope, storeKey) {
+			await inner.delete(scope, storeKey);
+		},
+		async list(scope) {
+			const entries = await inner.list(scope);
+			if (!covers(scope)) return entries;
+			return Promise.all(entries.map(async (entry) => ({
+				key: entry.key,
+				value: await decrypt(entry.value)
+			})));
+		},
+		async clear(scope) {
+			await inner.clear(scope);
+		}
+	};
+	if (inner.transaction) store.transaction = async (scope, fn) => inner.transaction(scope, async (raw) => fn(createEncryptedMemoryStore(raw, key, options)));
+	return store;
+}
+/**
+* 生成一把不可导出的 AES-GCM 256 密钥（FR-19.5）。不可导出意味着页面脚本
+* 拿不到原始字节，只能通过 Web Crypto 使用它；宿主负责持久化这个句柄（如 IndexedDB）。
+* @experimental
+*/
+async function generateMemoryEncryptionKey() {
+	return requireSubtle().generateKey({
+		name: "AES-GCM",
+		length: 256
+	}, false, ["encrypt", "decrypt"]);
+}
+const KEY_DB_NAME = "webskill-keys";
+const KEY_STORE_NAME = "keys";
+function request(req) {
+	return new Promise((resolve, reject) => {
+		req.onsuccess = () => resolve(req.result);
+		req.onerror = () => reject(req.error ?? /* @__PURE__ */ new Error("IndexedDB request failed"));
+	});
+}
+function openDb() {
+	const indexedDb = globalThis.indexedDB;
+	if (indexedDb === void 0) throw new WebSkillError("PROFILE_KEY_UNAVAILABLE", "IndexedDB is unavailable, so the encryption key for stored user data cannot be persisted.");
+	return new Promise((resolve, reject) => {
+		const open = indexedDb.open(KEY_DB_NAME, 1);
+		open.onupgradeneeded = () => {
+			if (!open.result.objectStoreNames.contains(KEY_STORE_NAME)) open.result.createObjectStore(KEY_STORE_NAME);
+		};
+		open.onsuccess = () => resolve(open.result);
+		open.onerror = () => reject(open.error ?? /* @__PURE__ */ new Error("IndexedDB open failed"));
+	});
+}
+/**
+* 取（必要时生成）本地数据加密密钥并持久化在 IndexedDB（FR-19.5）。
+* 存的是 `CryptoKey` 句柄本身而不是密钥字节：结构化克隆能存它，
+* 而它是 non-extractable 的，页面脚本与扩展都读不出原始字节。
+* @experimental
+*/
+async function openMemoryEncryptionKey(name = "user-profile") {
+	const db = await openDb();
+	try {
+		const existing = await request(db.transaction(KEY_STORE_NAME, "readonly").objectStore(KEY_STORE_NAME).get(name));
+		if (existing instanceof CryptoKey) return existing;
+		const created = await generateMemoryEncryptionKey();
+		await request(db.transaction(KEY_STORE_NAME, "readwrite").objectStore(KEY_STORE_NAME).put(created, name));
+		return created;
+	} finally {
+		db.close();
+	}
+}
+/** 删除本地数据加密密钥；清除画像与记录时一并调用，避免留下解不开的旧密文 @experimental */
+async function deleteMemoryEncryptionKey(name = "user-profile") {
+	const db = await openDb();
+	try {
+		await request(db.transaction(KEY_STORE_NAME, "readwrite").objectStore(KEY_STORE_NAME).delete(name));
+	} finally {
+		db.close();
+	}
+}
 
 //#endregion
-export { BrowserSkillManager, BrowserWorkerScriptExecutor, IframeWorkerLike, OpfsProvider, TsTranspiler, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, bridgeError, createIframeWorker, extractZipWeb, installWebSkillNavigator, isOpfsAvailable, parseBridgeRequest, parseMainMessage, parseWorkerEvent, sha256HexWeb, startWorkerRuntimeHost };
+export { BrowserSkillManager, BrowserWorkerScriptExecutor, ChromeBuiltinLlmClient, IframeWorkerLike, OpfsProvider, TsTranspiler, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createDomPerceptionReader, createEncryptedMemoryStore, createIframeWorker, createLlmClient, deleteMemoryEncryptionKey, extractZipWeb, generateMemoryEncryptionKey, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startWorkerRuntimeHost };