@nsnanocat/preference-panes 0.9.16 → 1.1.0

package/dist/preference-panes.mjs

@@ -11,76 +11,178 @@ function validatePathParts(parts) {
 }
 
 /**
- * BoxJS 的共同目录：模块、存储根和展示元数据都来自同一份 JSON。
- * Shared BoxJS catalog deriving modules, storage roots and metadata from one JSON document.
+ * 将 BoxJS 数组、app 或订阅转换为浏览器字段定义。
+ * Normalize a BoxJS array, app or subscription into browser field definitions.
+ * @param {unknown} config 原始 BoxJS JSON / Raw BoxJS JSON.
+ * @param {string} [module] API 模块路径段；省略时要求输入只有一个模块 / API module path segment; omission requires exactly one module.
+ * @returns {import("../index.js").ModuleDefinition} 浏览器字段定义 / Browser field definition.
  */
-class BoxJS {
-    /**
-     * 建立路径索引，不解析控件类型，也不读写持久化存储。
-     * Index field paths without interpreting controls or accessing persistence.
-     * @param {unknown} input 字段数组、单个 app 或 apps 订阅 / Field array, app or apps subscription.
-     */
-    constructor(input) {
-        if (!input || typeof input !== "object") throw new TypeError("Expected BoxJS JSON");
-        const document = JSON.parse(JSON.stringify(input));
-        const apps = Array.isArray(document) ? [{ settings: document }] : (document.apps ?? [document]);
-        if (!Array.isArray(apps)) throw new TypeError("Expected BoxJS apps array");
-        this.modules = new Map();
-        for (const app of apps) {
-            if (!app || !Array.isArray(app.settings)) throw new TypeError("Expected BoxJS settings array");
-            for (const entry of app.settings) {
-                if (typeof entry.id !== "string") throw new TypeError("BoxJS settings require string IDs");
-                if (!entry.id.startsWith("@")) {
-                    if (Array.isArray(document)) throw new TypeError("BoxJS settings require @root.path IDs");
-                    continue;
-                }
-                const [storageKey, ...parts] = entry.id.slice(1).split(".");
-                if (!storageKey || storageKey.startsWith("@") || parts.length < 2) throw new TypeError("A BoxJS setting must be below a literal storage root and module");
-                validatePathParts(parts);
-                const module = parts[0];
-                let target = this.modules.get(module);
-                if (!target) {
-                    target = { module, storageKey, entries: [], owners: new Set() };
-                    this.modules.set(module, target);
-                }
-                if (target.storageKey !== storageKey) throw new TypeError(`A module must use one storage root: ${module}`);
-                target.entries.push(entry);
-                target.owners.add(app);
+function normalizeBoxJs(config, module) {
+    if (!config || typeof config !== "object") throw new TypeError("Expected BoxJS JSON");
+    const document = JSON.parse(JSON.stringify(config));
+    const apps = Array.isArray(document) ? [{ settings: document }] : (document.apps ?? [document]);
+    if (!Array.isArray(apps)) throw new TypeError("Expected BoxJS apps array");
+    const modules = new Map();
+    for (const app of apps) {
+        if (!app || !Array.isArray(app.settings)) throw new TypeError("Expected BoxJS settings array");
+        for (const entry of app.settings) {
+            if (typeof entry.id !== "string") throw new TypeError("BoxJS settings require string IDs");
+            if (!entry.id.startsWith("@")) {
+                if (Array.isArray(document)) throw new TypeError("BoxJS settings require @root.path IDs");
+                continue;
+            }
+            const [storageKey, ...parts] = entry.id.slice(1).split(".");
+            if (!storageKey || storageKey.startsWith("@") || parts.length < 2) throw new TypeError("A BoxJS setting must be below a literal storage root and module");
+            validatePathParts(parts);
+            const name = parts[0];
+            let target = modules.get(name);
+            if (!target) {
+                target = { module: name, storageKey, entries: [], owners: new Set() };
+                modules.set(name, target);
             }
+            if (target.storageKey !== storageKey) throw new TypeError(`A module must use one storage root: ${name}`);
+            target.entries.push(entry);
+            target.owners.add(app);
         }
-        this.metadata = metadata(Array.isArray(document) ? {} : document);
-        for (const target of this.modules.values()) target.metadata = target.owners.size === 1 ? metadata([...target.owners][0]) : {};
     }
+    if (module === undefined && modules.size !== 1) throw new TypeError("Import BoxJS JSON for exactly one module");
+    const target = module === undefined ? modules.values().next().value : modules.get(module);
+    if (!target) throw new TypeError(`No BoxJS settings for module: ${module}`);
+    const metadata = normalizeMetadata(target.owners.size === 1 ? presentation([...target.owners][0]) : {});
+    const fields = [];
+    for (const entry of target.entries) {
+        const parts = entry.id.slice(1).split(".").slice(1);
+        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("."),
+            type: type === "select" ? typeof entry.val : type,
 
-    /**
-     * 取得本次导入的唯一模块，避免把模块数据变成项目目录。
-     * Get the single imported module without turning module data into a project directory.
-     * @returns {object} 唯一模块的目录项 / The single module entry.
-     */
-    get module() {
-        if (this.modules.size !== 1) throw new TypeError("Import BoxJS JSON for exactly one module");
-        return this.modules.values().next().value;
+            name: entry.name,
+            description: entry.desc ?? "",
+            control: entry.type,
+            ...(entry.placeholder === undefined ? {} : { placeholder: entry.placeholder }),
+            ...(entry.rows === undefined ? {} : { rows: entry.rows }),
+            ...(entry.autoGrow === undefined ? {} : { autoGrow: entry.autoGrow }),
+        };
+        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" ||
+            (field.placeholder !== undefined && typeof field.placeholder !== "string") ||
+            (field.rows !== undefined && (!Number.isInteger(field.rows) || field.rows < 1)) ||
+            (field.autoGrow !== undefined && typeof field.autoGrow !== "boolean") ||
+            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: ${target.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: target.module,
+        storageKey: target.storageKey,
+        fields,
+        settingsPath: common,
+        ...(Object.keys(metadata).length ? { metadata } : {}),
+    };
 }
 
 /**
- * 保留标准 BoxJS 展示信息；script 仅为元数据，不执行。
- * Retain standard BoxJS presentation data; script is metadata only and never executed.
- * @param {object} source BoxJS app 或订阅 / BoxJS app or subscription.
- * @returns {object} 经过类型检查的展示信息 / Type-checked presentation metadata.
+ * 保留字段所属 app 的原始展示信息。
+ * Retain raw presentation metadata from the app owning the fields.
+ * @param {object} source BoxJS app / BoxJS app.
+ * @returns {Record<string, unknown>} 原始展示信息 / Raw presentation metadata.
  */
-function metadata(source) {
+function presentation(source) {
     const result = {};
     for (const key of ["id", "name", "author", "repo", "script", "icon", "description", "desc", "icons", "descs"]) {
         if (source[key] === undefined) continue;
+        result[key] = source[key];
+    }
+    return result;
+}
+
+/**
+ * 校验供浏览器展示的标准 BoxJS 元数据。
+ * Validate standard BoxJS metadata used by the browser renderer.
+ * @param {Record<string, unknown>} source 原始展示元数据 / Raw presentation metadata.
+ * @returns {import("../index.js").BoxJSMetadata} 规范化展示元数据 / Normalized presentation metadata.
+ */
+function normalizeMetadata(source) {
+    const result = {};
+    for (const [key, value] of Object.entries(source)) {
         const multiple = key === "icons" || key === "descs";
-        const values = multiple ? source[key] : [source[key]];
+        const values = multiple ? value : [value];
         if (!Array.isArray(values) || values.some(item => typeof item !== "string")) throw new TypeError(`Invalid BoxJS app ${key}`);
-        result[key] = multiple ? [...values] : source[key];
+        result[key] = multiple ? [...values] : value;
     }
     return result;
 }
 
+/**
+ * 归一化 BoxJS 的字符串存储值，不改变普通文本内容。
+ * Normalize BoxJS string persistence without changing free-text values.
+ * @param {import("../index.js").SettingsField} field 前端字段约束 / Frontend field constraints.
+ * @param {unknown} value 存储值 / Stored value.
+ * @returns {unknown} 转换后的控件值；是否允许写入由 validValue 单独校验 / Converted control value; write eligibility is checked separately by validValue.
+ */
+function normalizeStoredValue(field, value) {
+    switch (field.type) {
+        case "boolean":
+            if (value === "true" || value === "false") return value === "true";
+            break;
+        case "number":
+            if (typeof value === "string" && value.trim() !== "") return Number(value);
+            break;
+        case "array":
+            if (typeof value === "string") value = value === "" || value === "[]" ? [] : value.split(",");
+            break;
+    }
+    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;
+}
+
+/**
+ * 校验支持的标量范围，包括文本长度与数值有限性。
+ * Validate supported scalar bounds, including text length and numeric finiteness.
+ * @param {unknown} value 待检查值 / Value to inspect.
+ * @returns {boolean} 是否为有效标量 / Whether the scalar is valid.
+ */
+function scalar(value) {
+    switch (typeof value) {
+        case "boolean":
+            return true;
+        case "string":
+            return value.length <= 2048;
+        case "number":
+            return Number.isFinite(value);
+        default:
+            return false;
+    }
+}
+
+/**
+ * 检查值类型、数组唯一性及声明的选项，不进行转换。
+ * Check value type, array uniqueness and declared choices without coercion.
+ * @param {import("../index.js").SettingsField} field 前端归一化字段 / Normalized frontend field.
+ * @param {unknown} value 待写入的 JSON 值 / JSON value to write.
+ * @returns {boolean} 是否符合字段约束 / Whether the value satisfies field constraints.
+ */
+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));
+}
+
 /**
  * 创建元素，所有展示文本通过 textContent 写入。
  * Create elements and assign display text through textContent only.
@@ -321,337 +423,183 @@ class ActionMenu {
 }
 
 /**
- * 将 BoxJS 数组、app 或订阅转换为模块字段，保留原文件为唯一字段来源。
- * Normalize a BoxJS array, app or subscription using the source JSON as the field authority.
- * @param {unknown | BoxJS} config BoxJS JSON 或已解析目录 / BoxJS document or parsed catalog.
- * @param {string} module API 第一段模块名 / First API path segment.
- * @returns {import("../index.js").ModuleDefinition} 存储根和字段 / Storage root and fields.
- * @throws {TypeError} 配置结构、字段路径、默认值或展示属性无效 / Invalid configuration, field path, default or presentation attribute.
+ * 管理单模块页面的 API 请求、值快照和会话终止。
+ * Manage API requests, value snapshots, and session termination for one module page.
  */
-function normalizeBoxJs(config, module) {
-    validatePathParts([module]);
-    const catalog = config instanceof BoxJS ? config : new BoxJS(config);
-    const target = catalog.modules.get(module);
-    if (!target) throw new TypeError(`No BoxJS settings for module: ${module}`);
-    const { entries, storageKey, metadata } = target;
-    const fields = [];
-    for (const entry of entries) {
-        const parts = entry.id.slice(1).split(".").slice(1);
-        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("."),
-            type: type === "select" ? typeof entry.val : type,
+class PreferencesClient {
+    #module;
+    #configURL;
+    #definition;
+    #request;
+    #notify;
+    #timeout;
+    #session = new AbortController();
+    #values;
+    #saving = false;
 
-            name: entry.name,
-            description: entry.desc ?? "",
-            control: entry.type,
-            ...(entry.placeholder === undefined ? {} : { placeholder: entry.placeholder }),
-            ...(entry.rows === undefined ? {} : { rows: entry.rows }),
-            ...(entry.autoGrow === undefined ? {} : { autoGrow: entry.autoGrow }),
-        };
-        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" ||
-            (field.placeholder !== undefined && typeof field.placeholder !== "string") ||
-            (field.rows !== undefined && (!Number.isInteger(field.rows) || field.rows < 1)) ||
-            (field.autoGrow !== undefined && typeof field.autoGrow !== "boolean") ||
-            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);
+    /**
+     * 创建只调用模块 API、不读取或解析 BoxJS 的页面客户端。
+     * Create a page client that only calls the module API and never reads or parses BoxJS.
+     * @param {import("./client.mjs").PreferencesClientOptions} options API 模型、请求与通知 / API model, requests, and notifications.
+     */
+    constructor({ model, definition, fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 }) {
+        this.#module = model.module;
+        this.#configURL = model.configURL;
+        this.#definition = definition;
+        this.#request = request;
+        this.#notify = notify;
+        this.#timeout = timeout;
+        this.#values = structuredClone(model.values);
     }
-    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,
-        ...(Object.keys(metadata).length ? { metadata } : {}),
-    };
-}
 
-/**
- * 归一化 BoxJS 的字符串存储值，不改变普通文本内容。
- * Normalize BoxJS string persistence without changing free-text values.
- * @param {import("../index.js").SettingsField} field 前端字段约束 / Frontend field constraints.
- * @param {unknown} value 存储值 / Stored value.
- * @returns {unknown} 转换后的控件值；是否允许写入由 validValue 单独校验 / Converted control value; write eligibility is checked separately by validValue.
- */
-function normalizeStoredValue(field, value) {
-    switch (field.type) {
-        case "boolean":
-            if (value === "true" || value === "false") return value === "true";
-            break;
-        case "number":
-            if (typeof value === "string" && value.trim() !== "") return Number(value);
-            break;
-        case "array":
-            if (typeof value === "string") value = value === "" || value === "[]" ? [] : value.split(",");
-            break;
+    /**
+     * 获取当前字段定义和值的深拷贝，不发起网络请求。
+     * Return a deep copy of the current field definition and values without a network request.
+     * @returns {import("./client.mjs").ModuleSnapshot} 会话快照 / Session snapshot.
+     */
+    snapshot() {
+        return structuredClone({ definition: this.#definition, values: this.#values });
     }
-    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);
+
+    /**
+     * 读取 Settings 子树。
+     * Read the Settings subtree.
+     * @returns {Promise<unknown>} Settings 内容或 undefined / Settings content or undefined.
+     */
+    async readSettings() {
+        const response = await this.#send("get", { scope: "settings" });
+        return response.status === 404 ? undefined : response.json();
     }
-    return value;
-}
 
-/**
- * 校验支持的标量范围，包括文本长度与数值有限性。
- * Validate supported scalar bounds, including text length and numeric finiteness.
- * @param {unknown} value 待检查值 / Value to inspect.
- * @returns {boolean} 是否为有效标量 / Whether the scalar is valid.
- */
-function scalar(value) {
-    switch (typeof value) {
-        case "boolean":
-            return true;
-        case "string":
-            return value.length <= 2048;
-        case "number":
-            return Number.isFinite(value);
-        default:
-            return false;
+    /**
+     * 读取 Caches 子树。
+     * Read the Caches subtree.
+     * @returns {Promise<unknown>} Caches 内容或 undefined / Caches content or undefined.
+     */
+    async readCaches() {
+        const response = await this.#send("get", { scope: "caches" });
+        return response.status === 404 ? undefined : response.json();
     }
-}
 
-/**
- * 检查值类型、数组唯一性及声明的选项，不进行转换。
- * Check value type, array uniqueness and declared choices without coercion.
- * @param {import("../index.js").SettingsField} field 前端归一化字段 / Normalized frontend field.
- * @param {unknown} value 待写入的 JSON 值 / JSON value to write.
- * @returns {boolean} 是否符合字段约束 / Whether the value satisfies field constraints.
- */
-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));
-}
+    /**
+     * 删除当前模块的 Caches 子树。
+     * Delete the current module Caches subtree.
+     * @returns {Promise<void>} 操作完成 / Operation completion.
+     */
+    clearCaches() {
+        return this.#change("delete", { scope: "caches" }, "clearCaches");
+    }
 
-/**
- * 单个模块的临时会话；离开页面后丢弃。
- * 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("./client.mjs").ModuleSnapshot["values"]} values 当前显示值 / Current display values.
- * @property {boolean} saving 是否正在写入 / Whether a mutation is in progress.
- */
+    /**
+     * 删除当前模块数据并恢复页面默认值。
+     * Delete current module data and restore page defaults.
+     * @returns {Promise<void>} 操作完成 / Operation completion.
+     */
+    reset() {
+        return this.#change("delete", { scope: "module" }, "reset");
+    }
+
+    /**
+     * 终止当前页面仍在进行的请求。
+     * Abort requests still owned by the current page.
+     * @returns {void} 无返回值 / No return value.
+     */
+    leave() {
+        this.#session.abort();
+    }
+
+    /**
+     * 写入单个字段。
+     * Write one field.
+     * @param {string} key 字段路径 / Field path.
+     * @param {unknown} value 已校验值 / Validated value.
+     * @returns {Promise<void>} 操作完成 / Operation completion.
+     */
+    set(key, value) {
+        return this.#change("set", { key, value }, "write", key);
+    }
 
-/**
- * 创建页面会话缓存；打开时重读，选项操作仅在 HTTP 200 后更新缓存。
- * Create a page-session cache; reload on open and mutate cache only after HTTP 200.
- * @param {import("./client.mjs").PreferencesClientOptions} options 包内目录、请求与通知 / Internal catalog, requests and notifications.
- * @returns {import("./client.mjs").PreferencesClient} 通用客户端 / Generic client.
- */
-function createPreferencesClient({ catalog, fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 }) {
     /**
-     * 模块会话表
-     * Module session map.
-     * @type {Map<string, ModuleSession>}
+     * 删除单个字段覆盖值。
+     * Delete one field override.
+     * @param {string} key 字段路径 / Field path.
+     * @returns {Promise<void>} 操作完成 / Operation completion.
      */
-    const sessions = new Map();
+    remove(key) {
+        return this.#change("delete", { key }, "delete", key);
+    }
+
     /**
-     * 用 form 发送完整存储键；读取 404 交给调用方处理。
-     * Send a complete storage key as form data; callers handle missing reads.
-     * @param {string} path 完整 @root.path / Complete @root.path.
-     * @param {"get" | "set" | "delete"} action 存储操作 / Storage operation.
-     * @param {unknown} body set 值，其它操作忽略 / Set value, ignored by other operations.
-     * @param {AbortSignal | undefined} signal 会话取消信号 / Session cancellation signal.
-     * @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.
+     * 向模块 API 发送 JSON 动作。
+     * Send a JSON action to the module API.
+     * @param {"get" | "set" | "delete"} action 模块动作 / Module action.
+     * @param {unknown} payload JSON 请求体 / JSON request body.
+     * @returns {Promise<Response>} 原始响应 / Raw response.
      */
-    async function send(path, action, body, signal) {
+    async #send(action, payload) {
         const controller = new AbortController();
         const abort = () => controller.abort();
-        if (signal?.aborted) abort();
-        signal?.addEventListener("abort", abort, { once: true });
-        const timer = setTimeout(abort, timeout);
+        if (this.#session.signal.aborted) abort();
+        this.#session.signal.addEventListener("abort", abort, { once: true });
+        const timer = setTimeout(abort, this.#timeout);
         try {
-            const response = await request(`/api/${action}`, {
+            const response = await this.#request(`/api/${encodeURIComponent(this.#module)}/${action}`, {
                 method: "POST",
                 credentials: "omit",
                 cache: "no-store",
                 signal: controller.signal,
-                headers: { "Content-Type": "application/x-www-form-urlencoded" },
-                body: new URLSearchParams([[path, action === "set" ? JSON.stringify(body) : ""]]).toString(),
+                headers: { "Content-Type": "application/json", "X-PreferencePanes-JSON": this.#configURL },
+                body: JSON.stringify(payload),
             });
             if (response.status !== 200 && !(action === "get" && response.status === 404)) throw new Error(`HTTP ${response.status}`);
             return response;
         } finally {
             clearTimeout(timer);
-            signal?.removeEventListener("abort", abort);
+            this.#session.signal.removeEventListener("abort", abort);
         }
     }
+
     /**
-     * 获取独立快照，避免调用方修改内部缓存。
-     * Return an independent snapshot so callers cannot mutate the cache.
-     * @param {string} module 已打开模块 / Open module.
-     * @returns {import("./client.mjs").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 {"set" | "delete"} action 写入或删除 / Write or delete.
-     * @param {unknown} value 写入值，删除时忽略 / Write value, ignored for deletion.
-     * @param {"write" | "delete" | "clearCaches" | "reset"} [operation] 操作类型 / Operation kind.
+     * 执行写入动作；成功后只更新当前页面值。
+     * Execute a mutation and update only the current page values after success.
+     * @param {"set" | "delete"} action API 动作 / API action.
+     * @param {Record<string, unknown>} payload JSON 请求体 / JSON request body.
+     * @param {"write" | "delete" | "clearCaches" | "reset"} operation 通知操作 / Notification operation.
+     * @param {string} [key] 字段路径 / Field path.
      * @returns {Promise<void>} 操作完成 / Operation completion.
-     * @throws {Error} 会话、字段、值或请求错误 / Session, field, value or request error.
      */
-    async function change(module, key, action, value, operation = action === "set" ? "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;
+    async #change(action, payload, operation, key) {
+        if (this.#saving) throw new Error("A settings write is already in progress");
+        this.#saving = true;
         try {
-            if ((operation === "write" || operation === "delete") && (!field || (action === "set" && !validValue(field, value)))) throw new TypeError("Invalid setting value");
-            await send(`@${state.definition.storageKey}.${key}`, action, 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;
+            await this.#send(action, payload);
+            switch (operation) {
+                case "write":
+                    this.#values[key] = structuredClone(payload.value);
+                    break;
+                case "delete": {
+                    const field = this.#definition.fields.find(candidate => candidate.key === key);
+                    delete this.#values[key];
+                    if (field && Object.hasOwn(field, "defaultValue")) this.#values[key] = structuredClone(field.defaultValue);
+                    break;
                 }
+                case "clearCaches":
+                    break;
+                case "reset":
+                    for (const field of this.#definition.fields) {
+                        delete this.#values[field.key];
+                        if (Object.hasOwn(field, "defaultValue")) this.#values[field.key] = structuredClone(field.defaultValue);
+                    }
+                    break;
             }
-            notify({ kind: "success", operation, module, key });
+            this.#notify({ kind: "success", operation, module: this.#module, key });
         } catch (error) {
-            notify({ kind: "error", operation, module, key, message: error.message });
+            this.#notify({ kind: "error", operation, module: this.#module, key, message: error.message });
             throw error;
         } finally {
-            state.saving = false;
+            this.#saving = false;
         }
     }
-    return {
-        /**
-         * 从已导入的 JSON 创建新会话，只读取一次设置值。
-         * Create a session from imported JSON and read stored settings once.
-         * @param {string} module 模块标识 / Module identifier.
-         * @returns {Promise<import("./client.mjs").ModuleSnapshot>} 新快照 / New snapshot.
-         * @throws {Error} 读取失败、会话被替换或写入尚未完成 / Read failure, replaced session or unfinished write.
-         */
-        async open(module) {
-            const binding = catalog.modules.get(module);
-            if (!binding) throw new TypeError(`No BoxJS settings for module: ${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(catalog, module);
-                const response = await send(`@${definition.storageKey}.${definition.settingsPath.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,
-        /**
-         * 按需重新读取模块 Settings，不更新页面会话缓存。
-         * Reread module Settings on demand without updating the page-session cache.
-         * @param {string} module 已打开的模块 / Open module.
-         * @returns {Promise<unknown>} 设置值，缺失为 undefined / Settings value, or undefined when absent.
-         */
-        async readSettings(module) {
-            const state = sessions.get(module);
-            if (!state?.definition) throw new Error("Open the module first");
-            const response = await send(`@${state.definition.storageKey}.${state.definition.settingsPath.join(".")}`, "get", undefined, state.controller.signal);
-            return response.status === 404 ? undefined : response.json();
-        },
-        /**
-         * 按需读取模块 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(`@${state.definition.storageKey}.${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, "set", 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"),
-    };
 }
 
 /**
@@ -814,488 +762,515 @@ class Navigation extends EventTarget {
 }
 
 /**
- * 挂载已导入 BoxJS 对应的模块表单和短暂通知。
- * Mount the imported BoxJS module form and transient notifications.
- * @param {HTMLElement} root 包内挂载元素 / Internal mount element.
- * @param {import("../BoxJS.mjs").BoxJS} catalog 包内 BoxJS 目录 / Internal BoxJS catalog.
- * @returns {import("./index.js").MountedPreferences} 面板生命周期句柄 / Panel lifecycle handle.
+ * 管理模块表单、导航、操作队列和短暂通知。
+ * Manage the module form, navigation, operation queue, and transient notifications.
  */
-function mountPanel(root, catalog) {
-    const title = catalog.module.metadata.name ?? catalog.module.module;
-    const document = root.ownerDocument;
-    const window = document.defaultView;
-    const shell = element("div", "pp-panel");
-    shell.dataset.module = catalog.module.module;
-    const header = element("header", "pp-header");
-    const back = element("button", "pp-back", "‹");
-    back.setAttribute("aria-label", "返回");
-    back.type = "button";
-    const heading = element("h1", "pp-title", title);
-    const handlers = new Map();
-    const menuItems = [
-        { id: "viewSettings", label: "查看设置" },
-        { id: "viewCaches", label: "查看缓存" },
-        { id: "clearCaches", label: "清空缓存", destructive: true },
-        { id: "reset", label: "重置设置", destructive: true },
-    ];
-    const menu = new ActionMenu(id => runAction(id));
-    const trailing = element("span", "pp-nav-spacer");
-    trailing.append(menu.element);
-    const viewport = element("div", "pp-viewport");
-    let toast;
-    header.append(back, heading, trailing);
-    shell.append(header, viewport);
-    root.append(shell);
-    // 嵌入模式向宿主发布导航状态，宿主不读取或修改模块内部 DOM。
-    // Embedded mode publishes navigation state without host reads or mutations of the module DOM.
-    const publishNavigation = () => {
-        const actions = handlers.size ? menuItems : [];
-        menu.update(actions, saving);
-        const frame = window.frameElement;
-        if (!frame?.dataset.preferencePanes) return;
-        frame.dispatchEvent(
-            new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:change", {
-                detail: { title: heading.textContent, module: catalog.module.module, busy: saving, canGoBack: !back.disabled, actions },
-            }),
-        );
-    };
-    const onAction = event => {
-        if (!saving && handlers.has(event.detail)) runAction(event.detail);
-    };
-    window.frameElement?.addEventListener("preferencepanes:action", onAction);
-    let timer,
-        navigation,
-        generation = 0,
-        active = null,
-        saving = false,
-        destroyed = false;
-    /**
-     * 展示短暂通知，不刷新设置数据。
-     * Display a transient notification without refreshing settings.
-     * @param {{kind: "success" | "error", operation?: "write" | "delete" | "clearCaches" | "reset", message?: string}} event 操作结果 / Operation result.
-     * @returns {void} 无返回值 / No return value.
-     */
-    const notify = event => {
-        if (destroyed) return;
-        let message;
-        switch (true) {
-            case event.kind === "error":
-                message = `操作失败：${event.message}`;
-                break;
-            case event.operation === "delete":
-                message = "删除成功";
-                break;
-            case event.operation === "clearCaches":
-                message = "Caches 已清空";
-                break;
-            case event.operation === "reset":
-                message = "设置已重置";
-                break;
-            default:
-                message = "修改成功";
-                break;
-        }
-        // 宿主接管时不创建网页 Toast，也不运行其计时器。
-        // A host-owned notice creates no web Toast and starts no local timer.
-        const frame = window.frameElement;
-        if (frame && !frame.dispatchEvent(new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:notice", { cancelable: true, detail: { kind: event.kind, message } }))) return;
-        if (!toast) {
-            toast = element("div", "pp-toast");
-            toast.setAttribute("role", "status");
-            shell.append(toast);
-        }
-        toast.textContent = message;
-        toast.dataset.kind = event.kind;
-        toast.hidden = false;
-        clearTimeout(timer);
-        timer = setTimeout(() => {
-            toast.hidden = true;
-        }, 2400);
-    };
-    const client = createPreferencesClient({ catalog, notify });
-    /**
-     * 两种菜单入口共用异步错误处理，包含宿主确认框错误。
-     * Share async error handling between both menus, including host-dialog errors.
-     * @param {string} id 操作标识 / Action identifier.
-     * @returns {Promise<void>} 操作已处理 / Action handled.
-     */
-    async function runAction(id) {
-        try {
-            await handlers.get(id)();
-        } catch (error) {
-            notify({ kind: "error", message: error.message });
-        }
-    }
+class PreferencesPanel {
+    #release;
+
     /**
-     * 打开模块并忽略已过期的异步结果。
-     * Open a module and ignore stale asynchronous results.
-     * @param {string} module 模块标识 / Module identifier.
-     * @returns {Promise<void>} 视图加载完成，失败显示错误视图 / View load completion; failures display an error view.
+     * 挂载 API 返回的模块模型表单。
+     * Mount the module form returned by the API.
+     * @param {HTMLElement} root 包内挂载元素 / Internal mount element.
+     * @param {import("../index.js").ModuleModel & {definition: import("../index.js").ModuleDefinition}} model 已规范化模块模型 / Normalized module model.
      */
-    async function open(module) {
-        const version = ++generation;
-        active = module;
-        back.disabled = window.history.length <= 1;
-        heading.textContent = module;
-        publishNavigation();
-        viewport.replaceChildren(statusView("读取设置…"));
-        try {
-            await client.open(module);
-            if (version === generation) controls();
-        } catch (error) {
-            if (version !== generation) return;
-            viewport.replaceChildren(statusView(`加载失败：${error.message}`, () => open(module)));
-            publishNavigation();
-        }
+    constructor(root, model) {
+        this.#release = this.#mount(root, model);
     }
+
     /**
-     * 从会话快照创建控件与操作按钮，不重新读取网络配置。
-     * Build controls and actions from the session snapshot without fetching config again.
-     * @returns {void} 无返回值 / No return value.
+     * 建立面板 DOM、交互和会话，并返回其释放操作。
+     * Build panel DOM, interactions, and session, then return its release operation.
+     * @param {HTMLElement} root 包内挂载元素 / Internal mount element.
+     * @param {import("../index.js").ModuleModel & {definition: import("../index.js").ModuleDefinition}} model 已规范化模块模型 / Normalized module model.
+     * @returns {() => void} 释放操作 / Release operation.
      */
-    function controls() {
-        const { definition, values } = client.snapshot(active);
-        heading.textContent = definition.metadata?.name || active;
-        const view = element("section", "pp-fields");
-        /**
-         * 挂载后执行的多行高度更新
-         * Textarea sizing callbacks run after mounting.
-         * @type {Array<() => void>}
-         */
-        const growingInputs = [];
-        const editors = new Map();
-        const summaries = [];
-        const groups = new Map();
-        let queue = Promise.resolve(),
-            pendingWrites = 0;
+    #mount(root, model) {
+        const { definition } = model;
+        const title = definition.metadata?.name ?? definition.module;
+        const document = root.ownerDocument;
+        const window = document.defaultView;
+        const shell = element("div", "pp-panel");
+        shell.dataset.module = definition.module;
+        const header = element("header", "pp-header");
+        const back = element("button", "pp-back", "‹");
+        back.setAttribute("aria-label", "返回");
+        back.type = "button";
+        const heading = element("h1", "pp-title", title);
+        const handlers = new Map();
+        const menuItems = [
+            { id: "viewSettings", label: "查看设置" },
+            { id: "viewCaches", label: "查看缓存" },
+            { id: "clearCaches", label: "清空缓存", destructive: true },
+            { id: "reset", label: "重置设置", destructive: true },
+        ];
+        const menu = new ActionMenu(id => runAction(id));
+        const trailing = element("span", "pp-nav-spacer");
+        trailing.append(menu.element);
+        const viewport = element("div", "pp-viewport");
+        let toast;
+        header.append(back, heading, trailing);
+        shell.append(header, viewport);
+        root.append(shell);
+        // 嵌入模式向宿主发布导航状态，宿主不读取或修改模块内部 DOM。
+        // Embedded mode publishes navigation state without host reads or mutations of the module DOM.
+        const publishNavigation = () => {
+            const actions = handlers.size ? menuItems : [];
+            menu.update(actions, saving);
+            const frame = window.frameElement;
+            if (!frame?.dataset.preferencePanes) return;
+            frame.dispatchEvent(
+                new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:change", {
+                    detail: { title: heading.textContent, module: definition.module, busy: saving, canGoBack: !back.disabled, actions },
+                }),
+            );
+        };
+        const onAction = event => {
+            if (!saving && handlers.has(event.detail)) runAction(event.detail);
+        };
+        window.frameElement?.addEventListener("preferencepanes:action", onAction);
+        let timer,
+            navigation,
+            generation = 0,
+            active = null,
+            saving = false,
+            destroyed = false;
         /**
-         * 导航组件处理页面切换，表单只更新当前标题与返回按钮。
-         * Let navigation own transitions; the form only updates the title and back button.
+         * 展示短暂通知，不刷新设置数据。
+         * Display a transient notification without refreshing settings.
+         * @param {{kind: "success" | "error", operation?: "write" | "delete" | "clearCaches" | "reset", message?: string}} event 操作结果 / Operation result.
          * @returns {void} 无返回值 / No return value.
          */
-        const updateNavigation = () => {
-            const editor = editors.get(navigation.current);
-            heading.textContent = editor?.title ?? definition.metadata?.name ?? active;
-            back.disabled = saving || !navigation.canGoBack;
-            publishNavigation();
+        const notify = event => {
+            if (destroyed) return;
+            let message;
+            switch (true) {
+                case event.kind === "error":
+                    message = `操作失败：${event.message}`;
+                    break;
+                case event.operation === "delete":
+                    message = "删除成功";
+                    break;
+                case event.operation === "clearCaches":
+                    message = "Caches 已清空";
+                    break;
+                case event.operation === "reset":
+                    message = "设置已重置";
+                    break;
+                default:
+                    message = "修改成功";
+                    break;
+            }
+            // 宿主接管时不创建网页 Toast，也不运行其计时器。
+            // A host-owned notice creates no web Toast and starts no local timer.
+            const frame = window.frameElement;
+            if (frame && !frame.dispatchEvent(new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:notice", { cancelable: true, detail: { kind: event.kind, message } }))) return;
+            if (!toast) {
+                toast = element("div", "pp-toast");
+                toast.setAttribute("role", "status");
+                shell.append(toast);
+            }
+            toast.textContent = message;
+            toast.dataset.kind = event.kind;
+            toast.hidden = false;
+            clearTimeout(timer);
+            timer = setTimeout(() => {
+                toast.hidden = true;
+            }, 2400);
         };
+        const client = new PreferencesClient({ model, definition, notify });
         /**
-         * 串行执行模块操作，保持输入可编辑。
-         * Serialize module actions while keeping inputs editable.
-         * @param {() => Promise<void>} action 请求或写入 / Request or mutation.
-         * @param {() => void} success 成功后的局部更新 / Local update after success.
-         * @param {() => void} [failure] 失败后恢复当前输入 / Restore the current input on failure.
-         * @returns {Promise<void>} 操作完成 / Operation completion.
+         * 两种菜单入口共用异步错误处理，包含宿主确认框错误。
+         * Share async error handling between both menus, including host-dialog errors.
+         * @param {string} id 操作标识 / Action identifier.
+         * @returns {Promise<void>} 操作已处理 / Action handled.
          */
-        function perform(action, success, failure = () => {}) {
-            pendingWrites++;
-            saving = true;
-            back.disabled = true;
-            publishNavigation();
-            return (queue = queue
-                .then(action)
-                .then(() => {
-                    if (!destroyed) success();
-                })
-                .catch(() => {
-                    /* 请求层已通知错误。
-                     * The request layer has already reported the error. */
-                    if (!destroyed) failure();
-                })
-                .finally(() => {
-                    pendingWrites--;
-                    saving = pendingWrites > 0;
-                    if (destroyed && !saving) client.leave(active);
-                    back.disabled = saving || !navigation.canGoBack;
-                    publishNavigation();
-                }));
-        }
-        const metadata = definition.metadata;
-        if (metadata) {
-            const info = element("div", "pp-module-info");
-            const details = element("div", "pp-module-details");
-            for (const description of [metadata.author, metadata.desc ?? metadata.description, ...(metadata.descs ?? [])]) if (description) details.append(element("p", "pp-description", description));
-            if (metadata.repo) {
-                const link = element("a", "pp-module-source", "项目主页");
-                link.href = resourceURL(metadata.repo);
-                link.target = "_blank";
-                link.rel = "noopener noreferrer";
-                details.append(link);
+        async function runAction(id) {
+            try {
+                await handlers.get(id)();
+            } catch (error) {
+                notify({ kind: "error", message: error.message });
             }
-            info.append(details);
-            view.append(info);
         }
-        for (const field of definition.fields) {
-            const match = /^\[([^\]]+)\]\s*(.*)$/.exec(field.name);
-            const group = match?.[1] ?? "通用";
-            if (!groups.has(group)) {
-                const section = element("section", "pp-group");
-                const rows = element("div", "pp-rows");
-                section.append(element("h2", "pp-group-title", group), rows);
-                groups.set(group, rows);
-                view.append(section);
+        /**
+         * 打开模块并忽略已过期的异步结果。
+         * Open a module and ignore stale asynchronous results.
+         * @param {string} module 模块标识 / Module identifier.
+         * @returns {Promise<void>} 视图加载完成，失败显示错误视图 / View load completion; failures display an error view.
+         */
+        async function open(module) {
+            const version = ++generation;
+            active = module;
+            back.disabled = window.history.length <= 1;
+            heading.textContent = module;
+            publishNavigation();
+            viewport.replaceChildren(statusView("读取设置…"));
+            try {
+                if (version === generation) controls();
+            } catch (error) {
+                if (version !== generation) return;
+                viewport.replaceChildren(statusView(`加载失败：${error.message}`, () => open(module)));
+                publishNavigation();
             }
-            const row = settingRow("div");
-            row.classList.add("pp-field");
-            const label = element("div", "pp-label");
-            label.append(element("span", "pp-field-name", match?.[2] ?? field.name));
-            if (field.description) label.append(element("span", "pp-field-description", field.description));
-            row.append(label);
-            const value = values[field.key];
+        }
+        /**
+         * 从会话快照创建控件与操作按钮，不重新读取网络配置。
+         * Build controls and actions from the session snapshot without fetching config again.
+         * @returns {void} 无返回值 / No return value.
+         */
+        function controls() {
+            const { definition, values } = client.snapshot();
+            heading.textContent = definition.metadata?.name || active;
+            const view = element("section", "pp-fields");
             /**
-             * 读取尚未保存的输入
-             * Read the unsaved input.
-             * @type {() => unknown}
+             * 挂载后执行的多行高度更新
+             * Textarea sizing callbacks run after mounting.
+             * @type {Array<() => void>}
              */
-            let read;
+            const growingInputs = [];
+            const editors = new Map();
+            const summaries = [];
+            const groups = new Map();
+            let queue = Promise.resolve(),
+                pendingWrites = 0;
             /**
-             * 更新当前控件
-             * Update the current control.
-             * @type {(value: unknown) => void}
+             * 导航组件处理页面切换，表单只更新当前标题与返回按钮。
+             * Let navigation own transitions; the form only updates the title and back button.
+             * @returns {void} 无返回值 / No return value.
              */
-            let write;
-            let inputContainer = row;
-            let eventName = "change";
-            switch (true) {
-                case Boolean(field.options) && field.type !== "array": {
-                    const select = element("select", "");
-                    select.setAttribute("aria-label", field.name);
-                    field.options.forEach((option, index) => {
-                        const item = element("option", "", option.label);
-                        item.value = String(index);
-                        select.append(item);
-                    });
-                    write = value => {
-                        select.selectedIndex = field.options.findIndex(option => option.key === value);
-                    };
-                    row.append(fieldControl(select));
-                    read = () => field.options[select.selectedIndex]?.key;
-                    break;
-                }
-                case field.type === "array" && Boolean(field.options): {
-                    const page = element("section", "pp-choice-page");
-                    if (field.description) page.append(element("p", "pp-description", field.description));
-                    const choices = element("div", "pp-rows");
-                    page.append(choices);
-                    inputContainer = choices;
-                    editors.set(field.key, { node: page, title: match?.[2] ?? field.name });
-                    const summary = element("span", "pp-summary");
-                    const link = element("button", "pp-choice-link");
-                    link.type = "button";
-                    link.setAttribute("aria-label", field.name);
-                    link.append(summary, element("span", "pp-chevron", "›"));
-                    row.append(link);
-                    const refresh = () => {
-                        const value = client.snapshot(active).values[field.key];
-                        summary.textContent =
-                            field.options
-                                .filter(option => Array.isArray(value) && value.includes(option.key))
-                                .map(option => option.label)
-                                .join("、") || "未选择";
-                    };
-                    summaries.push(refresh);
-                    refresh();
-                    link.onclick = () => navigation.open(field.key);
-                    row.addEventListener("click", event => {
-                        if (!link.contains(event.target)) link.click();
-                    });
-                    const inputs = field.options.map(option => {
-                        const label = settingRow("label");
-                        label.classList.add("pp-choice");
-                        label.textContent = option.label;
-                        const input = element("input", "");
-                        input.type = "checkbox";
-                        input.setAttribute("aria-label", option.label);
-                        label.append(input);
-                        choices.append(label);
-                        return { input, key: option.key };
+            const updateNavigation = () => {
+                const editor = editors.get(navigation.current);
+                heading.textContent = editor?.title ?? definition.metadata?.name ?? active;
+                back.disabled = saving || !navigation.canGoBack;
+                publishNavigation();
+            };
+            /**
+             * 串行执行模块操作，保持输入可编辑。
+             * Serialize module actions while keeping inputs editable.
+             * @param {() => Promise<void>} action 请求或写入 / Request or mutation.
+             * @param {() => void} success 成功后的局部更新 / Local update after success.
+             * @param {() => void} [failure] 失败后恢复当前输入 / Restore the current input on failure.
+             * @returns {Promise<void>} 操作完成 / Operation completion.
+             */
+            function perform(action, success, failure = () => {}) {
+                pendingWrites++;
+                saving = true;
+                back.disabled = true;
+                publishNavigation();
+                queue = queue
+                    .then(action)
+                    .then(() => {
+                        if (!destroyed) success();
+                    })
+                    .catch(() => {
+                        /* 请求层已通知错误。
+                         * The request layer has already reported the error. */
+                        if (!destroyed) failure();
+                    })
+                    .finally(() => {
+                        pendingWrites--;
+                        saving = pendingWrites > 0;
+                        if (destroyed && !saving) client.leave();
+                        back.disabled = saving || !navigation.canGoBack;
+                        publishNavigation();
                     });
-                    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);
-                    };
-                    break;
+                return queue;
+            }
+            const metadata = definition.metadata;
+            if (metadata) {
+                const info = element("div", "pp-module-info");
+                const details = element("div", "pp-module-details");
+                for (const description of [metadata.author, metadata.desc ?? metadata.description, ...(metadata.descs ?? [])]) if (description) details.append(element("p", "pp-description", description));
+                if (metadata.repo) {
+                    const link = element("a", "pp-module-source", "项目主页");
+                    link.href = resourceURL(metadata.repo);
+                    link.target = "_blank";
+                    link.rel = "noopener noreferrer";
+                    details.append(link);
                 }
-                case field.type === "boolean": {
-                    const toggle = element("input", "pp-switch");
-                    toggle.type = "checkbox";
-                    toggle.setAttribute("switch", "");
-                    toggle.setAttribute("role", "switch");
-                    toggle.setAttribute("aria-label", field.name);
-                    write = value => {
-                        toggle.checked = value === true;
-                    };
-                    read = () => toggle.checked;
-                    row.append(toggle);
-                    break;
+                info.append(details);
+                view.append(info);
+            }
+            for (const field of definition.fields) {
+                const match = /^\[([^\]]+)\]\s*(.*)$/.exec(field.name);
+                const group = match?.[1] ?? "通用";
+                if (!groups.has(group)) {
+                    const section = element("section", "pp-group");
+                    const rows = element("div", "pp-rows");
+                    section.append(element("h2", "pp-group-title", group), rows);
+                    groups.set(group, rows);
+                    view.append(section);
                 }
-                default: {
-                    const multiline = field.control === "textarea" || field.type === "array";
-                    const input = element(multiline ? "textarea" : "input", "");
-                    if (multiline) row.classList.add("pp-multiline");
-                    input.setAttribute("aria-label", field.name);
-                    if (field.placeholder) input.placeholder = field.placeholder;
-                    if (multiline && field.rows) input.rows = field.rows;
-                    /**
-                     * 在挂载后根据内容调整高度，同时保留基础行数。
-                     * Size mounted textareas to their contents while retaining baseline rows.
-                     * @returns {void} 无返回值 / No return value.
-                     */
-                    const grow = () => {
-                        if (!multiline || !field.autoGrow || !input.isConnected) return;
-                        input.style.height = "auto";
-                        const baseline = input.getBoundingClientRect().height;
-                        const style = window.getComputedStyle(input);
-                        const borders = Number.parseFloat(style.borderTopWidth) + Number.parseFloat(style.borderBottomWidth);
-                        input.style.height = `${Math.max(baseline, input.scrollHeight + borders)}px`;
-                    };
-                    if (multiline && field.autoGrow) {
-                        input.addEventListener("input", grow);
-                        growingInputs.push(grow);
+                const row = settingRow("div");
+                row.classList.add("pp-field");
+                const label = element("div", "pp-label");
+                label.append(element("span", "pp-field-name", match?.[2] ?? field.name));
+                if (field.description) label.append(element("span", "pp-field-description", field.description));
+                row.append(label);
+                const value = values[field.key];
+                /**
+                 * 读取尚未保存的输入
+                 * Read the unsaved input.
+                 * @type {() => unknown}
+                 */
+                let read;
+                /**
+                 * 更新当前控件
+                 * Update the current control.
+                 * @type {(value: unknown) => void}
+                 */
+                let write;
+                let inputContainer = row;
+                let eventName = "change";
+                switch (true) {
+                    case Boolean(field.options) && field.type !== "array": {
+                        const select = element("select", "");
+                        select.setAttribute("aria-label", field.name);
+                        field.options.forEach((option, index) => {
+                            const item = element("option", "", option.label);
+                            item.value = String(index);
+                            select.append(item);
+                        });
+                        write = value => {
+                            select.selectedIndex = field.options.findIndex(option => option.key === value);
+                        };
+                        row.append(fieldControl(select));
+                        read = () => field.options[select.selectedIndex]?.key;
+                        break;
                     }
-                    eventName = "input";
-                    if (!multiline) input.type = field.type === "number" ? "number" : "text";
-                    write = value => {
-                        input.value = field.type === "array" ? JSON.stringify(value ?? []) : (value ?? "");
-                        grow();
-                    };
-                    read = () => {
-                        switch (field.type) {
-                            case "array":
-                                return JSON.parse(input.value);
-                            case "number":
-                                return input.value === "" ? Number.NaN : Number(input.value);
-                            default:
-                                return input.value;
+                    case field.type === "array" && Boolean(field.options): {
+                        const page = element("section", "pp-choice-page");
+                        if (field.description) page.append(element("p", "pp-description", field.description));
+                        const choices = element("div", "pp-rows");
+                        page.append(choices);
+                        inputContainer = choices;
+                        editors.set(field.key, { node: page, title: match?.[2] ?? field.name });
+                        const summary = element("span", "pp-summary");
+                        const link = element("button", "pp-choice-link");
+                        link.type = "button";
+                        link.setAttribute("aria-label", field.name);
+                        link.append(summary, element("span", "pp-chevron", "›"));
+                        row.append(link);
+                        const refresh = () => {
+                            const value = client.snapshot().values[field.key];
+                            summary.textContent =
+                                field.options
+                                    .filter(option => Array.isArray(value) && value.includes(option.key))
+                                    .map(option => option.label)
+                                    .join("、") || "未选择";
+                        };
+                        summaries.push(refresh);
+                        refresh();
+                        link.onclick = () => navigation.open(field.key);
+                        row.addEventListener("click", event => {
+                            if (!link.contains(event.target)) link.click();
+                        });
+                        const inputs = field.options.map(option => {
+                            const label = settingRow("label");
+                            label.classList.add("pp-choice");
+                            label.textContent = option.label;
+                            const input = element("input", "");
+                            input.type = "checkbox";
+                            input.setAttribute("aria-label", option.label);
+                            label.append(input);
+                            choices.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);
+                        };
+                        break;
+                    }
+                    case field.type === "boolean": {
+                        const toggle = element("input", "pp-switch");
+                        toggle.type = "checkbox";
+                        toggle.setAttribute("switch", "");
+                        toggle.setAttribute("role", "switch");
+                        toggle.setAttribute("aria-label", field.name);
+                        write = value => {
+                            toggle.checked = value === true;
+                        };
+                        read = () => toggle.checked;
+                        row.append(toggle);
+                        break;
+                    }
+                    default: {
+                        const multiline = field.control === "textarea" || field.type === "array";
+                        const input = element(multiline ? "textarea" : "input", "");
+                        if (multiline) row.classList.add("pp-multiline");
+                        input.setAttribute("aria-label", field.name);
+                        if (field.placeholder) input.placeholder = field.placeholder;
+                        if (multiline && field.rows) input.rows = field.rows;
+                        /**
+                         * 在挂载后根据内容调整高度，同时保留基础行数。
+                         * Size mounted textareas to their contents while retaining baseline rows.
+                         * @returns {void} 无返回值 / No return value.
+                         */
+                        const grow = () => {
+                            if (!multiline || !field.autoGrow || !input.isConnected) return;
+                            input.style.height = "auto";
+                            const baseline = input.getBoundingClientRect().height;
+                            const style = window.getComputedStyle(input);
+                            const borders = Number.parseFloat(style.borderTopWidth) + Number.parseFloat(style.borderBottomWidth);
+                            input.style.height = `${Math.max(baseline, input.scrollHeight + borders)}px`;
+                        };
+                        if (multiline && field.autoGrow) {
+                            input.addEventListener("input", grow);
+                            growingInputs.push(grow);
                         }
-                    };
-                    row.append(fieldControl(input));
-                    break;
+                        eventName = "input";
+                        if (!multiline) input.type = field.type === "number" ? "number" : "text";
+                        write = value => {
+                            input.value = field.type === "array" ? JSON.stringify(value ?? []) : (value ?? "");
+                            grow();
+                        };
+                        read = () => {
+                            switch (field.type) {
+                                case "array":
+                                    return JSON.parse(input.value);
+                                case "number":
+                                    return input.value === "" ? Number.NaN : Number(input.value);
+                                default:
+                                    return input.value;
+                            }
+                        };
+                        row.append(fieldControl(input));
+                        break;
+                    }
                 }
+                write(value);
+                let inputVersion = 0;
+                inputContainer.addEventListener(eventName, event => {
+                    if (event.isComposing) return;
+                    const version = ++inputVersion;
+                    let value;
+                    try {
+                        value = read();
+                    } catch (error) {
+                        notify({ kind: "error", message: error.message });
+                        return;
+                    }
+                    const restore = () => {
+                        if (version === inputVersion) write(client.snapshot().values[field.key]);
+                    };
+                    perform(
+                        () => {
+                            if (!validValue(field, value)) {
+                                const error = new TypeError("Invalid setting value");
+                                notify({ kind: "error", operation: "write", key: field.key, message: error.message });
+                                throw error;
+                            }
+                            return client.set(field.key, value);
+                        },
+                        () => {
+                            for (const refresh of summaries) refresh();
+                        },
+                        restore,
+                    );
+                });
+                if (eventName === "input") inputContainer.addEventListener("compositionend", event => event.target.dispatchEvent(new window.Event("input", { bubbles: true })));
+                groups.get(group).append(row);
             }
-            write(value);
-            let inputVersion = 0;
-            inputContainer.addEventListener(eventName, event => {
-                if (event.isComposing) return;
-                const version = ++inputVersion,
-                    module = active;
+            const settingsPage = element("section", "pp-settings-page");
+            const settingsOutput = element("pre", "pp-cache");
+            settingsOutput.setAttribute("aria-label", "Settings 内容");
+            settingsPage.append(settingsOutput);
+            editors.set("$settings", { node: settingsPage, title: "设置" });
+            handlers.set("viewSettings", () => {
+                if (saving) return;
                 let value;
-                try {
-                    value = read();
-                } catch (error) {
-                    notify({ kind: "error", message: error.message });
-                    return;
-                }
-                const restore = () => {
-                    if (version === inputVersion) write(client.snapshot(module).values[field.key]);
-                };
-                perform(
-                    () => client.set(module, field.key, value),
+                return perform(
+                    async () => {
+                        try {
+                            value = await client.readSettings();
+                        } catch (error) {
+                            notify({ kind: "error", message: error.message });
+                            throw error;
+                        }
+                    },
                     () => {
-                        for (const refresh of summaries) refresh();
+                        settingsOutput.textContent = value === undefined ? "暂无设置" : JSON.stringify(value, null, 2);
+                        navigation.open("$settings");
                     },
-                    restore,
                 );
             });
-            if (eventName === "input") inputContainer.addEventListener("compositionend", event => event.target.dispatchEvent(new window.Event("input", { bubbles: true })));
-            groups.get(group).append(row);
+            const cachePage = element("section", "pp-cache-page");
+            const output = element("pre", "pp-cache");
+            output.textContent = "暂无缓存";
+            output.setAttribute("aria-label", "Caches 内容");
+            cachePage.append(output);
+            editors.set("$caches", { node: cachePage, title: "缓存" });
+            handlers.set("viewCaches", () => {
+                if (saving) return;
+                let value;
+                return perform(
+                    async () => {
+                        try {
+                            value = await client.readCaches();
+                        } catch (error) {
+                            notify({ kind: "error", message: error.message });
+                            throw error;
+                        }
+                    },
+                    () => {
+                        output.textContent = value === undefined ? "暂无缓存" : JSON.stringify(value, null, 2);
+                        navigation.open("$caches");
+                    },
+                );
+            });
+            handlers.set("clearCaches", async () => {
+                if (saving) return;
+                if (!(await requestConfirmation(window, `清空 ${active} 的全部 Caches？`)) || destroyed || saving) return;
+                return perform(
+                    () => client.clearCaches(),
+                    () => {
+                        output.textContent = "暂无缓存";
+                    },
+                );
+            });
+            handlers.set("reset", async () => {
+                if (saving) return;
+                if (!(await requestConfirmation(window, `重置 ${active} 的设置？这将删除该模块的 Settings、Caches 和其它持久化数据。`)) || destroyed || saving) return;
+                return perform(() => client.reset(), controls);
+            });
+            navigation?.destroy();
+            navigation = new Navigation(viewport, view, key => editors.get(key)?.node);
+            navigation.addEventListener("change", updateNavigation);
+            for (const grow of growingInputs) grow();
+            updateNavigation();
         }
-        const settingsPage = element("section", "pp-settings-page");
-        const settingsOutput = element("pre", "pp-cache");
-        settingsOutput.setAttribute("aria-label", "Settings 内容");
-        settingsPage.append(settingsOutput);
-        editors.set("$settings", { node: settingsPage, title: "设置" });
-        handlers.set("viewSettings", () => {
-            if (saving) return;
-            let value;
-            return perform(
-                async () => {
-                    try {
-                        value = await client.readSettings(active);
-                    } catch (error) {
-                        notify({ kind: "error", message: error.message });
-                        throw error;
-                    }
-                },
-                () => {
-                    settingsOutput.textContent = value === undefined ? "暂无设置" : JSON.stringify(value, null, 2);
-                    navigation.open("$settings");
-                },
-            );
-        });
-        const cachePage = element("section", "pp-cache-page");
-        const output = element("pre", "pp-cache");
-        output.textContent = "暂无缓存";
-        output.setAttribute("aria-label", "Caches 内容");
-        cachePage.append(output);
-        editors.set("$caches", { node: cachePage, title: "缓存" });
-        handlers.set("viewCaches", () => {
-            if (saving) return;
-            let value;
-            return perform(
-                async () => {
-                    try {
-                        value = await client.readCaches(active);
-                    } catch (error) {
-                        notify({ kind: "error", message: error.message });
-                        throw error;
-                    }
-                },
-                () => {
-                    output.textContent = value === undefined ? "暂无缓存" : JSON.stringify(value, null, 2);
-                    navigation.open("$caches");
-                },
-            );
-        });
-        handlers.set("clearCaches", async () => {
-            if (saving) return;
-            if (!(await requestConfirmation(window, `清空 ${active} 的全部 Caches？`)) || destroyed || saving) return;
-            return perform(
-                () => client.clearCaches(active),
-                () => {
-                    output.textContent = "暂无缓存";
-                },
-            );
-        });
-        handlers.set("reset", async () => {
-            if (saving) return;
-            if (!(await requestConfirmation(window, `重置 ${active} 的设置？这将删除该模块的 Settings、Caches 和其它持久化数据。`)) || destroyed || saving) return;
-            return perform(() => client.reset(active), controls);
-        });
-        navigation?.destroy();
-        navigation = new Navigation(viewport, view, key => editors.get(key)?.node);
-        navigation.addEventListener("change", updateNavigation);
-        for (const grow of growingInputs) grow();
-        updateNavigation();
-    }
-    /**
-     * 已加载的表单交由导航组件返回；加载阶段可以返回先前文档。
-     * Loaded forms delegate back to navigation; loading views can return to the previous document.
-     * @returns {void} 无返回值 / No return value.
-     */
-    back.onclick = () => {
-        if (saving) return;
-        if (navigation) navigation.back();
-        else window.history.back();
-    };
-    open(catalog.module.module);
-    return {
         /**
-         * 移除监听器、定时器、会话和挂载内容。
-         * Remove listeners, timers, session and mounted content.
+         * 已加载的表单交由导航组件返回；加载阶段可以返回先前文档。
+         * Loaded forms delegate back to navigation; loading views can return to the previous document.
          * @returns {void} 无返回值 / No return value.
          */
-        destroy() {
+        back.onclick = () => {
+            if (saving) return;
+            if (navigation) navigation.back();
+            else window.history.back();
+        };
+        open(definition.module);
+        return () => {
             destroyed = true;
             menu.destroy();
             window.frameElement?.removeEventListener("preferencepanes:action", onAction);
             navigation?.destroy();
             generation++;
-            if (active && !saving) client.leave(active);
+            if (active && !saving) client.leave();
             clearTimeout(timer);
             shell.remove();
-        },
-    };
+        };
+    }
+
+    /**
+     * 移除监听器、定时器、会话和挂载内容。
+     * Remove listeners, timers, session, and mounted content.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#release();
+    }
 }
 
 var defaults = "/* 通用默认样式只使用 pp 命名空间；项目可通过 CSS 输入覆盖变量和组件。\n * Generic defaults use only the pp namespace; projects may override variables and components through CSS input. */\n.pp-panel {\n    --pp-text: #18191c;\n    --pp-background: #f6f7f8;\n    --pp-surface: #fff;\n    --pp-field: #f1f2f3;\n    --pp-border: #e3e5e7;\n    --pp-muted: #797f87;\n    --pp-accent: #1677ff;\n    font:\n        15px / 1.5 -apple-system,\n        BlinkMacSystemFont,\n        \"Segoe UI\",\n        sans-serif;\n    color: var(--pp-text);\n    background: var(--pp-background);\n    position: relative;\n    display: flex;\n    flex-direction: column;\n    width: 100%;\n    max-width: 100vw;\n    min-width: 0;\n    height: 100vh;\n    overflow: hidden;\n}\n\n:root[data-theme=\"dark\"] .pp-panel {\n    --pp-text: #f1f2f3;\n    --pp-background: #0d0e0f;\n    --pp-surface: #18191c;\n    --pp-field: #2f3238;\n    --pp-border: #2f3238;\n    --pp-muted: #9499a0;\n}\n.pp-panel * {\n    box-sizing: border-box;\n    letter-spacing: 0;\n}\n.pp-header {\n    flex: none;\n    height: calc(52px + env(safe-area-inset-top));\n    padding: env(safe-area-inset-top) 12px 0;\n    display: flex;\n    align-items: center;\n    background: var(--pp-surface);\n    border-bottom: 1px solid var(--pp-border);\n    position: relative;\n    z-index: 2;\n}\n.pp-title {\n    flex: 1;\n    text-align: center;\n    font-size: 17px;\n    font-weight: 500;\n    margin: 0;\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n.pp-nav-spacer {\n    width: 44px;\n    flex: none;\n}\n.pp-panel button {\n    font: inherit;\n    cursor: pointer;\n    border: 0;\n    background: none;\n    color: inherit;\n}\n.pp-panel .pp-back {\n    width: 44px;\n    height: 44px;\n    flex: none;\n    font-size: 34px;\n    line-height: 32px;\n    padding: 0;\n}\n.pp-panel button:disabled {\n    opacity: 0.5;\n    cursor: wait;\n}\n.pp-viewport {\n    position: relative;\n    flex: 1;\n    min-width: 0;\n    min-height: 0;\n    overflow: hidden;\n}\n:root[data-preference-panes-embedded] .pp-header {\n    display: none;\n}\n@supports (height: 100dvh) {\n    .pp-panel {\n        height: 100dvh;\n    }\n}\n.pp-fields,\n.pp-choice-page,\n.pp-settings-page,\n.pp-cache-page {\n    position: absolute;\n    inset: 0;\n    min-width: 0;\n    overflow-x: hidden;\n    overflow-y: auto;\n    padding: 12px max(16px, calc((100% - 688px) / 2)) calc(28px + env(safe-area-inset-bottom) + var(--pp-keyboard-height, 0px));\n    scroll-padding-bottom: var(--pp-keyboard-height, 0px);\n    background: var(--pp-background);\n}\n.pp-choice-link {\n    display: flex;\n    align-items: center;\n    justify-content: flex-end;\n    gap: 8px;\n    max-width: 45%;\n    min-width: 44px;\n    min-height: 44px;\n    padding: 0;\n    text-align: right;\n    flex: 1;\n}\n.pp-summary {\n    color: var(--pp-muted);\n    font-size: 13px;\n    line-height: 18px;\n    display: -webkit-box;\n    -webkit-line-clamp: 2;\n    -webkit-box-orient: vertical;\n    overflow: hidden;\n    overflow-wrap: anywhere;\n}\n.pp-chevron {\n    color: var(--pp-muted);\n    font-size: 22px;\n    flex: none;\n}\n.pp-editor {\n    flex: none;\n    width: 45%;\n    min-width: 0;\n    min-height: 36px;\n    padding: 8px 10px;\n    font: inherit;\n    color: var(--pp-text);\n    background: var(--pp-field);\n    border: 0;\n    border-radius: 6px;\n}\n.pp-panel .pp-multiline {\n    display: block;\n}\n.pp-multiline .pp-editor {\n    width: 100%;\n    margin-top: 10px;\n}\n.pp-panel [hidden] {\n    display: none !important;\n}\n.pp-label {\n    flex: 1;\n    min-width: 0;\n    display: flex;\n    flex-direction: column;\n    align-items: flex-start;\n    margin-right: 16px;\n}\n.pp-field-name {\n    color: var(--pp-text);\n    font-size: 15px;\n}\n.pp-field-description {\n    margin-top: 2px;\n    color: var(--pp-muted);\n    font-size: 12px;\n}\n.pp-group {\n    margin-top: 16px;\n}\n.pp-group-title {\n    margin: 0 0 8px;\n    color: var(--pp-muted);\n    font-size: 15px;\n    font-weight: 400;\n}\n.pp-row {\n    min-width: 0;\n    min-height: 48px;\n    padding: 16px;\n    display: flex;\n    align-items: center;\n    justify-content: space-between;\n    background: var(--pp-surface);\n    border-bottom: 1px solid var(--pp-border);\n}\n.pp-rows > :last-child {\n    border-bottom: 0 !important;\n}\n.pp-switch {\n    flex: none;\n    accent-color: var(--pp-accent);\n}\n.pp-choice {\n    justify-content: space-between;\n    cursor: pointer;\n}\n.pp-choice input {\n    width: 20px;\n    height: 20px;\n    flex: none;\n    accent-color: var(--pp-accent);\n    margin: 0;\n}\n.pp-description {\n    font-size: 12px;\n    line-height: 1.6;\n    color: var(--pp-muted);\n    white-space: pre-wrap;\n    overflow-wrap: anywhere;\n}\n.pp-module-info {\n    display: flex;\n    gap: 12px;\n    margin: 12px 0;\n}\n.pp-module-details {\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n.pp-module-source {\n    color: inherit;\n    text-decoration: underline;\n}\n.pp-status {\n    position: fixed;\n    inset: 0;\n    display: grid;\n    place-content: center;\n    justify-items: center;\n    gap: 12px;\n    min-width: 0;\n    min-height: 0;\n    margin: 0;\n    padding: 24px;\n    color: var(--pp-muted, GrayText);\n    text-align: center;\n    background: var(--pp-background, Canvas);\n}\n.pp-viewport > .pp-status {\n    position: absolute;\n}\n.pp-status-spinner {\n    box-sizing: border-box;\n    width: 28px;\n    height: 28px;\n    border: 3px solid color-mix(in srgb, currentColor 25%, transparent);\n    border-top-color: var(--pp-accent, AccentColor);\n    border-radius: 50%;\n    animation: pp-status-spin 0.8s linear infinite;\n}\n.pp-status-message {\n    max-width: 100%;\n    margin: 0;\n    overflow-wrap: anywhere;\n}\n.pp-status-action {\n    min-width: 96px;\n    min-height: 44px;\n    padding: 8px 16px;\n    border: 0;\n    border-radius: 6px;\n    color: var(--pp-text, ButtonText);\n    font: inherit;\n    cursor: pointer;\n    background: var(--pp-surface, ButtonFace);\n}\n@keyframes pp-status-spin {\n    to {\n        transform: rotate(1turn);\n    }\n}\n.pp-cache {\n    white-space: pre-wrap;\n    overflow-wrap: anywhere;\n}\n.pp-toast {\n    pointer-events: none;\n    position: fixed;\n    bottom: calc(30px + env(safe-area-inset-bottom));\n    left: 50%;\n    transform: translateX(-50%);\n    max-width: 90vw;\n    padding: 10px 16px;\n    border-radius: 8px;\n    background: #333e;\n    color: white;\n    font-size: 13px;\n    z-index: 20;\n}\n.pp-toast[data-kind=\"error\"] {\n    background: #8d2424;\n}\n.pp-panel :focus-visible {\n    outline: 2px solid var(--pp-accent);\n    outline-offset: -2px;\n}\n";
@@ -1319,81 +1294,118 @@ function installDefaultStyles(document) {
 }
 
 /**
- * 挂载模块设置页；默认样式由包提供，可选 CSS 仅作用于当前模块。
- * Mount a module page with package defaults and optional module-scoped CSS.
- * @param {import("../index.js").BoxJSInput} boxjs 单个模块的 BoxJS JSON / BoxJS JSON for one module.
- * @param {string} [css] 可选 CSS 正文 / Optional CSS text.
- * @returns {import("./index.js").MountedPreferences} 模块生命周期句柄 / Module lifecycle handle.
+ * 管理模块设置视图的模型规范化、样式、主题同步和面板生命周期。
+ * Manage model normalization, styles, theme synchronization, and panel lifecycle for a module settings view.
  */
-function mount(boxjs, css = "") {
-    if (typeof css !== "string") throw new TypeError("CSS must be a string");
-    const catalog = boxjs instanceof BoxJS ? boxjs : new BoxJS(boxjs);
-    const metadata = catalog.module.metadata;
-    const image = metadata.icon || metadata.icons?.[1] || metadata.icons?.[0];
-    if (image) resourceURL(image);
-    if (metadata.repo) resourceURL(metadata.repo);
-    const existing = document.querySelector("#preferences");
-    const root = existing ?? element("main", "");
-    if (!existing) {
-        root.id = "preferences";
-        document.body.append(root);
+class PreferencesView {
+    #existing;
+    #root;
+    #base;
+    #ownsBase;
+    #custom;
+    #previousTitle;
+    #previousTheme;
+    #systemTheme;
+    #previousKeyboard;
+    #host;
+    #observer;
+    #panel;
+
+    /**
+     * 使用模块 API 返回的模型挂载设置页。
+     * Mount a settings page from the model returned by the module API.
+     * @param {import("../index.js").ModuleModel} model API 返回的模块模型 / Module model returned by the API.
+     * @param {string} [css] 可选 CSS 正文 / Optional module-scoped CSS text.
+     */
+    constructor(model, css = "") {
+        if (typeof css !== "string") throw new TypeError("CSS must be a string");
+        const definition = normalizeBoxJs(model.boxjs, model.module);
+        const values = { ...model.values };
+        for (const field of definition.fields) {
+            if (values[field.key] === undefined) continue;
+            values[field.key] = normalizeStoredValue(field, values[field.key]);
+            if (!validValue(field, values[field.key])) throw new TypeError(`Invalid stored value: ${field.key}`);
+        }
+        for (const field of definition.fields) if (values[field.key] === undefined && Object.hasOwn(field, "defaultValue")) values[field.key] = structuredClone(field.defaultValue);
+        const rendered = { ...model, definition, values };
+        const metadata = definition.metadata ?? {};
+        const image = metadata.icon || metadata.icons?.[1] || metadata.icons?.[0];
+        if (image) resourceURL(image);
+        if (metadata.repo) resourceURL(metadata.repo);
+
+        this.#existing = document.querySelector("#preferences");
+        this.#root = this.#existing ?? element("main", "");
+        if (!this.#existing) {
+            this.#root.id = "preferences";
+            document.body.append(this.#root);
+        }
+        const styles = installDefaultStyles(document);
+        this.#base = styles.element;
+        this.#ownsBase = styles.owned;
+        this.#custom = element("style", "");
+        this.#custom.textContent = css;
+        document.head.append(this.#custom);
+        this.#previousTitle = document.title;
+        this.#previousTheme = document.documentElement.dataset.theme;
+        this.#systemTheme = window.matchMedia("(prefers-color-scheme: dark)");
+        this.#previousKeyboard = document.documentElement.style.getPropertyValue("--pp-keyboard-height");
+        this.#host = window.frameElement?.ownerDocument.documentElement;
+        this.#syncAppearance();
+        this.#systemTheme.addEventListener("change", this.#syncAppearance);
+        if (this.#host) {
+            this.#observer = new MutationObserver(this.#syncAppearance);
+            this.#observer.observe(this.#host, { attributes: true, attributeFilter: ["data-theme", "style"] });
+        }
+        document.title = metadata.name ?? definition.module;
+        try {
+            this.#root.replaceChildren();
+            this.#panel = new PreferencesPanel(this.#root, rendered);
+        } catch (error) {
+            this.destroy();
+            throw error;
+        }
     }
-    const { element: base, owned: ownsBase } = installDefaultStyles(document);
-    const custom = element("style", "");
-    custom.textContent = css;
-    document.head.append(custom);
-    const previousTitle = document.title;
-    const previousTheme = document.documentElement.dataset.theme;
-    const systemTheme = window.matchMedia("(prefers-color-scheme: dark)");
-    const previousKeyboard = document.documentElement.style.getPropertyValue("--pp-keyboard-height");
-    const host = window.frameElement?.ownerDocument.documentElement;
+
     /**
      * 跟随嵌入宿主的通用环境状态，不识别业务 App 或解析其 UA。
-     * Follow generic host appearance without detecting a business app or parsing its user agent.
+     * Follow generic host appearance without detecting a business App or parsing its UA.
      * @returns {void} 已同步主题与键盘避让 / Theme and keyboard clearance synchronized.
      */
-    const syncAppearance = () => {
-        const theme = host?.dataset.theme ?? previousTheme ?? (systemTheme.matches ? "dark" : "light");
+    #syncAppearance = () => {
+        const theme = this.#host?.dataset.theme ?? this.#previousTheme ?? (this.#systemTheme.matches ? "dark" : "light");
         document.documentElement.dataset.theme = theme;
-        if (host) document.documentElement.style.setProperty("--pp-keyboard-height", host.style.getPropertyValue("--pp-keyboard-height"));
+        if (this.#host) document.documentElement.style.setProperty("--pp-keyboard-height", this.#host.style.getPropertyValue("--pp-keyboard-height"));
     };
-    let observer;
-    syncAppearance();
-    systemTheme.addEventListener("change", syncAppearance);
-    if (host) {
-        observer = new MutationObserver(syncAppearance);
-        observer.observe(host, { attributes: true, attributeFilter: ["data-theme", "style"] });
-    }
-    document.title = metadata.name ?? catalog.module.module;
-    let panel;
-    const view = {
-        /**
-         * 释放模块视图、样式与会话，不操作项目入口页。
-         * Release the module view, styles and session without operating a project landing page.
-         * @returns {void} 无返回值 / No return value.
-         */
-        destroy() {
-            observer?.disconnect();
-            systemTheme.removeEventListener("change", syncAppearance);
-            panel?.destroy();
-            if (ownsBase) base.remove();
-            custom.remove();
-            if (existing) root.replaceChildren();
-            else root.remove();
-            document.title = previousTitle;
-            if (previousTheme === undefined) delete document.documentElement.dataset.theme;
-            else document.documentElement.dataset.theme = previousTheme;
-            document.documentElement.style.setProperty("--pp-keyboard-height", previousKeyboard);
-        },
-    };
-    try {
-        root.replaceChildren();
-        panel = mountPanel(root, catalog);
-        return view;
-    } catch (error) {
-        view.destroy();
-        throw error;
+
+    /**
+     * 释放模块视图、样式与会话，不操作项目入口页。
+     * Release the module view, styles, and session without operating a project landing page.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#observer?.disconnect();
+        this.#systemTheme.removeEventListener("change", this.#syncAppearance);
+        this.#panel?.destroy();
+        if (this.#ownsBase) this.#base.remove();
+        this.#custom.remove();
+        if (this.#existing) this.#root.replaceChildren();
+        else this.#root.remove();
+        document.title = this.#previousTitle;
+        if (this.#previousTheme === undefined) delete document.documentElement.dataset.theme;
+        else document.documentElement.dataset.theme = this.#previousTheme;
+        document.documentElement.style.setProperty("--pp-keyboard-height", this.#previousKeyboard);
     }
 }
 
-export { mount };
+/**
+ * 使用模块 API 返回的模型挂载设置页；CSS 仅覆盖当前模块。
+ * Mount a settings page from a module API model; CSS only overrides this module.
+ * @param {import("../index.js").ModuleModel} model API 返回的模块模型 / Module model returned by the API.
+ * @param {string} [css] 可选 CSS 正文 / Optional module-scoped CSS text.
+ * @returns {PreferencesView} 模块视图 / Module view.
+ */
+function mount(model, css = "") {
+    return new PreferencesView(model, css);
+}
+
+export { PreferencesView, mount };