@nsnanocat/preference-panes 0.9.15 → 1.0.0

package/package.json

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

package/src/api.mjs

@@ -0,0 +1,191 @@
+import { URL } from "@nsnanocat/url";
+import { fetch as transport } from "@nsnanocat/util";
+import { $app } from "@nsnanocat/util/lib/app.mjs";
+import { done } from "@nsnanocat/util/lib/done.mjs";
+import { Storage } from "@nsnanocat/util/polyfill/Storage";
+import { validatePathParts } from "./lib/settings-path.mjs";
+
+const MISSING = Symbol("missing");
+
+/**
+ * PreferencePanes 后端 API，只处理模块数据和持久化请求。
+ * PreferencePanes backend API handling only module data and persistence requests.
+ */
+class API {
+    /**
+     * 处理当前代理请求并将结果交给宿主。
+     * Handle the current proxy request and deliver its result to the host.
+     * @returns {Promise<void>} 响应已交给代理宿主 / Response delivered to the proxy host.
+     */
+    async run() {
+        const request = globalThis.$request;
+        let result;
+        try {
+            result = await this.handle(request);
+        } catch (error) {
+            console.error(`PreferencePanes: ${error.message}`);
+            result = this.#response(request, error.status ?? 500, { error: error.message });
+        }
+        if (!result) done({});
+        else done($app === "Quantumult X" ? result : { response: result });
+    }
+
+    /**
+     * 处理 `/api/{module}` 及其动作，不接管页面或静态资源。
+     * Handle `/api/{module}` and its actions without intercepting pages or static assets.
+     * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
+     * @returns {Promise<import("./index.js").SettingsResponse | undefined>} API 响应或未接管 / API response or pass-through.
+     */
+    async handle(request) {
+        const url = new URL(request.url);
+        const match = /^\/api\/([a-zA-Z0-9_-]+)(?:\/(get|set|delete))?\/?$/.exec(url.pathname);
+        if (!match) return;
+        const [, module, action] = match;
+        const configURL = this.#configURL(request, url, module);
+        switch (true) {
+            case !action && request.method === "HEAD":
+                return this.#probe(request, configURL);
+            case !action && request.method === "GET":
+                return this.#model(request, module, configURL);
+            case Boolean(action) && request.method === "POST":
+                return this.#action(request, module, action, configURL);
+            default:
+                return this.#response(request, 405, { error: "Use GET or HEAD for module reads, POST for module actions" });
+        }
+    }
+
+    #configURL(request, url, module) {
+        const headers = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
+        const source = headers["x-preferencepanes-json"] ?? `/configs/${module}`;
+        if (/^https?:\/\//i.test(source)) return source;
+        if (/^[a-zA-Z][a-zA-Z\d+.-]*:/.test(source)) throw Object.assign(new TypeError("BoxJS resources must use HTTP(S) URLs"), { status: 400 });
+        return `${url.origin}/${source.replace(/^\/+/, "")}`;
+    }
+
+    async #probe(request, configURL) {
+        let result;
+        try {
+            result = await transport({ url: configURL, method: "HEAD", timeout: 5000, headers: { Accept: "application/json" } });
+        } catch (error) {
+            return this.#response(request, 502, { error: error.message });
+        }
+        const version = this.#header(result.headers, "x-preferencepanes-version");
+        return this.#response(request, result.statusCode ?? result.status, undefined, version ? { "X-PreferencePanes-Version": version } : {});
+    }
+
+    async #model(request, module, configURL) {
+        const loaded = await this.#load(module, configURL);
+        const values = {};
+        for (const entry of loaded.entries) {
+            const value = Storage.getItem(entry.id, MISSING);
+            if (value !== MISSING) values[entry.id.slice(loaded.storageKey.length + 2)] = value;
+        }
+        return this.#response(request, 200, { module, boxjs: loaded.boxjs, values, configURL }, loaded.version ? { "X-PreferencePanes-Version": loaded.version } : {});
+    }
+
+    async #action(request, module, action, configURL) {
+        const payload = this.#jsonBody(request);
+        const target = await this.#load(module, configURL);
+        switch (action) {
+            case "get": {
+                const value = Storage.getItem(payload?.scope ? this.#scopePath(target, payload.scope) : this.#storagePath(target, payload?.key), MISSING);
+                return value === MISSING ? this.#response(request, 404, { error: "Stored path does not exist" }) : this.#response(request, 200, value);
+            }
+            case "set":
+                if (!Object.hasOwn(payload ?? {}, "value")) throw Object.assign(new TypeError("A value is required"), { status: 400 });
+                if (!Storage.setItem(this.#storagePath(target, payload.key), payload.value)) throw new Error("Storage write failed");
+                return this.#response(request, 200, { saved: true });
+            case "delete": {
+                const path = payload?.scope ? this.#scopePath(target, payload.scope) : this.#storagePath(target, payload?.key);
+                if (!Storage.removeItem(path)) throw new Error("Storage write failed");
+                return this.#response(request, 200, { deleted: true });
+            }
+        }
+    }
+
+    async #load(module, configURL) {
+        let result;
+        try {
+            result = await transport({ url: configURL, method: "GET", timeout: 5000, headers: { Accept: "application/json" } });
+        } catch (error) {
+            throw Object.assign(new Error(`Configuration request failed: ${error.message}`), { status: 502 });
+        }
+        const status = result.statusCode ?? result.status;
+        if (status !== 200) throw Object.assign(new Error(`Configuration HTTP ${status}`), { status });
+        try {
+            const body = typeof result.body === "string" ? result.body : new TextDecoder().decode(result.body);
+            const boxjs = JSON.parse(body);
+            const apps = Array.isArray(boxjs) ? [{ settings: boxjs }] : (boxjs.apps ?? [boxjs]);
+            if (!Array.isArray(apps)) throw new TypeError("Expected BoxJS apps array");
+            const entries = [];
+            let storageKey;
+            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(boxjs)) throw new TypeError("BoxJS settings require @root.path IDs");
+                        continue;
+                    }
+                    const [root, ...parts] = entry.id.slice(1).split(".");
+                    if (!root || root.startsWith("@") || parts.length < 2) throw new TypeError("A BoxJS setting must be below a literal storage root and module");
+                    validatePathParts(parts);
+                    if (parts[0] !== module) continue;
+                    if (storageKey && storageKey !== root) throw new TypeError(`A module must use one storage root: ${module}`);
+                    storageKey = root;
+                    entries.push(entry);
+                }
+            }
+            if (!entries.length) throw new TypeError(`No BoxJS settings for module: ${module}`);
+            return { boxjs, entries, module, storageKey, version: this.#header(result.headers, "x-preferencepanes-version") };
+        } catch (error) {
+            throw Object.assign(new Error(`Invalid BoxJS: ${error.message}`), { status: 422 });
+        }
+    }
+
+    #jsonBody(request) {
+        const headers = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
+        if (headers["content-type"]?.split(";")[0].trim().toLowerCase() !== "application/json") throw Object.assign(new TypeError("Expected application/json"), { status: 415 });
+        if (typeof request.body !== "string" || request.body.length > 65536) throw Object.assign(new TypeError("Expected a JSON body up to 65536 characters"), { status: 400 });
+        try {
+            return JSON.parse(request.body);
+        } catch (error) {
+            throw Object.assign(error, { status: 400 });
+        }
+    }
+
+    #storagePath(target, key) {
+        if (typeof key !== "string") throw Object.assign(new TypeError("A BoxJS field path is required"), { status: 400 });
+        const path = `@${target.storageKey}.${key}`;
+        if (!target.entries.some(entry => entry.id === path)) throw Object.assign(new TypeError(`Unknown BoxJS field: ${key}`), { status: 400 });
+        return path;
+    }
+
+    #scopePath(target, scope) {
+        switch (scope) {
+            case "settings":
+                return `@${target.storageKey}.${target.module}.Settings`;
+            case "caches":
+                return `@${target.storageKey}.${target.module}.Caches`;
+            case "module":
+                return `@${target.storageKey}.${target.module}`;
+            default:
+                throw Object.assign(new TypeError("Scope must be settings, caches or module"), { status: 400 });
+        }
+    }
+
+    #response(request, status, body, extraHeaders = {}) {
+        return {
+            status,
+            headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", ...extraHeaders },
+            body: request.method === "HEAD" ? "" : JSON.stringify(body),
+        };
+    }
+
+    #header(headers, name) {
+        const entry = Object.entries(headers ?? {}).find(([key]) => key.toLowerCase() === name);
+        return entry?.[1] === undefined ? undefined : String(entry[1]).trim();
+    }
+}
+
+new API().run();

package/src/browser/ModuleStatus.mjs

@@ -1,41 +1,28 @@
-/**
- * 模块 JSON Mock 的 HEAD 探测结果。
- * Result returned by a module JSON Mock HEAD probe.
- * @typedef {object} ModuleProbeResult
- * @property {"installed" | "missing"} state 安装状态 / Installation state.
- * @property {string | null} version 业务版本，缺失时为 null / Business version, or null when absent.
- * @property {number | null} httpStatus HTTP 状态码，网络错误时为 null / HTTP status, or null for network errors.
- */
-
 /**
  * 模块探测请求选项。
  * Options for a module probe request.
  * @typedef {object} ModuleProbeOptions
  * @property {typeof globalThis.fetch} [fetch] 可注入的 fetch / Injectable fetch.
  * @property {AbortSignal} [signal] 外部取消信号 / External cancellation signal.
+ * @property {string} [json] BoxJS JSON 来源，将随探测请求头传递 / BoxJS JSON source sent in the probe header.
  * @property {number} [timeout] 超时毫秒数，默认 3500 / Timeout in milliseconds, defaults to 3500.
  */
 
 /**
- * 通过模块 JSON Mock 的 HEAD 响应检测安装状态和业务版本。
- * Detect module installation and business version from a module JSON Mock HEAD response.
- * @param {string | URL} url 配置 Mock 地址 / Configuration Mock URL.
+ * 通过模块 API 的 HEAD 响应检测安装状态和业务版本。
+ * Probe installation and business version from the module API HEAD response.
+ * @param {string | URL} url 模块 API 地址 / Module API URL.
  * @param {ModuleProbeOptions} [options] 请求选项 / Request options.
- * @returns {Promise<ModuleProbeResult>} 探测结果 / Probe result.
- * @throws {Error} 外部取消请求 / External cancellation.
+ * @returns {Promise<Response>} 原始 HTTP 响应，可直接读取 status 和响应头 / Native HTTP response; read status and headers directly.
  */
-export async function probeModule(url, { fetch: request = globalThis.fetch, signal, timeout = 3500 } = {}) {
+export async function probeModule(url, { fetch: request = globalThis.fetch, json, signal, timeout = 3500 } = {}) {
     const controller = new AbortController();
     const abort = () => controller.abort();
     if (signal?.aborted) abort();
     signal?.addEventListener("abort", abort, { once: true });
     const timer = setTimeout(() => controller.abort(), timeout);
     try {
-        const response = await request(url, { method: "HEAD", cache: "no-store", credentials: "omit", signal: controller.signal });
-        return response.status === 200 ? { state: "installed", version: response.headers.get("X-PreferencePanes-Version")?.trim() || null, httpStatus: 200 } : { state: "missing", version: null, httpStatus: response.status };
-    } catch (error) {
-        if (signal?.aborted) throw error;
-        return { state: "missing", version: null, httpStatus: null };
+        return await request(url, { method: "HEAD", cache: "no-store", credentials: "omit", signal: controller.signal, headers: json ? { "X-PreferencePanes-JSON": json } : undefined });
     } finally {
         clearTimeout(timer);
         signal?.removeEventListener("abort", abort);
@@ -73,9 +60,9 @@ export class ModuleStatus extends EventTarget {
     /**
      * 每次进入重新探测，取消旧请求并忽略其迟到结果。
      * Reprobe on entry, cancelling old requests and ignoring late results.
-     * @param {string | URL} url 配置 Mock 地址 / Configuration Mock URL.
+     * @param {string | URL} url 模块 API 地址 / Module API URL.
      * @param {ModuleProbeOptions} [options] 请求选项 / Request options.
-     * @returns {Promise<ModuleProbeResult>} 探测结果 / Probe result.
+     * @returns {Promise<Response | undefined>} 原始响应；被取消时无返回值 / Native response; undefined when cancelled.
      */
     async check(url, options = {}) {
         this.#controller?.abort();
@@ -87,13 +74,15 @@ export class ModuleStatus extends EventTarget {
         externalSignal?.addEventListener("abort", abort, { once: true });
         this.#render("checking");
         try {
-            const result = await probeModule(url, { ...options, signal: controller.signal });
-            if (controller !== this.#controller) return result;
-            this.#render(result.state, result.version);
-            return result;
+            const response = await probeModule(url, { ...options, signal: controller.signal });
+            if (controller !== this.#controller) return response;
+            const version = response.status === 200 ? response.headers.get("X-PreferencePanes-Version")?.trim() || null : null;
+            this.#render(response.status === 200 ? "installed" : "missing", version);
+            return response;
         } catch (error) {
-            if (controller !== this.#controller) return { state: "missing", version: null, httpStatus: null };
-            throw error;
+            if (controller !== this.#controller) return;
+            if (externalSignal?.aborted) throw error;
+            this.#render("missing");
         } finally {
             externalSignal?.removeEventListener("abort", abort);
         }

package/src/browser/Navigation.d.mts

@@ -160,28 +160,6 @@ export class ActionMenu {
     destroy(): void;
 }
 
-/**
- * 模块 JSON Mock 的 HEAD 探测结果。
- * Result returned by a module JSON Mock HEAD probe.
- */
-export interface ModuleProbeResult {
-    /**
-     * 安装状态。
-     * Installation state.
-     */
-    state: "installed" | "missing";
-    /**
-     * 业务版本，缺失时为 null。
-     * Business version, or null when absent.
-     */
-    version: string | null;
-    /**
-     * HTTP 状态码，网络错误时为 null。
-     * HTTP status, or null for network errors.
-     */
-    httpStatus: number | null;
-}
-
 /**
  * 模块探测请求选项。
  * Options for a module probe request.
@@ -191,18 +169,20 @@ export interface ModuleProbeOptions {
     fetch?: typeof globalThis.fetch;
     /** 外部取消信号 / External cancellation signal. */
     signal?: AbortSignal;
+    /** 传给模块 API 的 BoxJS JSON 来源 / BoxJS JSON source sent to the module API. */
+    json?: string;
     /** 超时毫秒数，默认 3500 / Timeout in milliseconds, defaults to 3500. */
     timeout?: number;
 }
 
 /**
- * 通过模块 JSON Mock 的 HEAD 响应检测安装状态和业务版本。
- * Detect module installation and business version from a module JSON Mock HEAD response.
- * @param url 配置 Mock 地址 / Configuration Mock URL.
+ * 通过模块 API 的 HEAD 响应检测安装状态和业务版本。
+ * Probe installation and business version from a module API HEAD response.
+ * @param url 模块 API 地址 / Module API URL.
  * @param options 请求选项 / Request options.
- * @returns 探测结果 / Probe result.
+ * @returns 原始 HTTP 响应 / Native HTTP response.
  */
-export function probeModule(url: string | URL, options?: ModuleProbeOptions): Promise<ModuleProbeResult>;
+export function probeModule(url: string | URL, options?: ModuleProbeOptions): Promise<Response>;
 
 /**
  * HEAD 探测的固定模块状态行。
@@ -221,13 +201,13 @@ export class ModuleStatus extends EventTarget {
      */
     readonly state: { status: "checking" | "installed" | "missing"; version: string | null };
     /**
-     * 探测配置 Mock。
-     * Probe a configuration Mock.
-     * @param url 配置地址 / Configuration URL.
+     * 探测模块 API。
+     * Probe the module API.
+     * @param url 模块 API 地址 / Module API URL.
      * @param options 请求选项 / Request options.
-     * @returns 探测结果 / Probe result.
+     * @returns 原始 HTTP 响应；网络错误时状态行显示“未安装” / Native HTTP response; network errors render “未安装”.
      */
-    check(url: string | URL, options?: ModuleProbeOptions): Promise<ModuleProbeResult>;
+    check(url: string | URL, options?: ModuleProbeOptions): Promise<Response | undefined>;
     /**
      * 取消探测。
      * Cancel probes.

package/src/browser/app.mjs

@@ -1,4 +1,3 @@
-import { BoxJS } from "../BoxJS.mjs";
 import { pageInputs } from "../lib/page-inputs.mjs";
 import { statusView } from "./components.mjs";
 import { mount } from "./index.mjs";
@@ -30,17 +29,16 @@ async function start() {
             default:
                 inputs = pageInputs(new URL(location.href));
         }
-        const resources = [inputs.json, inputs.css].map(source => {
+        const apiURL = new URL(`/api/${encodeURIComponent(inputs.module)}`, inputs.url).href;
+        const resources = [inputs.css].map(source => {
             if (!source) return null;
             const url = new URL(source, inputs.url);
             if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("Resources must use HTTP(S) URLs");
             return url.href;
         });
-        const [data, style] = await Promise.all(resources.map(url => (url ? fetch(url, { cache: "no-store", credentials: "omit" }) : null)));
-        if (data.status !== 200 || (style && style.status !== 200)) throw new Error(`HTTP ${data.status !== 200 ? data.status : style.status}`);
-        const catalog = new BoxJS(await data.json());
-        if (catalog.module.module !== inputs.module) throw new Error("Imported JSON does not match the module URL");
-        view = mount(catalog, style ? await style.text() : "");
+        const [style, modelResponse] = await Promise.all([...resources.map(url => (url ? fetch(url, { cache: "no-store", credentials: "omit" }) : null)), fetch(apiURL, { cache: "no-store", credentials: "omit", headers: { Accept: "application/json", "X-PreferencePanes-JSON": inputs.json } })]);
+        if ((style && style.status !== 200) || modelResponse.status !== 200) throw new Error(`HTTP ${modelResponse.status !== 200 ? modelResponse.status : style.status}`);
+        view = mount(await modelResponse.json(), style ? await style.text() : "");
     } catch (error) {
         document.querySelector("#preferences").replaceChildren(statusView(`加载失败：${error.message}`, start));
     }

package/src/{lib → browser}/boxjs.mjs

@@ -1,22 +1,46 @@
-import { BoxJS } from "../BoxJS.mjs";
-import { validatePathParts } from "./settings-path.mjs";
+import { validatePathParts } from "../lib/settings-path.mjs";
 
 /**
- * 将 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.
+ * 将 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.
  */
 export function normalizeBoxJs(config, module) {
-    validatePathParts([module]);
-    const catalog = config instanceof BoxJS ? config : new BoxJS(config);
-    const target = catalog.modules.get(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);
+        }
+    }
+    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 { entries, storageKey, metadata } = target;
+    const metadata = normalizeMetadata(target.owners.size === 1 ? presentation([...target.owners][0]) : {});
     const fields = [];
-    for (const entry of entries) {
+    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}`);
@@ -46,18 +70,50 @@ export function normalizeBoxJs(config, module) {
         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}`);
+    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,
-        storageKey,
+        module: target.module,
+        storageKey: target.storageKey,
         fields,
         settingsPath: common,
         ...(Object.keys(metadata).length ? { 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 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 ? value : [value];
+        if (!Array.isArray(values) || values.some(item => typeof item !== "string")) throw new TypeError(`Invalid BoxJS app ${key}`);
+        result[key] = multiple ? [...values] : value;
+    }
+    return result;
+}
+
 /**
  * 归一化 BoxJS 的字符串存储值，不改变普通文本内容。
  * Normalize BoxJS string persistence without changing free-text values.