@nsnanocat/preference-panes 0.7.2 → 0.8.1

package/dist/module/navigation.mjs

@@ -1,3 +1,119 @@
+/**
+ * 标题栏共用三点菜单；Shadow DOM 隔离项目样式，保留继承的主题色。
+ * Shared title-bar overflow menu; Shadow DOM isolates layout while inheriting theme colors.
+ */
+class ActionMenu {
+    #button;
+    #popup;
+    #backdrop;
+    #select;
+    #document;
+    #key = event => {
+        if (event.key === "Escape" && !this.#popup.hidden) {
+            event.preventDefault();
+            this.close();
+            this.#button.focus();
+        }
+    };
+
+    /**
+     * 创建菜单，操作逻辑由调用方提供。
+     * Create a menu whose actions are handled by the caller.
+     * @param {(id: string) => void} select 菜单选择回调 / Selection callback.
+     */
+    constructor(select) {
+        this.#document = document;
+        this.#select = select;
+        this.element = document.createElement("span");
+        const root = this.element.attachShadow({ mode: "open" });
+        root.innerHTML = `<style>
+          :host{display:inline-flex;position:relative;width:44px;height:44px;color:inherit}
+          :host([hidden]),[hidden]{display:none!important}
+          button{font:inherit;cursor:pointer;border:0;color:inherit;background:none}
+          button:disabled{opacity:.4;cursor:default}
+          button:focus-visible{outline:2px solid currentColor;outline-offset:-3px}
+          #trigger{width:44px;height:44px;padding:10px;position:relative;z-index:3}
+          svg{display:block;width:24px;height:24px;fill:currentColor}
+          #backdrop{position:fixed;inset:0;z-index:1}
+          #items{position:absolute;right:0;top:46px;z-index:2;min-width:160px;padding:6px;background:var(--pp-surface,Canvas);color:var(--pp-text,CanvasText);border:1px solid var(--pp-border,#8884);border-radius:12px;box-shadow:0 8px 28px #0003}
+          #items button{display:block;text-align:left;white-space:nowrap;width:100%;padding:11px 14px;border-radius:8px;font:14px/1.4 system-ui,sans-serif}
+          #items button:hover{background:#8882}
+          #items button[data-danger]{color:#e45656}
+        </style><button id="trigger" type="button" aria-label="更多操作" aria-haspopup="menu" aria-expanded="false" aria-controls="items"><svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="4" cy="12" r="2"/><circle cx="12" cy="12" r="2"/><circle cx="20" cy="12" r="2"/></svg></button><button id="backdrop" type="button" tabindex="-1" aria-label="关闭菜单" hidden></button><div id="items" role="menu" hidden></div>`;
+        this.#button = root.querySelector("#trigger");
+        this.#popup = root.querySelector("#items");
+        this.#backdrop = root.querySelector("#backdrop");
+        this.#button.onclick = () => {
+            const open = this.#popup.hidden;
+            this.#popup.hidden = this.#backdrop.hidden = !open;
+            this.#button.setAttribute("aria-expanded", String(open));
+            if (open) this.#popup.firstElementChild.focus();
+        };
+        this.#backdrop.onclick = () => this.close();
+        this.#popup.onkeydown = event => {
+            if (event.key === "Tab") {
+                this.close();
+                return;
+            }
+            const items = [...this.#popup.children];
+            const index = items.indexOf(root.activeElement);
+            const offsets = { ArrowDown: 1, ArrowUp: -1 };
+            if (event.key in offsets) {
+                event.preventDefault();
+                items[(index + offsets[event.key] + items.length) % items.length].focus();
+            }
+        };
+        document.addEventListener("keydown", this.#key);
+        this.update([]);
+    }
+
+    /**
+     * 同步可用操作和忙碌状态，不重建菜单触发按钮。
+     * Update actions and busy state without replacing the trigger button.
+     * @param {Array<{id: string, label: string, destructive?: boolean}>} items 操作列表 / Actions.
+     * @param {boolean} [disabled] 是否忙碌 / Whether operations are busy.
+     * @returns {void} 无返回值 / No return value.
+     */
+    update(items, disabled = false) {
+        this.close();
+        this.#button.disabled = disabled || items.length === 0;
+        this.#popup.replaceChildren(
+            ...items.map(item => {
+                const button = this.#document.createElement("button");
+                button.type = "button";
+                button.setAttribute("role", "menuitem");
+                button.textContent = item.label;
+                button.toggleAttribute("data-danger", Boolean(item.destructive));
+                button.onclick = () => {
+                    this.close();
+                    this.#select(item.id);
+                };
+                return button;
+            }),
+        );
+    }
+
+    /**
+     * 关闭菜单。
+     * Close the menu.
+     * @returns {void} 无返回值 / No return value.
+     */
+    close() {
+        this.#popup.hidden = this.#backdrop.hidden = true;
+        this.#button.setAttribute("aria-expanded", "false");
+    }
+
+    /**
+     * 移除监听器与节点。
+     * Remove listeners and elements.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#document.removeEventListener("keydown", this.#key);
+        this.element.remove();
+    }
+}
+
 /**
  * 统一解析模块页的资源地址：Header 优先于查询参数，再使用模块约定。
  * Resolve module resource locations: headers override query parameters and module conventions.
@@ -11,7 +127,7 @@ function pageInputs(url, headers = {}) {
     const module = match[1];
     const values = Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
     const json = values["x-preferencepanes-json"] ?? url.searchParams.get("json") ?? `/configs/${module}`;
-    const css = values["x-preferencepanes-css"] ?? url.searchParams.get("css") ?? `/settings/assets/${module}.css`;
+    const css = values["x-preferencepanes-css"] ?? url.searchParams.get("css") ?? "";
     if (!json.trim()) throw new TypeError("JSON resource URL is required");
     return { url: url.href, module, json, css };
 }
@@ -27,7 +143,7 @@ class ModuleFrame extends EventTarget {
     #abort = () => this.destroy();
     #state;
     #change = event => {
-        this.#state = event.detail;
+        this.#state = { ...event.detail, actions: event.detail.actions ?? [] };
         this.dispatchEvent(new Event("change"));
     };
 
@@ -46,7 +162,7 @@ class ModuleFrame extends EventTarget {
         this.element.title = `${inputs.module} 设置`;
         this.element.dataset.preferencePanes = JSON.stringify(inputs);
         this.element.addEventListener("preferencepanes:change", this.#change);
-        this.#state = { title: inputs.module, module: inputs.module, busy: false, canGoBack: true };
+        this.#state = { title: inputs.module, module: inputs.module, busy: false, canGoBack: true, actions: [] };
         options.signal?.addEventListener("abort", this.#abort, { once: true });
     }
 
@@ -86,6 +202,17 @@ class ModuleFrame extends EventTarget {
         if (!this.#state.busy && this.#state.canGoBack) this.element.contentWindow.history.back();
     }
 
+    /**
+     * 向模块发送菜单操作，不让宿主访问内部 DOM 或存储客户端。
+     * Dispatch a menu action without host access to internal DOM or the storage client.
+     * @param {string} id 当前可用操作 / Available action identifier.
+     * @returns {void} 无返回值 / No return value.
+     */
+    perform(id) {
+        if (this.#state.busy || !this.#state.actions.some(action => action.id === id)) throw new Error("Action is not available");
+        this.element.dispatchEvent(new CustomEvent("preferencepanes:action", { detail: id }));
+    }
+
     /**
      * 取消加载与事件订阅；节点保留到 Navigation 的退出动画结束。
      * Cancel loading and subscriptions; Navigation retains the node until its exit animation ends.
@@ -98,6 +225,93 @@ class ModuleFrame extends EventTarget {
     }
 }
 
+/**
+ * 模块入口的固定状态行，只通过 HEAD 探测安装状态和业务版本。
+ * Fixed module status row, probing installation and business version with HEAD only.
+ */
+class ModuleStatus extends EventTarget {
+    #element;
+    #controller;
+    #state = { status: "checking", version: null };
+
+    /**
+     * 绑定调用方提供的状态行。
+     * Bind a caller-owned status row.
+     * @param {HTMLElement} element 状态文字容器 / Status text container.
+     */
+    constructor(element) {
+        super();
+        this.#element = element;
+        this.#render("checking");
+    }
+
+    /**
+     * 当前安装状态与业务版本。
+     * Current installation state and business version.
+     */
+    get state() {
+        return { ...this.#state };
+    }
+
+    /**
+     * 每次进入重新探测，取消旧请求并忽略其迟到结果。
+     * Reprobe on entry, cancelling old requests and ignoring late results.
+     * @param {string | URL} url 配置 Mock 地址 / Configuration Mock URL.
+     * @returns {Promise<void>} 探测完成 / Probe completion.
+     */
+    async check(url) {
+        this.#controller?.abort();
+        const controller = (this.#controller = new AbortController());
+        this.#render("checking");
+        const timer = setTimeout(() => controller.abort(), 3500);
+        try {
+            const response = await fetch(url, { method: "HEAD", cache: "no-store", credentials: "omit", signal: controller.signal });
+            if (controller !== this.#controller) return;
+            const version = response.headers.get("X-PreferencePanes-Version")?.trim() || null;
+            this.#render(response.status === 200 ? "installed" : "missing", version);
+        } catch {
+            if (controller === this.#controller) this.#render("missing");
+        } finally {
+            clearTimeout(timer);
+        }
+    }
+
+    /**
+     * 更新状态标签，缺少版本时不伪造版本号。
+     * Render the label without inventing a missing version.
+     * @param {"checking" | "installed" | "missing"} status 状态 / State.
+     * @param {string | null} [version] 业务版本 / Business version.
+     * @returns {void} 无返回值 / No return value.
+     */
+    #render(status, version = null) {
+        this.#state = { status, version: status === "installed" ? version : null };
+        switch (status) {
+            case "checking":
+                this.#element.textContent = "检测中";
+                break;
+            case "installed":
+                this.#element.textContent = version ?? "版本未知";
+                break;
+            case "missing":
+                this.#element.textContent = "未安装";
+                break;
+        }
+        this.#element.dataset.state = status;
+        this.#element.title = this.#element.textContent;
+        this.dispatchEvent(new Event("change"));
+    }
+
+    /**
+     * 释放尚未完成的探测。
+     * Release pending probes.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#controller?.abort();
+        this.#controller = undefined;
+    }
+}
+
 /**
  * 同一文档内的主页/子页导航；iframe 各自的实例通过浏览器联合历史协作。
  * Navigate home/detail views within a document; iframe instances cooperate through joint browser history.
@@ -257,4 +471,4 @@ class Navigation extends EventTarget {
     }
 }
 
-export { ModuleFrame, Navigation };
+export { ActionMenu, ModuleFrame, ModuleStatus, Navigation };

package/dist/preference-panes.mjs

@@ -1,12 +1,4 @@
-var defaults = "/* 分组列表沿用 Bilibili 设置页的行结构，样式限定在面板内。\n * Grouped rows follow the Bilibili settings layout, scoped to the panel. */\n.pp-panel {\n    --pp-text: #18191c;\n    --pp-background: #f6f7f8;\n    --pp-surface: #fff;\n    --pp-border: #e3e5e7;\n    --pp-muted: #9499a0;\n    --pp-accent: #fb7299;\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    min-height: 100vh;\n}\n.pp-panel * {\n    box-sizing: border-box;\n    letter-spacing: 0;\n}\n.pp-header {\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: sticky;\n    top: 0;\n    z-index: 1;\n}\n.pp-title {\n    font-size: 17px;\n    font-weight: 500;\n    margin: 0;\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n.pp-brand {\n    flex: 1;\n    min-width: 0;\n    display: flex;\n    align-items: center;\n    justify-content: center;\n    gap: 8px;\n    text-align: center;\n}\n.pp-brand-icon {\n    display: none;\n    flex: none;\n    width: 28px;\n    height: 28px;\n}\n.pp-brand-icon:not(:empty) {\n    display: block;\n}\n.pp-brand-icon img {\n    display: block;\n    width: 100%;\n    height: 100%;\n    object-fit: contain;\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    height: calc(100vh - 52px - env(safe-area-inset-top));\n    overflow: hidden;\n}\n:root[data-preference-panes-embedded] .pp-header {\n    display: none;\n}\n:root[data-preference-panes-embedded] .pp-viewport {\n    height: 100vh;\n}\n@supports (height: 100dvh) {\n    .pp-viewport {\n        height: calc(100dvh - 52px - env(safe-area-inset-top));\n    }\n    :root[data-preference-panes-embedded] .pp-viewport {\n        height: 100dvh;\n    }\n}\n.pp-fields,\n.pp-choice-page {\n    position: absolute;\n    inset: 0;\n    overflow: auto;\n    padding: 12px max(16px, calc((100% - 688px) / 2)) calc(28px + env(safe-area-inset-bottom));\n    background: var(--pp-background);\n}\n.pp-panel .form-group {\n    margin: 0 0 12px;\n}\n.pp-panel .form-group__title {\n    font-size: 12px;\n    line-height: 17px;\n    font-weight: 400;\n    color: var(--pp-muted);\n    padding-left: 12px;\n    margin: 12px 0 6px;\n}\n.pp-panel .form-group__row {\n    border-radius: 8px;\n    overflow: hidden;\n    background: var(--pp-surface);\n}\n.pp-panel .form-row {\n    position: relative;\n    display: flex;\n    align-items: center;\n    width: 100%;\n    min-height: 46px;\n    padding: 12px;\n    border: 0;\n    border-bottom: 1px solid var(--pp-border);\n    background: var(--pp-surface);\n    gap: 12px;\n}\n.pp-panel .form-row:last-child {\n    border-bottom: 0;\n}\n.pp-panel .form-row__text {\n    flex: 1;\n    min-width: 0;\n    margin: 0;\n    display: flex;\n    flex-direction: column;\n}\n.pp-panel .form-row__title {\n    font-size: 15px;\n    line-height: 22px;\n    color: var(--pp-text);\n    text-align: left;\n}\n.pp-panel .form-row__subtitle {\n    font-size: 12px;\n    line-height: 18px;\n    color: var(--pp-muted);\n    overflow-wrap: anywhere;\n    margin-top: 2px;\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-input {\n    font: inherit;\n    color: var(--pp-text);\n    background: var(--pp-surface);\n    border: 1px solid var(--pp-border);\n    border-radius: 6px;\n    padding: 8px;\n    min-width: 0;\n    max-width: 45%;\n    width: 45%;\n}\nselect.pp-input {\n    text-overflow: ellipsis;\n    font-size: 13px;\n}\n.pp-panel .pp-multiline {\n    display: block;\n}\n.pp-multiline .pp-input {\n    max-width: 100%;\n    width: 100%;\n    margin-top: 10px;\n}\n.pp-switch {\n    appearance: none;\n    -webkit-appearance: none;\n    position: relative;\n    flex: none;\n    width: 32px;\n    height: 20px;\n    max-width: none;\n    border: 0;\n    border-radius: 15px;\n    padding: 0;\n    background: #c9ccd0;\n    cursor: pointer;\n    transition: background 0.2s;\n}\n.pp-switch::before {\n    content: \"\";\n    position: absolute;\n    top: 3px;\n    left: 3px;\n    width: 14px;\n    height: 14px;\n    border-radius: 50%;\n    background: white;\n    transition: transform 0.2s;\n}\n.pp-switch:checked {\n    background: var(--pp-accent);\n}\n.pp-switch:checked::before {\n    transform: translateX(12px);\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-icon {\n    width: 48px;\n    height: 48px;\n    object-fit: contain;\n    flex: none;\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-maintenance {\n    margin-top: 24px;\n}\n.pp-actions {\n    display: flex;\n    flex-wrap: wrap;\n    gap: 8px;\n}\n.pp-actions button,\n.pp-error button {\n    min-height: 44px;\n    padding: 8px 12px;\n    border-radius: 6px;\n    background: var(--pp-surface);\n}\n.pp-panel .pp-danger {\n    color: #e45656;\n}\n.pp-cache {\n    max-height: 320px;\n    overflow: auto;\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@media (prefers-color-scheme: dark) {\n    .pp-panel {\n        --pp-text: #e3e5e7;\n        --pp-background: #17181a;\n        --pp-surface: #232427;\n        --pp-border: #343538;\n    }\n}\n:root[data-theme=\"dark\"] .pp-panel {\n    --pp-text: #e3e5e7;\n    --pp-background: #17181a;\n    --pp-surface: #232427;\n    --pp-border: #343538;\n}\n:root[data-theme=\"light\"] .pp-panel {\n    --pp-text: #18191c;\n    --pp-background: #f6f7f8;\n    --pp-surface: #fff;\n    --pp-border: #e3e5e7;\n}\n@media (prefers-reduced-motion: reduce) {\n    .pp-panel .pp-switch,\n    .pp-panel .pp-switch::before {\n        transition: none;\n    }\n}\n";
-
-/**
- * 解析已经取得的 pathname，避免重复构造 URL。
- * Parse an existing pathname without constructing another URL.
- * @param {string} pathname 以 / 开头的 URL pathname / URL pathname beginning with /.
- * @returns {string[] | undefined} 解码后的路径，非 API 路径不处理 / Decoded path, or undefined outside /api/.
- * @throws {TypeError} 转义编码或路径片段非法 / Invalid percent encoding or path segments.
- */
+var defaults = "/* 分组列表沿用 Bilibili 设置页的行结构，样式限定在面板内。\n * Grouped rows follow the Bilibili settings layout, scoped to the panel. */\n.pp-panel {\n    --pp-text: #18191c;\n    --pp-background: #f6f7f8;\n    --pp-surface: #fff;\n    --pp-border: #e3e5e7;\n    --pp-muted: #9499a0;\n    --pp-accent: #fb7299;\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    min-height: 100vh;\n}\n.pp-panel * {\n    box-sizing: border-box;\n    letter-spacing: 0;\n}\n.pp-header {\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: sticky;\n    top: 0;\n    z-index: 1;\n}\n.pp-title {\n    font-size: 17px;\n    font-weight: 500;\n    margin: 0;\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n.pp-brand {\n    flex: 1;\n    min-width: 0;\n    display: flex;\n    align-items: center;\n    justify-content: center;\n    gap: 8px;\n    text-align: center;\n}\n.pp-brand-icon {\n    display: none;\n    flex: none;\n    width: 28px;\n    height: 28px;\n}\n.pp-brand-icon:not(:empty) {\n    display: block;\n}\n.pp-brand-icon img {\n    display: block;\n    width: 100%;\n    height: 100%;\n    object-fit: contain;\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    height: calc(100vh - 52px - env(safe-area-inset-top));\n    overflow: hidden;\n}\n:root[data-preference-panes-embedded] .pp-header {\n    display: none;\n}\n:root[data-preference-panes-embedded] .pp-viewport {\n    height: 100vh;\n}\n@supports (height: 100dvh) {\n    .pp-viewport {\n        height: calc(100dvh - 52px - env(safe-area-inset-top));\n    }\n    :root[data-preference-panes-embedded] .pp-viewport {\n        height: 100dvh;\n    }\n}\n.pp-fields,\n.pp-choice-page,\n.pp-cache-page {\n    position: absolute;\n    inset: 0;\n    overflow: auto;\n    padding: 12px max(16px, calc((100% - 688px) / 2)) calc(28px + env(safe-area-inset-bottom));\n    background: var(--pp-background);\n}\n.pp-panel .form-group {\n    margin: 0 0 12px;\n}\n.pp-panel .form-group__title {\n    font-size: 12px;\n    line-height: 17px;\n    font-weight: 400;\n    color: var(--pp-muted);\n    padding-left: 12px;\n    margin: 12px 0 6px;\n}\n.pp-panel .form-group__row {\n    border-radius: 8px;\n    overflow: hidden;\n    background: var(--pp-surface);\n}\n.pp-panel .form-row {\n    position: relative;\n    display: flex;\n    align-items: center;\n    width: 100%;\n    min-height: 46px;\n    padding: 12px;\n    border: 0;\n    border-bottom: 1px solid var(--pp-border);\n    background: var(--pp-surface);\n    gap: 12px;\n}\n.pp-panel .form-row:last-child {\n    border-bottom: 0;\n}\n.pp-panel .form-row__text {\n    flex: 1;\n    min-width: 0;\n    margin: 0;\n    display: flex;\n    flex-direction: column;\n}\n.pp-panel .form-row__title {\n    font-size: 15px;\n    line-height: 22px;\n    color: var(--pp-text);\n    text-align: left;\n}\n.pp-panel .form-row__subtitle {\n    font-size: 12px;\n    line-height: 18px;\n    color: var(--pp-muted);\n    overflow-wrap: anywhere;\n    margin-top: 2px;\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-input {\n    font: inherit;\n    color: var(--pp-text);\n    background: var(--pp-surface);\n    border: 1px solid var(--pp-border);\n    border-radius: 6px;\n    padding: 8px;\n    min-width: 0;\n    max-width: 45%;\n    width: 45%;\n}\nselect.pp-input {\n    text-overflow: ellipsis;\n    font-size: 13px;\n}\n.pp-panel .pp-multiline {\n    display: block;\n}\n.pp-multiline .pp-input {\n    max-width: 100%;\n    width: 100%;\n    margin-top: 10px;\n}\n.pp-switch {\n    appearance: none;\n    -webkit-appearance: none;\n    position: relative;\n    flex: none;\n    width: 32px;\n    height: 20px;\n    max-width: none;\n    border: 0;\n    border-radius: 15px;\n    padding: 0;\n    background: #c9ccd0;\n    cursor: pointer;\n    transition: background 0.2s;\n}\n.pp-switch::before {\n    content: \"\";\n    position: absolute;\n    top: 3px;\n    left: 3px;\n    width: 14px;\n    height: 14px;\n    border-radius: 50%;\n    background: white;\n    transition: transform 0.2s;\n}\n.pp-switch:checked {\n    background: var(--pp-accent);\n}\n.pp-switch:checked::before {\n    transform: translateX(12px);\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-icon {\n    width: 48px;\n    height: 48px;\n    object-fit: contain;\n    flex: none;\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-error button {\n    min-height: 44px;\n    padding: 8px 12px;\n    border-radius: 6px;\n    background: var(--pp-surface);\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@media (prefers-color-scheme: dark) {\n    .pp-panel {\n        --pp-text: #e3e5e7;\n        --pp-background: #17181a;\n        --pp-surface: #232427;\n        --pp-border: #343538;\n    }\n}\n:root[data-theme=\"dark\"] .pp-panel {\n    --pp-text: #e3e5e7;\n    --pp-background: #17181a;\n    --pp-surface: #232427;\n    --pp-border: #343538;\n}\n:root[data-theme=\"light\"] .pp-panel {\n    --pp-text: #18191c;\n    --pp-background: #f6f7f8;\n    --pp-surface: #fff;\n    --pp-border: #e3e5e7;\n}\n@media (prefers-reduced-motion: reduce) {\n    .pp-panel .pp-switch,\n    .pp-panel .pp-switch::before {\n        transition: none;\n    }\n}\n";
 
 /**
  * 校验原始路径片段，不进行 URL 编码转换。
@@ -165,6 +157,122 @@ function errorView(error, retry) {
     return view;
 }
 
+/**
+ * 标题栏共用三点菜单；Shadow DOM 隔离项目样式，保留继承的主题色。
+ * Shared title-bar overflow menu; Shadow DOM isolates layout while inheriting theme colors.
+ */
+class ActionMenu {
+    #button;
+    #popup;
+    #backdrop;
+    #select;
+    #document;
+    #key = event => {
+        if (event.key === "Escape" && !this.#popup.hidden) {
+            event.preventDefault();
+            this.close();
+            this.#button.focus();
+        }
+    };
+
+    /**
+     * 创建菜单，操作逻辑由调用方提供。
+     * Create a menu whose actions are handled by the caller.
+     * @param {(id: string) => void} select 菜单选择回调 / Selection callback.
+     */
+    constructor(select) {
+        this.#document = document;
+        this.#select = select;
+        this.element = document.createElement("span");
+        const root = this.element.attachShadow({ mode: "open" });
+        root.innerHTML = `<style>
+          :host{display:inline-flex;position:relative;width:44px;height:44px;color:inherit}
+          :host([hidden]),[hidden]{display:none!important}
+          button{font:inherit;cursor:pointer;border:0;color:inherit;background:none}
+          button:disabled{opacity:.4;cursor:default}
+          button:focus-visible{outline:2px solid currentColor;outline-offset:-3px}
+          #trigger{width:44px;height:44px;padding:10px;position:relative;z-index:3}
+          svg{display:block;width:24px;height:24px;fill:currentColor}
+          #backdrop{position:fixed;inset:0;z-index:1}
+          #items{position:absolute;right:0;top:46px;z-index:2;min-width:160px;padding:6px;background:var(--pp-surface,Canvas);color:var(--pp-text,CanvasText);border:1px solid var(--pp-border,#8884);border-radius:12px;box-shadow:0 8px 28px #0003}
+          #items button{display:block;text-align:left;white-space:nowrap;width:100%;padding:11px 14px;border-radius:8px;font:14px/1.4 system-ui,sans-serif}
+          #items button:hover{background:#8882}
+          #items button[data-danger]{color:#e45656}
+        </style><button id="trigger" type="button" aria-label="更多操作" aria-haspopup="menu" aria-expanded="false" aria-controls="items"><svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="4" cy="12" r="2"/><circle cx="12" cy="12" r="2"/><circle cx="20" cy="12" r="2"/></svg></button><button id="backdrop" type="button" tabindex="-1" aria-label="关闭菜单" hidden></button><div id="items" role="menu" hidden></div>`;
+        this.#button = root.querySelector("#trigger");
+        this.#popup = root.querySelector("#items");
+        this.#backdrop = root.querySelector("#backdrop");
+        this.#button.onclick = () => {
+            const open = this.#popup.hidden;
+            this.#popup.hidden = this.#backdrop.hidden = !open;
+            this.#button.setAttribute("aria-expanded", String(open));
+            if (open) this.#popup.firstElementChild.focus();
+        };
+        this.#backdrop.onclick = () => this.close();
+        this.#popup.onkeydown = event => {
+            if (event.key === "Tab") {
+                this.close();
+                return;
+            }
+            const items = [...this.#popup.children];
+            const index = items.indexOf(root.activeElement);
+            const offsets = { ArrowDown: 1, ArrowUp: -1 };
+            if (event.key in offsets) {
+                event.preventDefault();
+                items[(index + offsets[event.key] + items.length) % items.length].focus();
+            }
+        };
+        document.addEventListener("keydown", this.#key);
+        this.update([]);
+    }
+
+    /**
+     * 同步可用操作和忙碌状态，不重建菜单触发按钮。
+     * Update actions and busy state without replacing the trigger button.
+     * @param {Array<{id: string, label: string, destructive?: boolean}>} items 操作列表 / Actions.
+     * @param {boolean} [disabled] 是否忙碌 / Whether operations are busy.
+     * @returns {void} 无返回值 / No return value.
+     */
+    update(items, disabled = false) {
+        this.close();
+        this.#button.disabled = disabled || items.length === 0;
+        this.#popup.replaceChildren(
+            ...items.map(item => {
+                const button = this.#document.createElement("button");
+                button.type = "button";
+                button.setAttribute("role", "menuitem");
+                button.textContent = item.label;
+                button.toggleAttribute("data-danger", Boolean(item.destructive));
+                button.onclick = () => {
+                    this.close();
+                    this.#select(item.id);
+                };
+                return button;
+            }),
+        );
+    }
+
+    /**
+     * 关闭菜单。
+     * Close the menu.
+     * @returns {void} 无返回值 / No return value.
+     */
+    close() {
+        this.#popup.hidden = this.#backdrop.hidden = true;
+        this.#button.setAttribute("aria-expanded", "false");
+    }
+
+    /**
+     * 移除监听器与节点。
+     * Remove listeners and elements.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#document.removeEventListener("keydown", this.#key);
+        this.element.remove();
+    }
+}
+
 /**
  * 将 BoxJS 数组、app 或订阅转换为模块字段，保留原文件为唯一字段来源。
  * Normalize a BoxJS array, app or subscription using the source JSON as the field authority.
@@ -304,31 +412,31 @@ function createPreferencesClient({ catalog, fetch: request = globalThis.fetch.bi
      */
     const sessions = new Map();
     /**
-     * 发送同源请求，处理超时与取消；数据 GET 的 404 交给调用方处理。
-     * Send a same-origin request with timeout and cancellation; callers handle missing-data GET responses.
-     * @param {string} path 相对请求路径 / Relative request path.
-     * @param {"HEAD" | "GET" | "POST" | "DELETE"} method HTTP 方法 / HTTP method.
-     * @param {unknown} body POST 值，其它方法忽略 / POST value, ignored by other methods.
+     * 用 form 发送完整存储键；读取 404 交给调用方处理。
+     * Send a complete storage key as form data; callers handle missing reads.
+     * @param {string} path 完整 @root.path / Complete @root.path.
+     * @param {"get" | "set" | "delete"} action 存储操作 / Storage operation.
+     * @param {unknown} body set 值，其它操作忽略 / Set value, ignored by other operations.
      * @param {AbortSignal | undefined} signal 会话取消信号 / Session cancellation signal.
      * @returns {Promise<Response>} 未消费正文的响应 / Response with an unread body.
      * @throws {Error} 非 200 且非数据 GET 404、超时、取消或网络错误 / Non-200 status except missing-data GETs, timeout, cancellation or network error.
      */
-    async function send(path, method, body, signal) {
+    async function send(path, action, body, signal) {
         const controller = new AbortController();
         const abort = () => controller.abort();
         if (signal?.aborted) abort();
         signal?.addEventListener("abort", abort, { once: true });
         const timer = setTimeout(abort, timeout);
         try {
-            const response = await request(path, {
-                method,
+            const response = await request(`/api/${action}`, {
+                method: "POST",
                 credentials: "omit",
                 cache: "no-store",
                 signal: controller.signal,
-                headers: { "X-Settings-Client": "1", ...(method === "POST" ? { "Content-Type": "application/json" } : {}) },
-                ...(method === "POST" ? { body: JSON.stringify(body) } : {}),
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: new URLSearchParams([[path, action === "set" ? JSON.stringify(body) : ""]]).toString(),
             });
-            if (response.status !== 200 && !(method === "GET" && response.status === 404)) throw new Error(`HTTP ${response.status}`);
+            if (response.status !== 200 && !(action === "get" && response.status === 404)) throw new Error(`HTTP ${response.status}`);
             return response;
         } finally {
             clearTimeout(timer);
@@ -352,21 +460,21 @@ function createPreferencesClient({ catalog, fetch: request = globalThis.fetch.bi
      * Serialize single-key mutations and update a still-active session only after success.
      * @param {string} module 已打开模块 / Open module.
      * @param {string} key 完整点分字段路径 / Complete dotted field path.
-     * @param {"POST" | "DELETE"} method 写入或删除 / Write or delete.
+     * @param {"set" | "delete"} action 写入或删除 / Write or delete.
      * @param {unknown} value 写入值，删除时忽略 / Write value, ignored for deletion.
      * @param {"write" | "delete" | "clearCaches" | "reset"} [operation] 操作类型 / Operation kind.
      * @returns {Promise<void>} 操作完成 / Operation completion.
      * @throws {Error} 会话、字段、值或请求错误 / Session, field, value or request error.
      */
-    async function change(module, key, method, value, operation = method === "POST" ? "write" : "delete") {
+    async function change(module, key, action, value, operation = action === "set" ? "write" : "delete") {
         const state = sessions.get(module);
         if (!state?.definition) throw new Error("Open the module first");
         if (state.saving) throw new Error("A settings write is already in progress");
         const field = state.definition.fields.find(field => field.key === key);
         state.saving = true;
         try {
-            if ((operation === "write" || operation === "delete") && (!field || (method === "POST" && !validValue(field, value)))) throw new TypeError("Invalid setting value");
-            await send(`/api/${key.split(".").map(encodeURIComponent).join("/")}`, method, value);
+            if ((operation === "write" || operation === "delete") && (!field || (action === "set" && !validValue(field, value)))) throw new TypeError("Invalid setting value");
+            await send(`@${state.definition.storageKey}.${key}`, action, value);
             if (sessions.get(module) === state) {
                 switch (operation) {
                     case "write":
@@ -409,7 +517,7 @@ function createPreferencesClient({ catalog, fetch: request = globalThis.fetch.bi
             sessions.set(module, state);
             try {
                 const definition = normalizeBoxJs(catalog.select(module), module);
-                const response = await send(`/api/${definition.settingsPath.map(encodeURIComponent).join("/")}/`, "GET", undefined, state.controller.signal);
+                const response = await send(`@${definition.storageKey}.${definition.settingsPath.join(".")}`, "get", undefined, state.controller.signal);
                 let subtree = response.status === 404 ? {} : await response.json();
                 if (typeof subtree === "string") subtree = JSON.parse(subtree);
                 if (!subtree || typeof subtree !== "object" || Array.isArray(subtree)) throw new TypeError("Expected a settings subtree object");
@@ -439,7 +547,7 @@ function createPreferencesClient({ catalog, fetch: request = globalThis.fetch.bi
         async readCaches(module) {
             const state = sessions.get(module);
             if (!state?.definition) throw new Error("Open the module first");
-            const response = await send(`/api/${encodeURIComponent(module)}/Caches`, "GET", undefined, state.controller.signal);
+            const response = await send(`@${state.definition.storageKey}.${module}.Caches`, "get", undefined, state.controller.signal);
             return response.status === 404 ? undefined : response.json();
         },
         /**
@@ -448,14 +556,14 @@ function createPreferencesClient({ catalog, fetch: request = globalThis.fetch.bi
          * @param {string} module 已打开模块 / Open module.
          * @returns {Promise<void>} 清理完成 / Cleanup completion.
          */
-        clearCaches: module => change(module, `${module}.Caches`, "DELETE", undefined, "clearCaches"),
+        clearCaches: module => change(module, `${module}.Caches`, "delete", undefined, "clearCaches"),
         /**
          * 删除整个模块持久化节点，以当前 BoxJS 默认值重置页面缓存。
          * Delete module persistence and reset the page cache using current BoxJS defaults.
          * @param {string} module 已打开模块 / Open module.
          * @returns {Promise<void>} 重置完成 / Reset completion.
          */
-        reset: module => change(module, module, "DELETE", undefined, "reset"),
+        reset: module => change(module, module, "delete", undefined, "reset"),
         /**
          * 取消读取并清除会话，不撤销已发送的写入。
          * Abort reads and clear the session without undoing dispatched writes.
@@ -474,7 +582,7 @@ function createPreferencesClient({ catalog, fetch: request = globalThis.fetch.bi
          * @param {import("../index.js").SettingsScalar | import("../index.js").SettingsScalar[]} value 字段值 / Field value.
          * @returns {Promise<void>} 写入完成 / Write completion.
          */
-        set: (module, key, value) => change(module, key, "POST", value),
+        set: (module, key, value) => change(module, key, "set", value),
         /**
          * 删除单键覆盖值并显示默认值。
          * Delete one override and display its default value.
@@ -482,7 +590,7 @@ function createPreferencesClient({ catalog, fetch: request = globalThis.fetch.bi
          * @param {string} key 点分字段路径 / Dotted field path.
          * @returns {Promise<void>} 删除完成 / Delete completion.
          */
-        remove: (module, key) => change(module, key, "DELETE"),
+        remove: (module, key) => change(module, key, "delete"),
     };
 }
 
@@ -663,6 +771,15 @@ function mountPanel(root, catalog) {
     back.setAttribute("aria-label", "返回");
     back.type = "button";
     const heading = element("h1", "pp-title", title);
+    const handlers = new Map();
+    const menuItems = [
+        { id: "viewCaches", label: "查看缓存" },
+        { id: "clearCaches", label: "清空缓存", destructive: true },
+        { id: "reset", label: "重置模块", destructive: true },
+    ];
+    const menu = new ActionMenu(id => handlers.get(id)());
+    const trailing = element("span", "pp-nav-spacer");
+    trailing.append(menu.element);
     const brand = element("div", "pp-brand");
     const logo = element("span", "pp-brand-icon");
     logo.setAttribute("aria-hidden", "true");
@@ -673,20 +790,26 @@ function mountPanel(root, catalog) {
     const toast = element("div", "pp-toast");
     toast.setAttribute("role", "status");
     toast.hidden = true;
-    header.append(back, brand, element("span", "pp-nav-spacer"));
+    header.append(back, brand, trailing);
     shell.append(header, viewport, toast);
     root.append(shell);
     // 嵌入模式向宿主发布导航状态，宿主不读取或修改模块内部 DOM。
     // Embedded mode publishes navigation state without host reads or mutations of the module DOM.
     const publishNavigation = () => {
+        const actions = handlers.size ? menuItems : [];
+        menu.update(actions, saving);
         const frame = window.frameElement;
         if (!frame?.dataset.preferencePanes) return;
         frame.dispatchEvent(
             new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:change", {
-                detail: { title: heading.textContent, module: catalog.module.module, busy: saving, canGoBack: !back.disabled },
+                detail: { title: heading.textContent, module: catalog.module.module, busy: saving, canGoBack: !back.disabled, actions },
             }),
         );
     };
+    const onAction = event => {
+        if (!saving && handlers.has(event.detail)) handlers.get(event.detail)();
+    };
+    window.frameElement?.addEventListener("preferencepanes:action", onAction);
     let timer,
         navigation,
         generation = 0,
@@ -996,17 +1119,13 @@ function mountPanel(root, catalog) {
             if (eventName === "input") inputContainer.addEventListener("compositionend", event => event.target.dispatchEvent(new window.Event("input", { bubbles: true })));
             groups.get(group).append(row);
         }
-        const maintenance = element("section", "pp-maintenance");
-        maintenance.append(element("h2", "pp-title", "模块数据"));
-        const actions = element("div", "pp-actions");
-        const cacheView = element("button", "", "查看 Caches");
-        const cacheClear = element("button", "", "清空 Caches");
-        const reset = element("button", "pp-danger", "重置模块");
+        const cachePage = element("section", "pp-cache-page");
         const output = element("pre", "pp-cache");
-        output.hidden = true;
+        output.textContent = "暂无缓存";
         output.setAttribute("aria-label", "Caches 内容");
-        for (const button of [cacheView, cacheClear, reset]) button.type = "button";
-        cacheView.onclick = () => {
+        cachePage.append(output);
+        editors.set("$caches", { node: cachePage, title: "缓存" });
+        handlers.set("viewCaches", () => {
             if (saving) return;
             let value;
             return perform(
@@ -1020,12 +1139,11 @@ function mountPanel(root, catalog) {
                 },
                 () => {
                     output.textContent = value === undefined ? "暂无缓存" : JSON.stringify(value, null, 2);
-                    output.hidden = false;
-                    cacheView.textContent = "刷新 Caches";
+                    navigation.open("$caches");
                 },
             );
-        };
-        cacheClear.onclick = () => {
+        });
+        handlers.set("clearCaches", () => {
             if (saving) return;
             if (!window.confirm(`清空 ${active} 的全部 Caches？`)) return;
             return perform(
@@ -1034,15 +1152,12 @@ function mountPanel(root, catalog) {
                     output.textContent = "暂无缓存";
                 },
             );
-        };
-        reset.onclick = () => {
+        });
+        handlers.set("reset", () => {
             if (saving) return;
             if (!window.confirm(`重置 ${active}？这将删除该模块的 Settings、Caches 和其它持久化数据。`)) return;
             return perform(() => client.reset(active), controls);
-        };
-        actions.append(cacheView, cacheClear, reset);
-        maintenance.append(actions, output);
-        view.append(maintenance);
+        });
         navigation?.destroy();
         navigation = new Navigation(viewport, view, key => editors.get(key)?.node);
         navigation.addEventListener("change", updateNavigation);
@@ -1068,6 +1183,8 @@ function mountPanel(root, catalog) {
          */
         destroy() {
             destroyed = true;
+            menu.destroy();
+            window.frameElement?.removeEventListener("preferencepanes:action", onAction);
             navigation?.destroy();
             generation++;
             if (active && !saving) client.leave(active);