@nsnanocat/preference-panes 0.9.15 → 1.0.0

package/dist/preference-panes.mjs

@@ -11,76 +11,178 @@ function validatePathParts(parts) {
 }
 
 /**
- * BoxJS 的共同目录：模块、存储根和展示元数据都来自同一份 JSON。
- * Shared BoxJS catalog deriving modules, storage roots and metadata from one JSON document.
+ * 将 BoxJS 数组、app 或订阅转换为浏览器字段定义。
+ * Normalize a BoxJS array, app or subscription into browser field definitions.
+ * @param {unknown} config 原始 BoxJS JSON / Raw BoxJS JSON.
+ * @param {string} [module] API 模块路径段；省略时要求输入只有一个模块 / API module path segment; omission requires exactly one module.
+ * @returns {import("../index.js").ModuleDefinition} 浏览器字段定义 / Browser field definition.
  */
-class BoxJS {
-    /**
-     * 建立路径索引，不解析控件类型，也不读写持久化存储。
-     * Index field paths without interpreting controls or accessing persistence.
-     * @param {unknown} input 字段数组、单个 app 或 apps 订阅 / Field array, app or apps subscription.
-     */
-    constructor(input) {
-        if (!input || typeof input !== "object") throw new TypeError("Expected BoxJS JSON");
-        const document = JSON.parse(JSON.stringify(input));
-        const apps = Array.isArray(document) ? [{ settings: document }] : (document.apps ?? [document]);
-        if (!Array.isArray(apps)) throw new TypeError("Expected BoxJS apps array");
-        this.modules = new Map();
-        for (const app of apps) {
-            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");
-                if (!entry.id.startsWith("@")) {
-                    if (Array.isArray(document)) throw new TypeError("BoxJS settings require @root.path IDs");
-                    continue;
-                }
-                const [storageKey, ...parts] = entry.id.slice(1).split(".");
-                if (!storageKey || storageKey.startsWith("@") || parts.length < 2) throw new TypeError("A BoxJS setting must be below a literal storage root and module");
-                validatePathParts(parts);
-                const module = parts[0];
-                let target = this.modules.get(module);
-                if (!target) {
-                    target = { module, storageKey, entries: [], owners: new Set() };
-                    this.modules.set(module, target);
-                }
-                if (target.storageKey !== storageKey) throw new TypeError(`A module must use one storage root: ${module}`);
-                target.entries.push(entry);
-                target.owners.add(app);
+function normalizeBoxJs(config, module) {
+    if (!config || typeof config !== "object") throw new TypeError("Expected BoxJS JSON");
+    const document = JSON.parse(JSON.stringify(config));
+    const apps = Array.isArray(document) ? [{ settings: document }] : (document.apps ?? [document]);
+    if (!Array.isArray(apps)) throw new TypeError("Expected BoxJS apps array");
+    const modules = new Map();
+    for (const app of apps) {
+        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");
+            if (!entry.id.startsWith("@")) {
+                if (Array.isArray(document)) throw new TypeError("BoxJS settings require @root.path IDs");
+                continue;
+            }
+            const [storageKey, ...parts] = entry.id.slice(1).split(".");
+            if (!storageKey || storageKey.startsWith("@") || parts.length < 2) throw new TypeError("A BoxJS setting must be below a literal storage root and module");
+            validatePathParts(parts);
+            const name = parts[0];
+            let target = modules.get(name);
+            if (!target) {
+                target = { module: name, storageKey, entries: [], owners: new Set() };
+                modules.set(name, target);
             }
+            if (target.storageKey !== storageKey) throw new TypeError(`A module must use one storage root: ${name}`);
+            target.entries.push(entry);
+            target.owners.add(app);
         }
-        this.metadata = metadata(Array.isArray(document) ? {} : document);
-        for (const target of this.modules.values()) target.metadata = target.owners.size === 1 ? metadata([...target.owners][0]) : {};
     }
+    if (module === undefined && modules.size !== 1) throw new TypeError("Import BoxJS JSON for exactly one module");
+    const target = module === undefined ? modules.values().next().value : modules.get(module);
+    if (!target) throw new TypeError(`No BoxJS settings for module: ${module}`);
+    const metadata = normalizeMetadata(target.owners.size === 1 ? presentation([...target.owners][0]) : {});
+    const fields = [];
+    for (const entry of target.entries) {
+        const parts = entry.id.slice(1).split(".").slice(1);
+        const type = { boolean: "boolean", checkboxes: "array", selects: "select", text: "string", textarea: "string", number: "number" }[entry.type];
+        if (!type) throw new TypeError(`Unsupported BoxJS control: ${entry.type}`);
+        const field = {
+            key: parts.join("."),
+            type: type === "select" ? typeof entry.val : type,
 
-    /**
-     * 取得本次导入的唯一模块，避免把模块数据变成项目目录。
-     * Get the single imported module without turning module data into a project directory.
-     * @returns {object} 唯一模块的目录项 / The single module entry.
-     */
-    get module() {
-        if (this.modules.size !== 1) throw new TypeError("Import BoxJS JSON for exactly one module");
-        return this.modules.values().next().value;
+            name: entry.name,
+            description: entry.desc ?? "",
+            control: entry.type,
+            ...(entry.placeholder === undefined ? {} : { placeholder: entry.placeholder }),
+            ...(entry.rows === undefined ? {} : { rows: entry.rows }),
+            ...(entry.autoGrow === undefined ? {} : { autoGrow: entry.autoGrow }),
+        };
+        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 (
+            typeof field.name !== "string" ||
+            (field.placeholder !== undefined && typeof field.placeholder !== "string") ||
+            (field.rows !== undefined && (!Number.isInteger(field.rows) || field.rows < 1)) ||
+            (field.autoGrow !== undefined && typeof field.autoGrow !== "boolean") ||
+            fields.some(other => other.key === field.key || other.key.startsWith(`${field.key}.`) || field.key.startsWith(`${other.key}.`))
+        )
+            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}`);
+        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) while (!field.key.startsWith(`${common.join(".")}.`)) common.pop();
+    return {
+        module: target.module,
+        storageKey: target.storageKey,
+        fields,
+        settingsPath: common,
+        ...(Object.keys(metadata).length ? { metadata } : {}),
+    };
 }
 
 /**
- * 保留标准 BoxJS 展示信息；script 仅为元数据，不执行。
- * Retain standard BoxJS presentation data; script is metadata only and never executed.
- * @param {object} source BoxJS app 或订阅 / BoxJS app or subscription.
- * @returns {object} 经过类型检查的展示信息 / Type-checked presentation metadata.
+ * 保留字段所属 app 的原始展示信息。
+ * Retain raw presentation metadata from the app owning the fields.
+ * @param {object} source BoxJS app / BoxJS app.
+ * @returns {Record<string, unknown>} 原始展示信息 / Raw presentation metadata.
  */
-function metadata(source) {
+function presentation(source) {
     const result = {};
     for (const key of ["id", "name", "author", "repo", "script", "icon", "description", "desc", "icons", "descs"]) {
         if (source[key] === undefined) continue;
+        result[key] = source[key];
+    }
+    return result;
+}
+
+/**
+ * 校验供浏览器展示的标准 BoxJS 元数据。
+ * Validate standard BoxJS metadata used by the browser renderer.
+ * @param {Record<string, unknown>} source 原始展示元数据 / Raw presentation metadata.
+ * @returns {import("../index.js").BoxJSMetadata} 规范化展示元数据 / Normalized presentation metadata.
+ */
+function normalizeMetadata(source) {
+    const result = {};
+    for (const [key, value] of Object.entries(source)) {
         const multiple = key === "icons" || key === "descs";
-        const values = multiple ? source[key] : [source[key]];
+        const values = multiple ? value : [value];
         if (!Array.isArray(values) || values.some(item => typeof item !== "string")) throw new TypeError(`Invalid BoxJS app ${key}`);
-        result[key] = multiple ? [...values] : source[key];
+        result[key] = multiple ? [...values] : value;
     }
     return result;
 }
 
+/**
+ * 归一化 BoxJS 的字符串存储值，不改变普通文本内容。
+ * Normalize BoxJS string persistence without changing free-text values.
+ * @param {import("../index.js").SettingsField} field 前端字段约束 / Frontend field constraints.
+ * @param {unknown} value 存储值 / Stored value.
+ * @returns {unknown} 转换后的控件值；是否允许写入由 validValue 单独校验 / Converted control value; write eligibility is checked separately by validValue.
+ */
+function normalizeStoredValue(field, value) {
+    switch (field.type) {
+        case "boolean":
+            if (value === "true" || value === "false") return value === "true";
+            break;
+        case "number":
+            if (typeof value === "string" && value.trim() !== "") return Number(value);
+            break;
+        case "array":
+            if (typeof value === "string") value = value === "" || value === "[]" ? [] : value.split(",");
+            break;
+    }
+    if (field.options) {
+        const match = item => field.options.find(option => String(option.key) === String(item))?.key ?? item;
+        return field.type === "array" && Array.isArray(value) ? value.map(match) : match(value);
+    }
+    return value;
+}
+
+/**
+ * 校验支持的标量范围，包括文本长度与数值有限性。
+ * Validate supported scalar bounds, including text length and numeric finiteness.
+ * @param {unknown} value 待检查值 / Value to inspect.
+ * @returns {boolean} 是否为有效标量 / Whether the scalar is valid.
+ */
+function scalar(value) {
+    switch (typeof value) {
+        case "boolean":
+            return true;
+        case "string":
+            return value.length <= 2048;
+        case "number":
+            return Number.isFinite(value);
+        default:
+            return false;
+    }
+}
+
+/**
+ * 检查值类型、数组唯一性及声明的选项，不进行转换。
+ * Check value type, array uniqueness and declared choices without coercion.
+ * @param {import("../index.js").SettingsField} field 前端归一化字段 / Normalized frontend field.
+ * @param {unknown} value 待写入的 JSON 值 / JSON value to write.
+ * @returns {boolean} 是否符合字段约束 / Whether the value satisfies field constraints.
+ */
+function validValue(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;
+    return !field.options || (field.type === "array" ? value : [value]).every(item => field.options.some(option => option.key === item));
+}
+
 /**
  * 创建元素，所有展示文本通过 textContent 写入。
  * Create elements and assign display text through textContent only.
@@ -321,336 +423,104 @@ class ActionMenu {
 }
 
 /**
- * 将 BoxJS 数组、app 或订阅转换为模块字段，保留原文件为唯一字段来源。
- * Normalize a BoxJS array, app or subscription using the source JSON as the field authority.
- * @param {unknown | BoxJS} config BoxJS JSON 或已解析目录 / BoxJS document or parsed catalog.
- * @param {string} module API 第一段模块名 / First API path segment.
- * @returns {import("../index.js").ModuleDefinition} 存储根和字段 / Storage root and fields.
- * @throws {TypeError} 配置结构、字段路径、默认值或展示属性无效 / Invalid configuration, field path, default or presentation attribute.
- */
-function normalizeBoxJs(config, module) {
-    validatePathParts([module]);
-    const catalog = config instanceof BoxJS ? config : new BoxJS(config);
-    const target = catalog.modules.get(module);
-    if (!target) throw new TypeError(`No BoxJS settings for module: ${module}`);
-    const { entries, storageKey, metadata } = target;
-    const fields = [];
-    for (const entry of entries) {
-        const parts = entry.id.slice(1).split(".").slice(1);
-        const type = { boolean: "boolean", checkboxes: "array", selects: "select", text: "string", textarea: "string", number: "number" }[entry.type];
-        if (!type) throw new TypeError(`Unsupported BoxJS control: ${entry.type}`);
-        const field = {
-            key: parts.join("."),
-            type: type === "select" ? typeof entry.val : type,
-
-            name: entry.name,
-            description: entry.desc ?? "",
-            control: entry.type,
-            ...(entry.placeholder === undefined ? {} : { placeholder: entry.placeholder }),
-            ...(entry.rows === undefined ? {} : { rows: entry.rows }),
-            ...(entry.autoGrow === undefined ? {} : { autoGrow: entry.autoGrow }),
-        };
-        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 (
-            typeof field.name !== "string" ||
-            (field.placeholder !== undefined && typeof field.placeholder !== "string") ||
-            (field.rows !== undefined && (!Number.isInteger(field.rows) || field.rows < 1)) ||
-            (field.autoGrow !== undefined && typeof field.autoGrow !== "boolean") ||
-            fields.some(other => other.key === field.key || other.key.startsWith(`${field.key}.`) || field.key.startsWith(`${other.key}.`))
-        )
-            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}`);
-        fields.push(field);
-    }
-    if (!fields.length) throw new TypeError(`No BoxJS settings for module: ${module}`);
-    const common = fields[0].key.split(".").slice(0, -1);
-    for (const field of fields) while (!field.key.startsWith(`${common.join(".")}.`)) common.pop();
-    return {
-        module,
-        storageKey,
-        fields,
-        settingsPath: common,
-        ...(Object.keys(metadata).length ? { metadata } : {}),
-    };
-}
-
-/**
- * 归一化 BoxJS 的字符串存储值，不改变普通文本内容。
- * Normalize BoxJS string persistence without changing free-text values.
- * @param {import("../index.js").SettingsField} field 前端字段约束 / Frontend field constraints.
- * @param {unknown} value 存储值 / Stored value.
- * @returns {unknown} 转换后的控件值；是否允许写入由 validValue 单独校验 / Converted control value; write eligibility is checked separately by validValue.
- */
-function normalizeStoredValue(field, value) {
-    switch (field.type) {
-        case "boolean":
-            if (value === "true" || value === "false") return value === "true";
-            break;
-        case "number":
-            if (typeof value === "string" && value.trim() !== "") return Number(value);
-            break;
-        case "array":
-            if (typeof value === "string") value = value === "" || value === "[]" ? [] : value.split(",");
-            break;
-    }
-    if (field.options) {
-        const match = item => field.options.find(option => String(option.key) === String(item))?.key ?? item;
-        return field.type === "array" && Array.isArray(value) ? value.map(match) : match(value);
-    }
-    return value;
-}
-
-/**
- * 校验支持的标量范围，包括文本长度与数值有限性。
- * Validate supported scalar bounds, including text length and numeric finiteness.
- * @param {unknown} value 待检查值 / Value to inspect.
- * @returns {boolean} 是否为有效标量 / Whether the scalar is valid.
- */
-function scalar(value) {
-    switch (typeof value) {
-        case "boolean":
-            return true;
-        case "string":
-            return value.length <= 2048;
-        case "number":
-            return Number.isFinite(value);
-        default:
-            return false;
-    }
-}
-
-/**
- * 检查值类型、数组唯一性及声明的选项，不进行转换。
- * Check value type, array uniqueness and declared choices without coercion.
- * @param {import("../index.js").SettingsField} field 前端归一化字段 / Normalized frontend field.
- * @param {unknown} value 待写入的 JSON 值 / JSON value to write.
- * @returns {boolean} 是否符合字段约束 / Whether the value satisfies field constraints.
- */
-function validValue(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;
-    return !field.options || (field.type === "array" ? value : [value]).every(item => field.options.some(option => option.key === item));
-}
-
-/**
- * 单个模块的临时会话；离开页面后丢弃。
- * 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.
  */
+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.
- */
-function createPreferencesClient({ catalog, fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 }) {
-    /**
-     * 模块会话表
-     * Module session map.
-     * @type {Map<string, ModuleSession>}
-     */
-    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.
+     * 向模块 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.
      */
-    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),
     };
 }
 
@@ -814,18 +684,19 @@ class Navigation extends EventTarget {
 }
 
 /**
- * 挂载已导入 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.
  */
-function mountPanel(root, catalog) {
-    const title = catalog.module.metadata.name ?? catalog.module.module;
+function mountPanel(root, model) {
+    const { definition } = model;
+    const title = definition.metadata?.name ?? definition.module;
     const document = root.ownerDocument;
     const window = document.defaultView;
     const shell = element("div", "pp-panel");
-    shell.dataset.module = catalog.module.module;
+    shell.dataset.module = definition.module;
     const header = element("header", "pp-header");
     const back = element("button", "pp-back", "‹");
     back.setAttribute("aria-label", "返回");
@@ -855,7 +726,7 @@ 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 },
             }),
         );
     };
@@ -912,7 +783,7 @@ 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.
@@ -940,7 +811,6 @@ function mountPanel(root, catalog) {
         publishNavigation();
         viewport.replaceChildren(statusView("读取设置…"));
         try {
-            await client.open(module);
             if (version === generation) controls();
         } catch (error) {
             if (version !== generation) return;
@@ -954,7 +824,7 @@ 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 = element("section", "pp-fields");
         /**
@@ -992,7 +862,7 @@ function mountPanel(root, catalog) {
             saving = true;
             back.disabled = true;
             publishNavigation();
-            return (queue = queue
+            queue = queue
                 .then(action)
                 .then(() => {
                     if (!destroyed) success();
@@ -1005,10 +875,11 @@ 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) {
@@ -1086,7 +957,7 @@ function mountPanel(root, catalog) {
                     link.append(summary, element("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))
@@ -1177,8 +1048,7 @@ function mountPanel(root, catalog) {
             let inputVersion = 0;
             inputContainer.addEventListener(eventName, event => {
                 if (event.isComposing) return;
-                const version = ++inputVersion,
-                    module = active;
+                const version = ++inputVersion;
                 let value;
                 try {
                     value = read();
@@ -1187,10 +1057,17 @@ 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", key: field.key, message: error.message });
+                            throw error;
+                        }
+                        return client.set(field.key, value);
+                    },
                     () => {
                         for (const refresh of summaries) refresh();
                     },
@@ -1211,7 +1088,7 @@ 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;
@@ -1235,7 +1112,7 @@ 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;
@@ -1251,7 +1128,7 @@ 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 = "暂无缓存";
                 },
@@ -1260,7 +1137,7 @@ 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);
@@ -1278,7 +1155,7 @@ function mountPanel(root, catalog) {
         if (navigation) navigation.back();
         else window.history.back();
     };
-    open(catalog.module.module);
+    open(definition.module);
     return {
         /**
          * 移除监听器、定时器、会话和挂载内容。
@@ -1291,7 +1168,7 @@ 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();
         },
@@ -1321,14 +1198,22 @@ function installDefaultStyles(document) {
 /**
  * 挂载模块设置页；默认样式由包提供，可选 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.
  */
-function mount(boxjs, css = "") {
+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);
@@ -1364,7 +1249,7 @@ 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 = {
         /**
@@ -1388,7 +1273,7 @@ function mount(boxjs, css = "") {
     };
     try {
         root.replaceChildren();
-        panel = mountPanel(root, catalog);
+        panel = mountPanel(root, rendered);
         return view;
     } catch (error) {
         view.destroy();