@nsnanocat/preference-panes 0.9.16 → 1.0.0

package/src/browser/client.mjs

@@ -1,219 +1,101 @@
-import { normalizeBoxJs, normalizeStoredValue, validValue } from "../lib/boxjs.mjs";
-
 /**
- * 单个模块的临时会话；离开页面后丢弃。
- * Transient module session discarded when leaving the page.
- * @typedef {object} ModuleSession
- * @property {AbortController} controller 读取请求的取消控制器 / Abort controller for reads.
- * @property {import("../index.js").ModuleDefinition | null} definition 加载完成的配置，加载中为 null / Loaded configuration, or null while loading.
- * @property {import("./client.mjs").ModuleSnapshot["values"]} values 当前显示值 / Current display values.
- * @property {boolean} saving 是否正在写入 / Whether a mutation is in progress.
+ * 创建单模块页面客户端；只调用模块 API，不读取或解析 BoxJS。
+ * Create a single-module page client that only calls the module API and never reads or parses BoxJS.
+ * @param {import("./client.mjs").PreferencesClientOptions} options API 模型、请求与通知 / API model, requests and notifications.
+ * @returns {import("./client.mjs").PreferencesClient} 页面客户端 / Page client.
  */
+export function createPreferencesClient({ model, definition, fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 }) {
+    const { module, configURL } = model;
+    const session = new AbortController();
+    const values = structuredClone(model.values);
+    let saving = false;
 
-/**
- * 创建页面会话缓存；打开时重读，选项操作仅在 HTTP 200 后更新缓存。
- * Create a page-session cache; reload on open and mutate cache only after HTTP 200.
- * @param {import("./client.mjs").PreferencesClientOptions} options 包内目录、请求与通知 / Internal catalog, requests and notifications.
- * @returns {import("./client.mjs").PreferencesClient} 通用客户端 / Generic client.
- */
-export function createPreferencesClient({ catalog, fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 }) {
     /**
-     * 模块会话表
-     * Module session map.
-     * @type {Map<string, ModuleSession>}
+     * 向模块 API 发送 JSON 动作。
+     * Send a JSON action to the module API.
+     * @param {"get" | "set" | "delete"} action 模块动作 / Module action.
+     * @param {unknown} payload JSON 请求体 / JSON request body.
+     * @returns {Promise<Response>} 原始响应 / Raw response.
      */
-    const sessions = new Map();
-    /**
-     * 用 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, action, body, signal) {
+    async function send(action, payload) {
         const controller = new AbortController();
         const abort = () => controller.abort();
-        if (signal?.aborted) abort();
-        signal?.addEventListener("abort", abort, { once: true });
+        if (session.signal.aborted) abort();
+        session.signal.addEventListener("abort", abort, { once: true });
         const timer = setTimeout(abort, timeout);
         try {
-            const response = await request(`/api/${action}`, {
+            const response = await request(`/api/${encodeURIComponent(module)}/${action}`, {
                 method: "POST",
                 credentials: "omit",
                 cache: "no-store",
                 signal: controller.signal,
-                headers: { "Content-Type": "application/x-www-form-urlencoded" },
-                body: new URLSearchParams([[path, action === "set" ? JSON.stringify(body) : ""]]).toString(),
+                headers: { "Content-Type": "application/json", "X-PreferencePanes-JSON": configURL },
+                body: JSON.stringify(payload),
             });
             if (response.status !== 200 && !(action === "get" && response.status === 404)) throw new Error(`HTTP ${response.status}`);
             return response;
         } finally {
             clearTimeout(timer);
-            signal?.removeEventListener("abort", abort);
+            session.signal.removeEventListener("abort", abort);
         }
     }
+
     /**
-     * 获取独立快照，避免调用方修改内部缓存。
-     * Return an independent snapshot so callers cannot mutate the cache.
-     * @param {string} module 已打开模块 / Open module.
-     * @returns {import("./client.mjs").ModuleSnapshot} 会话快照 / Session snapshot.
-     * @throws {Error} 模块未完成加载 / Module has not finished loading.
-     */
-    const snapshot = module => {
-        const state = sessions.get(module);
-        if (!state?.definition) throw new Error("Open the module first");
-        return structuredClone({ definition: state.definition, values: state.values });
-    };
-    /**
-     * 串行修改单键，仅成功后更新仍存活的会话。
-     * 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 {"set" | "delete"} action 写入或删除 / Write or delete.
-     * @param {unknown} value 写入值，删除时忽略 / Write value, ignored for deletion.
-     * @param {"write" | "delete" | "clearCaches" | "reset"} [operation] 操作类型 / Operation kind.
+     * 执行写入动作；成功后只更新当前页面值。
+     * Execute a mutation and update only the current page values after success.
+     * @param {"set" | "delete"} action API 动作 / API action.
+     * @param {unknown} payload JSON 请求体 / JSON request body.
+     * @param {"write" | "delete" | "clearCaches" | "reset"} operation 通知操作 / Notification operation.
+     * @param {string} [key] 字段路径 / Field path.
      * @returns {Promise<void>} 操作完成 / Operation completion.
-     * @throws {Error} 会话、字段、值或请求错误 / Session, field, value or request error.
      */
-    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;
+    async function change(action, payload, operation, key) {
+        if (saving) throw new Error("A settings write is already in progress");
+        saving = true;
         try {
-            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":
-                        state.values[key] = structuredClone(value);
-                        break;
-                    case "delete":
-                    case "clearCaches":
-                    case "reset":
-                        for (const candidate of state.definition.fields) {
-                            if (candidate.key !== key && !candidate.key.startsWith(`${key}.`)) continue;
-                            delete state.values[candidate.key];
-                            if (Object.hasOwn(candidate, "defaultValue")) state.values[candidate.key] = structuredClone(candidate.defaultValue);
-                        }
-                        break;
+            await send(action, payload);
+            switch (operation) {
+                case "write":
+                    values[key] = structuredClone(payload.value);
+                    break;
+                case "delete": {
+                    const field = definition.fields.find(candidate => candidate.key === key);
+                    delete values[key];
+                    if (field && Object.hasOwn(field, "defaultValue")) values[key] = structuredClone(field.defaultValue);
+                    break;
                 }
+                case "clearCaches":
+                    break;
+                case "reset":
+                    for (const field of definition.fields) {
+                        delete values[field.key];
+                        if (Object.hasOwn(field, "defaultValue")) values[field.key] = structuredClone(field.defaultValue);
+                    }
+                    break;
             }
             notify({ kind: "success", operation, module, key });
         } catch (error) {
             notify({ kind: "error", operation, module, key, message: error.message });
             throw error;
         } finally {
-            state.saving = false;
+            saving = false;
         }
     }
+
     return {
-        /**
-         * 从已导入的 JSON 创建新会话，只读取一次设置值。
-         * Create a session from imported JSON and read stored settings once.
-         * @param {string} module 模块标识 / Module identifier.
-         * @returns {Promise<import("./client.mjs").ModuleSnapshot>} 新快照 / New snapshot.
-         * @throws {Error} 读取失败、会话被替换或写入尚未完成 / Read failure, replaced session or unfinished write.
-         */
-        async open(module) {
-            const binding = catalog.modules.get(module);
-            if (!binding) throw new TypeError(`No BoxJS settings for module: ${module}`);
-            const previous = sessions.get(module);
-            if (previous?.saving) throw new Error("Cannot refresh while saving");
-            previous?.controller.abort();
-            const state = { controller: new AbortController(), definition: null, values: {}, saving: false };
-            sessions.set(module, state);
-            try {
-                const definition = normalizeBoxJs(catalog, module);
-                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");
-                if (sessions.get(module) !== state) throw new Error("Module session was replaced");
-                state.definition = definition;
-                for (const field of definition.fields) {
-                    const stored = field.key
-                        .split(".")
-                        .slice(definition.settingsPath.length)
-                        .reduce((parent, part) => Object(parent)[part], subtree);
-                    const value = stored === undefined ? field.defaultValue : stored;
-                    if (value !== undefined) state.values[field.key] = normalizeStoredValue(field, value);
-                }
-                return snapshot(module);
-            } catch (error) {
-                if (sessions.get(module) === state) sessions.delete(module);
-                throw error;
-            }
-        },
-        snapshot,
-        /**
-         * 按需重新读取模块 Settings，不更新页面会话缓存。
-         * Reread module Settings on demand without updating the page-session cache.
-         * @param {string} module 已打开的模块 / Open module.
-         * @returns {Promise<unknown>} 设置值，缺失为 undefined / Settings value, or undefined when absent.
-         */
-        async readSettings(module) {
-            const state = sessions.get(module);
-            if (!state?.definition) throw new Error("Open the module first");
-            const response = await send(`@${state.definition.storageKey}.${state.definition.settingsPath.join(".")}`, "get", undefined, state.controller.signal);
+        snapshot: () => structuredClone({ definition, values }),
+        async readSettings() {
+            const response = await send("get", { scope: "settings" });
             return response.status === 404 ? undefined : response.json();
         },
-        /**
-         * 按需读取模块 Caches，不自动读取其它设置。
-         * Read module Caches on demand without refreshing other settings.
-         * @param {string} module 已打开的模块 / Open module.
-         * @returns {Promise<unknown>} 缓存值，缺失为 undefined / Cache value, or undefined when absent.
-         */
-        async readCaches(module) {
-            const state = sessions.get(module);
-            if (!state?.definition) throw new Error("Open the module first");
-            const response = await send(`@${state.definition.storageKey}.${module}.Caches`, "get", undefined, state.controller.signal);
+        async readCaches() {
+            const response = await send("get", { scope: "caches" });
             return response.status === 404 ? undefined : response.json();
         },
-        /**
-         * 删除整个 Caches 节点，成功后不追加 GET。
-         * Delete the entire Caches node without a follow-up GET.
-         * @param {string} module 已打开模块 / Open module.
-         * @returns {Promise<void>} 清理完成 / Cleanup completion.
-         */
-        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"),
-        /**
-         * 取消读取并清除会话，不撤销已发送的写入。
-         * Abort reads and clear the session without undoing dispatched writes.
-         * @param {string} module 模块标识 / Module identifier.
-         * @returns {void} 无返回值 / No return value.
-         */
-        leave(module) {
-            sessions.get(module)?.controller.abort();
-            sessions.delete(module);
-        },
-        /**
-         * 写入单键并更新当前会话。
-         * Write one key and update the current session.
-         * @param {string} module 已打开模块 / Open module.
-         * @param {string} key 点分字段路径 / Dotted field path.
-         * @param {import("../index.js").SettingsScalar | import("../index.js").SettingsScalar[]} value 字段值 / Field value.
-         * @returns {Promise<void>} 写入完成 / Write completion.
-         */
-        set: (module, key, value) => change(module, key, "set", value),
-        /**
-         * 删除单键覆盖值并显示默认值。
-         * Delete one override and display its default value.
-         * @param {string} module 已打开模块 / Open module.
-         * @param {string} key 点分字段路径 / Dotted field path.
-         * @returns {Promise<void>} 删除完成 / Delete completion.
-         */
-        remove: (module, key) => change(module, key, "delete"),
+        clearCaches: () => change("delete", { scope: "caches" }, "clearCaches"),
+        reset: () => change("delete", { scope: "module" }, "reset"),
+        leave: () => session.abort(),
+        set: (key, value) => change("set", { key, value }, "write", key),
+        remove: key => change("delete", { key }, "delete", key),
     };
 }

package/src/browser/index.d.ts

@@ -1,22 +1,18 @@
-import type { BoxJSInput } from "../index.js";
+import type { ModuleModel } from "../index.js";
 
 /**
  * 具体模块设置页的生命周期句柄。
  * Lifecycle handle for a concrete module settings page.
  */
 export interface MountedPreferences {
-    /**
-     * 移除页面、样式、监听器和临时会话。
-     * Remove the page, styles, listeners and transient sessions.
-     * @returns 无返回值 / No return value.
-     */
+    /** 移除页面、样式和监听器 / Remove page, styles and listeners. */
     destroy(): void;
 }
 /**
- * 仅以 BoxJS 和可选 CSS 挂载一个模块页，不生成项目主页。
- * Mount one module page using BoxJS and optional CSS, without a project landing page.
- * @param boxjs 恰好包含一个模块的 BoxJS JSON / BoxJS JSON describing exactly one module.
- * @param css 可选 CSS 正文；默认样式始终内置 / Optional CSS text; default styles are built in.
+ * 使用模块 API 返回的模型挂载设置页；CSS 仅覆盖当前模块。
+ * Mount a settings page from a module API model; CSS only overrides this module.
+ * @param model 模块 API 模型 / Module API model.
+ * @param css 可选 CSS 正文 / Optional CSS text.
  * @returns 生命周期句柄 / Lifecycle handle.
  */
-export function mount(boxjs: BoxJSInput, css?: string): MountedPreferences;
+export function mount(model: ModuleModel, css?: string): MountedPreferences;

package/src/browser/index.mjs

@@ -1,4 +1,4 @@
-import { BoxJS } from "../BoxJS.mjs";
+import { normalizeBoxJs, normalizeStoredValue, validValue } from "./boxjs.mjs";
 import { element, resourceURL } from "./components.mjs";
 import { mountPanel } from "./panel.mjs";
 import { installDefaultStyles } from "./styles.mjs";
@@ -6,14 +6,22 @@ import { installDefaultStyles } from "./styles.mjs";
 /**
  * 挂载模块设置页；默认样式由包提供，可选 CSS 仅作用于当前模块。
  * Mount a module page with package defaults and optional module-scoped CSS.
- * @param {import("../index.js").BoxJSInput} boxjs 单个模块的 BoxJS JSON / BoxJS JSON for one module.
+ * @param {import("../index.js").ModuleModel} model API 返回的模块模型 / Module model returned by the API.
  * @param {string} [css] 可选 CSS 正文 / Optional CSS text.
  * @returns {import("./index.js").MountedPreferences} 模块生命周期句柄 / Module lifecycle handle.
  */
-export function mount(boxjs, css = "") {
+export function mount(model, css = "") {
     if (typeof css !== "string") throw new TypeError("CSS must be a string");
-    const catalog = boxjs instanceof BoxJS ? boxjs : new BoxJS(boxjs);
-    const metadata = catalog.module.metadata;
+    const definition = normalizeBoxJs(model.boxjs, model.module);
+    const values = { ...model.values };
+    for (const field of definition.fields) {
+        if (values[field.key] === undefined) continue;
+        values[field.key] = normalizeStoredValue(field, values[field.key]);
+        if (!validValue(field, values[field.key])) throw new TypeError(`Invalid stored value: ${field.key}`);
+    }
+    for (const field of definition.fields) if (values[field.key] === undefined && Object.hasOwn(field, "defaultValue")) values[field.key] = structuredClone(field.defaultValue);
+    const rendered = { ...model, definition, values };
+    const metadata = definition.metadata ?? {};
     const image = metadata.icon || metadata.icons?.[1] || metadata.icons?.[0];
     if (image) resourceURL(image);
     if (metadata.repo) resourceURL(metadata.repo);
@@ -49,7 +57,7 @@ export function mount(boxjs, css = "") {
         observer = new MutationObserver(syncAppearance);
         observer.observe(host, { attributes: true, attributeFilter: ["data-theme", "style"] });
     }
-    document.title = metadata.name ?? catalog.module.module;
+    document.title = metadata.name ?? definition.module;
     let panel;
     const view = {
         /**
@@ -73,7 +81,7 @@ export function mount(boxjs, css = "") {
     };
     try {
         root.replaceChildren();
-        panel = mountPanel(root, catalog);
+        panel = mountPanel(root, rendered);
         return view;
     } catch (error) {
         view.destroy();

package/src/browser/panel.mjs

@@ -1,21 +1,23 @@
 import { ActionMenu } from "./ActionMenu.mjs";
+import { validValue } from "./boxjs.mjs";
 import { createPreferencesClient } from "./client.mjs";
 import { fieldControl, element as node, requestConfirmation, resourceURL, settingRow, statusView } from "./components.mjs";
 import { Navigation } from "./Navigation.mjs";
 
 /**
- * 挂载已导入 BoxJS 对应的模块表单和短暂通知。
- * Mount the imported BoxJS module form and transient notifications.
+ * 挂载 API 返回的模块模型表单和短暂通知。
+ * Mount the module model returned by the API and transient notifications.
  * @param {HTMLElement} root 包内挂载元素 / Internal mount element.
- * @param {import("../BoxJS.mjs").BoxJS} catalog 包内 BoxJS 目录 / Internal BoxJS catalog.
+ * @param {import("../index.js").ModuleModel} model API 返回的模块模型 / Module model returned by the API.
  * @returns {import("./index.js").MountedPreferences} 面板生命周期句柄 / Panel lifecycle handle.
  */
-export function mountPanel(root, catalog) {
-    const title = catalog.module.metadata.name ?? catalog.module.module;
+export function mountPanel(root, model) {
+    const { definition } = model;
+    const title = definition.metadata?.name ?? definition.module;
     const document = root.ownerDocument;
     const window = document.defaultView;
     const shell = node("div", "pp-panel");
-    shell.dataset.module = catalog.module.module;
+    shell.dataset.module = definition.module;
     const header = node("header", "pp-header");
     const back = node("button", "pp-back", "‹");
     back.setAttribute("aria-label", "返回");
@@ -45,7 +47,7 @@ export function mountPanel(root, catalog) {
         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, actions },
+                detail: { title: heading.textContent, module: definition.module, busy: saving, canGoBack: !back.disabled, actions },
             }),
         );
     };
@@ -102,7 +104,7 @@ export function mountPanel(root, catalog) {
             toast.hidden = true;
         }, 2400);
     };
-    const client = createPreferencesClient({ catalog, notify });
+    const client = createPreferencesClient({ model, definition, notify });
     /**
      * 两种菜单入口共用异步错误处理，包含宿主确认框错误。
      * Share async error handling between both menus, including host-dialog errors.
@@ -130,7 +132,6 @@ export function mountPanel(root, catalog) {
         publishNavigation();
         viewport.replaceChildren(statusView("读取设置…"));
         try {
-            await client.open(module);
             if (version === generation) controls();
         } catch (error) {
             if (version !== generation) return;
@@ -144,7 +145,7 @@ export function mountPanel(root, catalog) {
      * @returns {void} 无返回值 / No return value.
      */
     function controls() {
-        const { definition, values } = client.snapshot(active);
+        const { definition, values } = client.snapshot();
         heading.textContent = definition.metadata?.name || active;
         const view = node("section", "pp-fields");
         /**
@@ -182,7 +183,7 @@ export function mountPanel(root, catalog) {
             saving = true;
             back.disabled = true;
             publishNavigation();
-            return (queue = queue
+            queue = queue
                 .then(action)
                 .then(() => {
                     if (!destroyed) success();
@@ -195,10 +196,11 @@ export function mountPanel(root, catalog) {
                 .finally(() => {
                     pendingWrites--;
                     saving = pendingWrites > 0;
-                    if (destroyed && !saving) client.leave(active);
+                    if (destroyed && !saving) client.leave();
                     back.disabled = saving || !navigation.canGoBack;
                     publishNavigation();
-                }));
+                });
+            return queue;
         }
         const metadata = definition.metadata;
         if (metadata) {
@@ -276,7 +278,7 @@ export function mountPanel(root, catalog) {
                     link.append(summary, node("span", "pp-chevron", "›"));
                     row.append(link);
                     const refresh = () => {
-                        const value = client.snapshot(active).values[field.key];
+                        const value = client.snapshot().values[field.key];
                         summary.textContent =
                             field.options
                                 .filter(option => Array.isArray(value) && value.includes(option.key))
@@ -377,10 +379,17 @@ export function mountPanel(root, catalog) {
                     return;
                 }
                 const restore = () => {
-                    if (version === inputVersion) write(client.snapshot(module).values[field.key]);
+                    if (version === inputVersion) write(client.snapshot().values[field.key]);
                 };
                 perform(
-                    () => client.set(module, field.key, value),
+                    () => {
+                        if (!validValue(field, value)) {
+                            const error = new TypeError("Invalid setting value");
+                            notify({ kind: "error", operation: "write", module, key: field.key, message: error.message });
+                            throw error;
+                        }
+                        return client.set(field.key, value);
+                    },
                     () => {
                         for (const refresh of summaries) refresh();
                     },
@@ -401,7 +410,7 @@ export function mountPanel(root, catalog) {
             return perform(
                 async () => {
                     try {
-                        value = await client.readSettings(active);
+                        value = await client.readSettings();
                     } catch (error) {
                         notify({ kind: "error", message: error.message });
                         throw error;
@@ -425,7 +434,7 @@ export function mountPanel(root, catalog) {
             return perform(
                 async () => {
                     try {
-                        value = await client.readCaches(active);
+                        value = await client.readCaches();
                     } catch (error) {
                         notify({ kind: "error", message: error.message });
                         throw error;
@@ -441,7 +450,7 @@ export function mountPanel(root, catalog) {
             if (saving) return;
             if (!(await requestConfirmation(window, `清空 ${active} 的全部 Caches？`)) || destroyed || saving) return;
             return perform(
-                () => client.clearCaches(active),
+                () => client.clearCaches(),
                 () => {
                     output.textContent = "暂无缓存";
                 },
@@ -450,7 +459,7 @@ export function mountPanel(root, catalog) {
         handlers.set("reset", async () => {
             if (saving) return;
             if (!(await requestConfirmation(window, `重置 ${active} 的设置？这将删除该模块的 Settings、Caches 和其它持久化数据。`)) || destroyed || saving) return;
-            return perform(() => client.reset(active), controls);
+            return perform(() => client.reset(), controls);
         });
         navigation?.destroy();
         navigation = new Navigation(viewport, view, key => editors.get(key)?.node);
@@ -468,7 +477,7 @@ export function mountPanel(root, catalog) {
         if (navigation) navigation.back();
         else window.history.back();
     };
-    open(catalog.module.module);
+    open(definition.module);
     return {
         /**
          * 移除监听器、定时器、会话和挂载内容。
@@ -481,7 +490,7 @@ export function mountPanel(root, catalog) {
             window.frameElement?.removeEventListener("preferencepanes:action", onAction);
             navigation?.destroy();
             generation++;
-            if (active && !saving) client.leave(active);
+            if (active && !saving) client.leave();
             clearTimeout(timer);
             shell.remove();
         },

package/src/build.mjs

@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { BoxJS } from "./BoxJS.mjs";
+import { normalizeBoxJs } from "./browser/boxjs.mjs";
 
 /**
  * 仅生成模块前端文件，不复制配置或生成绑定业务的读写脚本。
@@ -10,8 +10,7 @@ import { BoxJS } from "./BoxJS.mjs";
  */
 export async function build(boxjs, css = "") {
     if (typeof css !== "string") throw new TypeError("CSS must be a string");
-    const catalog = new BoxJS(boxjs);
-    const module = catalog.module.module;
+    const module = normalizeBoxJs(boxjs).module;
     const [html, app] = await Promise.all([readFile(new URL("../dist/module/index.html", import.meta.url), "utf8"), readFile(new URL("../dist/module/app.mjs", import.meta.url), "utf8")]);
     return {
         [`settings/${module}/index.html`]: html,

package/src/index.d.ts

@@ -92,8 +92,8 @@ export interface SettingsRequest {
      */
     headers?: Record<string, string | undefined>;
     /**
-     * POST 的正文为一个 form 字段，字段名是完整 @root.path
-     * POST contains one form field whose name is the complete @root.path.
+     * 模块动作的 JSON 正文
+     * JSON body for a module action.
      */
     body?: string;
 }
@@ -268,6 +268,20 @@ export interface BoxJSSubscription extends BoxJSMetadata {
  * The sole data configuration input.
  */
 export type BoxJSInput = BoxJSSetting[] | BoxJSApp | BoxJSSubscription;
+/**
+ * 模块 API 返回的原始 BoxJS 与当前值模型。
+ * Raw BoxJS and current-value model returned by the module API.
+ */
+export interface ModuleModel {
+    /** 模块路径段 / Module path segment. */
+    module: string;
+    /** API 获取的原始 BoxJS JSON / Raw BoxJS JSON fetched by the API. */
+    boxjs: BoxJSInput;
+    /** API 读取到的原始已保存字段值 / Raw persisted field values read by the API. */
+    values: Record<string, JsonValue>;
+    /** 后续 API 动作使用的 BoxJS JSON 地址 / BoxJS JSON URL used by later API actions. */
+    configURL: string;
+}
 /**
  * 生成模块前端文件，不复制配置、不生成绑定模块的代理脚本。
  * Build module frontend files without copying configuration or producing bound proxy scripts.

package/src/web.mjs

@@ -0,0 +1,52 @@
+import { URL } from "@nsnanocat/url";
+import { $app } from "@nsnanocat/util/lib/app.mjs";
+import { done } from "@nsnanocat/util/lib/done.mjs";
+import assets from "#assets";
+import { pageInputs } from "./lib/page-inputs.mjs";
+
+/**
+ * 返回模块页面及其公共浏览器资源，不处理 API、网络或持久化。
+ * Serve module pages and common browser assets without handling APIs, network access or persistence.
+ * @returns {void} 响应已交给代理宿主 / Response delivered to the proxy host.
+ */
+function run() {
+    const request = globalThis.$request;
+    let result;
+    try {
+        const url = new URL(request.url);
+        if (/^\/settings\/[a-zA-Z0-9_-]+\/?$/.test(url.pathname)) {
+            if (!["GET", "HEAD"].includes(request.method)) result = response(request, 405, { error: "Method not allowed" });
+            else {
+                const inputs = encodeURIComponent(JSON.stringify(pageInputs(url, request.headers)));
+                result = response(request, 200, assets.page.body.replace("</head>", `<meta name="preference-panes-inputs" content="${inputs}"></head>`), "text/html");
+            }
+        } else {
+            const asset = assets[url.pathname];
+            if (asset) result = ["GET", "HEAD"].includes(request.method) ? response(request, 200, asset.body, asset.type) : response(request, 405, { error: "Method not allowed" });
+        }
+    } catch (error) {
+        console.error(`PreferencePanes Web: ${error.message}`);
+        result = response(request, 500, { error: error.message });
+    }
+    if (!result) done({});
+    else done($app === "Quantumult X" ? result : { response: result });
+}
+
+/**
+ * 构造静态资源响应，HEAD 请求不返回正文。
+ * Build a static resource response without a body for HEAD requests.
+ * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
+ * @param {number} status HTTP 状态 / HTTP status.
+ * @param {unknown} body 响应正文 / Response body.
+ * @param {string} [type] 媒体类型 / Media type.
+ * @returns {import("./index.js").SettingsResponse} 静态资源响应 / Static resource response.
+ */
+function response(request, status, body, type = "application/json") {
+    return {
+        status,
+        headers: { "Content-Type": `${type}; charset=utf-8`, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" },
+        body: request.method === "HEAD" ? "" : type === "application/json" ? JSON.stringify(body) : body,
+    };
+}
+
+run();