@nsnanocat/preference-panes 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nsnanocat/preference-panes",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "description": "Shared settings API runtime for JavaScript proxy modules",
     "author": "VirgilClyne <Virgil@nanocat.me>",
     "homepage": "https://NSNanoCat.github.io/preference-panes",

package/src/browser/client.d.mts

@@ -42,10 +42,12 @@ export interface ModuleSnapshot {
     values: Record<string, SettingsScalar | SettingsScalar[] | null>;
 }
 /**
- * 只调用模块 API 的页面客户端。
- * Page client that only calls the module API.
+ * 管理单模块页面的 API 请求、值快照和会话终止。
+ * Manage API requests, value snapshots, and session termination for one module page.
  */
-export interface PreferencesClient {
+export class PreferencesClient {
+    /** 创建页面客户端 / Create the page client. */
+    constructor(options: PreferencesClientOptions);
     /** 获取页面快照，不发请求 / Get a page snapshot without a request. */
     snapshot(): ModuleSnapshot;
     /** 读取 Settings 子树 / Read the Settings subtree. */
@@ -63,10 +65,3 @@ export interface PreferencesClient {
     /** 删除单个字段覆盖值 / Delete one field override. */
     remove(key: string): Promise<void>;
 }
-/**
- * 创建只调用模块 API 的页面客户端。
- * Create a page client that only calls the module API.
- * @param options API 模型与运行环境 / API model and runtime.
- * @returns 页面客户端 / Page client.
- */
-export function createPreferencesClient(options: PreferencesClientOptions): PreferencesClient;

package/src/browser/client.mjs

@@ -1,14 +1,109 @@
 /**
- * 创建单模块页面客户端；只调用模块 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.
  */
-export 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;
+export class PreferencesClient {
+    #module;
+    #configURL;
+    #definition;
+    #request;
+    #notify;
+    #timeout;
+    #session = new AbortController();
+    #values;
+    #saving = false;
+
+    /**
+     * 创建只调用模块 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);
+    }
+
+    /**
+     * 获取当前字段定义和值的深拷贝，不发起网络请求。
+     * 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 动作。
@@ -17,26 +112,26 @@ export function createPreferencesClient({ model, definition, fetch: request = gl
      * @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", "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);
-            session.signal.removeEventListener("abort", abort);
+            this.#session.signal.removeEventListener("abort", abort);
         }
     }
 
@@ -44,58 +139,41 @@ export function createPreferencesClient({ model, definition, fetch: request = gl
      * 执行写入动作；成功后只更新当前页面值。
      * 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);
+            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),
-    };
 }

package/src/browser/index.d.ts

@@ -8,11 +8,26 @@ export interface MountedPreferences {
     /** 移除页面、样式和监听器 / Remove page, styles and listeners. */
     destroy(): void;
 }
+/**
+ * 管理模块设置视图的模型、样式、主题和面板生命周期。
+ * Manage model, styles, theme, and panel lifecycle for a module settings view.
+ */
+export class PreferencesView implements MountedPreferences {
+    /**
+     * 使用模块 API 返回的模型挂载设置页。
+     * Mount a settings page from the model returned by the module API.
+     * @param model 模块 API 模型 / Module API model.
+     * @param css 可选 CSS 正文 / Optional CSS text.
+     */
+    constructor(model: ModuleModel, css?: string);
+    /** 移除页面、样式和监听器 / Remove page, styles and listeners. */
+    destroy(): void;
+}
 /**
  * 使用模块 API 返回的模型挂载设置页；CSS 仅覆盖当前模块。
  * Mount a settings page from a module API model; CSS only overrides this module.
  * @param model 模块 API 模型 / Module API model.
  * @param css 可选 CSS 正文 / Optional CSS text.
- * @returns 生命周期句柄 / Lifecycle handle.
+ * @returns 模块视图 / Module view.
  */
-export function mount(model: ModuleModel, css?: string): MountedPreferences;
+export function mount(model: ModuleModel, css?: string): PreferencesView;

package/src/browser/index.mjs

@@ -1,90 +1,105 @@
-import { normalizeBoxJs, normalizeStoredValue, validValue } from "./boxjs.mjs";
-import { element, resourceURL } from "./components.mjs";
-import { mountPanel } from "./panel.mjs";
+import { pageInputs } from "../lib/page-inputs.mjs";
+import { statusView } from "./components.mjs";
+import { PreferencesView } from "./mount.mjs";
 import { installDefaultStyles } from "./styles.mjs";
 
 /**
- * 挂载模块设置页；默认样式由包提供，可选 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.
+ * 管理模块文档的页面输入、初始请求、重载和错误状态。
+ * Manage page inputs, initial requests, reloads, and error states for a module document.
  */
-export 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}`);
+export class ModulePage {
+    #document;
+    #window;
+    #root;
+    #view;
+
+    /**
+     * 创建模块页面控制器并安装基础样式。
+     * Create the module page controller and install base styles.
+     * @param {Document} document 模块文档 / Module document.
+     */
+    constructor(document) {
+        this.#document = document;
+        this.#window = document.defaultView;
+        this.#root = document.querySelector("#preferences");
+        installDefaultStyles(document);
+        this.#window.addEventListener("pageshow", this.#show);
     }
-    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);
+
+    /**
+     * 从 URL 或代理传递的 Header 导入 JSON/CSS，支持独立文档与 srcdoc。
+     * Import JSON/CSS from the URL or proxy-carried headers in standalone and srcdoc documents.
+     * @returns {Promise<void>} 启动完成 / Startup completion.
+     */
+    async start() {
+        try {
+            this.#view?.destroy();
+            this.#view = undefined;
+            this.#root.replaceChildren(statusView("读取设置…"));
+            const inputs = this.#readInputs();
+            const apiURL = new URL(`/api/${encodeURIComponent(inputs.module)}`, inputs.url).href;
+            const styleURL = this.#resourceURL(inputs.css, inputs.url);
+            const [style, modelResponse] = await Promise.all([styleURL ? fetch(styleURL, { cache: "no-store", credentials: "omit" }) : null, fetch(apiURL, { cache: "no-store", credentials: "omit", headers: { Accept: "application/json", "X-PreferencePanes-JSON": inputs.json } })]);
+            if ((style && style.status !== 200) || modelResponse.status !== 200) throw new Error(`HTTP ${modelResponse.status !== 200 ? modelResponse.status : style.status}`);
+            this.#view = new PreferencesView(await modelResponse.json(), style ? await style.text() : "");
+        } catch (error) {
+            this.#root.replaceChildren(statusView(`加载失败：${error.message}`, () => this.start()));
+        }
     }
-    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.
-     * @returns {void} 已同步主题与键盘避让 / Theme and keyboard clearance synchronized.
+     * 释放页面视图和页面级监听器。
+     * Release the page view and page-level listener.
+     * @returns {void} 无返回值 / No return value.
      */
-    const syncAppearance = () => {
-        const theme = host?.dataset.theme ?? previousTheme ?? (systemTheme.matches ? "dark" : "light");
-        document.documentElement.dataset.theme = theme;
-        if (host) document.documentElement.style.setProperty("--pp-keyboard-height", 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"] });
+    destroy() {
+        this.#window.removeEventListener("pageshow", this.#show);
+        this.#view?.destroy();
+        this.#view = undefined;
     }
-    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;
+
+    /**
+     * 读取嵌入参数、文档元数据或当前 URL 输入。
+     * Read embedded parameters, document metadata, or current URL inputs.
+     * @returns {ReturnType<typeof pageInputs>} 页面输入 / Page inputs.
+     */
+    #readInputs() {
+        const context = this.#document.querySelector('meta[name="preference-panes-inputs"]');
+        const embedded = this.#window.frameElement?.dataset.preferencePanes;
+        switch (true) {
+            case embedded !== undefined:
+                this.#document.documentElement.dataset.preferencePanesEmbedded = "";
+                return JSON.parse(embedded);
+            case context !== null:
+                return JSON.parse(decodeURIComponent(context.content));
+            default:
+                return pageInputs(new URL(this.#window.location.href));
+        }
+    }
+
+    /**
+     * 将可选页面资源限制为 HTTP(S) 地址。
+     * Restrict an optional page resource to an HTTP(S) URL.
+     * @param {string | undefined} source 资源地址 / Resource location.
+     * @param {string} baseURL 页面基准地址 / Page base URL.
+     * @returns {string | null} 绝对资源地址 / Absolute resource URL.
+     */
+    #resourceURL(source, baseURL) {
+        if (!source) return null;
+        const url = new URL(source, baseURL);
+        if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("Resources must use HTTP(S) URLs");
+        return url.href;
     }
+
+    /**
+     * 从前进后退缓存恢复时重新加载模块。
+     * Reload the module when restored from the back-forward cache.
+     * @param {PageTransitionEvent} event 页面显示事件 / Page show event.
+     * @returns {void} 无返回值 / No return value.
+     */
+    #show = event => {
+        if (event.persisted) this.start();
+    };
 }
+
+new ModulePage(document).start();

package/src/browser/module.html

@@ -9,6 +9,6 @@
     </head>
     <body>
         <main id="preferences"></main>
-        <script type="module" src="/settings/assets/app.mjs?v=__VERSION__"></script>
+        <script type="module" src="/settings/assets/index.mjs?v=__VERSION__"></script>
     </body>
 </html>

package/src/browser/mount.mjs

@@ -0,0 +1,119 @@
+import { normalizeBoxJs, normalizeStoredValue, validValue } from "./boxjs.mjs";
+import { element, resourceURL } from "./components.mjs";
+import { PreferencesPanel } from "./panel.mjs";
+import { installDefaultStyles } from "./styles.mjs";
+
+/**
+ * 管理模块设置视图的模型规范化、样式、主题同步和面板生命周期。
+ * Manage model normalization, styles, theme synchronization, and panel lifecycle for a module settings view.
+ */
+export 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;
+        }
+    }
+
+    /**
+     * 跟随嵌入宿主的通用环境状态，不识别业务 App 或解析其 UA。
+     * Follow generic host appearance without detecting a business App or parsing its UA.
+     * @returns {void} 已同步主题与键盘避让 / Theme and keyboard clearance synchronized.
+     */
+    #syncAppearance = () => {
+        const theme = this.#host?.dataset.theme ?? this.#previousTheme ?? (this.#systemTheme.matches ? "dark" : "light");
+        document.documentElement.dataset.theme = theme;
+        if (this.#host) document.documentElement.style.setProperty("--pp-keyboard-height", this.#host.style.getPropertyValue("--pp-keyboard-height"));
+    };
+
+    /**
+     * 释放模块视图、样式与会话，不操作项目入口页。
+     * 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);
+    }
+}
+
+/**
+ * 使用模块 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.
+ */
+export function mount(model, css = "") {
+    return new PreferencesView(model, css);
+}