@nsnanocat/preference-panes 0.8.0 → 0.8.1

package/dist/preference-panes.mjs

@@ -1,4 +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";
+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 编码转换。
@@ -157,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.
@@ -655,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");
@@ -665,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,
@@ -988,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(
@@ -1012,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(
@@ -1026,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);
@@ -1060,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);

package/package.json

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

package/src/browser/ActionMenu.mjs

@@ -0,0 +1,115 @@
+/**
+ * 标题栏共用三点菜单；Shadow DOM 隔离项目样式，保留继承的主题色。
+ * Shared title-bar overflow menu; Shadow DOM isolates layout while inheriting theme colors.
+ */
+export 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();
+    }
+}

package/src/browser/ModuleFrame.mjs

@@ -11,7 +11,7 @@ export 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"));
     };
 
@@ -30,7 +30,7 @@ export 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 });
     }
 
@@ -70,6 +70,17 @@ export 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.

package/src/browser/ModuleStatus.mjs

@@ -0,0 +1,86 @@
+/**
+ * 模块入口的固定状态行，只通过 HEAD 探测安装状态和业务版本。
+ * Fixed module status row, probing installation and business version with HEAD only.
+ */
+export 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;
+    }
+}

package/src/browser/Navigation.d.mts

@@ -19,7 +19,7 @@ export class ModuleFrame extends EventTarget {
      * change 事件对应的导航状态。
      * Navigation state exposed with change events.
      */
-    readonly state: { title: string; module: string; busy: boolean; canGoBack: boolean };
+    readonly state: { title: string; module: string; busy: boolean; canGoBack: boolean; actions: MenuAction[] };
     /**
      * 获取原始 HTML。
      * Fetch unmodified HTML.
@@ -32,6 +32,13 @@ export class ModuleFrame extends EventTarget {
      * @returns 无返回值 / No return value.
      */
     back(): void;
+    /**
+     * 执行模块提供的菜单操作。
+     * Perform a module-provided menu action.
+     * @param id 操作标识 / Action identifier.
+     * @returns 无返回值 / No return value.
+     */
+    perform(id: string): void;
     /**
      * 取消请求与事件订阅。
      * Cancel requests and subscriptions.
@@ -40,6 +47,97 @@ export class ModuleFrame extends EventTarget {
     destroy(): void;
 }
 
+/**
+ * 菜单操作描述。
+ * Menu action descriptor.
+ */
+export interface MenuAction {
+    /**
+     * 操作标识。
+     * Action identifier.
+     */
+    id: string;
+    /**
+     * 显示文字。
+     * Display text.
+     */
+    label: string;
+    /**
+     * 危险操作样式。
+     * Destructive action style.
+     */
+    destructive?: boolean;
+}
+
+/**
+ * 共用三点菜单。
+ * Shared overflow menu.
+ */
+export class ActionMenu {
+    /**
+     * 创建菜单。
+     * Create a menu.
+     * @param select 选择回调 / Selection callback.
+     */
+    constructor(select: (id: string) => void);
+    /**
+     * 菜单节点。
+     * Menu element.
+     */
+    readonly element: HTMLElement;
+    /**
+     * 更新操作列表。
+     * Update available actions.
+     * @param items 操作列表 / Actions.
+     * @param disabled 是否忙碌 / Busy state.
+     * @returns 无返回值 / No return value.
+     */
+    update(items: MenuAction[], disabled?: boolean): void;
+    /**
+     * 关闭菜单。
+     * Close the menu.
+     * @returns 无返回值 / No return value.
+     */
+    close(): void;
+    /**
+     * 释放组件。
+     * Release the component.
+     * @returns 无返回值 / No return value.
+     */
+    destroy(): void;
+}
+
+/**
+ * HEAD 探测的固定模块状态行。
+ * Fixed module status row backed by HEAD probes.
+ */
+export class ModuleStatus extends EventTarget {
+    /**
+     * 绑定状态行。
+     * Bind a status row.
+     * @param element 状态行节点 / Status row node.
+     */
+    constructor(element: HTMLElement);
+    /**
+     * 当前状态及模块版本。
+     * Current state and module version.
+     */
+    readonly state: { status: "checking" | "installed" | "missing"; version: string | null };
+    /**
+     * 探测配置 Mock。
+     * Probe a configuration Mock.
+     * @param url 配置地址 / Configuration URL.
+     * @returns 探测完成 / Probe completion.
+     */
+    check(url: string | URL): Promise<void>;
+    /**
+     * 取消探测。
+     * Cancel probes.
+     * @returns 无返回值 / No return value.
+     */
+    destroy(): void;
+}
+
 /**
  * 同一文档的根页/子页导航，不定义页面布局或模块业务。
  * Home/detail navigation within a document, without layout or module business rules.

package/src/browser/Navigation.mjs

@@ -1,4 +1,6 @@
+export { ActionMenu } from "./ActionMenu.mjs";
 export { ModuleFrame } from "./ModuleFrame.mjs";
+export { ModuleStatus } from "./ModuleStatus.mjs";
 
 /**
  * 同一文档内的主页/子页导航；iframe 各自的实例通过浏览器联合历史协作。