@nsnanocat/preference-panes 1.1.2 → 1.1.4

package/dist/module/index.mjs

@@ -35,6 +35,7 @@ function normalizeBoxJs(config, module) {
             if (!storageKey || storageKey.startsWith("@") || parts.length < 2) throw new TypeError("A BoxJS setting must be below a literal storage root and module");
             validatePathParts(parts);
             const name = parts[0];
+            if (["get", "set", "delete"].includes(name)) throw new TypeError(`Reserved API module name: ${name}`);
             let target = modules.get(name);
             if (!target) {
                 target = { module: name, storageKey, entries: [], owners: new Set() };
@@ -275,8 +276,8 @@ function requestConfirmation(host, message) {
 }
 
 /**
- * 共用三点按钮和底部操作菜单；弹层挂载到文档根部，不受标题栏显示状态影响。
- * Shared overflow trigger and bottom action sheet; the layer is mounted at document level and remains independent of header visibility.
+ * 独立页面的三点按钮和底部操作菜单；嵌入页面由宿主提供对应界面。
+ * Overflow trigger and bottom action sheet for standalone pages; embedded pages use host-provided chrome.
  */
 class ActionMenu {
     #button;
@@ -816,13 +817,9 @@ class PreferencesPanel {
         const title = definition.metadata?.name ?? definition.module;
         const document = root.ownerDocument;
         const window = document.defaultView;
+        const frame = window.frameElement?.dataset.preferencePanes ? window.frameElement : undefined;
         const shell = element("div", "pp-panel");
         shell.dataset.module = definition.module;
-        const header = element("header", "pp-header");
-        const back = element("button", "pp-back", "‹");
-        back.setAttribute("aria-label", "返回");
-        back.type = "button";
-        const heading = element("h1", "pp-title", title);
         const handlers = new Map();
         const menuItems = [
             { id: "viewSettings", label: "查看设置" },
@@ -830,37 +827,51 @@ class PreferencesPanel {
             { id: "clearCaches", label: "清空缓存", destructive: true },
             { id: "reset", label: "重置设置", destructive: true },
         ];
-        const menu = new ActionMenu(id => runAction(id));
-        const trailing = element("span", "pp-nav-spacer");
-        trailing.append(menu.element);
         const viewport = element("div", "pp-viewport");
+        let back, heading, menu;
+        if (frame) shell.append(viewport);
+        else {
+            const header = element("header", "pp-header");
+            back = element("button", "pp-back", "‹");
+            back.setAttribute("aria-label", "返回");
+            back.type = "button";
+            heading = element("h1", "pp-title", title);
+            menu = new ActionMenu(id => runAction(id));
+            const trailing = element("span", "pp-nav-spacer");
+            trailing.append(menu.element);
+            header.append(back, heading, trailing);
+            shell.append(header, viewport);
+        }
         let toast;
-        header.append(back, heading, trailing);
-        shell.append(header, viewport);
         root.append(shell);
         // 嵌入模式向宿主发布导航状态，宿主不读取或修改模块内部 DOM。
         // Embedded mode publishes navigation state without host reads or mutations of the module DOM.
         const publishNavigation = () => {
             const actions = handlers.size ? menuItems : [];
-            menu.update(actions, saving);
-            const frame = window.frameElement;
-            if (!frame?.dataset.preferencePanes) return;
-            frame.dispatchEvent(
-                new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:change", {
-                    detail: { title: heading.textContent, module: definition.module, busy: saving, canGoBack: !back.disabled, actions },
-                }),
-            );
+            if (frame)
+                frame.dispatchEvent(
+                    new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:change", {
+                        detail: { title: currentTitle, module: definition.module, busy: saving, canGoBack, actions },
+                    }),
+                );
+            else {
+                heading.textContent = currentTitle;
+                back.disabled = !canGoBack;
+                menu.update(actions, saving);
+            }
         };
         const onAction = event => {
             if (!saving && handlers.has(event.detail)) runAction(event.detail);
         };
-        window.frameElement?.addEventListener("preferencepanes:action", onAction);
+        frame?.addEventListener("preferencepanes:action", onAction);
         let timer,
             navigation,
             generation = 0,
             active = null,
             saving = false,
-            destroyed = false;
+            destroyed = false,
+            currentTitle = title,
+            canGoBack = window.history.length > 1;
         /**
          * 展示短暂通知，不刷新设置数据。
          * Display a transient notification without refreshing settings.
@@ -889,7 +900,6 @@ class PreferencesPanel {
             }
             // 宿主接管时不创建网页 Toast，也不运行其计时器。
             // A host-owned notice creates no web Toast and starts no local timer.
-            const frame = window.frameElement;
             if (frame && !frame.dispatchEvent(new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:notice", { cancelable: true, detail: { kind: event.kind, message } }))) return;
             if (!toast) {
                 toast = element("div", "pp-toast");
@@ -927,8 +937,8 @@ class PreferencesPanel {
         async function open(module) {
             const version = ++generation;
             active = module;
-            back.disabled = window.history.length <= 1;
-            heading.textContent = module;
+            currentTitle = module;
+            canGoBack = window.history.length > 1;
             publishNavigation();
             viewport.replaceChildren(statusView("读取设置…"));
             try {
@@ -947,7 +957,7 @@ class PreferencesPanel {
          */
         function controls() {
             const { definition, values } = client.snapshot();
-            heading.textContent = definition.metadata?.name || active;
+            currentTitle = definition.metadata?.name || active;
             const view = element("section", "pp-fields");
             /**
              * 挂载后执行的多行高度更新
@@ -967,8 +977,8 @@ class PreferencesPanel {
              */
             const updateNavigation = () => {
                 const editor = editors.get(navigation.current);
-                heading.textContent = editor?.title ?? definition.metadata?.name ?? active;
-                back.disabled = saving || !navigation.canGoBack;
+                currentTitle = editor?.title ?? definition.metadata?.name ?? active;
+                canGoBack = !saving && navigation.canGoBack;
                 publishNavigation();
             };
             /**
@@ -982,7 +992,7 @@ class PreferencesPanel {
             function perform(action, success, failure = () => {}) {
                 pendingWrites++;
                 saving = true;
-                back.disabled = true;
+                canGoBack = false;
                 publishNavigation();
                 queue = queue
                     .then(action)
@@ -998,7 +1008,7 @@ class PreferencesPanel {
                         pendingWrites--;
                         saving = pendingWrites > 0;
                         if (destroyed && !saving) client.leave();
-                        back.disabled = saving || !navigation.canGoBack;
+                        canGoBack = !saving && navigation.canGoBack;
                         publishNavigation();
                     });
                 return queue;
@@ -1272,16 +1282,17 @@ class PreferencesPanel {
          * Loaded forms delegate back to navigation; loading views can return to the previous document.
          * @returns {void} 无返回值 / No return value.
          */
-        back.onclick = () => {
-            if (saving) return;
-            if (navigation) navigation.back();
-            else window.history.back();
-        };
+        if (back)
+            back.onclick = () => {
+                if (saving) return;
+                if (navigation) navigation.back();
+                else window.history.back();
+            };
         open(definition.module);
         return () => {
             destroyed = true;
-            menu.destroy();
-            window.frameElement?.removeEventListener("preferencepanes:action", onAction);
+            menu?.destroy();
+            frame?.removeEventListener("preferencepanes:action", onAction);
             navigation?.destroy();
             generation++;
             if (active && !saving) client.leave();
@@ -1300,7 +1311,7 @@ class PreferencesPanel {
     }
 }
 
-var defaults = "/* 通用默认样式只使用 pp 命名空间；项目可通过 CSS 输入覆盖变量和组件。\n * Generic defaults use only the pp namespace; projects may override variables and components through CSS input. */\n.pp-panel {\n    --pp-text: #18191c;\n    --pp-background: #f6f7f8;\n    --pp-surface: #fff;\n    --pp-field: #f1f2f3;\n    --pp-border: #e3e5e7;\n    --pp-muted: #797f87;\n    --pp-accent: #1677ff;\n    font:\n        15px / 1.5 -apple-system,\n        BlinkMacSystemFont,\n        \"Segoe UI\",\n        sans-serif;\n    color: var(--pp-text);\n    background: var(--pp-background);\n    position: relative;\n    display: flex;\n    flex-direction: column;\n    width: 100%;\n    max-width: 100vw;\n    min-width: 0;\n    height: 100vh;\n    overflow: hidden;\n}\n\n:root[data-theme=\"dark\"] .pp-panel {\n    --pp-text: #f1f2f3;\n    --pp-background: #0d0e0f;\n    --pp-surface: #18191c;\n    --pp-field: #2f3238;\n    --pp-border: #2f3238;\n    --pp-muted: #9499a0;\n}\n.pp-panel * {\n    box-sizing: border-box;\n    letter-spacing: 0;\n}\n.pp-header {\n    flex: none;\n    height: calc(52px + env(safe-area-inset-top));\n    padding: env(safe-area-inset-top) 12px 0;\n    display: flex;\n    align-items: center;\n    background: var(--pp-surface);\n    border-bottom: 1px solid var(--pp-border);\n    position: relative;\n    z-index: 2;\n}\n.pp-title {\n    flex: 1;\n    text-align: center;\n    font-size: 17px;\n    font-weight: 500;\n    margin: 0;\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n.pp-nav-spacer {\n    width: 44px;\n    flex: none;\n}\n.pp-panel button {\n    font: inherit;\n    cursor: pointer;\n    border: 0;\n    background: none;\n    color: inherit;\n}\n.pp-panel .pp-back {\n    width: 44px;\n    height: 44px;\n    flex: none;\n    font-size: 34px;\n    line-height: 32px;\n    padding: 0;\n}\n.pp-panel button:disabled {\n    opacity: 0.5;\n    cursor: wait;\n}\n.pp-viewport {\n    position: relative;\n    flex: 1;\n    min-width: 0;\n    min-height: 0;\n    overflow: hidden;\n}\n:root[data-preference-panes-embedded] .pp-header {\n    display: none;\n}\n@supports (height: 100dvh) {\n    .pp-panel {\n        height: 100dvh;\n    }\n}\n.pp-fields,\n.pp-choice-page,\n.pp-settings-page,\n.pp-cache-page {\n    position: absolute;\n    inset: 0;\n    min-width: 0;\n    overflow-x: hidden;\n    overflow-y: auto;\n    padding: 12px max(16px, calc((100% - 688px) / 2)) calc(28px + env(safe-area-inset-bottom) + var(--pp-keyboard-height, 0px));\n    scroll-padding-bottom: var(--pp-keyboard-height, 0px);\n    background: var(--pp-background);\n}\n.pp-choice-link {\n    display: flex;\n    align-items: center;\n    justify-content: flex-end;\n    gap: 8px;\n    max-width: 45%;\n    min-width: 44px;\n    min-height: 44px;\n    padding: 0;\n    text-align: right;\n    flex: 1;\n}\n.pp-summary {\n    color: var(--pp-muted);\n    font-size: 13px;\n    line-height: 18px;\n    display: -webkit-box;\n    -webkit-line-clamp: 2;\n    -webkit-box-orient: vertical;\n    overflow: hidden;\n    overflow-wrap: anywhere;\n}\n.pp-chevron {\n    color: var(--pp-muted);\n    font-size: 22px;\n    flex: none;\n}\n.pp-editor {\n    flex: none;\n    width: 45%;\n    min-width: 0;\n    min-height: 36px;\n    padding: 8px 10px;\n    font: inherit;\n    color: var(--pp-text);\n    background: var(--pp-field);\n    border: 0;\n    border-radius: 6px;\n}\n.pp-panel .pp-multiline {\n    display: block;\n}\n.pp-multiline .pp-editor {\n    width: 100%;\n    margin-top: 10px;\n}\n.pp-panel [hidden] {\n    display: none !important;\n}\n.pp-label {\n    flex: 1;\n    min-width: 0;\n    display: flex;\n    flex-direction: column;\n    align-items: flex-start;\n    margin-right: 16px;\n}\n.pp-field-name {\n    color: var(--pp-text);\n    font-size: 15px;\n}\n.pp-field-description {\n    margin-top: 2px;\n    color: var(--pp-muted);\n    font-size: 12px;\n}\n.pp-group {\n    margin-top: 16px;\n}\n.pp-group-title {\n    margin: 0 0 8px;\n    color: var(--pp-muted);\n    font-size: 15px;\n    font-weight: 400;\n}\n.pp-row {\n    min-width: 0;\n    min-height: 48px;\n    padding: 16px;\n    display: flex;\n    align-items: center;\n    justify-content: space-between;\n    background: var(--pp-surface);\n    border-bottom: 1px solid var(--pp-border);\n}\n.pp-rows > :last-child {\n    border-bottom: 0 !important;\n}\n.pp-switch {\n    flex: none;\n    accent-color: var(--pp-accent);\n}\n.pp-choice {\n    justify-content: space-between;\n    cursor: pointer;\n}\n.pp-choice input {\n    width: 20px;\n    height: 20px;\n    flex: none;\n    accent-color: var(--pp-accent);\n    margin: 0;\n}\n.pp-description {\n    font-size: 12px;\n    line-height: 1.6;\n    color: var(--pp-muted);\n    white-space: pre-wrap;\n    overflow-wrap: anywhere;\n}\n.pp-module-info {\n    display: flex;\n    gap: 12px;\n    margin: 12px 0;\n}\n.pp-module-details {\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n.pp-module-source {\n    color: inherit;\n    text-decoration: underline;\n}\n.pp-status {\n    position: fixed;\n    inset: 0;\n    display: grid;\n    place-content: center;\n    justify-items: center;\n    gap: 12px;\n    min-width: 0;\n    min-height: 0;\n    margin: 0;\n    padding: 24px;\n    color: var(--pp-muted, GrayText);\n    text-align: center;\n    background: var(--pp-background, Canvas);\n}\n.pp-viewport > .pp-status {\n    position: absolute;\n}\n.pp-status-spinner {\n    box-sizing: border-box;\n    width: 28px;\n    height: 28px;\n    border: 3px solid color-mix(in srgb, currentColor 25%, transparent);\n    border-top-color: var(--pp-accent, AccentColor);\n    border-radius: 50%;\n    animation: pp-status-spin 0.8s linear infinite;\n}\n.pp-status-message {\n    max-width: 100%;\n    margin: 0;\n    overflow-wrap: anywhere;\n}\n.pp-status-action {\n    min-width: 96px;\n    min-height: 44px;\n    padding: 8px 16px;\n    border: 0;\n    border-radius: 6px;\n    color: var(--pp-text, ButtonText);\n    font: inherit;\n    cursor: pointer;\n    background: var(--pp-surface, ButtonFace);\n}\n@keyframes pp-status-spin {\n    to {\n        transform: rotate(1turn);\n    }\n}\n.pp-cache {\n    white-space: pre-wrap;\n    overflow-wrap: anywhere;\n}\n.pp-toast {\n    pointer-events: none;\n    position: fixed;\n    bottom: calc(30px + env(safe-area-inset-bottom));\n    left: 50%;\n    transform: translateX(-50%);\n    max-width: 90vw;\n    padding: 10px 16px;\n    border-radius: 8px;\n    background: #333e;\n    color: white;\n    font-size: 13px;\n    z-index: 20;\n}\n.pp-toast[data-kind=\"error\"] {\n    background: #8d2424;\n}\n.pp-panel :focus-visible {\n    outline: 2px solid var(--pp-accent);\n    outline-offset: -2px;\n}\n";
+var defaults = "/* 通用默认样式只使用 pp 命名空间；项目可通过 CSS 输入覆盖变量和组件。\n * Generic defaults use only the pp namespace; projects may override variables and components through CSS input. */\n.pp-panel {\n    --pp-text: #18191c;\n    --pp-background: #f6f7f8;\n    --pp-surface: #fff;\n    --pp-field: #f1f2f3;\n    --pp-border: #e3e5e7;\n    --pp-muted: #797f87;\n    --pp-accent: #1677ff;\n    font:\n        15px / 1.5 -apple-system,\n        BlinkMacSystemFont,\n        \"Segoe UI\",\n        sans-serif;\n    color: var(--pp-text);\n    background: var(--pp-background);\n    position: relative;\n    display: flex;\n    flex-direction: column;\n    width: 100%;\n    max-width: 100vw;\n    min-width: 0;\n    height: 100vh;\n    overflow: hidden;\n}\n\n:root[data-theme=\"dark\"] .pp-panel {\n    --pp-text: #f1f2f3;\n    --pp-background: #0d0e0f;\n    --pp-surface: #18191c;\n    --pp-field: #2f3238;\n    --pp-border: #2f3238;\n    --pp-muted: #9499a0;\n}\n.pp-panel * {\n    box-sizing: border-box;\n    letter-spacing: 0;\n}\n.pp-header {\n    flex: none;\n    height: calc(52px + env(safe-area-inset-top));\n    padding: env(safe-area-inset-top) 12px 0;\n    display: flex;\n    align-items: center;\n    background: var(--pp-surface);\n    border-bottom: 1px solid var(--pp-border);\n    position: relative;\n    z-index: 2;\n}\n.pp-title {\n    flex: 1;\n    text-align: center;\n    font-size: 17px;\n    font-weight: 500;\n    margin: 0;\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n.pp-nav-spacer {\n    width: 44px;\n    flex: none;\n}\n.pp-panel button {\n    font: inherit;\n    cursor: pointer;\n    border: 0;\n    background: none;\n    color: inherit;\n}\n.pp-panel .pp-back {\n    width: 44px;\n    height: 44px;\n    flex: none;\n    font-size: 34px;\n    line-height: 32px;\n    padding: 0;\n}\n.pp-panel button:disabled {\n    opacity: 0.5;\n    cursor: wait;\n}\n.pp-viewport {\n    position: relative;\n    flex: 1;\n    min-width: 0;\n    min-height: 0;\n    overflow: hidden;\n}\n@supports (height: 100dvh) {\n    .pp-panel {\n        height: 100dvh;\n    }\n}\n.pp-fields,\n.pp-choice-page,\n.pp-settings-page,\n.pp-cache-page {\n    position: absolute;\n    inset: 0;\n    min-width: 0;\n    overflow-x: hidden;\n    overflow-y: auto;\n    padding: 12px max(16px, calc((100% - 688px) / 2)) calc(28px + env(safe-area-inset-bottom) + var(--pp-keyboard-height, 0px));\n    scroll-padding-bottom: var(--pp-keyboard-height, 0px);\n    background: var(--pp-background);\n}\n.pp-choice-link {\n    display: flex;\n    align-items: center;\n    justify-content: flex-end;\n    gap: 8px;\n    max-width: 45%;\n    min-width: 44px;\n    min-height: 44px;\n    padding: 0;\n    text-align: right;\n    flex: 1;\n}\n.pp-summary {\n    color: var(--pp-muted);\n    font-size: 13px;\n    line-height: 18px;\n    display: -webkit-box;\n    -webkit-line-clamp: 2;\n    -webkit-box-orient: vertical;\n    overflow: hidden;\n    overflow-wrap: anywhere;\n}\n.pp-chevron {\n    color: var(--pp-muted);\n    font-size: 22px;\n    flex: none;\n}\n.pp-editor {\n    flex: none;\n    width: 45%;\n    min-width: 0;\n    min-height: 36px;\n    padding: 8px 10px;\n    font: inherit;\n    color: var(--pp-text);\n    background: var(--pp-field);\n    border: 0;\n    border-radius: 6px;\n}\n.pp-panel .pp-multiline {\n    display: block;\n}\n.pp-multiline .pp-editor {\n    width: 100%;\n    margin-top: 10px;\n}\n.pp-panel [hidden] {\n    display: none !important;\n}\n.pp-label {\n    flex: 1;\n    min-width: 0;\n    display: flex;\n    flex-direction: column;\n    align-items: flex-start;\n    margin-right: 16px;\n}\n.pp-field-name {\n    color: var(--pp-text);\n    font-size: 15px;\n}\n.pp-field-description {\n    margin-top: 2px;\n    color: var(--pp-muted);\n    font-size: 12px;\n}\n.pp-group {\n    margin-top: 16px;\n}\n.pp-group-title {\n    margin: 0 0 8px;\n    color: var(--pp-muted);\n    font-size: 15px;\n    font-weight: 400;\n}\n.pp-row {\n    min-width: 0;\n    min-height: 48px;\n    padding: 16px;\n    display: flex;\n    align-items: center;\n    justify-content: space-between;\n    background: var(--pp-surface);\n    border-bottom: 1px solid var(--pp-border);\n}\n.pp-rows > :last-child {\n    border-bottom: 0 !important;\n}\n.pp-switch {\n    flex: none;\n    accent-color: var(--pp-accent);\n}\n.pp-choice {\n    justify-content: space-between;\n    cursor: pointer;\n}\n.pp-choice input {\n    width: 20px;\n    height: 20px;\n    flex: none;\n    accent-color: var(--pp-accent);\n    margin: 0;\n}\n.pp-description {\n    font-size: 12px;\n    line-height: 1.6;\n    color: var(--pp-muted);\n    white-space: pre-wrap;\n    overflow-wrap: anywhere;\n}\n.pp-module-info {\n    display: flex;\n    gap: 12px;\n    margin: 12px 0;\n}\n.pp-module-details {\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n.pp-module-source {\n    color: inherit;\n    text-decoration: underline;\n}\n.pp-status {\n    position: fixed;\n    inset: 0;\n    display: grid;\n    place-content: center;\n    justify-items: center;\n    gap: 12px;\n    min-width: 0;\n    min-height: 0;\n    margin: 0;\n    padding: 24px;\n    color: var(--pp-muted, GrayText);\n    text-align: center;\n    background: var(--pp-background, Canvas);\n}\n.pp-viewport > .pp-status {\n    position: absolute;\n}\n.pp-status-spinner {\n    box-sizing: border-box;\n    width: 28px;\n    height: 28px;\n    border: 3px solid color-mix(in srgb, currentColor 25%, transparent);\n    border-top-color: var(--pp-accent, AccentColor);\n    border-radius: 50%;\n    animation: pp-status-spin 0.8s linear infinite;\n}\n.pp-status-message {\n    max-width: 100%;\n    margin: 0;\n    overflow-wrap: anywhere;\n}\n.pp-status-action {\n    min-width: 96px;\n    min-height: 44px;\n    padding: 8px 16px;\n    border: 0;\n    border-radius: 6px;\n    color: var(--pp-text, ButtonText);\n    font: inherit;\n    cursor: pointer;\n    background: var(--pp-surface, ButtonFace);\n}\n@keyframes pp-status-spin {\n    to {\n        transform: rotate(1turn);\n    }\n}\n.pp-cache {\n    white-space: pre-wrap;\n    overflow-wrap: anywhere;\n}\n.pp-toast {\n    pointer-events: none;\n    position: fixed;\n    bottom: calc(30px + env(safe-area-inset-bottom));\n    left: 50%;\n    transform: translateX(-50%);\n    max-width: 90vw;\n    padding: 10px 16px;\n    border-radius: 8px;\n    background: #333e;\n    color: white;\n    font-size: 13px;\n    z-index: 20;\n}\n.pp-toast[data-kind=\"error\"] {\n    background: #8d2424;\n}\n.pp-panel :focus-visible {\n    outline: 2px solid var(--pp-accent);\n    outline-offset: -2px;\n}\n";
 
 const selector = "style[data-preference-panes-defaults]";
 

package/dist/module/navigation.mjs

@@ -1,6 +1,6 @@
 /**
- * 共用三点按钮和底部操作菜单；弹层挂载到文档根部，不受标题栏显示状态影响。
- * Shared overflow trigger and bottom action sheet; the layer is mounted at document level and remains independent of header visibility.
+ * 独立页面的三点按钮和底部操作菜单；嵌入页面由宿主提供对应界面。
+ * Overflow trigger and bottom action sheet for standalone pages; embedded pages use host-provided chrome.
  */
 class ActionMenu {
     #button;
@@ -331,7 +331,7 @@ class ModuleStatus extends EventTarget {
             const response = await probeModule(url, { ...options, signal: controller.signal });
             if (controller !== this.#controller) return response;
             const version = response.status === 200 ? response.headers.get("X-PreferencePanes-Version")?.trim() || null : null;
-            this.#render(response.status === 200 ? "installed" : "missing", version);
+            this.#render(version ? "installed" : "missing", version);
             return response;
         } catch (error) {
             if (controller !== this.#controller) return;

package/dist/preference-panes.mjs

@@ -35,6 +35,7 @@ function normalizeBoxJs(config, module) {
             if (!storageKey || storageKey.startsWith("@") || parts.length < 2) throw new TypeError("A BoxJS setting must be below a literal storage root and module");
             validatePathParts(parts);
             const name = parts[0];
+            if (["get", "set", "delete"].includes(name)) throw new TypeError(`Reserved API module name: ${name}`);
             let target = modules.get(name);
             if (!target) {
                 target = { module: name, storageKey, entries: [], owners: new Set() };
@@ -275,8 +276,8 @@ function requestConfirmation(host, message) {
 }
 
 /**
- * 共用三点按钮和底部操作菜单；弹层挂载到文档根部，不受标题栏显示状态影响。
- * Shared overflow trigger and bottom action sheet; the layer is mounted at document level and remains independent of header visibility.
+ * 独立页面的三点按钮和底部操作菜单；嵌入页面由宿主提供对应界面。
+ * Overflow trigger and bottom action sheet for standalone pages; embedded pages use host-provided chrome.
  */
 class ActionMenu {
     #button;
@@ -816,13 +817,9 @@ class PreferencesPanel {
         const title = definition.metadata?.name ?? definition.module;
         const document = root.ownerDocument;
         const window = document.defaultView;
+        const frame = window.frameElement?.dataset.preferencePanes ? window.frameElement : undefined;
         const shell = element("div", "pp-panel");
         shell.dataset.module = definition.module;
-        const header = element("header", "pp-header");
-        const back = element("button", "pp-back", "‹");
-        back.setAttribute("aria-label", "返回");
-        back.type = "button";
-        const heading = element("h1", "pp-title", title);
         const handlers = new Map();
         const menuItems = [
             { id: "viewSettings", label: "查看设置" },
@@ -830,37 +827,51 @@ class PreferencesPanel {
             { id: "clearCaches", label: "清空缓存", destructive: true },
             { id: "reset", label: "重置设置", destructive: true },
         ];
-        const menu = new ActionMenu(id => runAction(id));
-        const trailing = element("span", "pp-nav-spacer");
-        trailing.append(menu.element);
         const viewport = element("div", "pp-viewport");
+        let back, heading, menu;
+        if (frame) shell.append(viewport);
+        else {
+            const header = element("header", "pp-header");
+            back = element("button", "pp-back", "‹");
+            back.setAttribute("aria-label", "返回");
+            back.type = "button";
+            heading = element("h1", "pp-title", title);
+            menu = new ActionMenu(id => runAction(id));
+            const trailing = element("span", "pp-nav-spacer");
+            trailing.append(menu.element);
+            header.append(back, heading, trailing);
+            shell.append(header, viewport);
+        }
         let toast;
-        header.append(back, heading, trailing);
-        shell.append(header, viewport);
         root.append(shell);
         // 嵌入模式向宿主发布导航状态，宿主不读取或修改模块内部 DOM。
         // Embedded mode publishes navigation state without host reads or mutations of the module DOM.
         const publishNavigation = () => {
             const actions = handlers.size ? menuItems : [];
-            menu.update(actions, saving);
-            const frame = window.frameElement;
-            if (!frame?.dataset.preferencePanes) return;
-            frame.dispatchEvent(
-                new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:change", {
-                    detail: { title: heading.textContent, module: definition.module, busy: saving, canGoBack: !back.disabled, actions },
-                }),
-            );
+            if (frame)
+                frame.dispatchEvent(
+                    new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:change", {
+                        detail: { title: currentTitle, module: definition.module, busy: saving, canGoBack, actions },
+                    }),
+                );
+            else {
+                heading.textContent = currentTitle;
+                back.disabled = !canGoBack;
+                menu.update(actions, saving);
+            }
         };
         const onAction = event => {
             if (!saving && handlers.has(event.detail)) runAction(event.detail);
         };
-        window.frameElement?.addEventListener("preferencepanes:action", onAction);
+        frame?.addEventListener("preferencepanes:action", onAction);
         let timer,
             navigation,
             generation = 0,
             active = null,
             saving = false,
-            destroyed = false;
+            destroyed = false,
+            currentTitle = title,
+            canGoBack = window.history.length > 1;
         /**
          * 展示短暂通知，不刷新设置数据。
          * Display a transient notification without refreshing settings.
@@ -889,7 +900,6 @@ class PreferencesPanel {
             }
             // 宿主接管时不创建网页 Toast，也不运行其计时器。
             // A host-owned notice creates no web Toast and starts no local timer.
-            const frame = window.frameElement;
             if (frame && !frame.dispatchEvent(new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:notice", { cancelable: true, detail: { kind: event.kind, message } }))) return;
             if (!toast) {
                 toast = element("div", "pp-toast");
@@ -927,8 +937,8 @@ class PreferencesPanel {
         async function open(module) {
             const version = ++generation;
             active = module;
-            back.disabled = window.history.length <= 1;
-            heading.textContent = module;
+            currentTitle = module;
+            canGoBack = window.history.length > 1;
             publishNavigation();
             viewport.replaceChildren(statusView("读取设置…"));
             try {
@@ -947,7 +957,7 @@ class PreferencesPanel {
          */
         function controls() {
             const { definition, values } = client.snapshot();
-            heading.textContent = definition.metadata?.name || active;
+            currentTitle = definition.metadata?.name || active;
             const view = element("section", "pp-fields");
             /**
              * 挂载后执行的多行高度更新
@@ -967,8 +977,8 @@ class PreferencesPanel {
              */
             const updateNavigation = () => {
                 const editor = editors.get(navigation.current);
-                heading.textContent = editor?.title ?? definition.metadata?.name ?? active;
-                back.disabled = saving || !navigation.canGoBack;
+                currentTitle = editor?.title ?? definition.metadata?.name ?? active;
+                canGoBack = !saving && navigation.canGoBack;
                 publishNavigation();
             };
             /**
@@ -982,7 +992,7 @@ class PreferencesPanel {
             function perform(action, success, failure = () => {}) {
                 pendingWrites++;
                 saving = true;
-                back.disabled = true;
+                canGoBack = false;
                 publishNavigation();
                 queue = queue
                     .then(action)
@@ -998,7 +1008,7 @@ class PreferencesPanel {
                         pendingWrites--;
                         saving = pendingWrites > 0;
                         if (destroyed && !saving) client.leave();
-                        back.disabled = saving || !navigation.canGoBack;
+                        canGoBack = !saving && navigation.canGoBack;
                         publishNavigation();
                     });
                 return queue;
@@ -1272,16 +1282,17 @@ class PreferencesPanel {
          * Loaded forms delegate back to navigation; loading views can return to the previous document.
          * @returns {void} 无返回值 / No return value.
          */
-        back.onclick = () => {
-            if (saving) return;
-            if (navigation) navigation.back();
-            else window.history.back();
-        };
+        if (back)
+            back.onclick = () => {
+                if (saving) return;
+                if (navigation) navigation.back();
+                else window.history.back();
+            };
         open(definition.module);
         return () => {
             destroyed = true;
-            menu.destroy();
-            window.frameElement?.removeEventListener("preferencepanes:action", onAction);
+            menu?.destroy();
+            frame?.removeEventListener("preferencepanes:action", onAction);
             navigation?.destroy();
             generation++;
             if (active && !saving) client.leave();
@@ -1300,7 +1311,7 @@ class PreferencesPanel {
     }
 }
 
-var defaults = "/* 通用默认样式只使用 pp 命名空间；项目可通过 CSS 输入覆盖变量和组件。\n * Generic defaults use only the pp namespace; projects may override variables and components through CSS input. */\n.pp-panel {\n    --pp-text: #18191c;\n    --pp-background: #f6f7f8;\n    --pp-surface: #fff;\n    --pp-field: #f1f2f3;\n    --pp-border: #e3e5e7;\n    --pp-muted: #797f87;\n    --pp-accent: #1677ff;\n    font:\n        15px / 1.5 -apple-system,\n        BlinkMacSystemFont,\n        \"Segoe UI\",\n        sans-serif;\n    color: var(--pp-text);\n    background: var(--pp-background);\n    position: relative;\n    display: flex;\n    flex-direction: column;\n    width: 100%;\n    max-width: 100vw;\n    min-width: 0;\n    height: 100vh;\n    overflow: hidden;\n}\n\n:root[data-theme=\"dark\"] .pp-panel {\n    --pp-text: #f1f2f3;\n    --pp-background: #0d0e0f;\n    --pp-surface: #18191c;\n    --pp-field: #2f3238;\n    --pp-border: #2f3238;\n    --pp-muted: #9499a0;\n}\n.pp-panel * {\n    box-sizing: border-box;\n    letter-spacing: 0;\n}\n.pp-header {\n    flex: none;\n    height: calc(52px + env(safe-area-inset-top));\n    padding: env(safe-area-inset-top) 12px 0;\n    display: flex;\n    align-items: center;\n    background: var(--pp-surface);\n    border-bottom: 1px solid var(--pp-border);\n    position: relative;\n    z-index: 2;\n}\n.pp-title {\n    flex: 1;\n    text-align: center;\n    font-size: 17px;\n    font-weight: 500;\n    margin: 0;\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n.pp-nav-spacer {\n    width: 44px;\n    flex: none;\n}\n.pp-panel button {\n    font: inherit;\n    cursor: pointer;\n    border: 0;\n    background: none;\n    color: inherit;\n}\n.pp-panel .pp-back {\n    width: 44px;\n    height: 44px;\n    flex: none;\n    font-size: 34px;\n    line-height: 32px;\n    padding: 0;\n}\n.pp-panel button:disabled {\n    opacity: 0.5;\n    cursor: wait;\n}\n.pp-viewport {\n    position: relative;\n    flex: 1;\n    min-width: 0;\n    min-height: 0;\n    overflow: hidden;\n}\n:root[data-preference-panes-embedded] .pp-header {\n    display: none;\n}\n@supports (height: 100dvh) {\n    .pp-panel {\n        height: 100dvh;\n    }\n}\n.pp-fields,\n.pp-choice-page,\n.pp-settings-page,\n.pp-cache-page {\n    position: absolute;\n    inset: 0;\n    min-width: 0;\n    overflow-x: hidden;\n    overflow-y: auto;\n    padding: 12px max(16px, calc((100% - 688px) / 2)) calc(28px + env(safe-area-inset-bottom) + var(--pp-keyboard-height, 0px));\n    scroll-padding-bottom: var(--pp-keyboard-height, 0px);\n    background: var(--pp-background);\n}\n.pp-choice-link {\n    display: flex;\n    align-items: center;\n    justify-content: flex-end;\n    gap: 8px;\n    max-width: 45%;\n    min-width: 44px;\n    min-height: 44px;\n    padding: 0;\n    text-align: right;\n    flex: 1;\n}\n.pp-summary {\n    color: var(--pp-muted);\n    font-size: 13px;\n    line-height: 18px;\n    display: -webkit-box;\n    -webkit-line-clamp: 2;\n    -webkit-box-orient: vertical;\n    overflow: hidden;\n    overflow-wrap: anywhere;\n}\n.pp-chevron {\n    color: var(--pp-muted);\n    font-size: 22px;\n    flex: none;\n}\n.pp-editor {\n    flex: none;\n    width: 45%;\n    min-width: 0;\n    min-height: 36px;\n    padding: 8px 10px;\n    font: inherit;\n    color: var(--pp-text);\n    background: var(--pp-field);\n    border: 0;\n    border-radius: 6px;\n}\n.pp-panel .pp-multiline {\n    display: block;\n}\n.pp-multiline .pp-editor {\n    width: 100%;\n    margin-top: 10px;\n}\n.pp-panel [hidden] {\n    display: none !important;\n}\n.pp-label {\n    flex: 1;\n    min-width: 0;\n    display: flex;\n    flex-direction: column;\n    align-items: flex-start;\n    margin-right: 16px;\n}\n.pp-field-name {\n    color: var(--pp-text);\n    font-size: 15px;\n}\n.pp-field-description {\n    margin-top: 2px;\n    color: var(--pp-muted);\n    font-size: 12px;\n}\n.pp-group {\n    margin-top: 16px;\n}\n.pp-group-title {\n    margin: 0 0 8px;\n    color: var(--pp-muted);\n    font-size: 15px;\n    font-weight: 400;\n}\n.pp-row {\n    min-width: 0;\n    min-height: 48px;\n    padding: 16px;\n    display: flex;\n    align-items: center;\n    justify-content: space-between;\n    background: var(--pp-surface);\n    border-bottom: 1px solid var(--pp-border);\n}\n.pp-rows > :last-child {\n    border-bottom: 0 !important;\n}\n.pp-switch {\n    flex: none;\n    accent-color: var(--pp-accent);\n}\n.pp-choice {\n    justify-content: space-between;\n    cursor: pointer;\n}\n.pp-choice input {\n    width: 20px;\n    height: 20px;\n    flex: none;\n    accent-color: var(--pp-accent);\n    margin: 0;\n}\n.pp-description {\n    font-size: 12px;\n    line-height: 1.6;\n    color: var(--pp-muted);\n    white-space: pre-wrap;\n    overflow-wrap: anywhere;\n}\n.pp-module-info {\n    display: flex;\n    gap: 12px;\n    margin: 12px 0;\n}\n.pp-module-details {\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n.pp-module-source {\n    color: inherit;\n    text-decoration: underline;\n}\n.pp-status {\n    position: fixed;\n    inset: 0;\n    display: grid;\n    place-content: center;\n    justify-items: center;\n    gap: 12px;\n    min-width: 0;\n    min-height: 0;\n    margin: 0;\n    padding: 24px;\n    color: var(--pp-muted, GrayText);\n    text-align: center;\n    background: var(--pp-background, Canvas);\n}\n.pp-viewport > .pp-status {\n    position: absolute;\n}\n.pp-status-spinner {\n    box-sizing: border-box;\n    width: 28px;\n    height: 28px;\n    border: 3px solid color-mix(in srgb, currentColor 25%, transparent);\n    border-top-color: var(--pp-accent, AccentColor);\n    border-radius: 50%;\n    animation: pp-status-spin 0.8s linear infinite;\n}\n.pp-status-message {\n    max-width: 100%;\n    margin: 0;\n    overflow-wrap: anywhere;\n}\n.pp-status-action {\n    min-width: 96px;\n    min-height: 44px;\n    padding: 8px 16px;\n    border: 0;\n    border-radius: 6px;\n    color: var(--pp-text, ButtonText);\n    font: inherit;\n    cursor: pointer;\n    background: var(--pp-surface, ButtonFace);\n}\n@keyframes pp-status-spin {\n    to {\n        transform: rotate(1turn);\n    }\n}\n.pp-cache {\n    white-space: pre-wrap;\n    overflow-wrap: anywhere;\n}\n.pp-toast {\n    pointer-events: none;\n    position: fixed;\n    bottom: calc(30px + env(safe-area-inset-bottom));\n    left: 50%;\n    transform: translateX(-50%);\n    max-width: 90vw;\n    padding: 10px 16px;\n    border-radius: 8px;\n    background: #333e;\n    color: white;\n    font-size: 13px;\n    z-index: 20;\n}\n.pp-toast[data-kind=\"error\"] {\n    background: #8d2424;\n}\n.pp-panel :focus-visible {\n    outline: 2px solid var(--pp-accent);\n    outline-offset: -2px;\n}\n";
+var defaults = "/* 通用默认样式只使用 pp 命名空间；项目可通过 CSS 输入覆盖变量和组件。\n * Generic defaults use only the pp namespace; projects may override variables and components through CSS input. */\n.pp-panel {\n    --pp-text: #18191c;\n    --pp-background: #f6f7f8;\n    --pp-surface: #fff;\n    --pp-field: #f1f2f3;\n    --pp-border: #e3e5e7;\n    --pp-muted: #797f87;\n    --pp-accent: #1677ff;\n    font:\n        15px / 1.5 -apple-system,\n        BlinkMacSystemFont,\n        \"Segoe UI\",\n        sans-serif;\n    color: var(--pp-text);\n    background: var(--pp-background);\n    position: relative;\n    display: flex;\n    flex-direction: column;\n    width: 100%;\n    max-width: 100vw;\n    min-width: 0;\n    height: 100vh;\n    overflow: hidden;\n}\n\n:root[data-theme=\"dark\"] .pp-panel {\n    --pp-text: #f1f2f3;\n    --pp-background: #0d0e0f;\n    --pp-surface: #18191c;\n    --pp-field: #2f3238;\n    --pp-border: #2f3238;\n    --pp-muted: #9499a0;\n}\n.pp-panel * {\n    box-sizing: border-box;\n    letter-spacing: 0;\n}\n.pp-header {\n    flex: none;\n    height: calc(52px + env(safe-area-inset-top));\n    padding: env(safe-area-inset-top) 12px 0;\n    display: flex;\n    align-items: center;\n    background: var(--pp-surface);\n    border-bottom: 1px solid var(--pp-border);\n    position: relative;\n    z-index: 2;\n}\n.pp-title {\n    flex: 1;\n    text-align: center;\n    font-size: 17px;\n    font-weight: 500;\n    margin: 0;\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n.pp-nav-spacer {\n    width: 44px;\n    flex: none;\n}\n.pp-panel button {\n    font: inherit;\n    cursor: pointer;\n    border: 0;\n    background: none;\n    color: inherit;\n}\n.pp-panel .pp-back {\n    width: 44px;\n    height: 44px;\n    flex: none;\n    font-size: 34px;\n    line-height: 32px;\n    padding: 0;\n}\n.pp-panel button:disabled {\n    opacity: 0.5;\n    cursor: wait;\n}\n.pp-viewport {\n    position: relative;\n    flex: 1;\n    min-width: 0;\n    min-height: 0;\n    overflow: hidden;\n}\n@supports (height: 100dvh) {\n    .pp-panel {\n        height: 100dvh;\n    }\n}\n.pp-fields,\n.pp-choice-page,\n.pp-settings-page,\n.pp-cache-page {\n    position: absolute;\n    inset: 0;\n    min-width: 0;\n    overflow-x: hidden;\n    overflow-y: auto;\n    padding: 12px max(16px, calc((100% - 688px) / 2)) calc(28px + env(safe-area-inset-bottom) + var(--pp-keyboard-height, 0px));\n    scroll-padding-bottom: var(--pp-keyboard-height, 0px);\n    background: var(--pp-background);\n}\n.pp-choice-link {\n    display: flex;\n    align-items: center;\n    justify-content: flex-end;\n    gap: 8px;\n    max-width: 45%;\n    min-width: 44px;\n    min-height: 44px;\n    padding: 0;\n    text-align: right;\n    flex: 1;\n}\n.pp-summary {\n    color: var(--pp-muted);\n    font-size: 13px;\n    line-height: 18px;\n    display: -webkit-box;\n    -webkit-line-clamp: 2;\n    -webkit-box-orient: vertical;\n    overflow: hidden;\n    overflow-wrap: anywhere;\n}\n.pp-chevron {\n    color: var(--pp-muted);\n    font-size: 22px;\n    flex: none;\n}\n.pp-editor {\n    flex: none;\n    width: 45%;\n    min-width: 0;\n    min-height: 36px;\n    padding: 8px 10px;\n    font: inherit;\n    color: var(--pp-text);\n    background: var(--pp-field);\n    border: 0;\n    border-radius: 6px;\n}\n.pp-panel .pp-multiline {\n    display: block;\n}\n.pp-multiline .pp-editor {\n    width: 100%;\n    margin-top: 10px;\n}\n.pp-panel [hidden] {\n    display: none !important;\n}\n.pp-label {\n    flex: 1;\n    min-width: 0;\n    display: flex;\n    flex-direction: column;\n    align-items: flex-start;\n    margin-right: 16px;\n}\n.pp-field-name {\n    color: var(--pp-text);\n    font-size: 15px;\n}\n.pp-field-description {\n    margin-top: 2px;\n    color: var(--pp-muted);\n    font-size: 12px;\n}\n.pp-group {\n    margin-top: 16px;\n}\n.pp-group-title {\n    margin: 0 0 8px;\n    color: var(--pp-muted);\n    font-size: 15px;\n    font-weight: 400;\n}\n.pp-row {\n    min-width: 0;\n    min-height: 48px;\n    padding: 16px;\n    display: flex;\n    align-items: center;\n    justify-content: space-between;\n    background: var(--pp-surface);\n    border-bottom: 1px solid var(--pp-border);\n}\n.pp-rows > :last-child {\n    border-bottom: 0 !important;\n}\n.pp-switch {\n    flex: none;\n    accent-color: var(--pp-accent);\n}\n.pp-choice {\n    justify-content: space-between;\n    cursor: pointer;\n}\n.pp-choice input {\n    width: 20px;\n    height: 20px;\n    flex: none;\n    accent-color: var(--pp-accent);\n    margin: 0;\n}\n.pp-description {\n    font-size: 12px;\n    line-height: 1.6;\n    color: var(--pp-muted);\n    white-space: pre-wrap;\n    overflow-wrap: anywhere;\n}\n.pp-module-info {\n    display: flex;\n    gap: 12px;\n    margin: 12px 0;\n}\n.pp-module-details {\n    min-width: 0;\n    overflow-wrap: anywhere;\n}\n.pp-module-source {\n    color: inherit;\n    text-decoration: underline;\n}\n.pp-status {\n    position: fixed;\n    inset: 0;\n    display: grid;\n    place-content: center;\n    justify-items: center;\n    gap: 12px;\n    min-width: 0;\n    min-height: 0;\n    margin: 0;\n    padding: 24px;\n    color: var(--pp-muted, GrayText);\n    text-align: center;\n    background: var(--pp-background, Canvas);\n}\n.pp-viewport > .pp-status {\n    position: absolute;\n}\n.pp-status-spinner {\n    box-sizing: border-box;\n    width: 28px;\n    height: 28px;\n    border: 3px solid color-mix(in srgb, currentColor 25%, transparent);\n    border-top-color: var(--pp-accent, AccentColor);\n    border-radius: 50%;\n    animation: pp-status-spin 0.8s linear infinite;\n}\n.pp-status-message {\n    max-width: 100%;\n    margin: 0;\n    overflow-wrap: anywhere;\n}\n.pp-status-action {\n    min-width: 96px;\n    min-height: 44px;\n    padding: 8px 16px;\n    border: 0;\n    border-radius: 6px;\n    color: var(--pp-text, ButtonText);\n    font: inherit;\n    cursor: pointer;\n    background: var(--pp-surface, ButtonFace);\n}\n@keyframes pp-status-spin {\n    to {\n        transform: rotate(1turn);\n    }\n}\n.pp-cache {\n    white-space: pre-wrap;\n    overflow-wrap: anywhere;\n}\n.pp-toast {\n    pointer-events: none;\n    position: fixed;\n    bottom: calc(30px + env(safe-area-inset-bottom));\n    left: 50%;\n    transform: translateX(-50%);\n    max-width: 90vw;\n    padding: 10px 16px;\n    border-radius: 8px;\n    background: #333e;\n    color: white;\n    font-size: 13px;\n    z-index: 20;\n}\n.pp-toast[data-kind=\"error\"] {\n    background: #8d2424;\n}\n.pp-panel :focus-visible {\n    outline: 2px solid var(--pp-accent);\n    outline-offset: -2px;\n}\n";
 
 const selector = "style[data-preference-panes-defaults]";