@nsnanocat/preference-panes 0.7.1 → 0.8.0

package/dist/module/app.mjs

@@ -1,11 +1,3 @@
-/**
- * 解析已经取得的 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.
- */
-
 /**
  * 校验原始路径片段，不进行 URL 编码转换。
  * Validate raw path segments without URL encoding conversion.
@@ -116,7 +108,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 };
 }
@@ -181,7 +173,7 @@ function errorView(error, retry) {
     return view;
 }
 
-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@supports (height: 100dvh) {\n    .pp-viewport {\n        height: calc(100dvh - 52px - env(safe-area-inset-top));\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    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";
 
 /**
  * 将 BoxJS 数组、app 或订阅转换为模块字段，保留原文件为唯一字段来源。
@@ -322,31 +314,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);
@@ -370,21 +362,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":
@@ -427,7 +419,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");
@@ -457,7 +449,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();
         },
         /**
@@ -466,14 +458,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.
@@ -492,7 +484,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.
@@ -500,7 +492,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"),
     };
 }
 
@@ -694,6 +686,17 @@ function mountPanel(root, catalog) {
     header.append(back, brand, element("span", "pp-nav-spacer"));
     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 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 },
+            }),
+        );
+    };
     let timer,
         navigation,
         generation = 0,
@@ -744,6 +747,7 @@ function mountPanel(root, catalog) {
         active = module;
         back.disabled = window.history.length <= 1;
         heading.textContent = module;
+        publishNavigation();
         viewport.replaceChildren(element("p", "pp-loading", "读取设置…"));
         try {
             await client.open(module);
@@ -751,6 +755,7 @@ function mountPanel(root, catalog) {
         } catch (error) {
             if (version !== generation) return;
             viewport.replaceChildren(errorView(error, () => open(module)));
+            publishNavigation();
         }
     }
     /**
@@ -782,6 +787,7 @@ function mountPanel(root, catalog) {
             const editor = editors.get(navigation.current);
             heading.textContent = editor?.title ?? definition.metadata?.name ?? active;
             back.disabled = saving || !navigation.canGoBack;
+            publishNavigation();
         };
         /**
          * 串行执行模块操作，保持输入可编辑。
@@ -795,6 +801,7 @@ function mountPanel(root, catalog) {
             pendingWrites++;
             saving = true;
             back.disabled = true;
+            publishNavigation();
             return (queue = queue
                 .then(action)
                 .then(() => {
@@ -810,6 +817,7 @@ function mountPanel(root, catalog) {
                     saving = pendingWrites > 0;
                     if (destroyed && !saving) client.leave(active);
                     back.disabled = saving || !navigation.canGoBack;
+                    publishNavigation();
                 }));
         }
         const metadata = definition.metadata;
@@ -1148,7 +1156,19 @@ async function start() {
         view?.destroy();
         view = undefined;
         const context = document.querySelector('meta[name="preference-panes-inputs"]');
-        const inputs = context ? JSON.parse(decodeURIComponent(context.content)) : pageInputs(new URL(location.href));
+        const embedded = window.frameElement?.dataset.preferencePanes;
+        let inputs;
+        switch (true) {
+            case embedded !== undefined:
+                inputs = JSON.parse(embedded);
+                document.documentElement.dataset.preferencePanesEmbedded = "";
+                break;
+            case context !== null:
+                inputs = JSON.parse(decodeURIComponent(context.content));
+                break;
+            default:
+                inputs = pageInputs(new URL(location.href));
+        }
         const resources = [inputs.json, inputs.css].map(source => {
             if (!source) return null;
             const url = new URL(source, inputs.url);

package/dist/module/index.html

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

package/dist/module/navigation.mjs

@@ -1,3 +1,103 @@
+/**
+ * 统一解析模块页的资源地址：Header 优先于查询参数，再使用模块约定。
+ * Resolve module resource locations: headers override query parameters and module conventions.
+ * @param {URL} url 已解析的页面请求地址 / Parsed page request URL.
+ * @param {Record<string, string | undefined>} [headers] 请求头，名称不区分大小写 / Case-insensitive request headers.
+ * @returns {{url: string, module: string, json: string, css: string}} 页面上下文与两个资源输入 / Page context and two resource inputs.
+ */
+function pageInputs(url, headers = {}) {
+    const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(url.pathname);
+    if (!match) throw new TypeError("Open a concrete module URL");
+    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") ?? "";
+    if (!json.trim()) throw new TypeError("JSON resource URL is required");
+    return { url: url.href, module, json, css };
+}
+
+/**
+ * 模块文档容器：原始 HTML 不改写，请求上下文随 iframe 元素传递。
+ * Module document container: preserve HTML verbatim and carry request context on the iframe element.
+ */
+class ModuleFrame extends EventTarget {
+    #url;
+    #options;
+    #controller = new AbortController();
+    #abort = () => this.destroy();
+    #state;
+    #change = event => {
+        this.#state = event.detail;
+        this.dispatchEvent(new Event("change"));
+    };
+
+    /**
+     * 建立 iframe 与请求输入；调用方挂载 element 后调用 load。
+     * Create the iframe and request inputs; callers mount element and then call load.
+     * @param {string | URL} url 模块请求地址 / Module request URL.
+     * @param {RequestInit} [options] 原生请求头和取消信号 / Native headers and cancellation signal.
+     */
+    constructor(url, options = {}) {
+        super();
+        this.#url = new URL(url, document.baseURI);
+        this.#options = { ...options, headers: new Headers(options.headers) };
+        const inputs = pageInputs(this.#url, Object.fromEntries(this.#options.headers));
+        this.element = document.createElement("iframe");
+        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 };
+        options.signal?.addEventListener("abort", this.#abort, { once: true });
+    }
+
+    /**
+     * 当前模块导航状态。
+     * Current module navigation state.
+     */
+    get state() {
+        return { ...this.#state };
+    }
+
+    /**
+     * 获取原始 HTML；晚到响应在退出后不得重新挂载。
+     * Fetch unmodified HTML; a late response must not remount after departure.
+     * @returns {Promise<void>} HTML 已交给 iframe；表单状态通过 change 事件提供 / HTML assigned; form state is reported through change.
+     */
+    async load() {
+        if (this.#options.signal?.aborted) this.destroy();
+        const timer = setTimeout(() => this.#controller.abort(), 10000);
+        try {
+            const response = await fetch(this.#url, { cache: "no-store", credentials: "omit", ...this.#options, signal: this.#controller.signal });
+            if (response.status !== 200) throw new Error(`HTTP ${response.status}`);
+            const html = await response.text();
+            this.#controller.signal.throwIfAborted();
+            this.element.srcdoc = html;
+        } finally {
+            clearTimeout(timer);
+        }
+    }
+
+    /**
+     * 使用 iframe 的联合历史返回；写入期间不导航。
+     * Navigate joint iframe history back, except while a write is pending.
+     * @returns {void} 无返回值 / No return value.
+     */
+    back() {
+        if (!this.#state.busy && this.#state.canGoBack) this.element.contentWindow.history.back();
+    }
+
+    /**
+     * 取消加载与事件订阅；节点保留到 Navigation 的退出动画结束。
+     * Cancel loading and subscriptions; Navigation retains the node until its exit animation ends.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#controller.abort();
+        this.#options.signal?.removeEventListener("abort", this.#abort);
+        this.element.removeEventListener("preferencepanes:change", this.#change);
+    }
+}
+
 /**
  * 同一文档内的主页/子页导航；iframe 各自的实例通过浏览器联合历史协作。
  * Navigate home/detail views within a document; iframe instances cooperate through joint browser history.
@@ -157,4 +257,4 @@ class Navigation extends EventTarget {
     }
 }
 
-export { Navigation };
+export { ModuleFrame, 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@supports (height: 100dvh) {\n    .pp-viewport {\n        height: calc(100dvh - 52px - env(safe-area-inset-top));\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    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";
 
 /**
  * 校验原始路径片段，不进行 URL 编码转换。
@@ -304,31 +296,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 +344,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 +401,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 +431,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 +440,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 +466,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 +474,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"),
     };
 }
 
@@ -676,6 +668,17 @@ function mountPanel(root, catalog) {
     header.append(back, brand, element("span", "pp-nav-spacer"));
     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 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 },
+            }),
+        );
+    };
     let timer,
         navigation,
         generation = 0,
@@ -726,6 +729,7 @@ function mountPanel(root, catalog) {
         active = module;
         back.disabled = window.history.length <= 1;
         heading.textContent = module;
+        publishNavigation();
         viewport.replaceChildren(element("p", "pp-loading", "读取设置…"));
         try {
             await client.open(module);
@@ -733,6 +737,7 @@ function mountPanel(root, catalog) {
         } catch (error) {
             if (version !== generation) return;
             viewport.replaceChildren(errorView(error, () => open(module)));
+            publishNavigation();
         }
     }
     /**
@@ -764,6 +769,7 @@ function mountPanel(root, catalog) {
             const editor = editors.get(navigation.current);
             heading.textContent = editor?.title ?? definition.metadata?.name ?? active;
             back.disabled = saving || !navigation.canGoBack;
+            publishNavigation();
         };
         /**
          * 串行执行模块操作，保持输入可编辑。
@@ -777,6 +783,7 @@ function mountPanel(root, catalog) {
             pendingWrites++;
             saving = true;
             back.disabled = true;
+            publishNavigation();
             return (queue = queue
                 .then(action)
                 .then(() => {
@@ -792,6 +799,7 @@ function mountPanel(root, catalog) {
                     saving = pendingWrites > 0;
                     if (destroyed && !saving) client.leave(active);
                     back.disabled = saving || !navigation.canGoBack;
+                    publishNavigation();
                 }));
         }
         const metadata = definition.metadata;

package/package.json

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