@nsnanocat/preference-panes 0.1.0 → 0.3.0

package/package.json

@@ -1,69 +1,66 @@
 {
-  "name": "@nsnanocat/preference-panes",
-  "version": "0.1.0",
-  "description": "Shared settings API runtime for JavaScript proxy modules",
-  "author": "VirgilClyne <Virgil@nanocat.me>",
-  "homepage": "https://NSNanoCat.github.io/preference-panes",
-  "keywords": [
-    "loon",
-    "quantumult",
-    "surge",
-    "shadowrocket",
-    "stash",
-    "egern",
-    "settings"
-  ],
-  "license": "Apache-2.0",
-  "bugs": "https://github.com/NSNanoCat/PreferencePanes/issues",
-  "type": "module",
-  "main": "index.mjs",
-  "exports": {
-    ".": {
-      "types": "./types/index.d.ts",
-      "import": "./index.mjs"
-    },
-    "./browser": {
-      "types": "./types/browser.d.ts",
-      "import": "./browser/index.mjs"
-    },
-    "./browser/panel.css": "./browser/panel.css",
-    "./dist/preference-panes.mjs": "./dist/preference-panes.mjs",
-    "./dist/preference-panes.request.js": "./dist/preference-panes.request.js"
-  },
-  "types": "types/index.d.ts",
-  "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "check": "npm run lint && npm run typecheck && npm test",
-    "lint": "biome check .",
-    "format": "biome check --write .",
-    "typecheck": "tsc --noEmit",
-    "build": "rollup -c",
-    "prepack": "npm run build",
-    "apifox:generate": "node scripts/generate-apifox.mjs"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/NSNanoCat/PreferencePanes.git"
-  },
-  "files": [
-    "index.mjs",
-    "lib",
-    "browser",
-    "types",
-    "dist",
-    "proxy"
-  ],
-  "dependencies": {
-    "@nsnanocat/url": "^1.2.6",
-    "@nsnanocat/util": "^2.7.4"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "2.4.6",
-    "@rollup/plugin-node-resolve": "^16.0.3",
-    "rollup": "^4.63.1",
-    "typescript": "^5.9.3"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
+	"name": "@nsnanocat/preference-panes",
+	"version": "0.3.0",
+	"description": "Shared settings API runtime for JavaScript proxy modules",
+	"author": "VirgilClyne <Virgil@nanocat.me>",
+	"homepage": "https://NSNanoCat.github.io/preference-panes",
+	"keywords": [
+		"loon",
+		"quantumult",
+		"surge",
+		"shadowrocket",
+		"stash",
+		"egern",
+		"settings"
+	],
+	"license": "Apache-2.0",
+	"bugs": "https://github.com/NSNanoCat/PreferencePanes/issues",
+	"type": "module",
+	"main": "src/index.mjs",
+	"exports": {
+		".": {
+			"types": "./src/index.d.ts",
+			"import": "./src/index.mjs"
+		},
+		"./browser": {
+			"types": "./src/browser/index.d.ts",
+			"import": "./src/browser/index.mjs"
+		},
+		"./browser/panel.css": "./src/browser/panel.css",
+		"./dist/preference-panes.mjs": "./dist/preference-panes.mjs",
+		"./dist/preference-panes.request.js": "./dist/preference-panes.request.js"
+	},
+	"types": "src/index.d.ts",
+	"scripts": {
+		"test": "node --test test/*.test.mjs",
+		"check": "npm run lint && npm run typecheck && npm test",
+		"lint": "biome check .",
+		"format": "biome check --write .",
+		"typecheck": "tsc --noEmit",
+		"build": "rollup -c",
+		"prepack": "npm run build",
+		"apifox:generate": "node apifox/generate.mjs",
+		"apifox:check": "node apifox/generate.mjs --check"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/NSNanoCat/PreferencePanes.git"
+	},
+	"files": [
+		"src",
+		"dist"
+	],
+	"dependencies": {
+		"@nsnanocat/url": "^1.2.6",
+		"@nsnanocat/util": "^2.7.4"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.6",
+		"@rollup/plugin-node-resolve": "^16.0.3",
+		"rollup": "^4.63.1",
+		"typescript": "^5.9.3"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
 }

package/src/SettingsHandler.mjs

@@ -0,0 +1,142 @@
+import { URL } from "@nsnanocat/url";
+import { Lodash as _ } from "@nsnanocat/util/polyfill/Lodash.mjs";
+import { Storage } from "@nsnanocat/util/polyfill/Storage";
+import { parseSettingsPathname, validatePathParts } from "./lib/settings-path.mjs";
+
+/**
+ * 按插件声明的根和模块桥接持久化存储，不下载或解析 BoxJS。
+ * Bridge persistence within the installed root and module without downloading or parsing BoxJS.
+ */
+export class SettingsHandler {
+	/** @type {string} 接管来源 / Handled origin. */
+	#origin;
+	/** @type {string} 安装配置中的存储根 / Storage root from installation config. */
+	#storageKey;
+	/** @type {string} 安装配置中的模块 / Module from installation config. */
+	#module;
+	/** @type {string} 页面标记头 / Page marker header. */
+	#requestHeader;
+
+	/**
+	 * 固定来源、存储根和模块，构造时不访问网络或存储。
+	 * Fix the origin, storage root and module without network or storage access at construction.
+	 * @param {import("./index.js").SettingsHandlerOptions} options 插件安装配置 / Plugin installation config.
+	 * @throws {TypeError} 安装配置无效 / Invalid installation config.
+	 */
+	constructor({ origin, storageKey, module, requestHeader = "X-Settings-Client" }) {
+		const target = new URL(origin);
+		if (target.protocol !== "https:" || target.pathname !== "/" || target.search || target.hash || target.username || target.password) throw new TypeError("origin must be an HTTPS origin");
+		if (typeof storageKey !== "string" || !storageKey || storageKey.startsWith("@")) throw new TypeError("storageKey must be a literal root key");
+		validatePathParts([module]);
+		if (!/^[a-z][a-z0-9-]*$/i.test(requestHeader)) throw new TypeError("Invalid requestHeader");
+		this.#origin = target.origin;
+		this.#storageKey = storageKey;
+		this.#module = module;
+		this.#requestHeader = requestHeader;
+	}
+
+	/**
+	 * GET 返回指定值，POST 替换指定值，DELETE 删除指定键或整个模块。
+	 * GET returns a value, POST replaces it, and DELETE removes a key or the entire module.
+	 * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
+	 * @returns {Promise<import("./index.js").SettingsResponse | undefined>} 响应或非接管请求 / Response, or undefined for an unhandled request.
+	 */
+	async handle(request) {
+		const url = new URL(request.url);
+		if (url.origin !== this.#origin || !url.pathname.startsWith("/api/")) return;
+		const headers = { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" };
+		const reply = (status, data) => ({ status, headers, body: request.method === "HEAD" ? "" : JSON.stringify(data) });
+		let parts;
+		try {
+			parts = parseSettingsPathname(url.pathname);
+		} catch (error) {
+			return reply(400, { error: error.message });
+		}
+		if (parts[0] !== this.#module) return reply(404, { error: "Module is not handled" });
+		const requestHeaders = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
+		if (requestHeaders[this.#requestHeader.toLowerCase()] !== "1" || (requestHeaders.origin && requestHeaders.origin !== this.#origin)) return reply(403, { error: "Forbidden settings client" });
+		let value;
+		switch (request.method) {
+			case "HEAD":
+				return reply(200, undefined);
+			case "GET":
+			case "DELETE":
+				break;
+			case "POST":
+				if (requestHeaders["content-type"]?.split(";")[0].trim().toLowerCase() !== "application/json") return reply(415, { error: "Expected application/json" });
+				if (typeof request.body !== "string") return reply(400, { error: "Expected a JSON string body" });
+				if (request.body.length > 65536) return reply(413, { error: "Body exceeds 65536 UTF-16 code units" });
+				try {
+					value = JSON.parse(request.body);
+				} catch {
+					return reply(400, { error: "Invalid JSON" });
+				}
+				break;
+			default:
+				return { ...reply(405, { error: "Method not allowed" }), headers: { ...headers, Allow: "HEAD, GET, POST, DELETE" } };
+		}
+		try {
+			const root = Storage.getItem(this.#storageKey, {});
+			if (!isRecord(root)) throw new TypeError("stored root must be an object");
+			const parent = storageParent(root, parts, request.method === "POST");
+			const key = parts.at(-1);
+			switch (request.method) {
+				case "GET": {
+					const result = parent ? _.get(parent, [key]) : undefined;
+					return result === undefined ? reply(404, { error: "Stored path does not exist" }) : reply(200, result);
+				}
+				case "POST":
+					_.set(parent, [key], value);
+					break;
+				case "DELETE":
+					if (parent) _.unset(parent, [key]);
+					break;
+			}
+			if (!Storage.setItem(this.#storageKey, root)) throw new Error("Storage write failed");
+			return reply(200, request.method === "POST" ? { saved: true } : { deleted: true });
+		} catch (error) {
+			return reply(500, { error: error.message });
+		}
+	}
+}
+
+/**
+ * 判断根节点是否为普通对象。
+ * Determine whether a root node is a plain object.
+ * @param {unknown} value 待检查值 / Value to inspect.
+ * @returns {boolean} 是否为普通对象 / Whether this is a plain object.
+ */
+function isRecord(value) {
+	return value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+/**
+ * 遍历父路径，兼容旧存储中 JSON 字符串形式的中间节点。
+ * Traverse parents, supporting legacy intermediate nodes serialized as JSON strings.
+ * @param {Record<string, unknown>} root 存储根 / Storage root.
+ * @param {string[]} parts 完整路径 / Complete path.
+ * @param {boolean} create 是否创建缺失节点 / Whether to create missing parents.
+ * @returns {object | undefined} 父节点，缺失且不创建时为 undefined / Parent, or undefined when absent and not creating.
+ * @throws {TypeError} 无法继续遍历标量节点 / A scalar node cannot be traversed.
+ */
+function storageParent(root, parts, create) {
+	let parent = root;
+	for (const part of parts.slice(0, -1)) {
+		let next = _.get(parent, [part]);
+		switch (typeof next) {
+			case "undefined":
+				if (!create) return;
+				next = {};
+				break;
+			case "string":
+				next = JSON.parse(next);
+				break;
+			default:
+				break;
+		}
+		if (!isRecord(next) && !Array.isArray(next)) throw new TypeError("Stored parent is not an object or array");
+		_.set(parent, [part], next);
+		parent = next;
+	}
+	return parent;
+}

package/src/browser/client.mjs

@@ -0,0 +1,228 @@
+import { normalizeBoxJs, normalizeStoredValue, validValue } from "../lib/boxjs.mjs";
+import { validatePathParts } from "../lib/settings-path.mjs";
+
+/**
+ * 单个模块的临时会话；离开页面后丢弃。
+ * Transient module session discarded when leaving the page.
+ * @typedef {object} ModuleSession
+ * @property {AbortController} controller 读取请求的取消控制器 / Abort controller for reads.
+ * @property {import("../index.js").ModuleDefinition | null} definition 加载完成的配置，加载中为 null / Loaded configuration, or null while loading.
+ * @property {import("./index.js").ModuleSnapshot["values"]} values 当前显示值 / Current display values.
+ * @property {boolean} saving 是否正在写入 / Whether a mutation is in progress.
+ */
+
+/**
+ * 创建页面会话缓存；打开时重读，选项操作仅在 HTTP 200 后更新缓存。
+ * Create a page-session cache; reload on open and mutate cache only after HTTP 200.
+ * @param {import("./index.js").PreferencesClientOptions} options 请求与通知 / Requests and notifications.
+ * @returns {import("./index.js").PreferencesClient} 通用客户端 / Generic client.
+ */
+export function createPreferencesClient({ fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 } = {}) {
+	/** @type {Map<string, ModuleSession>} 模块会话表 / Module session map. */
+	const sessions = new Map();
+	/**
+	 * 发送同源请求，处理超时与取消；数据 GET 的 404 交给调用方处理。
+	 * Send a same-origin request with timeout and cancellation; callers handle missing-data GET responses.
+	 * @param {string} path 相对请求路径 / Relative request path.
+	 * @param {"HEAD" | "GET" | "POST" | "DELETE"} method HTTP 方法 / HTTP method.
+	 * @param {unknown} body POST 值，其它方法忽略 / POST value, ignored by other methods.
+	 * @param {AbortSignal | undefined} signal 会话取消信号 / Session cancellation signal.
+	 * @param {boolean} [resource=false] 是否为无标记头的配置资源 / Whether this is a config resource without the marker header.
+	 * @returns {Promise<Response>} 未消费正文的响应 / Response with an unread body.
+	 * @throws {Error} 非 200 且非数据 GET 404、超时、取消或网络错误 / Non-200 status except missing-data GETs, timeout, cancellation or network error.
+	 */
+	async function send(path, method, body, signal, resource = false) {
+		const controller = new AbortController();
+		const abort = () => controller.abort();
+		if (signal?.aborted) abort();
+		signal?.addEventListener("abort", abort, { once: true });
+		const timer = setTimeout(abort, timeout);
+		try {
+			const response = await request(path, {
+				method,
+				credentials: "omit",
+				cache: "no-store",
+				signal: controller.signal,
+				headers: resource ? {} : { "X-Settings-Client": "1", ...(method === "POST" ? { "Content-Type": "application/json" } : {}) },
+				...(method === "POST" ? { body: JSON.stringify(body) } : {}),
+			});
+			if (response.status !== 200 && !(!resource && method === "GET" && response.status === 404)) throw new Error(`HTTP ${response.status}`);
+			return response;
+		} finally {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", abort);
+		}
+	}
+	/**
+	 * 由合法模块名生成配置 Mock 路径。
+	 * Build the config Mock path from a valid module name.
+	 * @param {string} module 模块标识 / Module identifier.
+	 * @returns {string} 配置路径 / Config path.
+	 */
+	const configPath = module => {
+		validatePathParts([module]);
+		return `/configs/${encodeURIComponent(module)}`;
+	};
+	/**
+	 * 获取独立快照，避免调用方修改内部缓存。
+	 * Return an independent snapshot so callers cannot mutate the cache.
+	 * @param {string} module 已打开模块 / Open module.
+	 * @returns {import("./index.js").ModuleSnapshot} 会话快照 / Session snapshot.
+	 * @throws {Error} 模块未完成加载 / Module has not finished loading.
+	 */
+	const snapshot = module => {
+		const state = sessions.get(module);
+		if (!state?.definition) throw new Error("Open the module first");
+		return structuredClone({ definition: state.definition, values: state.values });
+	};
+	/**
+	 * 串行修改单键，仅成功后更新仍存活的会话。
+	 * Serialize single-key mutations and update a still-active session only after success.
+	 * @param {string} module 已打开模块 / Open module.
+	 * @param {string} key 完整点分字段路径 / Complete dotted field path.
+	 * @param {"POST" | "DELETE"} method 写入或删除 / Write or delete.
+	 * @param {unknown} value 写入值，删除时忽略 / Write value, ignored for deletion.
+	 * @param {"write" | "delete" | "clearCaches" | "reset"} [operation] 操作类型 / Operation kind.
+	 * @returns {Promise<void>} 操作完成 / Operation completion.
+	 * @throws {Error} 会话、字段、值或请求错误 / Session, field, value or request error.
+	 */
+	async function change(module, key, method, value, operation = method === "POST" ? "write" : "delete") {
+		const state = sessions.get(module);
+		if (!state?.definition) throw new Error("Open the module first");
+		if (state.saving) throw new Error("A settings write is already in progress");
+		const field = state.definition.fields.find(field => field.key === key);
+		state.saving = true;
+		try {
+			if ((operation === "write" || operation === "delete") && (!field || (method === "POST" && !validValue(field, value)))) throw new TypeError("Invalid setting value");
+			await send(`/api/${key.split(".").map(encodeURIComponent).join("/")}`, method, value);
+			if (sessions.get(module) === state) {
+				switch (operation) {
+					case "write":
+						state.values[key] = structuredClone(value);
+						break;
+					case "delete":
+					case "clearCaches":
+					case "reset":
+						for (const candidate of state.definition.fields) {
+							if (candidate.key !== key && !candidate.key.startsWith(`${key}.`)) continue;
+							delete state.values[candidate.key];
+							if (Object.hasOwn(candidate, "defaultValue")) state.values[candidate.key] = structuredClone(candidate.defaultValue);
+						}
+						break;
+				}
+			}
+			notify({ kind: "success", operation, module, key });
+		} catch (error) {
+			notify({ kind: "error", operation, module, key, message: error.message });
+			throw error;
+		} finally {
+			state.saving = false;
+		}
+	}
+	return {
+		/**
+		 * 探测配置 Mock，不读写存储。
+		 * Probe the config Mock without accessing storage.
+		 * @param {string} module 模块标识 / Module identifier.
+		 * @returns {Promise<boolean>} 是否返回 HTTP 200 / Whether HTTP 200 was returned.
+		 */
+		async probe(module) {
+			try {
+				await send(configPath(module), "HEAD", undefined, undefined, true);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		/**
+		 * 替换旧会话，读取一次配置与一次设置子树。
+		 * Replace the previous session and read config and settings subtree once each.
+		 * @param {string} module 模块标识 / Module identifier.
+		 * @returns {Promise<import("./index.js").ModuleSnapshot>} 新快照 / New snapshot.
+		 * @throws {Error} 读取失败、会话被替换或写入尚未完成 / Read failure, replaced session or unfinished write.
+		 */
+		async open(module) {
+			const previous = sessions.get(module);
+			if (previous?.saving) throw new Error("Cannot refresh while saving");
+			previous?.controller.abort();
+			const state = { controller: new AbortController(), definition: null, values: {}, saving: false };
+			sessions.set(module, state);
+			try {
+				const definition = normalizeBoxJs(await (await send(configPath(module), "GET", undefined, state.controller.signal, true)).json(), module);
+				if (definition.settingsPath.length < 2) throw new TypeError("BoxJS fields must share a settings subtree below the module root");
+				const response = await send(`/api/${definition.settingsPath.map(encodeURIComponent).join("/")}/`, "GET", undefined, state.controller.signal);
+				let subtree = response.status === 404 ? {} : await response.json();
+				if (typeof subtree === "string") subtree = JSON.parse(subtree);
+				if (!subtree || typeof subtree !== "object" || Array.isArray(subtree)) throw new TypeError("Expected a settings subtree object");
+				if (sessions.get(module) !== state) throw new Error("Module session was replaced");
+				state.definition = definition;
+				for (const field of definition.fields) {
+					const stored = field.key
+						.split(".")
+						.slice(definition.settingsPath.length)
+						.reduce((parent, part) => Object(parent)[part], subtree);
+					const value = stored === undefined ? field.defaultValue : stored;
+					if (value !== undefined) state.values[field.key] = normalizeStoredValue(field, value);
+				}
+				return snapshot(module);
+			} catch (error) {
+				if (sessions.get(module) === state) sessions.delete(module);
+				throw error;
+			}
+		},
+		snapshot,
+		/**
+		 * 按需读取模块 Caches，不自动读取其它设置。
+		 * Read module Caches on demand without refreshing other settings.
+		 * @param {string} module 已打开的模块 / Open module.
+		 * @returns {Promise<unknown>} 缓存值，缺失为 undefined / Cache value, or undefined when absent.
+		 */
+		async readCaches(module) {
+			const state = sessions.get(module);
+			if (!state?.definition) throw new Error("Open the module first");
+			const response = await send(`/api/${encodeURIComponent(module)}/Caches`, "GET", undefined, state.controller.signal);
+			return response.status === 404 ? undefined : response.json();
+		},
+		/**
+		 * 删除整个 Caches 节点，成功后不追加 GET。
+		 * Delete the entire Caches node without a follow-up GET.
+		 * @param {string} module 已打开模块 / Open module.
+		 * @returns {Promise<void>} 清理完成 / Cleanup completion.
+		 */
+		clearCaches: module => change(module, `${module}.Caches`, "DELETE", undefined, "clearCaches"),
+		/**
+		 * 删除整个模块持久化节点，以当前 BoxJS 默认值重置页面缓存。
+		 * Delete module persistence and reset the page cache using current BoxJS defaults.
+		 * @param {string} module 已打开模块 / Open module.
+		 * @returns {Promise<void>} 重置完成 / Reset completion.
+		 */
+		reset: module => change(module, module, "DELETE", undefined, "reset"),
+		/**
+		 * 取消读取并清除会话，不撤销已发送的写入。
+		 * Abort reads and clear the session without undoing dispatched writes.
+		 * @param {string} module 模块标识 / Module identifier.
+		 * @returns {void} 无返回值 / No return value.
+		 */
+		leave(module) {
+			sessions.get(module)?.controller.abort();
+			sessions.delete(module);
+		},
+		/**
+		 * 写入单键并更新当前会话。
+		 * Write one key and update the current session.
+		 * @param {string} module 已打开模块 / Open module.
+		 * @param {string} key 点分字段路径 / Dotted field path.
+		 * @param {import("../index.js").SettingsScalar | import("../index.js").SettingsScalar[]} value 字段值 / Field value.
+		 * @returns {Promise<void>} 写入完成 / Write completion.
+		 */
+		set: (module, key, value) => change(module, key, "POST", value),
+		/**
+		 * 删除单键覆盖值并显示默认值。
+		 * Delete one override and display its default value.
+		 * @param {string} module 已打开模块 / Open module.
+		 * @param {string} key 点分字段路径 / Dotted field path.
+		 * @returns {Promise<void>} 删除完成 / Delete completion.
+		 */
+		remove: (module, key) => change(module, key, "DELETE"),
+	};
+}

package/src/browser/index.d.ts

@@ -0,0 +1,153 @@
+import type { ModuleDefinition, SettingsScalar } from "../index.js";
+/**
+ * 单键写入或删除的通知事件，携带对应模块与点分键路径。
+ * Notification for a single-key write or delete, including module and dotted key path.
+ */
+export interface Notification {
+	/** 结果类别 / Result kind. */
+	kind: "success" | "error";
+	/** 操作类别 / Operation kind. */
+	operation: "write" | "delete" | "clearCaches" | "reset";
+	/** 模块标识 / Module identifier. */
+	module: string;
+	/** 含模块名、不含存储根的点分路径 / Dotted path including the module but excluding the storage root. */
+	key: string;
+	/** 失败原因，仅错误事件提供 / Failure reason, provided for errors only. */
+	message?: string;
+}
+/**
+ * 浏览器会话客户端选项。
+ * Options for the browser session client.
+ */
+export interface PreferencesClientOptions {
+	/** 默认使用浏览器 fetch，可注入同签名传输 / Defaults to browser fetch; an equivalent transport may be supplied. */
+	fetch?: typeof globalThis.fetch;
+	/** 成功写入或失败时调用，不用于读取事件 / Called for successful mutations or failures, not reads. */
+	notify?: (notification: Notification) => void;
+	/** 单次请求超时，单位毫秒，默认 10000 / Per-request timeout in milliseconds; defaults to 10000. */
+	timeout?: number;
+}
+/**
+ * 会话的深拷贝快照，调用方修改不会影响缓存。
+ * Deep-cloned session snapshot; caller changes cannot alter the cache.
+ */
+export interface ModuleSnapshot {
+	/** 当前配置生成的模块定义 / Module definition generated from current config. */
+	definition: ModuleDefinition;
+	/** 点分键到显示值的映射，已包含适用的默认值 / Dotted keys mapped to display values including applicable defaults. */
+	values: Record<string, SettingsScalar | SettingsScalar[]>;
+}
+/**
+ * 只在页面存活期间维护模块缓存的通用客户端。
+ * Generic client maintaining module caches only during the page lifetime.
+ */
+export interface PreferencesClient {
+	/**
+	 * HEAD 探测配置 Mock，不读取持久化数据。
+	 * Probe the config Mock with HEAD without reading persistence.
+	 * @param module 模块标识 / Module identifier.
+	 * @returns 仅 HTTP 200 为 true；无效模块或请求失败为 false / True only for HTTP 200; false for invalid modules or failed requests.
+	 */
+	probe(module: string): Promise<boolean>;
+	/**
+	 * 替换会话，各读取一次配置与设置子树。
+	 * Replace the session and fetch config and settings subtree once each.
+	 * @param module 模块标识 / Module identifier.
+	 * @returns 新会话的独立快照 / Independent snapshot of the new session.
+	 * @throws {Error} 写入进行中、请求或配置无效、会话被替换 / Active write, invalid request or config, or replaced session.
+	 */
+	open(module: string): Promise<ModuleSnapshot>;
+	/**
+	 * 获取已打开模块的快照，不发请求。
+	 * Get a snapshot of an open module without network requests.
+	 * @param module 模块标识 / Module identifier.
+	 * @returns 深拷贝快照 / Deep-cloned snapshot.
+	 * @throws {Error} 模块尚未打开 / Module has not been opened.
+	 */
+	snapshot(module: string): ModuleSnapshot;
+	/**
+	 * 取消未完成的读取并移除缓存，不撤销已发送的写入。
+	 * Abort pending reads and discard the cache without undoing dispatched writes.
+	 * @param module 模块标识 / Module identifier.
+	 * @returns 无返回值 / No return value.
+	 */
+	leave(module: string): void;
+	/**
+	 * POST 单个字段，HTTP 200 后更新缓存，不追加 GET。
+	 * POST one field and update its cache only on HTTP 200, without a follow-up GET.
+	 * @param module 已打开的模块 / Open module.
+	 * @param key 完整点分字段路径 / Complete dotted field path.
+	 * @param value 符合字段类型和选项的值 / Value matching the field type and choices.
+	 * @returns 操作完成 / Completion of the operation.
+	 * @throws {Error} 会话、值、并发写入或网络错误 / Session, value, concurrent-write or network error.
+	 */
+	set(module: string, key: string, value: SettingsScalar | SettingsScalar[]): Promise<void>;
+	/**
+	 * DELETE 单个覆盖值，HTTP 200 后显示默认值，不追加 GET。
+	 * DELETE an override and display its default after HTTP 200, without a follow-up GET.
+	 * @param module 已打开的模块 / Open module.
+	 * @param key 完整点分字段路径 / Complete dotted field path.
+	 * @returns 操作完成 / Completion of the operation.
+	 * @throws {Error} 会话、路径、并发写入或网络错误 / Session, path, concurrent-write or network error.
+	 */
+	remove(module: string, key: string): Promise<void>;
+	/**
+	 * 按需读取整个模块 Caches，不刷新设置。
+	 * Read all module Caches on demand without refreshing settings.
+	 * @param module 已打开模块 / Open module.
+	 * @returns 缓存 JSON 值，缺失时为 undefined / Cache JSON value, or undefined when absent.
+	 */
+	readCaches(module: string): Promise<unknown>;
+	/**
+	 * 删除模块 Caches 并更新相关页面状态，不追加 GET。
+	 * Delete module Caches and update related page state without a follow-up GET.
+	 * @param module 已打开模块 / Open module.
+	 * @returns 清理完成 / Cleanup completion.
+	 */
+	clearCaches(module: string): Promise<void>;
+	/**
+	 * 删除整个模块持久化数据，页面使用当前 BoxJS 默认值。
+	 * Delete all module persistence and use current BoxJS defaults on the page.
+	 * @param module 已打开模块 / Open module.
+	 * @returns 重置完成 / Reset completion.
+	 */
+	reset(module: string): Promise<void>;
+}
+/**
+ * WebView 面板的挂载选项，模块标识从页面路径读取。
+ * Mount options for the WebView panel; the module is read from the page path.
+ */
+export interface PreferencesPanelOptions {
+	/** 具有浏览器 window 的挂载元素 / Mount element owned by a document with a browser window. */
+	element: HTMLElement;
+	/** 无有效模块时的标题，默认 Preferences / Title without a valid module; defaults to Preferences. */
+	title?: string;
+	/** 可选浏览器请求传输 / Optional browser request transport. */
+	fetch?: typeof globalThis.fetch;
+}
+/**
+ * 面板生命周期控制句柄。
+ * Handle controlling the panel lifecycle.
+ */
+export interface PreferencesPanel {
+	/**
+	 * 移除事件、面板与定时器，并取消当前读取。
+	 * Remove listeners, panel and timers, and abort the current read.
+	 * @returns 无返回值 / No return value.
+	 */
+	destroy(): void;
+}
+/**
+ * 创建模块会话客户端，不立即发出请求。
+ * Create a module session client without immediately making requests.
+ * @param options 请求、通知和超时选项 / Request, notification and timeout options.
+ * @returns 通用客户端 / Generic client.
+ */
+export function createPreferencesClient(options?: PreferencesClientOptions): PreferencesClient;
+/**
+ * 按 /settings/{module} 挂载动态面板，监听导航和页面恢复事件。
+ * Mount a dynamic panel at /settings/{module} and observe navigation and page restoration.
+ * @param options 挂载选项 / Mount options.
+ * @returns 面板生命周期句柄 / Panel lifecycle handle.
+ */
+export function mountPreferencePanes(options: PreferencesPanelOptions): PreferencesPanel;

package/src/browser/index.mjs

@@ -0,0 +1,7 @@
+/**
+ * WebView 面板与页面会话客户端的公开入口。
+ * Public entry for the WebView panel and page session client.
+ * @module @nsnanocat/preference-panes/browser
+ */
+export { createPreferencesClient } from "./client.mjs";
+export { mountPreferencePanes } from "./panel.mjs";