@nsnanocat/preference-panes 1.2.4 → 1.3.0

package/src/browser/client.mjs

@@ -14,6 +14,7 @@ export class PreferencesClient {
     #values = {};
     #warnings = {};
     #saving = false;
+    #arrays = new Map();
 
     /**
      * 创建从 BoxJS 定义读取和持久化设置的页面客户端。
@@ -40,13 +41,22 @@ export class PreferencesClient {
         if (!subtree || typeof subtree !== "object" || Array.isArray(subtree)) throw new TypeError("Expected a settings subtree object");
         const values = {};
         const warnings = {};
+        this.#arrays.clear();
         for (const field of this.#definition.fields) {
+            const indexed = /^(.*)\.(\d+)$/.exec(field.key);
+            if (indexed && !this.#arrays.has(indexed[1])) {
+                const storedArray = indexed[1]
+                    .split(".")
+                    .slice(this.#definition.settingsPath.length)
+                    .reduce((parent, part) => Object(parent)[part], subtree);
+                this.#arrays.set(indexed[1], Array.isArray(storedArray) ? [...storedArray] : []);
+            }
             const stored = field.key
                 .split(".")
                 .slice(this.#definition.settingsPath.length)
                 .reduce((parent, part) => Object(parent)[part], subtree);
             const resolved = resolveStoredValue(field, stored);
-            if (Object.hasOwn(resolved, "value")) values[field.key] = resolved.value;
+            if (Object.prototype.hasOwnProperty.call(resolved, "value")) values[field.key] = resolved.value;
             if (resolved.warning) warnings[field.key] = resolved.warning;
         }
         this.#values = values;
@@ -60,7 +70,7 @@ export class PreferencesClient {
      * @returns {import("./client.mjs").ModuleSnapshot} 会话快照 / Session snapshot.
      */
     snapshot() {
-        return structuredClone({ definition: this.#definition, values: this.#values, warnings: this.#warnings });
+        return JSON.parse(JSON.stringify({ definition: this.#definition, values: this.#values, warnings: this.#warnings }));
     }
 
     /**
@@ -79,22 +89,23 @@ export class PreferencesClient {
      * @returns {Promise<unknown>} Caches 内容或 undefined / Caches content or undefined.
      */
     async readCaches() {
-        const response = await this.#send("get", `@${this.#definition.storageKey}.${this.#module}.Caches`);
+        const response = await this.#send("get", this.#definition.cachePath ?? `@${this.#definition.storageKey}.${this.#module}.Caches`);
         return response.status === 404 ? undefined : response.json();
     }
 
     /**
-     * 删除当前模块的 Caches 子树。
-     * Delete the current module Caches subtree.
+     * 删除声明的缓存子树，默认当前模块 Caches。
+     * Delete the declared cache subtree, defaulting to the current module Caches.
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     clearCaches() {
-        return this.#change("delete", `${this.#module}.Caches`, undefined, "clearCaches");
+        const path = this.#definition.cachePath?.slice(this.#definition.storageKey.length + 2) ?? `${this.#module}.Caches`;
+        return this.#change("delete", path, undefined, "clearCaches");
     }
 
     /**
-     * 删除当前模块数据并恢复页面默认值。
-     * Delete current module data and restore page defaults.
+     * 删除声明的设置子树，默认删除当前模块数据，并恢复页面默认值。
+     * Delete declared settings subtrees, defaulting to current module data, and restore page defaults.
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     reset() {
@@ -175,30 +186,49 @@ export class PreferencesClient {
         if (this.#saving) throw new Error("A settings write is already in progress");
         this.#saving = true;
         try {
-            let field;
-            if (operation === "write" || operation === "delete") {
-                field = this.#definition.fields.find(candidate => candidate.key === key);
-                if (!field || (operation === "write" && !validValue(field, value))) throw new TypeError("Invalid setting value");
-            }
-            await this.#send(action, `@${this.#definition.storageKey}.${key}`, value);
             switch (operation) {
                 case "write":
-                    this.#values[key] = structuredClone(value);
-                    delete this.#warnings[key];
-                    break;
                 case "delete": {
-                    delete this.#values[key];
-                    delete this.#warnings[key];
-                    if (Object.hasOwn(field, "defaultValue")) this.#values[key] = structuredClone(field.defaultValue);
+                    const field = this.#definition.fields.find(candidate => candidate.key === key);
+                    if (!field || (operation === "write" && !validValue(field, value))) throw new TypeError("Invalid setting value");
+                    const indexed = /^(.*)\.(\d+)$/.exec(key);
+                    if (indexed) {
+                        const array = [...(this.#arrays.get(indexed[1]) ?? [])];
+                        for (const sibling of this.#definition.fields) {
+                            if (sibling.key.startsWith(`${indexed[1]}.`) && /^\d+$/.test(sibling.key.slice(indexed[1].length + 1))) {
+                                const index = Number(sibling.key.slice(indexed[1].length + 1));
+                                if (array[index] === undefined) array[index] = this.#values[sibling.key] ?? sibling.defaultValue;
+                            }
+                        }
+                        array[Number(indexed[2])] = operation === "delete" ? field.defaultValue : value;
+                        await this.#send("set", `@${this.#definition.storageKey}.${indexed[1]}`, array);
+                        this.#arrays.set(indexed[1], array);
+                    } else await this.#send(action, `@${this.#definition.storageKey}.${key}`, value);
+                    switch (operation) {
+                        case "write":
+                            this.#values[key] = JSON.parse(JSON.stringify(value));
+                            delete this.#warnings[key];
+                            break;
+                        case "delete":
+                            delete this.#values[key];
+                            delete this.#warnings[key];
+                            if (Object.prototype.hasOwnProperty.call(field, "defaultValue")) this.#values[key] = JSON.parse(JSON.stringify(field.defaultValue));
+                            break;
+                    }
                     break;
                 }
                 case "clearCaches":
+                    await this.#send(action, `@${this.#definition.storageKey}.${key}`, value);
                     break;
                 case "reset":
+                    if (this.#definition.resetPaths) {
+                        for (const path of this.#definition.resetPaths) await this.#send("delete", path);
+                    } else await this.#send(action, `@${this.#definition.storageKey}.${key}`, value);
+                    this.#arrays.clear();
                     this.#warnings = {};
                     for (const field of this.#definition.fields) {
                         delete this.#values[field.key];
-                        if (Object.hasOwn(field, "defaultValue")) this.#values[field.key] = structuredClone(field.defaultValue);
+                        if (Object.prototype.hasOwnProperty.call(field, "defaultValue")) this.#values[field.key] = JSON.parse(JSON.stringify(field.defaultValue));
                     }
                     break;
             }

package/src/browser/home.d.mts

@@ -0,0 +1,54 @@
+import type { ActionMenu, MenuAction, Notice } from "./Navigation.mjs";
+
+/** 宿主导航状态 / Bridge navigation state. */
+export interface HomeState {
+    /** 当前标题 / Current title. */
+    title: string;
+    /** 可用菜单操作 / Available menu actions. */
+    actions: MenuAction[];
+    /** 操作是否正在执行 / Whether an operation is in progress. */
+    busy: boolean;
+    /** 联合历史是否可返回 / Whether joint history can go back. */
+    canGoBack: boolean;
+}
+/** 宿主初始化输入 / Bridge initialization inputs. */
+export interface BridgeOptions {
+    /** 共用操作菜单 / Shared action menu. */
+    menu: ActionMenu;
+    /** 沿当前页面历史返回 / Go back through the current page history. */
+    back(): void;
+}
+/** 可选 Bridge 模块提供的宿主能力 / Host capabilities supplied by the optional Bridge module. */
+export interface Bridge {
+    /** 同步当前导航状态 / Synchronize current navigation state. */
+    update(state: HomeState): void | Promise<void>;
+    /** 返回确认或取消选择 / Return the confirmation or cancellation choice. */
+    confirm(message: string): boolean | Promise<boolean>;
+    /** 显示操作结果 / Display an operation result. */
+    notice(detail: Notice): void;
+    /** 打开完整地址；_blank 保留当前页面，_self 替换当前页面 / Open an absolute URL; _blank retains the current page and _self replaces it. */
+    openURL(url: string, target?: "_self" | "_blank"): void | Promise<void>;
+    /** 释放界面与监听器 / Release UI and listeners. */
+    destroy(): void;
+}
+/** 宿主工厂；默认导出 / Bridge factory; the override's default export. */
+export type BridgeFactory = (options: BridgeOptions) => Bridge | Promise<Bridge>;
+/**
+ * 初始化固定路径的 JSON 首页及可选 Bridge。
+ * Initialize the JSON homepage and optional Bridge at fixed paths.
+ * @returns 退出清理动作；失败显示错误并拒绝 / Cleanup action; failures display an error and reject.
+ */
+export function startHome(): Promise<() => void>;
+/** 首页入口图标 / Homepage entry icon. */
+export type HomeIcon = { src: string; text?: never } | { text: string; src?: never };
+/** 外链打开方式：带导航的内部框架、当前页面或新页面 / Link opening mode: an internal frame with navigation, the current page or a new page. */
+export type HomeLinkTarget = "internal" | "_self" | "_blank";
+/** 首页模块或链接入口 / Homepage module or link entry. */
+export type HomeItem = { name: string; icon: HomeIcon; description?: string } & ({ module: string; pageModule?: string; href?: never; target?: never } | { href: string; target?: HomeLinkTarget; module?: never; pageModule?: never });
+/** 运行时导入的首页配置 / Runtime-imported homepage configuration. */
+export interface HomeConfig {
+    title: string;
+    logo?: string;
+    sections: { title: string; layout?: "grid" | "list"; items: HomeItem[] }[];
+    footer?: string[];
+}

package/src/browser/home.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="zh-CN" class="pp-page">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+    <title>设置</title>
+  </head>
+  <body>
+    <div data-preference-panes-pages>
+      <main class="pp-home" data-preference-panes-home></main>
+    </div>
+    <template data-preference-panes-module><section data-preference-panes-module-page><p data-module-message>正在打开设置…</p></section></template>
+    <script type="module">__PREFERENCE_PANES_HOME_SCRIPT__
+await startHome();</script>
+  </body>
+</html>

package/src/browser/home.mjs

@@ -0,0 +1,441 @@
+import { ActionMenu, ModuleFrame, ModuleStatus, Navigation } from "./Navigation.mjs";
+import { installDefaultStyles } from "./styles.mjs";
+
+/**
+ * 校验外部 JSON 中的章节、入口和导航目标，避免生成不可访问的设置入口。
+ * Validate sections, entries and navigation targets in external JSON before rendering inaccessible entries.
+ * @param {unknown} config 外部首页配置 / External homepage configuration.
+ * @returns {void} 非法输入抛出错误 / Invalid input throws.
+ */
+function validateHome(config) {
+    if (!config || typeof config.title !== "string" || !Array.isArray(config.sections)) throw new Error("首页 JSON 缺少 title 或 sections");
+    if (config.logo !== undefined && typeof config.logo !== "string") throw new Error("首页 logo 必须是图片地址");
+    if (config.footer !== undefined && (!Array.isArray(config.footer) || config.footer.some(text => typeof text !== "string"))) throw new Error("首页 footer 必须是文字数组");
+    const modules = new Set();
+    for (const section of config.sections) {
+        if (!section || typeof section.title !== "string" || !Array.isArray(section.items) || (section.layout !== undefined && !["grid", "list"].includes(section.layout))) throw new Error("首页章节需要 title、items 和有效的 layout");
+        for (const item of section.items) {
+            if (!item || typeof item.name !== "string" || !item.icon || (typeof item.icon.src === "string") === (typeof item.icon.text === "string") || (item.icon.src !== undefined && typeof item.icon.src !== "string") || (item.icon.text !== undefined && typeof item.icon.text !== "string"))
+                throw new Error("首页入口需要 name 和唯一的图片或文字 icon");
+            if (item.description !== undefined && typeof item.description !== "string") throw new Error(`入口 ${item.name} 的 description 必须是文字`);
+            if (item.target !== undefined && (item.module !== undefined || !["internal", "_self", "_blank"].includes(item.target))) throw new Error(`入口 ${item.name} 的 target 只允许链接使用 internal、_self 或 _blank`);
+            if ((typeof item.module === "string") === (typeof item.href === "string") || (item.module !== undefined && typeof item.module !== "string") || (item.href !== undefined && typeof item.href !== "string")) throw new Error(`入口 ${item.name} 必须选择 module 或 href`);
+            if (item.module !== undefined) {
+                if (!/^[A-Za-z0-9_-]+$/.test(item.module) || (item.pageModule !== undefined && (typeof item.pageModule !== "string" || !/^[A-Za-z0-9_-]+$/.test(item.pageModule))) || modules.has(item.module)) throw new Error(`入口 ${item.name} 的模块名称无效或重复`);
+                modules.add(item.module);
+            } else {
+                const protocol = new URL(item.href, "https://preference-panes.invalid/").protocol;
+                if (item.pageModule !== undefined || ["javascript:", "data:", "vbscript:"].includes(protocol) || (item.target === "internal" && !["http:", "https:"].includes(protocol))) throw new Error(`入口 ${item.name} 的链接无效`);
+            }
+        }
+    }
+}
+
+/**
+ * 共用网格和列表章节；资源地址相对于 JSON，所有项目文字通过 textContent 绘制。
+ * Share grid and list sections, resolve resources against JSON and render project text through textContent.
+ * @param {import("./home.mjs").HomeConfig} config 已校验的首页配置 / Validated homepage configuration.
+ * @param {URL} url JSON 地址 / JSON URL.
+ * @param {HTMLElement} home 首页容器 / Homepage container.
+ * @returns {void} 无返回值 / No return value.
+ */
+function renderHome(config, url, home) {
+    const document = home.ownerDocument;
+    home.replaceChildren();
+    if (config.logo) {
+        const logo = document.createElement("img");
+        logo.className = "pp-home-logo";
+        logo.src = new URL(config.logo, url).href;
+        logo.alt = config.title;
+        home.append(logo);
+    }
+    for (const section of config.sections) {
+        const group = document.createElement("section");
+        group.className = "pp-group";
+        const title = document.createElement("h2");
+        title.className = "pp-group-title";
+        title.textContent = section.title;
+        const entries = document.createElement("div");
+        entries.className = "pp-home-entries";
+        entries.dataset.layout = section.layout ?? "grid";
+        for (const item of section.items) {
+            const entry = document.createElement(item.module ? "button" : "a");
+            entry.className = "pp-home-item";
+            if (item.module) {
+                entry.type = "button";
+                entry.disabled = true;
+                entry.dataset.module = item.module;
+                if (item.pageModule) entry.dataset.preferencePanesModule = item.pageModule;
+            } else {
+                entry.href = new URL(item.href, url).href;
+                if (item.target !== undefined) {
+                    entry.dataset.target = item.target;
+                    switch (item.target) {
+                        case "_blank":
+                            entry.target = item.target;
+                            entry.rel = "noopener noreferrer";
+                            break;
+                        case "_self":
+                            entry.target = item.target;
+                            break;
+                    }
+                }
+            }
+            const icon = document.createElement("span");
+            icon.className = "pp-home-icon";
+            icon.setAttribute("aria-hidden", "true");
+            if (item.icon.src !== undefined) {
+                const image = document.createElement("img");
+                image.src = new URL(item.icon.src, url).href;
+                image.alt = "";
+                icon.append(image);
+            } else icon.textContent = item.icon.text;
+            const content = document.createElement("span");
+            content.className = "pp-home-content";
+            const name = document.createElement("span");
+            name.className = "pp-home-name";
+            name.textContent = item.name;
+            content.append(name);
+            if (item.description !== undefined) {
+                const description = document.createElement("span");
+                description.className = "pp-description";
+                description.textContent = item.description;
+                content.append(description);
+            }
+            if (item.module) {
+                const status = document.createElement("span");
+                status.className = "pp-description";
+                status.dataset.moduleStatus = "";
+                status.textContent = "检测中";
+                content.append(status);
+            }
+            entry.append(icon, content);
+            if (entries.dataset.layout === "list") {
+                const arrow = document.createElement("span");
+                arrow.className = "pp-home-arrow";
+                arrow.textContent = "›";
+                arrow.setAttribute("aria-hidden", "true");
+                entry.append(arrow);
+            }
+            entries.append(entry);
+        }
+        group.append(title, entries);
+        home.append(group);
+    }
+    const footer = document.createElement("footer");
+    footer.className = "pp-home-footer pp-description";
+    for (const text of config.footer ?? []) {
+        const paragraph = document.createElement("p");
+        paragraph.textContent = text;
+        footer.append(paragraph);
+    }
+    home.append(footer);
+}
+
+/**
+ * 浏览器宿主提供网页导航、通知、主题和可视区域避让。
+ * The browser host provides web navigation, notices, theme and viewport clearance.
+ * @param {import("./home.mjs").BridgeOptions} options 菜单和返回动作 / Menu and back action.
+ * @returns {import("./home.mjs").Bridge} 浏览器宿主 / Browser host.
+ */
+function browserHost({ menu, back }) {
+    const root = document.documentElement;
+    const header = document.createElement("header");
+    header.className = "pp-host-header";
+    const button = document.createElement("button");
+    button.className = "pp-host-back";
+    button.type = "button";
+    button.textContent = "‹";
+    button.setAttribute("aria-label", "返回");
+    button.onclick = back;
+    const title = document.createElement("span");
+    title.className = "pp-host-title";
+    header.append(button, title, menu.element);
+    document.body.prepend(header);
+    const toast = document.createElement("div");
+    toast.className = "pp-host-toast";
+    toast.setAttribute("role", "status");
+    toast.hidden = true;
+    document.body.append(toast);
+    let timer;
+    const theme = window.matchMedia("(prefers-color-scheme: dark)");
+    const applyTheme = () => {
+        root.dataset.theme = theme.matches ? "dark" : "light";
+    };
+    const viewport = window.visualViewport;
+    const resize = () => {
+        root.style.setProperty("--pp-host-height", `${header.getBoundingClientRect().height}px`);
+        const clearance = viewport && viewport.scale === 1 ? Math.max(0, window.innerHeight - viewport.height - viewport.offsetTop) : 0;
+        root.style.setProperty("--pp-keyboard-height", `${clearance}px`);
+    };
+    theme.addEventListener("change", applyTheme);
+    window.addEventListener("resize", resize);
+    window.addEventListener("pageshow", resize);
+    viewport?.addEventListener("resize", resize);
+    viewport?.addEventListener("scroll", resize);
+    applyTheme();
+    resize();
+    return {
+        update(state) {
+            title.textContent = state.title;
+            button.hidden = !state.canGoBack;
+            menu.element.hidden = !state.actions.length;
+        },
+        confirm: message => window.confirm(message),
+        notice(detail) {
+            clearTimeout(timer);
+            toast.textContent = detail.message;
+            toast.hidden = false;
+            timer = setTimeout(() => {
+                toast.hidden = true;
+            }, 2400);
+        },
+        openURL(url, target) {
+            switch (target) {
+                case "_blank":
+                    window.open(url, "_blank", "noopener,noreferrer");
+                    break;
+                default:
+                    window.location.assign(url);
+                    break;
+            }
+        },
+        destroy() {
+            clearTimeout(timer);
+            theme.removeEventListener("change", applyTheme);
+            window.removeEventListener("resize", resize);
+            window.removeEventListener("pageshow", resize);
+            viewport?.removeEventListener("resize", resize);
+            viewport?.removeEventListener("scroll", resize);
+            root.style.removeProperty("--pp-host-height");
+            root.style.removeProperty("--pp-keyboard-height");
+            delete root.dataset.theme;
+            header.remove();
+            toast.remove();
+        },
+    };
+}
+
+/**
+ * 读取固定相对路径的首页 JSON 与可选 CSS、Bridge，初始化后共用模块探测与导航。
+ * Load homepage JSON and optional CSS and Bridge at fixed relative paths, then share module probes and navigation.
+ * @returns {Promise<() => void>} 退出清理动作；加载失败会显示错误并拒绝 / Cleanup action; load failures display an error and reject.
+ */
+export async function startHome() {
+    let host;
+    let menu;
+    let navigation;
+    let frame;
+    let linkTitle;
+    let statuses = [];
+    let destroyed = false;
+    let defaults;
+    let stylesheet;
+    const controller = new AbortController();
+    const destroy = () => {
+        if (destroyed) return;
+        destroyed = true;
+        controller.abort();
+        for (const { status } of statuses) status.destroy();
+        navigation?.destroy();
+        host?.destroy();
+        menu?.destroy();
+        stylesheet?.remove();
+        if (defaults?.owned) defaults.element.remove();
+        window.removeEventListener("pagehide", pagehide);
+    };
+    const pagehide = event => {
+        if (!event.persisted) destroy();
+    };
+    window.addEventListener("pagehide", pagehide);
+    try {
+        defaults = installDefaultStyles(document);
+        const jsonURL = new URL("./home.json", document.baseURI);
+        const response = await fetch(jsonURL, { signal: controller.signal });
+        if (!response.ok) throw new Error(`首页 JSON 加载失败：HTTP ${response.status}`);
+        const config = await response.json();
+        validateHome(config);
+        if (destroyed) return destroy;
+        const cssURL = new URL("./theme.css", document.baseURI);
+        const cssResponse = await fetch(cssURL, { method: "HEAD", cache: "no-store", signal: controller.signal });
+        if (destroyed) return destroy;
+        switch (cssResponse.status) {
+            case 200:
+                stylesheet = document.createElement("link");
+                stylesheet.rel = "stylesheet";
+                stylesheet.dataset.preferencePanesStylesheet = "";
+                stylesheet.href = cssURL.href;
+                await new Promise((resolve, reject) => {
+                    const abort = () => reject(new DOMException("页面已退出", "AbortError"));
+                    controller.signal.addEventListener("abort", abort, { once: true });
+                    stylesheet.onload = () => {
+                        controller.signal.removeEventListener("abort", abort);
+                        resolve();
+                    };
+                    stylesheet.onerror = () => {
+                        controller.signal.removeEventListener("abort", abort);
+                        reject(new Error("项目 CSS 加载失败"));
+                    };
+                    document.head.append(stylesheet);
+                });
+                break;
+            case 404:
+                break;
+            default:
+                throw new Error(`项目 CSS 探测失败：HTTP ${cssResponse.status}`);
+        }
+        if (destroyed) return destroy;
+        const bridgeURL = new URL("./bridge.mjs", document.baseURI);
+        const bridgeResponse = await fetch(bridgeURL, { method: "HEAD", cache: "no-store", signal: controller.signal });
+        if (destroyed) return destroy;
+        let factory;
+        switch (bridgeResponse.status) {
+            case 200:
+                factory = (await import(bridgeURL.href)).default;
+                break;
+            case 404:
+                factory = browserHost;
+                break;
+            default:
+                throw new Error(`Bridge 探测失败：HTTP ${bridgeResponse.status}`);
+        }
+        if (destroyed) return destroy;
+        document.title = config.title;
+        menu = new ActionMenu(id => frame.perform(id));
+        host = await factory({ menu, back: () => (navigation.current && frame ? frame.back() : navigation.back()) });
+        if (destroyed) {
+            host.destroy();
+            menu.destroy();
+            return destroy;
+        }
+        const container = document.querySelector("[data-preference-panes-pages]");
+        const home = document.querySelector("[data-preference-panes-home]");
+        const template = document.querySelector("template[data-preference-panes-module]");
+        renderHome(config, jsonURL, home);
+        const buttons = [...home.querySelectorAll("[data-module]")];
+        const links = [...home.querySelectorAll("a[href]")];
+        const stylesheetURL = stylesheet?.href;
+        const update = () => {
+            if (destroyed) return;
+            const state = navigation.current && frame ? frame.state : { title: navigation.current ? linkTitle : document.title, actions: [], busy: false, canGoBack: navigation.canGoBack };
+            menu.update(state.actions, state.busy);
+            Promise.resolve(host.update(state)).catch(error => {
+                if (!destroyed) host.notice({ kind: "error", message: error.message });
+            });
+        };
+        navigation = new Navigation(container, home, (module, signal) => {
+            frame = undefined;
+            const link = links.find((link, index) => link.dataset.target === "internal" && module === `link:${index}`);
+            if (link) {
+                const page = document.createElement("section");
+                page.dataset.preferencePanesLinkPage = "";
+                const iframe = document.createElement("iframe");
+                linkTitle = link.querySelector(".pp-home-name").textContent;
+                iframe.title = linkTitle;
+                iframe.setAttribute("sandbox", "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox");
+                iframe.src = link.href;
+                page.append(iframe);
+                signal.addEventListener("abort", () => iframe.remove(), { once: true });
+                return page;
+            }
+            const button = buttons.find(button => button.dataset.module === module);
+            if (!button) return;
+            const page = template.content.firstElementChild.cloneNode(true);
+            page.dataset.preferencePanesModulePage = "";
+            const message = page.querySelector("[data-module-message]");
+            const moduleName = encodeURIComponent(button.dataset.preferencePanesModule ?? module);
+            const current = new ModuleFrame(`/settings/${moduleName}`, {
+                signal,
+                headers: { "X-PreferencePanes-JSON": `/api/${encodeURIComponent(module)}`, ...(stylesheetURL ? { "X-PreferencePanes-CSS": stylesheetURL } : {}) },
+            });
+            frame = current;
+            current.addEventListener("confirm", event => {
+                event.preventDefault();
+                Promise.resolve()
+                    .then(() => host.confirm(event.detail.message))
+                    .then(
+                        value => {
+                            if (!signal.aborted) event.detail.resolve(value);
+                        },
+                        error => {
+                            if (!signal.aborted) event.detail.reject(error);
+                        },
+                    );
+            });
+            current.addEventListener("notice", event => {
+                event.preventDefault();
+                host.notice(event.detail);
+            });
+            current.addEventListener("open-url", event => {
+                event.preventDefault();
+                Promise.resolve()
+                    .then(() => host.openURL(event.detail.url))
+                    .catch(error => {
+                        if (!signal.aborted) host.notice({ kind: "error", message: error.message });
+                    });
+            });
+            current.addEventListener("change", () => {
+                if (!signal.aborted) update();
+            });
+            current.element.onload = () => {
+                if (!signal.aborted) message.hidden = true;
+            };
+            page.append(current.element);
+            current.load().catch(error => {
+                if (!signal.aborted) message.textContent = error.message;
+            });
+            return page;
+        });
+        for (const [index, link] of links.entries()) {
+            link.addEventListener(
+                "click",
+                event => {
+                    if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+                    event.preventDefault();
+                    switch (link.dataset.target) {
+                        case "internal":
+                            navigation.open(`link:${index}`);
+                            break;
+                        default:
+                            try {
+                                Promise.resolve(host.openURL(link.href, link.dataset.target)).catch(error => {
+                                    if (!destroyed) host.notice({ kind: "error", message: error.message });
+                                });
+                            } catch (error) {
+                                if (!destroyed) host.notice({ kind: "error", message: error.message });
+                            }
+                            break;
+                    }
+                },
+                { signal: controller.signal },
+            );
+        }
+        statuses = buttons.map(button => {
+            const status = new ModuleStatus(button.querySelector("[data-module-status]"));
+            status.addEventListener("change", () => {
+                button.disabled = status.state.status !== "installed";
+            });
+            button.addEventListener("click", () => navigation.open(button.dataset.module), { signal: controller.signal });
+            return { button, status };
+        });
+        const probe = () => {
+            update();
+            if (navigation.current) return;
+            for (const { button, status } of statuses) status.check(`/api/${encodeURIComponent(button.dataset.module)}`);
+        };
+        navigation.addEventListener("change", probe);
+        probe();
+        return destroy;
+    } catch (error) {
+        const display = !destroyed;
+        destroy();
+        if (display) {
+            const message = document.createElement("p");
+            message.className = "pp-host-error";
+            message.setAttribute("role", "alert");
+            message.textContent = `无法打开设置：${error.message}`;
+            document.body.prepend(message);
+        }
+        throw error;
+    }
+}

package/src/browser/index.d.ts

@@ -15,3 +15,5 @@ export interface MountedPreferences {
  * @returns 模块视图 / Module view.
  */
 export function mount(boxjs: BoxJSInput): MountedPreferences;
+
+export type { HomeConfig, HomeIcon, HomeItem, HomeLinkTarget, HomeState, Bridge, BridgeOptions, BridgeFactory } from "./home.mjs";