@nsnanocat/preference-panes 1.0.0 → 1.1.1

package/dist/preference-panes.mjs

@@ -45,8 +45,8 @@ function normalizeBoxJs(config, module) {
             target.owners.add(app);
         }
     }
-    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 (modules.size !== 1) throw new TypeError("Import BoxJS JSON for exactly one module");
+    const target = modules.values().next().value ;
     if (!target) throw new TypeError(`No BoxJS settings for module: ${module}`);
     const metadata = normalizeMetadata(target.owners.size === 1 ? presentation([...target.owners][0]) : {});
     const fields = [];
@@ -423,16 +423,133 @@ class ActionMenu {
 }
 
 /**
- * 创建单模块页面客户端；只调用模块 API，不读取或解析 BoxJS。
- * Create a single-module 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.
- * @returns {import("./client.mjs").PreferencesClient} 页面客户端 / Page client.
+ * 管理单模块页面的 API 请求、值快照和会话终止。
+ * Manage API requests, value snapshots, and session termination for one module page.
  */
-function createPreferencesClient({ model, definition, fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 }) {
-    const { module, configURL } = model;
-    const session = new AbortController();
-    const values = structuredClone(model.values);
-    let saving = false;
+class PreferencesClient {
+    #module;
+    #definition;
+    #request;
+    #notify;
+    #timeout;
+    #session = new AbortController();
+    #values = {};
+    #saving = false;
+
+    /**
+     * 创建从 BoxJS 定义读取和持久化设置的页面客户端。
+     * Create a page client that reads and persists settings from a BoxJS definition.
+     * @param {import("./client.mjs").PreferencesClientOptions} options 字段定义、请求与通知 / Field definition, requests, and notifications.
+     */
+    constructor({ definition, fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 }) {
+        this.#module = definition.module;
+        this.#definition = definition;
+        this.#request = request;
+        this.#notify = notify;
+        this.#timeout = timeout;
+    }
+
+    /**
+     * 读取一次 Settings 子树并建立页面值快照。
+     * Read the Settings subtree once and establish the page value snapshot.
+     * @returns {Promise<import("./client.mjs").ModuleSnapshot>} 页面快照 / Page snapshot.
+     */
+    async open() {
+        let subtree = await this.readSettings();
+        if (subtree === undefined) subtree = {};
+        if (typeof subtree === "string") subtree = JSON.parse(subtree);
+        if (!subtree || typeof subtree !== "object" || Array.isArray(subtree)) throw new TypeError("Expected a settings subtree object");
+        const values = {};
+        for (const field of this.#definition.fields) {
+            const stored = field.key
+                .split(".")
+                .slice(this.#definition.settingsPath.length)
+                .reduce((parent, part) => Object(parent)[part], subtree);
+            const value = normalizeStoredValue(field, stored === undefined ? field.defaultValue : stored);
+            if (value === undefined) continue;
+            if (!validValue(field, value)) throw new TypeError(`Invalid stored value: ${field.key}`);
+            values[field.key] = value;
+        }
+        this.#values = values;
+        return this.snapshot();
+    }
+
+    /**
+     * 获取当前字段定义和值的深拷贝，不发起网络请求。
+     * 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 });
+    }
+
+    /**
+     * 读取 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();
+    }
+
+    /**
+     * 读取 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();
+    }
+
+    /**
+     * 删除当前模块的 Caches 子树。
+     * Delete the current module Caches subtree.
+     * @returns {Promise<void>} 操作完成 / Operation completion.
+     */
+    clearCaches() {
+        return this.#change("delete", { scope: "caches" }, "clearCaches");
+    }
+
+    /**
+     * 删除当前模块数据并恢复页面默认值。
+     * 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);
+    }
+
+    /**
+     * 删除单个字段覆盖值。
+     * Delete one field override.
+     * @param {string} key 字段路径 / Field path.
+     * @returns {Promise<void>} 操作完成 / Operation completion.
+     */
+    remove(key) {
+        return this.#change("delete", { key }, "delete", key);
+    }
 
     /**
      * 向模块 API 发送 JSON 动作。
@@ -441,26 +558,26 @@ function createPreferencesClient({ model, definition, fetch: request = globalThi
      * @param {unknown} payload JSON 请求体 / JSON request body.
      * @returns {Promise<Response>} 原始响应 / Raw response.
      */
-    async function send(action, payload) {
+    async #send(action, payload) {
         const controller = new AbortController();
         const abort = () => controller.abort();
-        if (session.signal.aborted) abort();
-        session.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/${encodeURIComponent(module)}/${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/json", "X-PreferencePanes-JSON": configURL },
+                headers: { "Content-Type": "application/json" },
                 body: JSON.stringify(payload),
             });
             if (response.status !== 200 && !(action === "get" && response.status === 404)) throw new Error(`HTTP ${response.status}`);
             return response;
         } finally {
             clearTimeout(timer);
-            session.signal.removeEventListener("abort", abort);
+            this.#session.signal.removeEventListener("abort", abort);
         }
     }
 
@@ -468,60 +585,47 @@ function createPreferencesClient({ model, definition, fetch: request = globalThi
      * 执行写入动作；成功后只更新当前页面值。
      * Execute a mutation and update only the current page values after success.
      * @param {"set" | "delete"} action API 动作 / API action.
-     * @param {unknown} payload JSON 请求体 / JSON request body.
+     * @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.
      */
-    async function change(action, payload, operation, key) {
-        if (saving) throw new Error("A settings write is already in progress");
-        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 {
-            await send(action, payload);
+            if (operation === "write") {
+                const field = this.#definition.fields.find(candidate => candidate.key === key);
+                if (!field || !validValue(field, payload.value)) throw new TypeError("Invalid setting value");
+            }
+            await this.#send(action, payload);
             switch (operation) {
                 case "write":
-                    values[key] = structuredClone(payload.value);
+                    this.#values[key] = structuredClone(payload.value);
                     break;
                 case "delete": {
-                    const field = definition.fields.find(candidate => candidate.key === key);
-                    delete values[key];
-                    if (field && Object.hasOwn(field, "defaultValue")) values[key] = structuredClone(field.defaultValue);
+                    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 definition.fields) {
-                        delete values[field.key];
-                        if (Object.hasOwn(field, "defaultValue")) values[field.key] = structuredClone(field.defaultValue);
+                    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 {
-            saving = false;
+            this.#saving = false;
         }
     }
-
-    return {
-        snapshot: () => structuredClone({ definition, values }),
-        async readSettings() {
-            const response = await send("get", { scope: "settings" });
-            return response.status === 404 ? undefined : response.json();
-        },
-        async readCaches() {
-            const response = await send("get", { scope: "caches" });
-            return response.status === 404 ? undefined : response.json();
-        },
-        clearCaches: () => change("delete", { scope: "caches" }, "clearCaches"),
-        reset: () => change("delete", { scope: "module" }, "reset"),
-        leave: () => session.abort(),
-        set: (key, value) => change("set", { key, value }, "write", key),
-        remove: key => change("delete", { key }, "delete", key),
-    };
 }
 
 /**
@@ -684,485 +788,496 @@ class Navigation extends EventTarget {
 }
 
 /**
- * 挂载 API 返回的模块模型表单和短暂通知。
- * Mount the module model returned by the API and transient notifications.
- * @param {HTMLElement} root 包内挂载元素 / Internal mount element.
- * @param {import("../index.js").ModuleModel} model API 返回的模块模型 / Module model returned by the API.
- * @returns {import("./index.js").MountedPreferences} 面板生命周期句柄 / Panel lifecycle handle.
+ * 管理模块表单、导航、操作队列和短暂通知。
+ * Manage the module form, navigation, operation queue, and transient notifications.
  */
-function mountPanel(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;
-    /**
-     * 展示短暂通知，不刷新设置数据。
-     * 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({ model, definition, 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.
+     * 挂载 BoxJS 定义对应的模块表单。
+     * Mount the module form described by a BoxJS definition.
+     * @param {HTMLElement} root 包内挂载元素 / Internal mount element.
+     * @param {import("../index.js").ModuleDefinition} definition 已规范化字段定义 / Normalized field definition.
      */
-    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();
-        }
+    constructor(root, definition) {
+        this.#release = this.#mount(root, definition);
     }
+
     /**
-     * 从会话快照创建控件与操作按钮，不重新读取网络配置。
-     * 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").ModuleDefinition} definition 已规范化字段定义 / Normalized field definition.
+     * @returns {() => void} 释放操作 / Release operation.
      */
-    function controls() {
-        const { definition, values } = client.snapshot();
-        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, definition) {
+        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({ 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();
-            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();
-                });
-            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);
+        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 {
+                await client.open();
+                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().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;
+            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().values[field.key]);
-                };
-                perform(
+                return perform(
+                    async () => {
+                        try {
+                            value = await client.readSettings();
+                        } catch (error) {
+                            notify({ kind: "error", message: error.message });
+                            throw error;
+                        }
+                    },
                     () => {
-                        if (!validValue(field, value)) {
-                            const error = new TypeError("Invalid setting value");
-                            notify({ kind: "error", operation: "write", key: field.key, message: error.message });
+                        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();
+                        } catch (error) {
+                            notify({ kind: "error", message: error.message });
                             throw error;
                         }
-                        return client.set(field.key, value);
                     },
                     () => {
-                        for (const refresh of summaries) refresh();
+                        output.textContent = value === undefined ? "暂无缓存" : JSON.stringify(value, null, 2);
+                        navigation.open("$caches");
                     },
-                    restore,
                 );
             });
-            if (eventName === "input") inputContainer.addEventListener("compositionend", event => event.target.dispatchEvent(new window.Event("input", { bubbles: true })));
-            groups.get(group).append(row);
+            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();
-                    } 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();
-                    } 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();
-    }
-    /**
-     * 已加载的表单交由导航组件返回；加载阶段可以返回先前文档。
-     * 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(definition.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);
@@ -1171,8 +1286,17 @@ function mountPanel(root, model) {
             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";
@@ -1196,89 +1320,102 @@ function installDefaultStyles(document) {
 }
 
 /**
- * 挂载模块设置页；默认样式由包提供，可选 CSS 仅作用于当前模块。
- * Mount a module page with package defaults and optional module-scoped CSS.
- * @param {import("../index.js").ModuleModel} model API 返回的模块模型 / Module model returned by the API.
- * @param {string} [css] 可选 CSS 正文 / Optional CSS text.
- * @returns {import("./index.js").MountedPreferences} 模块生命周期句柄 / Module lifecycle handle.
+ * 管理 BoxJS 规范化、主题同步和面板生命周期。
+ * Manage BoxJS normalization, theme synchronization, and panel lifecycle.
  */
-function mount(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);
-    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;
+    #previousTitle;
+    #previousTheme;
+    #systemTheme;
+    #previousKeyboard;
+    #host;
+    #observer;
+    #panel;
+
+    /**
+     * 使用原始 BoxJS JSON 挂载设置页。
+     * Mount a settings page from raw BoxJS JSON.
+     * @param {import("../index.js").BoxJSInput} boxjs 单模块 BoxJS JSON / Single-module BoxJS JSON.
+     */
+    constructor(boxjs) {
+        const definition = normalizeBoxJs(boxjs);
+        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.#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, definition);
+        } 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 ?? definition.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, rendered);
-        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();
+        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);
     }
 }
 
+/**
+ * 使用原始 BoxJS JSON 挂载设置页。
+ * Mount a settings page from raw BoxJS JSON.
+ * @param {import("../index.js").BoxJSInput} boxjs 单模块 BoxJS JSON / Single-module BoxJS JSON.
+ * @returns {import("./index.js").MountedPreferences} 模块视图 / Module view.
+ */
+function mount(boxjs) {
+    return new PreferencesView(boxjs);
+}
+
 export { mount };