@nsnanocat/preference-panes 1.2.4 → 1.3.0

package/dist/module/index.html

@@ -1,16 +1,15 @@
 <!doctype html>
-<html lang="zh-CN">
+<html lang="zh-CN" class="pp-page">
     <head>
         <meta charset="utf-8">
         <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
         <meta name="color-scheme" content="light dark">
         
         <title>Module Preferences</title>
-        <style>body { margin: 0; }</style>
         
     </head>
     <body>
         <main id="preferences"></main>
-        <script type="module" src="/settings/assets/index.mjs?v=1.2.4"></script>
+        <script type="module" src="/settings/assets/index.mjs?v=1.3.0"></script>
     </body>
 </html>

package/dist/module/index.mjs

@@ -27,6 +27,7 @@ function normalizeBoxJs(config, module) {
         if (!app || !Array.isArray(app.settings)) throw new TypeError("Expected BoxJS settings array");
         for (const entry of app.settings) {
             if (typeof entry.id !== "string") throw new TypeError("BoxJS settings require string IDs");
+            entry.id = entry.id.replace(/\[(0|[1-9]\d*)\]$/, ".$1");
             if (!entry.id.startsWith("@")) {
                 if (Array.isArray(document)) throw new TypeError("BoxJS settings require @root.path IDs");
                 continue;
@@ -68,7 +69,7 @@ function normalizeBoxJs(config, module) {
         };
         if (type === "select" && !["string", "number", "boolean"].includes(field.type)) throw new TypeError(`Select requires a scalar val: ${entry.id}`);
         if (entry.items) field.options = entry.items.map(item => ({ key: item.key, label: item.label }));
-        if (Object.hasOwn(entry, "val")) field.defaultValue = normalizeStoredValue(field, entry.val);
+        if (Object.prototype.hasOwnProperty.call(entry, "val")) field.defaultValue = normalizeStoredValue(field, entry.val);
         if (
             typeof field.name !== "string" ||
             (field.placeholder !== undefined && typeof field.placeholder !== "string") ||
@@ -78,18 +79,42 @@ function normalizeBoxJs(config, module) {
         )
             throw new TypeError(`Invalid or overlapping BoxJS field: ${entry.id}`);
         if (field.options && (new Set(field.options.map(item => item.key)).size !== field.options.length || field.options.some(item => !scalar(item.key) || typeof item.label !== "string"))) throw new TypeError(`Invalid options: ${entry.id}`);
-        if (Object.hasOwn(field, "defaultValue") && !validValue(field, field.defaultValue)) throw new TypeError(`Invalid BoxJS val: ${entry.id}`);
-        if (field.control === "url" && !Object.hasOwn(field, "defaultValue")) throw new TypeError(`URL BoxJS settings require a val: ${entry.id}`);
+        if (Object.prototype.hasOwnProperty.call(field, "defaultValue") && !validValue(field, field.defaultValue)) throw new TypeError(`Invalid BoxJS val: ${entry.id}`);
+        if (field.control === "url" && !Object.prototype.hasOwnProperty.call(field, "defaultValue")) throw new TypeError(`URL BoxJS settings require a val: ${entry.id}`);
         fields.push(field);
     }
     if (!fields.length) throw new TypeError(`No BoxJS settings for module: ${target.module}`);
-    const common = fields[0].key.split(".").slice(0, -1);
+    for (const field of fields) {
+        const indexed = /^(.*)\.(\d+)$/.exec(field.key);
+        if (!indexed) continue;
+        const siblings = fields.filter(candidate => candidate.key.startsWith(`${indexed[1]}.`) && /^\d+$/.test(candidate.key.slice(indexed[1].length + 1)));
+        if (fields.some(candidate => candidate.key.startsWith(`${indexed[1]}.`) && !siblings.includes(candidate))) throw new TypeError(`Indexed settings cannot mix array entries and named children: ${indexed[1]}`);
+        if (siblings.some(candidate => !Object.prototype.hasOwnProperty.call(candidate, "defaultValue")) || !siblings.some(candidate => candidate.key === `${indexed[1]}.${siblings.length - 1}`) || siblings.some(candidate => Number(candidate.key.slice(indexed[1].length + 1)) >= siblings.length))
+            throw new TypeError(`Indexed settings require contiguous indices and defaults: ${indexed[1]}`);
+    }
+    const owner = target.owners.size === 1 ? [...target.owners][0] : undefined;
+    const cachePath = owner?.cachePath ?? `@${target.storageKey}.${target.module}.Caches`;
+    if (typeof cachePath !== "string" || !cachePath.startsWith(`@${target.storageKey}.`)) throw new TypeError("cachePath must use the module storage root");
+    const cacheParts = validatePathParts(cachePath.slice(target.storageKey.length + 2).split("."));
+    if (cacheParts.length !== 2 || cacheParts[1] !== "Caches") throw new TypeError("cachePath must identify a module Caches subtree");
+    if (owner?.resetPaths !== undefined) {
+        if (!Array.isArray(owner.resetPaths) || !owner.resetPaths.length) throw new TypeError("resetPaths must be a nonempty array");
+        for (const path of owner.resetPaths) {
+            if (typeof path !== "string" || !path.startsWith(`@${target.storageKey}.${target.module}.Settings.`)) throw new TypeError("resetPaths must stay in this module's Settings");
+            validatePathParts(path.slice(target.storageKey.length + 2).split("."));
+        }
+        if (fields.some(field => !owner.resetPaths.some(path => `@${target.storageKey}.${field.key}` === path || `@${target.storageKey}.${field.key}`.startsWith(`${path}.`)))) throw new TypeError("resetPaths must cover the page settings");
+    }
+    const firstIndexed = /^(.*)\.(\d+)$/.exec(fields[0].key);
+    const common = (firstIndexed ? firstIndexed[1] : fields[0].key).split(".").slice(0, -1);
     for (const field of fields) while (!field.key.startsWith(`${common.join(".")}.`)) common.pop();
     return {
         module: target.module,
         storageKey: target.storageKey,
         fields,
         settingsPath: common,
+        ...(owner?.cachePath === undefined ? {} : { cachePath }),
+        ...(owner?.resetPaths === undefined ? {} : { resetPaths: [...owner.resetPaths] }),
         ...(Object.keys(metadata).length ? { metadata } : {}),
     };
 }
@@ -179,9 +204,14 @@ function scalar(value) {
  * @returns {boolean} 是否可由控件表示 / Whether the control can represent the value.
  */
 function validValueShape(field, value) {
-    if (field.type === "array") {
-        if (!Array.isArray(value) || value.some(item => !scalar(item)) || new Set(value).size !== value.length) return false;
-    } else if (typeof value !== field.type || !scalar(value)) return false;
+    switch (field.type) {
+        case "array":
+            if (!Array.isArray(value) || value.some(item => !scalar(item)) || new Set(value).size !== value.length) return false;
+            break;
+        default:
+            if (typeof value !== field.type || !scalar(value)) return false;
+            break;
+    }
     if (field.control === "url" && (!/^[a-z][a-z\d+.-]*:/i.test(value) || /^(?:javascript|data|vbscript):/i.test(value))) return false;
     return true;
 }
@@ -211,7 +241,7 @@ function resolveStoredValue(field, stored) {
     if (value === undefined) return {};
     if (!validValueShape(field, value)) {
         return {
-            ...(Object.hasOwn(field, "defaultValue") ? { value: field.defaultValue } : {}),
+            ...(Object.prototype.hasOwnProperty.call(field, "defaultValue") ? { value: field.defaultValue } : {}),
             warning: { kind: "invalid-value", values: [stored] },
         };
     }
@@ -497,6 +527,7 @@ class PreferencesClient {
     #values = {};
     #warnings = {};
     #saving = false;
+    #arrays = new Map();
 
     /**
      * 创建从 BoxJS 定义读取和持久化设置的页面客户端。
@@ -523,13 +554,22 @@ class PreferencesClient {
         if (!subtree || typeof subtree !== "object" || Array.isArray(subtree)) throw new TypeError("Expected a settings subtree object");
         const values = {};
         const warnings = {};
+        this.#arrays.clear();
         for (const field of this.#definition.fields) {
+            const indexed = /^(.*)\.(\d+)$/.exec(field.key);
+            if (indexed && !this.#arrays.has(indexed[1])) {
+                const storedArray = indexed[1]
+                    .split(".")
+                    .slice(this.#definition.settingsPath.length)
+                    .reduce((parent, part) => Object(parent)[part], subtree);
+                this.#arrays.set(indexed[1], Array.isArray(storedArray) ? [...storedArray] : []);
+            }
             const stored = field.key
                 .split(".")
                 .slice(this.#definition.settingsPath.length)
                 .reduce((parent, part) => Object(parent)[part], subtree);
             const resolved = resolveStoredValue(field, stored);
-            if (Object.hasOwn(resolved, "value")) values[field.key] = resolved.value;
+            if (Object.prototype.hasOwnProperty.call(resolved, "value")) values[field.key] = resolved.value;
             if (resolved.warning) warnings[field.key] = resolved.warning;
         }
         this.#values = values;
@@ -543,7 +583,7 @@ class PreferencesClient {
      * @returns {import("./client.mjs").ModuleSnapshot} 会话快照 / Session snapshot.
      */
     snapshot() {
-        return structuredClone({ definition: this.#definition, values: this.#values, warnings: this.#warnings });
+        return JSON.parse(JSON.stringify({ definition: this.#definition, values: this.#values, warnings: this.#warnings }));
     }
 
     /**
@@ -562,22 +602,23 @@ class PreferencesClient {
      * @returns {Promise<unknown>} Caches 内容或 undefined / Caches content or undefined.
      */
     async readCaches() {
-        const response = await this.#send("get", `@${this.#definition.storageKey}.${this.#module}.Caches`);
+        const response = await this.#send("get", this.#definition.cachePath ?? `@${this.#definition.storageKey}.${this.#module}.Caches`);
         return response.status === 404 ? undefined : response.json();
     }
 
     /**
-     * 删除当前模块的 Caches 子树。
-     * Delete the current module Caches subtree.
+     * 删除声明的缓存子树，默认当前模块 Caches。
+     * Delete the declared cache subtree, defaulting to the current module Caches.
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     clearCaches() {
-        return this.#change("delete", `${this.#module}.Caches`, undefined, "clearCaches");
+        const path = this.#definition.cachePath?.slice(this.#definition.storageKey.length + 2) ?? `${this.#module}.Caches`;
+        return this.#change("delete", path, undefined, "clearCaches");
     }
 
     /**
-     * 删除当前模块数据并恢复页面默认值。
-     * Delete current module data and restore page defaults.
+     * 删除声明的设置子树，默认删除当前模块数据，并恢复页面默认值。
+     * Delete declared settings subtrees, defaulting to current module data, and restore page defaults.
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     reset() {
@@ -658,30 +699,49 @@ class PreferencesClient {
         if (this.#saving) throw new Error("A settings write is already in progress");
         this.#saving = true;
         try {
-            let field;
-            if (operation === "write" || operation === "delete") {
-                field = this.#definition.fields.find(candidate => candidate.key === key);
-                if (!field || (operation === "write" && !validValue(field, value))) throw new TypeError("Invalid setting value");
-            }
-            await this.#send(action, `@${this.#definition.storageKey}.${key}`, value);
             switch (operation) {
                 case "write":
-                    this.#values[key] = structuredClone(value);
-                    delete this.#warnings[key];
-                    break;
                 case "delete": {
-                    delete this.#values[key];
-                    delete this.#warnings[key];
-                    if (Object.hasOwn(field, "defaultValue")) this.#values[key] = structuredClone(field.defaultValue);
+                    const field = this.#definition.fields.find(candidate => candidate.key === key);
+                    if (!field || (operation === "write" && !validValue(field, value))) throw new TypeError("Invalid setting value");
+                    const indexed = /^(.*)\.(\d+)$/.exec(key);
+                    if (indexed) {
+                        const array = [...(this.#arrays.get(indexed[1]) ?? [])];
+                        for (const sibling of this.#definition.fields) {
+                            if (sibling.key.startsWith(`${indexed[1]}.`) && /^\d+$/.test(sibling.key.slice(indexed[1].length + 1))) {
+                                const index = Number(sibling.key.slice(indexed[1].length + 1));
+                                if (array[index] === undefined) array[index] = this.#values[sibling.key] ?? sibling.defaultValue;
+                            }
+                        }
+                        array[Number(indexed[2])] = operation === "delete" ? field.defaultValue : value;
+                        await this.#send("set", `@${this.#definition.storageKey}.${indexed[1]}`, array);
+                        this.#arrays.set(indexed[1], array);
+                    } else await this.#send(action, `@${this.#definition.storageKey}.${key}`, value);
+                    switch (operation) {
+                        case "write":
+                            this.#values[key] = JSON.parse(JSON.stringify(value));
+                            delete this.#warnings[key];
+                            break;
+                        case "delete":
+                            delete this.#values[key];
+                            delete this.#warnings[key];
+                            if (Object.prototype.hasOwnProperty.call(field, "defaultValue")) this.#values[key] = JSON.parse(JSON.stringify(field.defaultValue));
+                            break;
+                    }
                     break;
                 }
                 case "clearCaches":
+                    await this.#send(action, `@${this.#definition.storageKey}.${key}`, value);
                     break;
                 case "reset":
+                    if (this.#definition.resetPaths) {
+                        for (const path of this.#definition.resetPaths) await this.#send("delete", path);
+                    } else await this.#send(action, `@${this.#definition.storageKey}.${key}`, value);
+                    this.#arrays.clear();
                     this.#warnings = {};
                     for (const field of this.#definition.fields) {
                         delete this.#values[field.key];
-                        if (Object.hasOwn(field, "defaultValue")) this.#values[field.key] = structuredClone(field.defaultValue);
+                        if (Object.prototype.hasOwnProperty.call(field, "defaultValue")) this.#values[field.key] = JSON.parse(JSON.stringify(field.defaultValue));
                     }
                     break;
             }
@@ -962,17 +1022,17 @@ class PreferencesPanel {
         const notify = event => {
             if (destroyed) return;
             let message;
-            switch (true) {
-                case event.kind === "error":
+            switch (event.kind === "error" ? "error" : event.operation) {
+                case "error":
                     message = `操作失败：${event.message}`;
                     break;
-                case event.operation === "delete":
+                case "delete":
                     message = "删除成功";
                     break;
-                case event.operation === "clearCaches":
+                case "clearCaches":
                     message = "Caches 已清空";
                     break;
-                case event.operation === "reset":
+                case "reset":
                     message = "设置已重置";
                     break;
                 default:
@@ -1095,21 +1155,6 @@ class PreferencesPanel {
                     });
                 return queue;
             }
-            const metadata = definition.metadata;
-            if (metadata) {
-                const info = element("div", "pp-module-info");
-                const details = element("div", "pp-module-details");
-                for (const description of [metadata.author, metadata.desc ?? metadata.description, ...(metadata.descs ?? [])]) if (description) details.append(element("p", "pp-description", description));
-                if (metadata.repo) {
-                    const link = element("a", "pp-module-source", "项目主页");
-                    link.href = resourceURL(metadata.repo);
-                    link.target = "_blank";
-                    link.rel = "noopener noreferrer";
-                    details.append(link);
-                }
-                info.append(details);
-                view.append(info);
-            }
             for (const field of definition.fields) {
                 const match = /^\[([^\]]+)\]\s*(.*)$/.exec(field.name);
                 const group = match?.[1] ?? "通用";
@@ -1150,8 +1195,8 @@ class PreferencesPanel {
                 let write;
                 let inputContainer = row;
                 let eventName = "change";
-                switch (true) {
-                    case field.control === "url": {
+                switch (field.control === "url" ? "url" : field.options ? (field.type === "array" ? "checkboxes" : "selects") : field.type) {
+                    case "url": {
                         const link = element("a", "pp-choice-link", "打开");
                         link.setAttribute("aria-label", field.name);
                         link.rel = "noopener noreferrer";
@@ -1167,7 +1212,7 @@ class PreferencesPanel {
                         });
                         break;
                     }
-                    case Boolean(field.options) && field.type !== "array": {
+                    case "selects": {
                         const select = element("select", "");
                         select.setAttribute("aria-label", field.name);
                         field.options.forEach((option, index) => {
@@ -1182,7 +1227,7 @@ class PreferencesPanel {
                         read = () => field.options[select.selectedIndex]?.key;
                         break;
                     }
-                    case field.type === "array" && Boolean(field.options): {
+                    case "checkboxes": {
                         const page = element("section", "pp-choice-page");
                         if (field.description) page.append(element("p", "pp-description", field.description));
                         const choices = element("div", "pp-rows");
@@ -1226,7 +1271,7 @@ class PreferencesPanel {
                         };
                         break;
                     }
-                    case field.type === "boolean": {
+                    case "boolean": {
                         const toggle = element("input", "pp-switch");
                         toggle.type = "checkbox";
                         toggle.setAttribute("switch", "");
@@ -1264,7 +1309,12 @@ class PreferencesPanel {
                             growingInputs.push(grow);
                         }
                         eventName = "input";
-                        if (!multiline) input.type = field.type === "number" ? "number" : "text";
+                        if (!multiline) {
+                            input.type = field.type === "number" ? "number" : "text";
+                            input.autocapitalize = "off";
+                            input.setAttribute("autocorrect", "off");
+                            input.spellcheck = false;
+                        }
                         write = value => {
                             input.value = field.type === "array" ? JSON.stringify(value ?? []) : (value ?? "");
                             grow();
@@ -1366,7 +1416,9 @@ class PreferencesPanel {
             });
             handlers.set("clearCaches", async () => {
                 if (saving) return;
-                if (!(await requestConfirmation(window, `清空 ${active} 的全部 Caches？`)) || destroyed || saving) return;
+                const shared = definition.cachePath && definition.cachePath !== `@${definition.storageKey}.${active}.Caches`;
+                const message = shared ? `清空共享缓存 ${definition.cachePath}？使用该缓存的其它模块也会受影响。` : `清空 ${active} 的全部 Caches？`;
+                if (!(await requestConfirmation(window, message)) || destroyed || saving) return;
                 return perform(
                     () => client.clearCaches(),
                     () => {
@@ -1376,7 +1428,8 @@ class PreferencesPanel {
             });
             handlers.set("reset", async () => {
                 if (saving) return;
-                if (!(await requestConfirmation(window, `重置 ${active} 的设置？这将删除该模块的 Settings、Caches 和其它持久化数据。`)) || destroyed || saving) return;
+                const message = definition.resetPaths ? `重置 ${definition.metadata?.name ?? active} 的设置？只删除本页面的设置，保留共享存储中的其它设置和缓存。` : `重置 ${active} 的设置？这将删除该模块的 Settings、Caches 和其它持久化数据。`;
+                if (!(await requestConfirmation(window, message)) || destroyed || saving) return;
                 return perform(() => client.reset(), controls);
             });
             navigation?.destroy();
@@ -1419,7 +1472,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    --pp-warning: #9a6700;\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    --pp-warning: #f0b849;\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-panel a.pp-choice-link {\n    color: var(--pp-accent);\n    text-decoration: none;\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-field-warning {\n    margin-top: 4px;\n    color: var(--pp-warning);\n    font-size: 12px;\n    overflow-wrap: anywhere;\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:root {\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    --pp-warning: #9a6700;\n    --pp-host-height: 0px;\n    --pp-keyboard-height: 0px;\n}\n.pp-panel {\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\"] {\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    --pp-warning: #f0b849;\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-panel a.pp-choice-link {\n    color: var(--pp-accent);\n    text-decoration: none;\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    font-size: 16px;\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-field-warning {\n    margin-top: 4px;\n    color: var(--pp-warning);\n    font-size: 12px;\n    overflow-wrap: anywhere;\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 var(--pp-border, #8884);\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\n/* 首页沿用表单的分组与说明样式，入口按屏幕宽度自动换行。\n * The landing page reuses form groups and descriptions, with entries wrapping by viewport width. */\n:root.pp-page {\n    color-scheme: light dark;\n}\n.pp-page body {\n    margin: 0;\n    font:\n        16px / 1.5 -apple-system,\n        BlinkMacSystemFont,\n        \"Segoe UI\",\n        sans-serif;\n    background: var(--pp-background, Canvas);\n    color: var(--pp-text, CanvasText);\n}\n[data-preference-panes-pages] {\n    position: relative;\n    min-height: calc(100vh - var(--pp-host-height));\n    background: inherit;\n}\n[data-preference-panes-module-page],\n[data-preference-panes-link-page] {\n    position: fixed;\n    inset: var(--pp-host-height) 0 0;\n    background: inherit;\n    z-index: 1;\n    box-shadow: -8px 0 24px #00000014;\n}\n[data-preference-panes-module-page] iframe,\n[data-preference-panes-link-page] iframe {\n    display: block;\n    border: 0;\n    width: 100%;\n    height: 100%;\n    background: inherit;\n}\n[data-module-message] {\n    position: absolute;\n    inset: 0;\n    margin: 0;\n    padding: 20px;\n    background: inherit;\n}\n[data-module-message][hidden] {\n    display: none;\n}\n.pp-host-header {\n    position: sticky;\n    top: 0;\n    z-index: 2;\n    display: grid;\n    grid-template-columns: 44px minmax(0, 1fr) 44px;\n    align-items: center;\n    min-height: 44px;\n    padding: env(safe-area-inset-top) max(12px, env(safe-area-inset-right)) 0 max(12px, env(safe-area-inset-left));\n    border-bottom: 1px solid var(--pp-border, #8884);\n    background: var(--pp-surface, Canvas);\n    color: var(--pp-accent, Highlight);\n    font-size: 17px;\n}\n.pp-host-title {\n    text-align: center;\n    color: var(--pp-text, CanvasText);\n    font-weight: 600;\n    overflow: hidden;\n    text-overflow: ellipsis;\n    white-space: nowrap;\n}\n.pp-host-back {\n    border: 0;\n    background: none;\n    color: inherit;\n    width: 44px;\n    height: 44px;\n    padding: 8px;\n    font:\n        32px / 1 -apple-system,\n        sans-serif;\n    cursor: pointer;\n}\n.pp-host-back[hidden] {\n    visibility: hidden;\n    display: block;\n}\n.pp-host-toast {\n    position: fixed;\n    z-index: 3;\n    bottom: calc(24px + env(safe-area-inset-bottom) + var(--pp-keyboard-height));\n    left: 50%;\n    transform: translateX(-50%);\n    max-width: calc(100% - 48px);\n    padding: 10px 18px;\n    border-radius: 12px;\n    background: #222e;\n    color: #fff;\n    font-size: 14px;\n    text-align: center;\n}\n.pp-host-toast[hidden] {\n    display: none;\n}\n.pp-host-error {\n    margin: 24px;\n    padding: 16px;\n    border: 1px solid var(--pp-danger, #e45656);\n    border-radius: 12px;\n    font-size: 16px;\n    overflow-wrap: anywhere;\n}\n\n.pp-home {\n    max-width: 1000px;\n    margin: auto;\n    padding: 24px max(16px, env(safe-area-inset-right)) calc(24px + env(safe-area-inset-bottom)) max(16px, env(safe-area-inset-left));\n}\n.pp-home-logo {\n    display: block;\n    width: 64px;\n    height: 64px;\n    margin: 0 auto 24px;\n    object-fit: contain;\n}\n.pp-home-entries {\n    display: flex;\n    flex-wrap: wrap;\n    justify-content: space-around;\n    row-gap: 16px;\n    padding: 16px 0;\n    background: var(--pp-surface);\n}\n.pp-home-item {\n    box-sizing: border-box;\n    display: flex;\n    flex-direction: column;\n    align-items: center;\n    width: 25%;\n    min-width: 0;\n    padding: 0 4px;\n    border: 0;\n    background: none;\n    color: var(--pp-text);\n    font:\n        12px / 1.5 -apple-system,\n        sans-serif;\n    cursor: pointer;\n    text-decoration: none;\n}\n@media (min-width: 500px) {\n    .pp-home-item {\n        width: calc(100% / 6);\n    }\n}\n@media (min-width: 700px) {\n    .pp-home-item {\n        width: 12.5%;\n    }\n}\n.pp-home-icon {\n    box-sizing: border-box;\n    width: 56px;\n    height: 56px;\n    padding: 8px;\n    border-radius: 50%;\n    background: var(--pp-field);\n    font-size: 32px;\n    line-height: 40px;\n}\n.pp-home-icon img {\n    display: block;\n    width: 100%;\n    height: 100%;\n    object-fit: contain;\n}\n.pp-home-name {\n    margin-top: 8px;\n}\n.pp-home-content {\n    min-width: 0;\n    width: 100%;\n}\n.pp-home-content > span {\n    display: block;\n}\n.pp-home-name,\n.pp-home-item [data-module-status] {\n    width: 100%;\n    overflow: hidden;\n    text-align: center;\n    text-overflow: ellipsis;\n    white-space: nowrap;\n}\n.pp-home-item [data-module-status] {\n    min-height: 20px;\n}\n.pp-home-item:disabled {\n    opacity: 0.45;\n    cursor: default;\n}\n.pp-home-entries[data-layout=\"list\"] {\n    display: block;\n    padding: 0;\n}\n.pp-home-entries[data-layout=\"list\"] .pp-home-item {\n    flex-direction: row;\n    gap: 12px;\n    width: 100%;\n    padding: 12px 16px;\n    font-size: 15px;\n}\n.pp-home-entries[data-layout=\"list\"] .pp-home-item + .pp-home-item {\n    border-top: 1px solid var(--pp-border);\n}\n.pp-home-entries[data-layout=\"list\"] .pp-home-icon {\n    flex: none;\n    width: 40px;\n    height: 40px;\n    padding: 4px;\n    font-size: 24px;\n    line-height: 32px;\n}\n.pp-home-entries[data-layout=\"list\"] .pp-home-name {\n    margin-top: 0;\n    text-align: left;\n}\n.pp-home-arrow {\n    color: var(--pp-muted);\n    font-size: 24px;\n}\n.pp-home-footer {\n    margin-top: 16px;\n    text-align: center;\n    white-space: normal;\n}\n.pp-home-footer p {\n    margin: 8px 0 0;\n}\n";
 
 const selector = "style[data-preference-panes-defaults]";
 const stylesheetSelector = "link[data-preference-panes-stylesheet]";
@@ -1574,7 +1627,22 @@ class ModulePage {
             const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(this.#window.location.pathname);
             const module = embedded ?? match?.[1];
             if (!module) throw new TypeError("Open a concrete module URL");
-            const source = this.#window.document.querySelector('meta[name="preference-panes-boxjs"]')?.content || `/api/${encodeURIComponent(module)}`;
+            const frame = this.#window.frameElement?.dataset;
+            const base = frame?.preferencePanesBase ?? this.#window.location.href;
+            this.#window.document.querySelector("link[data-preference-panes-stylesheet]")?.remove();
+            const stylesheetSource = frame?.preferencePanesStylesheet ?? new URLSearchParams(this.#window.location.search).get("css")?.trim();
+            if (stylesheetSource) {
+                const stylesheet = new URL(stylesheetSource, base);
+                if (!["http:", "https:"].includes(stylesheet.protocol)) throw new TypeError("CSS resource must use HTTP(S)");
+                const link = this.#window.document.createElement("link");
+                link.dataset.preferencePanesStylesheet = "true";
+                link.rel = "stylesheet";
+                link.href = stylesheet.href;
+                this.#window.document.head.append(link);
+            }
+            const jsonSource = frame?.preferencePanesJson ?? new URLSearchParams(this.#window.location.search).get("json")?.trim();
+            const source = new URL(jsonSource || `/api/${encodeURIComponent(module)}`, base);
+            if (!["http:", "https:"].includes(source.protocol)) throw new TypeError("BoxJS resource must use HTTP(S)");
             const response = await fetch(source, { cache: "no-store", credentials: "omit", headers: { Accept: "application/json" } });
             if (response.status !== 200) throw new Error(`HTTP ${response.status}`);
             const boxjs = await response.json();

package/dist/module/navigation.mjs

@@ -147,8 +147,8 @@ class ActionMenu {
 }
 
 /**
- * 模块文档容器：发送 GET 请求并将原始 HTML 交给 iframe，只在元素上标记模块身份。
- * Module document container: send a GET request, preserve HTML verbatim and mark only the module identity on the iframe.
+ * 模块文档容器：获取静态 HTML，并通过 iframe 数据属性传递页面资源输入。
+ * Module document container: fetch static HTML and pass page resource inputs through iframe data attributes.
  */
 class ModuleFrame extends EventTarget {
     #url;
@@ -178,11 +178,27 @@ class ModuleFrame extends EventTarget {
         this.#url = new URL(url, document.baseURI);
         const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(this.#url.pathname);
         if (!match) throw new TypeError("Open a concrete module URL");
-        this.#options = { signal: options.signal, headers: options.headers };
+        this.#options = { signal: options.signal };
         this.element = document.createElement("iframe");
         this.element.title = `${match[1]} 设置`;
         this.element.dataset.preferencePanes = "true";
         this.element.dataset.preferencePanesModule = match[1];
+        this.element.dataset.preferencePanesBase = this.#url.href;
+        const headers = new Headers(options.headers);
+        for (const [header, property, kind] of [
+            ["X-PreferencePanes-JSON", "preferencePanesJson", "BoxJS"],
+            ["X-PreferencePanes-CSS", "preferencePanesStylesheet", "CSS"],
+        ]) {
+            if (!headers.has(header)) continue;
+            const source = headers.get(header)?.trim();
+            if (!source) {
+                if (kind === "BoxJS") throw new TypeError("BoxJS resource URL is required");
+                continue;
+            }
+            const resource = new URL(source, this.#url);
+            if (!["http:", "https:"].includes(resource.protocol)) throw new TypeError(`${kind} resource must use HTTP(S)`);
+            this.element.dataset[property] = resource.href;
+        }
         this.element.addEventListener("preferencepanes:change", this.#change);
         this.element.addEventListener("preferencepanes:confirm", this.#confirmation);
         this.element.addEventListener("preferencepanes:notice", this.#notice);
@@ -208,10 +224,10 @@ class ModuleFrame extends EventTarget {
         if (this.#options.signal?.aborted) this.destroy();
         const timer = setTimeout(() => this.#controller.abort(), 10000);
         try {
-            const response = await fetch(this.#url, { method: "GET", cache: "no-store", credentials: "omit", headers: this.#options.headers, signal: this.#controller.signal });
+            const response = await fetch(this.#url, { method: "GET", cache: "no-store", credentials: "omit", signal: this.#controller.signal });
             if (response.status !== 200) throw new Error(`HTTP ${response.status}`);
             const html = await response.text();
-            this.#controller.signal.throwIfAborted();
+            if (this.#controller.signal.aborted) throw new DOMException("The operation was aborted", "AbortError");
             this.element.srcdoc = html;
         } finally {
             clearTimeout(timer);