@nsnanocat/preference-panes 0.1.0

package/dist/preference-panes.mjs

@@ -0,0 +1,720 @@
+/* https://www.lodashjs.com */
+/**
+ * 轻量 Lodash 工具集。
+ * Lightweight Lodash-like utilities.
+ *
+ * 说明:
+ * Notes:
+ * - 这是 Lodash 的“部分方法”简化实现，不等价于完整 Lodash
+ * - This is a simplified subset, not a full Lodash implementation
+ * - 各方法语义可参考 Lodash 官方文档
+ * - Method semantics can be referenced from official Lodash docs
+ * - 导入时建议使用 `Lodash as _`，遵循 lodash 官方示例惯例
+ * - Use `Lodash as _` when importing, following official lodash example convention
+ *
+ * 参考:
+ * Reference:
+ * - https://www.lodashjs.com
+ * - https://lodash.com
+ */
+class Lodash {
+	/**
+	 * HTML 特殊字符转义。
+	 * Escape HTML special characters.
+	 *
+	 * @param {string} string 输入文本 / Input text.
+	 * @returns {string}
+	 * @see {@link https://lodash.com/docs/#escape lodash.escape}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.escape lodash.escape (中文)}
+	 */
+	static escape(string) {
+		const map = {
+			"&": "&",
+			"<": "&lt;",
+			">": "&gt;",
+			'"': "&quot;",
+			"'": "&#39;",
+		};
+		return string.replace(/[&<>"']/g, m => map[m]);
+	}
+
+	/**
+	 * 按路径读取对象值。
+	 * Get object value by path.
+	 *
+	 * @param {object} [object={}] 目标对象 / Target object.
+	 * @param {string|string[]} [path=""] 路径 / Path.
+	 * @param {*} [defaultValue=undefined] 默认值 / Default value.
+	 * @returns {*}
+	 * @see {@link https://lodash.com/docs/#get lodash.get}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.get lodash.get (中文)}
+	 */
+	static get(object = {}, path = "", defaultValue = undefined) {
+		// translate array case to dot case, then split with .
+		// a[0].b -> a.0.b -> ['a', '0', 'b']
+		if (!Array.isArray(path)) path = Lodash.toPath(path);
+
+		const result = path.reduce((previousValue, currentValue) => {
+			return Object(previousValue)[currentValue]; // null undefined get attribute will throwError, Object() can return a object
+		}, object);
+		return result === undefined ? defaultValue : result;
+	}
+
+	/**
+	 * 递归合并源对象的自身可枚举属性到目标对象
+	 * Recursively merge source enumerable properties into target object.
+	 * @description 简化版 lodash.merge，用于合并配置对象
+	 * @description A simplified lodash.merge for config merging.
+	 *
+	 * 适用情况:
+	 * - 合并嵌套的配置/设置对象
+	 * - 需要深度合并而非浅层覆盖的场景
+	 * - 多个源对象依次合并到目标对象
+	 *
+	 * 限制:
+	 * - 仅处理普通对象 (Plain Object)，不处理 Date/RegExp 等特殊对象
+	 * - Map/Set 仅支持同类型合并，不递归内部值
+	 * - 数组会被直接覆盖，不会合并数组元素
+	 * - 不处理循环引用，可能导致栈溢出
+	 * - 不复制 Symbol 属性和不可枚举属性
+	 * - 不保留原型链，仅处理自身属性
+	 * - 会修改原始目标对象 (mutates target)
+	 *
+	 * @param {object} object - 目标对象
+	 * @param {object} object - Target object.
+	 * @param {...object} sources - 源对象(可多个)
+	 * @param {...object} sources - Source objects.
+	 * @returns {object} 返回合并后的目标对象
+	 * @returns {object} Merged target object.
+	 * @see {@link https://lodash.com/docs/#merge lodash.merge}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.merge lodash.merge (中文)}
+	 * @example
+	 * const target = { a: { b: 1 }, c: 2 };
+	 * const source = { a: { d: 3 }, e: 4 };
+	 * Lodash.merge(target, source);
+	 * // => { a: { b: 1, d: 3 }, c: 2, e: 4 }
+	 */
+	static merge(object, ...sources) {
+		if (object === null || object === undefined) return object;
+
+		for (const source of sources) {
+			if (source === null || source === undefined) continue;
+
+			for (const key of Object.keys(source)) {
+				const sourceValue = source[key];
+				const targetValue = object[key];
+
+				switch (true) {
+					case Lodash.#isPlainObject(sourceValue) && Lodash.#isPlainObject(targetValue):
+						// 递归合并对象
+						object[key] = Lodash.merge(targetValue, sourceValue);
+						break;
+					case sourceValue instanceof Map && targetValue instanceof Map:
+						// 合并 Map（空 Map 跳过）
+						if (sourceValue.size > 0) {
+							for (const [k, v] of sourceValue) {
+								targetValue.set(k, v);
+							}
+						}
+						break;
+					case sourceValue instanceof Set && targetValue instanceof Set:
+						// 合并 Set（空 Set 跳过）
+						if (sourceValue.size > 0) {
+							for (const v of sourceValue) {
+								targetValue.add(v);
+							}
+						}
+						break;
+					case Array.isArray(sourceValue) && sourceValue.length === 0 && targetValue !== undefined:
+						// 空数组不覆盖已有值
+						break;
+					case (sourceValue instanceof Map && sourceValue.size === 0 && targetValue !== undefined):
+					case (sourceValue instanceof Set && sourceValue.size === 0 && targetValue !== undefined):
+						// 空 Map/Set 不覆盖已有值
+						break;
+					case sourceValue !== undefined:
+						object[key] = sourceValue;
+						break;
+				}
+			}
+		}
+
+		return object;
+	}
+
+	/**
+	 * 判断值是否为普通对象 (Plain Object)
+	 * Check whether a value is a plain object.
+	 * @param {*} value - 要检查的值
+	 * @param {*} value - Value to check.
+	 * @returns {boolean} 如果是普通对象返回 true
+	 * @returns {boolean} Returns true when value is a plain object.
+	 * @see {@link https://lodash.com/docs/#isPlainObject lodash.isPlainObject}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.isPlainObject lodash.isPlainObject (中文)}
+	 */
+	static #isPlainObject(value) {
+		if (value === null || typeof value !== "object") return false;
+		const proto = Object.getPrototypeOf(value);
+		return proto === null || proto === Object.prototype;
+	}
+
+	/**
+	 * 删除对象指定路径并返回对象。
+	 * Omit paths from object and return the same object.
+	 *
+	 * @param {object} [object={}] 目标对象 / Target object.
+	 * @param {string|string[]} [paths=[]] 要删除的路径 / Paths to remove.
+	 * @returns {object}
+	 * @see {@link https://lodash.com/docs/#omit lodash.omit}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.omit lodash.omit (中文)}
+	 */
+	static omit(object = {}, paths = []) {
+		if (!Array.isArray(paths)) paths = [paths.toString()];
+		paths.forEach(path => Lodash.unset(object, path));
+		return object;
+	}
+
+	/**
+	 * 仅保留对象指定键（第一层）。
+	 * Pick selected keys from object (top level only).
+	 *
+	 * @param {object} [object={}] 目标对象 / Target object.
+	 * @param {string|string[]} [paths=[]] 需要保留的键 / Keys to keep.
+	 * @returns {object}
+	 * @see {@link https://lodash.com/docs/#pick lodash.pick}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.pick lodash.pick (中文)}
+	 */
+	static pick(object = {}, paths = []) {
+		if (!Array.isArray(paths)) paths = [paths.toString()];
+		const filteredEntries = Object.entries(object).filter(([key, value]) => paths.includes(key));
+		return Object.fromEntries(filteredEntries);
+	}
+
+	/**
+	 * 按路径写入对象值。
+	 * Set object value by path.
+	 *
+	 * @param {object} object 目标对象 / Target object.
+	 * @param {string|string[]} path 路径 / Path.
+	 * @param {*} value 写入值 / Value.
+	 * @returns {object}
+	 * @see {@link https://lodash.com/docs/#set lodash.set}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.set lodash.set (中文)}
+	 */
+	static set(object, path, value) {
+		if (!Array.isArray(path)) path = Lodash.toPath(path);
+		path.slice(0, -1).reduce((previousValue, currentValue, currentIndex) => (Object(previousValue[currentValue]) === previousValue[currentValue] ? previousValue[currentValue] : (previousValue[currentValue] = /^\d+$/.test(path[currentIndex + 1]) ? [] : {})), object)[path[path.length - 1]] = value;
+		return object;
+	}
+
+	/**
+	 * 将点路径或数组下标路径转换为数组。
+	 * Convert dot/array-index path string into path segments.
+	 *
+	 * @param {string} value 路径字符串 / Path string.
+	 * @returns {string[]}
+	 * @see {@link https://lodash.com/docs/#toPath lodash.toPath}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.toPath lodash.toPath (中文)}
+	 */
+	static toPath(value) {
+		return value
+			.replace(/\[(\d+)\]/g, ".$1")
+			.split(".")
+			.filter(Boolean);
+	}
+
+	/**
+	 * HTML 实体反转义。
+	 * Unescape HTML entities.
+	 *
+	 * @param {string} string 输入文本 / Input text.
+	 * @returns {string}
+	 * @see {@link https://lodash.com/docs/#unescape lodash.unescape}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.unescape lodash.unescape (中文)}
+	 */
+	static unescape(string) {
+		const map = {
+			"&amp;": "&",
+			"&lt;": "<",
+			"&gt;": ">",
+			"&quot;": '"',
+			"&#39;": "'",
+		};
+		return string.replace(/&amp;|&lt;|&gt;|&quot;|&#39;/g, m => map[m]);
+	}
+
+	/**
+	 * 删除对象路径对应的值。
+	 * Remove value by object path.
+	 *
+	 * @param {object} [object={}] 目标对象 / Target object.
+	 * @param {string|string[]} [path=""] 路径 / Path.
+	 * @returns {boolean}
+	 * @see {@link https://lodash.com/docs/#unset lodash.unset}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.unset lodash.unset (中文)}
+	 */
+	static unset(object = {}, path = "") {
+		if (!Array.isArray(path)) path = Lodash.toPath(path);
+		const result = path.reduce((previousValue, currentValue, currentIndex) => {
+			if (currentIndex === path.length - 1) {
+				delete previousValue[currentValue];
+				return true;
+			}
+			return Object(previousValue)[currentValue];
+		}, object);
+		return result;
+	}
+}
+
+/**
+ * 将 /api/ 后的 URL 路径转换为 util 的路径片段；非 API 路径不处理。
+ * Convert URL segments after /api/ to util path segments; ignore non-API paths.
+ * @param {string} url 请求完整 URL / Absolute request URL.
+ * @returns {string[] | undefined} 键路径片段 / Key path segments.
+ * @throws {TypeError} API 路径无效或包含危险片段 / Invalid or unsafe API path.
+ */
+function parseSettingsPath(url) {
+  const pathname = new URL(url).pathname;
+  if (!pathname.startsWith("/api/")) return;
+  let parts;
+  try {
+    parts = pathname.slice(5).replace(/\/$/, "").split("/").map(decodeURIComponent);
+  } catch {
+    throw new TypeError("Invalid encoded key path");
+  }
+  if (!parts.every((part) => /^[a-zA-Z0-9_-]+$/.test(part) && !["__proto__", "prototype", "constructor"].includes(part)))
+    throw new TypeError("Invalid key path");
+  return parts;
+}
+
+/**
+ * 将 BoxJS 数组、app 或订阅转换为模块字段，保留原文件为唯一字段来源。
+ * Normalize a BoxJS array, app or subscription using the source JSON as the field authority.
+ * @param {unknown} config BoxJS JSON / BoxJS document.
+ * @param {string} module API 第一段模块名 / First API path segment.
+ * @returns {import("../types/index.js").ModuleDefinition} 存储根和字段 / Storage root and fields.
+ */
+function normalizeBoxJs(config, module) {
+  parseSettingsPath(`https://example.invalid/api/${module}`);
+  const entries = Array.isArray(config) ? config : config?.apps ? config.apps.flatMap((app) => app.settings ?? []) : config?.settings;
+  if (!Array.isArray(entries)) throw new TypeError("Expected BoxJS settings array, app or subscription");
+  let storageKey;
+  const fields = [];
+  for (const entry of entries) {
+    if (typeof entry.id !== "string" || !entry.id.startsWith("@")) throw new TypeError("BoxJS settings require @root.path IDs");
+    const [root, ...parts] = entry.id.slice(1).split(".");
+    if (parts[0] !== module) continue;
+    if (parts.length < 2) throw new TypeError("A BoxJS setting must be below the module root");
+    parseSettingsPath(`https://example.invalid/api/${parts.map(encodeURIComponent).join("/")}`);
+    if (!root || (storageKey && root !== storageKey)) throw new TypeError("A module must use one storage root");
+    storageKey = root;
+    const type = { boolean: "boolean", checkboxes: "array", selects: "select", text: "string", textarea: "string", number: "number" }[
+      entry.type
+    ];
+    if (!type) throw new TypeError(`Unsupported BoxJS control: ${entry.type}`);
+    const field = {
+      key: parts.join("."),
+      name: entry.name,
+      type: type === "select" ? typeof entry.val : type,
+      description: entry.desc ?? "",
+    };
+    if (type === "select" && !["string", "number", "boolean"].includes(field.type))
+      throw new TypeError(`Select requires a scalar val: ${entry.id}`);
+    if (entry.items) field.options = entry.items.map((item) => ({ key: item.key, label: item.label }));
+    if (Object.hasOwn(entry, "val")) field.defaultValue = normalizeStoredValue(field, entry.val);
+    if (
+      typeof field.name !== "string" ||
+      fields.some((other) => other.key === field.key || other.key.startsWith(`${field.key}.`) || field.key.startsWith(`${other.key}.`))
+    )
+      throw new TypeError(`Invalid or overlapping BoxJS field: ${entry.id}`);
+    if (
+      field.options &&
+      (new Set(field.options.map((item) => item.key)).size !== field.options.length ||
+        field.options.some((item) => !scalar(item.key) || typeof item.label !== "string"))
+    )
+      throw new TypeError(`Invalid options: ${entry.id}`);
+    if (Object.hasOwn(field, "defaultValue") && !validValue(field, field.defaultValue))
+      throw new TypeError(`Invalid BoxJS val: ${entry.id}`);
+    fields.push(field);
+  }
+  if (!fields.length) throw new TypeError(`No BoxJS settings for module: ${module}`);
+  const common = fields[0].key.split(".").slice(0, -1);
+  for (const field of fields) while (!field.key.startsWith(`${common.join(".")}.`)) common.pop();
+  return { module, storageKey, fields, settingsPath: common };
+}
+
+/**
+ * 归一化 BoxJS 的字符串存储值，不改变普通文本内容。
+ * Normalize BoxJS string persistence without changing free-text values.
+ * @param {import("../types/index.js").SettingsField} field 字段 / Field.
+ * @param {unknown} value 存储值 / Stored value.
+ * @returns {unknown} 控件值 / Control value.
+ */
+function normalizeStoredValue(field, value) {
+  if (field.type === "boolean" && (value === "true" || value === "false")) return value === "true";
+  if (field.type === "number" && typeof value === "string" && value.trim() !== "") return Number(value);
+  if (field.type === "array" && typeof value === "string") value = value === "" || value === "[]" ? [] : value.split(",");
+  if (field.options) {
+    const match = (item) => field.options.find((option) => String(option.key) === String(item))?.key ?? item;
+    return field.type === "array" && Array.isArray(value) ? value.map(match) : match(value);
+  }
+  return value;
+}
+
+function scalar(value) {
+  return (
+    typeof value === "boolean" ||
+    (typeof value === "string" && value.length <= 2048) ||
+    (typeof value === "number" && Number.isFinite(value))
+  );
+}
+
+function validValue(field, value) {
+  if (field.type === "array") {
+    if (!Array.isArray(value) || value.some((item) => !scalar(item)) || new Set(value).size !== value.length) return false;
+  } else if (typeof value !== field.type || !scalar(value)) return false;
+  return !field.options || (field.type === "array" ? value : [value]).every((item) => field.options.some((option) => option.key === item));
+}
+
+/**
+ * 创建页面会话缓存；打开时重读，选项操作仅在 HTTP 200 后更新缓存。
+ * Create a page-session cache; reload on open and mutate cache only after HTTP 200.
+ * @param {import("../types/browser.js").PreferencesClientOptions} options 请求与通知 / Requests and notifications.
+ * @returns {import("../types/browser.js").PreferencesClient} 通用客户端 / Generic client.
+ */
+function createPreferencesClient({ fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 } = {}) {
+  const sessions = new Map();
+  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) throw new Error(`HTTP ${response.status}`);
+      return response;
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+    }
+  }
+  const configPath = (module) => {
+    if (typeof module !== "string" || !module) throw new TypeError("module is required");
+    const parts = parseSettingsPath(`https://example.invalid/api/${encodeURIComponent(module)}/`);
+    if (parts.length !== 1) throw new TypeError("Expected a module name");
+    return `/configs/${encodeURIComponent(module)}`;
+  };
+  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 });
+  };
+  async function change(module, key, method, value) {
+    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 (!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) {
+        if (method === "DELETE") {
+          delete state.values[key];
+          if (Object.hasOwn(field, "defaultValue")) state.values[key] = structuredClone(field.defaultValue);
+        } else state.values[key] = structuredClone(value);
+      }
+      notify({ kind: "success", operation: method === "DELETE" ? "delete" : "write", module, key });
+    } catch (error) {
+      notify({ kind: "error", operation: method === "DELETE" ? "delete" : "write", module, key, message: error.message });
+      throw error;
+    } finally {
+      state.saving = false;
+    }
+  }
+  return {
+    async probe(module) {
+      try {
+        await send(configPath(module), "HEAD", undefined, undefined, true);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    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 resource = configPath(module);
+        const definition = normalizeBoxJs(await (await send(resource, "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 subtree = await (
+          await send(`/api/${definition.settingsPath.map(encodeURIComponent).join("/")}/`, "GET", undefined, state.controller.signal)
+        ).json();
+        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 value = Lodash.get(subtree, field.key.split(".").slice(definition.settingsPath.length), field.defaultValue);
+          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,
+    leave(module) {
+      sessions.get(module)?.controller.abort();
+      sessions.delete(module);
+    },
+    set: (module, key, value) => change(module, key, "POST", value),
+    remove: (module, key) => change(module, key, "DELETE"),
+  };
+}
+
+/**
+ * 挂载从 BoxJS 实时生成的设置面板和短暂通知。
+ * Mount runtime-generated BoxJS controls and transient notifications.
+ * @param {import("../types/browser.js").PreferencesPanelOptions} options 容器与请求；页面路径 /settings/{module} 对应配置 / Container and requests; /settings/{module} selects config.
+ * @returns {{destroy(): void}} 清理接口 / Cleanup handle.
+ */
+function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
+  const document = root.ownerDocument;
+  const window = document.defaultView;
+  const node = (tag, className, text) => {
+    const el = document.createElement(tag);
+    el.className = className;
+    if (text !== undefined) el.textContent = text;
+    return el;
+  };
+  const shell = node("div", "pp-panel");
+  const header = node("header", "pp-header");
+  const back = node("button", "pp-back", "返回");
+  back.type = "button";
+  const heading = node("h1", "pp-title", title);
+  const viewport = node("div", "pp-viewport");
+  const toast = node("div", "pp-toast");
+  toast.setAttribute("role", "status");
+  toast.hidden = true;
+  header.append(back, heading);
+  shell.append(header, viewport, toast);
+  root.append(shell);
+  let timer,
+    routedPath,
+    generation = 0,
+    active = null,
+    saving = false,
+    pendingRoute = false,
+    destroyed = false;
+  const notify = (event) => {
+    if (destroyed) return;
+    toast.textContent = event.kind === "error" ? `操作失败：${event.message}` : event.operation === "delete" ? "删除成功" : "修改成功";
+    toast.dataset.kind = event.kind;
+    toast.hidden = false;
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      toast.hidden = true;
+    }, 2400);
+  };
+  const client = createPreferencesClient({ ...(fetch ? { fetch } : {}), notify });
+  function replace(view, direction) {
+    const old = viewport.firstElementChild;
+    viewport.replaceChildren(view);
+    if (old && !document.defaultView.matchMedia("(prefers-reduced-motion: reduce)").matches)
+      view.animate(
+        [
+          { opacity: 0.4, transform: `translateX(${direction * 24}px)` },
+          { opacity: 1, transform: "translateX(0)" },
+        ],
+        { duration: 180, easing: "ease-out" },
+      );
+  }
+  async function open(module) {
+    const version = ++generation;
+    active = module;
+    back.disabled = window.history.length <= 1;
+    heading.textContent = module;
+    replace(node("p", "pp-loading", "读取设置…"), 1);
+    try {
+      await client.open(module);
+      if (version === generation) controls();
+    } catch (error) {
+      if (version !== generation) return;
+      const view = node("section", "pp-error");
+      view.append(node("p", "", `加载失败：${error.message}`));
+      const retry = node("button", "", "重新读取");
+      retry.onclick = () => open(module);
+      view.append(retry);
+      replace(view, 1);
+    }
+  }
+  function controls() {
+    const { definition, values } = client.snapshot(active);
+    const view = node("section", "pp-fields");
+    for (const field of definition.fields) {
+      const row = node("fieldset", "pp-field");
+      row.append(node("legend", "", field.name));
+      if (field.description) row.append(node("p", "pp-description", field.description));
+      const value = values[field.key];
+      let read, write;
+      if (field.options && field.type !== "array") {
+        const select = node("select", "pp-input");
+        select.setAttribute("aria-label", field.name);
+        field.options.forEach((option, index) => {
+          const item = node("option", "", option.label);
+          item.value = String(index);
+          select.append(item);
+        });
+        write = (value) => {
+          select.selectedIndex = field.options.findIndex((option) => option.key === value);
+        };
+        row.append(select);
+        read = () => field.options[select.selectedIndex]?.key;
+      } else if (field.type === "array" && field.options) {
+        const inputs = field.options.map((option) => {
+          const label = node("label", "pp-choice", option.label);
+          const input = node("input", "");
+          input.type = "checkbox";
+          input.checked = Array.isArray(value) && value.includes(option.key);
+          label.prepend(input);
+          row.append(label);
+          return { input, key: option.key };
+        });
+        read = () => inputs.filter((option) => option.input.checked).map((option) => option.key);
+        write = (value) => {
+          for (const option of inputs) option.input.checked = Array.isArray(value) && value.includes(option.key);
+        };
+      } else {
+        const input = node(field.type === "array" ? "textarea" : "input", "pp-input");
+        input.setAttribute("aria-label", field.name);
+        if (field.type === "boolean") {
+          input.type = "checkbox";
+          write = (value) => {
+            input.checked = value === true;
+          };
+          read = () => input.checked;
+        } else {
+          input.type = field.type === "number" ? "number" : "text";
+          write = (value) => {
+            input.value = field.type === "array" ? JSON.stringify(value ?? []) : (value ?? "");
+          };
+          read = () =>
+            field.type === "array"
+              ? JSON.parse(input.value)
+              : field.type === "number"
+                ? input.value === ""
+                  ? Number.NaN
+                  : Number(input.value)
+                : input.value;
+        }
+        row.append(input);
+      }
+      write(value);
+      const actions = node("div", "pp-actions");
+      for (const [operation, label] of [
+        ["write", "保存"],
+        ["delete", "删除覆盖值"],
+      ]) {
+        const button = node("button", "", label);
+        button.type = "button";
+        button.onclick = async () => {
+          if (saving) return;
+          saving = true;
+          back.disabled = true;
+          view.querySelectorAll("button,input,select,textarea").forEach((input) => {
+            input.disabled = true;
+          });
+          let success = false;
+          try {
+            if (operation === "delete") await client.remove(active, field.key);
+            else {
+              let value;
+              try {
+                value = read();
+              } catch (error) {
+                notify({ kind: "error", message: error.message });
+                throw error;
+              }
+              await client.set(active, field.key, value);
+            }
+            success = true;
+          } catch {
+            /* 客户端已显示错误通知 / Client already displayed an error notification. */
+          } finally {
+            saving = false;
+            back.disabled = window.history.length <= 1;
+            view.querySelectorAll("button,input,select,textarea").forEach((input) => {
+              input.disabled = false;
+            });
+            if (success && !destroyed) {
+              // 只更新当前控件，保留其它尚未保存的输入。
+              // Update this control without discarding other unsaved inputs.
+              write(client.snapshot(active).values[field.key]);
+            }
+            if (!destroyed && pendingRoute) route();
+          }
+        };
+        actions.append(button);
+      }
+      row.append(actions);
+      view.append(row);
+    }
+    viewport.replaceChildren(view);
+  }
+  function route() {
+    if (saving) {
+      pendingRoute = true;
+      return;
+    }
+    pendingRoute = false;
+    if (active) client.leave(active);
+    routedPath = window.location.pathname;
+    const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(routedPath);
+    if (!match) {
+      generation++;
+      active = null;
+      heading.textContent = title;
+      replace(node("p", "pp-error", "页面地址应为 /settings/模块标识。"), 1);
+      return;
+    }
+    open(match[1]);
+  }
+  const onPopState = () => {
+    if (window.location.pathname !== routedPath) route();
+  };
+  const onPageShow = (event) => {
+    if (event.persisted) route();
+  };
+  back.onclick = () => {
+    if (!saving) window.history.back();
+  };
+  window.addEventListener("popstate", onPopState);
+  window.addEventListener("pageshow", onPageShow);
+  route();
+  return {
+    destroy() {
+      destroyed = true;
+      window.removeEventListener("popstate", onPopState);
+      window.removeEventListener("pageshow", onPageShow);
+      generation++;
+      if (active) client.leave(active);
+      clearTimeout(timer);
+      shell.remove();
+    },
+  };
+}
+
+export { createPreferencesClient, mountPreferencePanes };