@nsnanocat/preference-panes 1.1.0 → 1.1.2

package/README.md

@@ -1,76 +1,92 @@
 # @nsnanocat/preference-panes
 
-PreferencePanes 分别提供具体模块的设置前端和本地持久化 API。`web.js` 只返回模块 HTML 与公共浏览器资源，`api.js` 只处理模块数据和持久化；业务模块自己发布版本对应的 BoxJS JSON。项目主页及其客户端 SDK 调用属于调用方，不进入本包。
+PreferencePanes 提供一个由 BoxJS JSON 驱动的通用设置前端，以及一个独立的代理配置与持久化 API。业务模块只发布自己的 `/configs/{module}`；通用 `/settings/**` 前端和 `/api/**` 后端分别只需要安装一次。
 
-## 模块 API
+在 Biliverse 中，Enhanced 是唯一安装 `web.js` 的模块。Global、Redirect、ADBlock 不携带 `web.js`，它们的设置页仍由同一份通用前端读取各自 BoxJS 后渲染。
 
-嵌入的模块页跟随宿主根元素的 `data-theme`（light/dark）和 `--pp-keyboard-height`（CSS 长度），退出时释放观察器。独立页面使用网页自身或系统主题；通用包不识别任何客户端 User-Agent。
+## 浏览器入口
 
-默认样式完全由包内 `pp-*` 类和 CSS 变量提供，不请求任何项目或客户端资源。调用方可通过 CSS 输入覆盖变量、组件，或在该 CSS 中自行引用所属客户端的官方样式。开关采用标准 checkbox 的 switch 属性及 switch 语义，由浏览器呈现原生控件（[Safari/iOS 17.4 起显示开关](https://webkit.org/blog/15054/an-html-switch-control/)，其他浏览器保留可操作的复选框）；单选使用 select，多选保留二级页面。BoxJS 动态生成及修改即保存保持不变。
+浏览器包只公开一个入口：
 
-宿主可监听 ModuleFrame 的 `confirm` 事件，调用 `preventDefault()` 接管确认框，再以 `event.detail.resolve(boolean)` 或 `reject(error)` 完成。未接管的独立网页使用浏览器对话框；模块离开后到达的确认结果不会继续写入。
-
-宿主也可监听 `notice` 事件，通过 `preventDefault()` 接管 `{kind, message}` 提示；被接管时模块不创建网页 Toast、不启用提示计时器。独立使用的通用面板仍提供默认通知。
+```ts
+function mount(boxjs: BoxJSInput): MountedPreferences;
+interface MountedPreferences { destroy(): void }
+```
 
-业务模块分别映射同一 Release 的两个产物：`api.js` 只匹配 `/api/{module}` 及其动作，`web.js` 只匹配 `/settings/{module}`、`/settings/assets/index.mjs` 和 `/settings/assets/navigation.mjs`。发布资源仍把 1.0.0 使用的 `/settings/assets/app.mjs` 映射到同一份 `index.mjs` 正文，兼容尚未更新的已安装模块，但不存在第二个页面入口实现。两者都不包含业务配置，也不需要额外安装独立设置插件。
+```js
+import { mount } from "@nsnanocat/preference-panes/browser";
 
-网页只调用模块 API：`HEAD /api/{module}` 探测模块，`GET /api/{module}` 取得原始 BoxJS 与当前已存值，`POST /api/{module}/get|set|delete` 执行持久化操作。`api.js` 负责取得 BoxJS、确认字段 ID 并把完整 `@root.path` 直接交给 util `Storage`；网页不直接请求配置 Mock，也不提交存储根。
+const boxjs = await fetch("/api/Module", {
+    cache: "no-store",
+    credentials: "omit",
+}).then(response => response.json());
 
-```js
-await fetch("/api/Enhanced/set", {
-    method: "POST",
-    headers: {
-        "Content-Type": "application/json",
-        "X-PreferencePanes-JSON": "/configs/Enhanced",
-    },
-    body: JSON.stringify({ key: "Enhanced.Settings.Home.Top_left", value: "mine" }),
-});
+const preferences = mount(boxjs);
+preferences.destroy();
 ```
 
-模块 API 返回的 `boxjs` 保持上游原样，`values` 只含实际已存值，不补默认值或解释控件类型。Web 侧 `mount()` 独占控件、选项、默认值、展示元数据和已存值校验，再生成页面。写入成功后只更新当前页面快照，不追加读取。旧 `/api/get|set|delete` form 接口和 `/api/module/{module}` 草稿路径均移除。
+`mount()` 同步建立页面生命周期。BoxJS 规范化、默认值、已存值校验、加载状态和失败重试都由内部流程管理；不公开 API Model、视图 class、构建器或 CSS 第二参数。
 
-## 页面与输入
+前端支持 BoxJS 字段数组、单个 app 和 apps 订阅，并要求输入恰好包含一个模块。模块名、存储根和 Settings 路径都从 `@Root.Module.Settings.key` 字段 ID 推导，不从 app 名称或调用参数补充。
 
-```js
-import { PreferencesView } from "@nsnanocat/preference-panes/browser";
-const model = await fetch("/api/Module", {
-    headers: { "X-PreferencePanes-JSON": "/configs/Module" },
-}).then(response => response.json());
-const page = new PreferencesView(model, ".pp-panel { --pp-accent: #16866a; }");
-page.destroy();
-```
+默认样式随包内置。嵌入页面只跟随宿主根元素的 `data-theme` 和 `--pp-keyboard-height`，不识别客户端 User-Agent，也不加载项目 CSS 或客户端 SDK。
+
+## 页面与 API
+
+`web.js` 只返回三类通用资源：
+
+- `GET /settings/{module}`
+- `GET /settings/assets/index.mjs`
+- `GET /settings/assets/navigation.mjs`
 
-浏览器生命周期依次由 `ModulePage`、`PreferencesView`、`PreferencesPanel` 和 `PreferencesClient` 管理：页面入口读取输入并请求初始模型，视图负责 BoxJS 解析、校验、样式与主题，面板负责控件和导航，客户端只负责 API 请求与页面值快照。`mount(model, css?)` 仍作为创建 `PreferencesView` 的便捷入口。
+模块页面从 URL 或 `ModuleFrame` 的模块标记取得模块名，通过同源 `/api/{module}` 读取原始 BoxJS，然后调用 `mount(boxjs)`。页面不接受 JSON/CSS 查询参数、私有请求头或兼容资源别名，也不直接访问 `/configs/**`。
 
-API 支持字段数组、单 app 和 apps 订阅，只扫描 `@Root.Module.Settings.key` 形式的字段 ID。浏览器从 API 返回的同一份 BoxJS 解析控件、名称、图标和默认值；省略 CSS 使用内置样式。
+`api.js` 只处理：
 
-`/settings/{module}` 由独立 `web.js` 返回模块文档。页面可通过 json/css 查询参数或 X-PreferencePanes-JSON/CSS Header 指定资源 URL；默认 JSON 是 /configs/{module}，CSS 默认空。Header 分别优先。`web.js` 不访问网络或存储，浏览器执行其中的 `index.mjs` 后才调用 `api.js`。
+- `HEAD /api/{module}`：探测同源 `/configs/{module}`，透传状态与 `X-PreferencePanes-Version`。
+- `GET /api/{module}`：原样返回同源 `/configs/{module}` 的 BoxJS JSON 与版本头。
+- `POST /api/get`：读取完整 `@root.path`。
+- `POST /api/set`：写入完整 `@root.path`。
+- `POST /api/delete`：删除完整 `@root.path` 或子树。
+
+模块 API 只转发业务配置；固定存储 API 不下载或解析 BoxJS。BoxJS 字段、控件、选项、默认值与写入值都由浏览器校验。
 
 ```js
-import { ModuleFrame, Navigation } from "@nsnanocat/preference-panes/navigation";
-const frame = new ModuleFrame("/settings/Module", {
-    headers: { "X-PreferencePanes-JSON": "/configs/Module", "X-PreferencePanes-CSS": "/theme.css" },
-    signal,
+await fetch("/api/set", {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams([["@BiliBili.Enhanced.Settings.Home.Top_left", JSON.stringify("mine")]]),
 });
-container.append(frame.element);
-await frame.load();
-frame.addEventListener("change", () => { title.textContent = frame.state.title; });
-back.onclick = () => frame.back();
-frame.destroy();
 ```
 
-ModuleFrame 在 iframe 元素上保存原请求上下文，HTML 原样加载，不从 about:srcdoc 猜模块、不注入临时 CSS。框架自身管理嵌入模式，通过事件发布标题、忙碌状态和返回能力。Navigation 统一管理 fragment 历史、滑动、滚动保留、加载取消及动画结束后释放；项目提供根页、子页工厂和布局。
+页面初始化时只执行一次 `POST /api/get` 读取 Settings 子树。写入成功后仅更新当前页面快照；查看 Settings/Caches 时按需读取，清空和重置通过 `/api/delete` 完成。
+
+## 宿主集成
+
+```js
+import { ModuleFrame, ModuleStatus } from "@nsnanocat/preference-panes/navigation";
 
-项目主页可按需使用导出的 `probeModule`、ModuleStatus、ModuleFrame 和 Navigation，也可以自行实现入口。`probeModule("/api/Module", { json: "/configs/Module" })` 只对模块 API 发送一次 HEAD，并原样返回浏览器 `Response`；代理 API 负责探测 BoxJS 上游并透传状态和 `X-PreferencePanes-Version`。ModuleStatus 仅负责把同一响应渲染到状态行。PreferencePanes 不提供主页运行脚本，不识别具体 App，不加载或调用任何客户端 Bridge SDK。调用方若运行在原生 WebView，应在自己的 HTML/页面脚本中直接接入该客户端的官方 SDK，再把 ModuleFrame 事件映射到原生界面。
+const status = new ModuleStatus(statusElement);
+await status.check("/api/Module");
 
-每次进入模块通过 API 取得 JSON 和设置一次，同时读取可选 CSS。二级多选返回复用内存缓存，修改经 Web 校验后提交 API；成功提示、失败回滚由公共组件处理。Caches 按需通过 API 查看/清空，重置只删除指定模块子树。
+const frame = new ModuleFrame("/settings/Module", { signal });
+container.append(frame.element);
+await frame.load();
+```
 
-标题栏只显示文字；嵌入模式隐藏模块自身标题栏，由宿主显示原生标题或自己的导航。模块数据操作位于标题栏右侧三点菜单，页面不再平铺维护按钮。`ActionMenu` 是共用的底部操作菜单：独立网页由其三点按钮打开；网页宿主或只有原生按钮、没有原生菜单的 WebView 宿主，将 `frame.state.actions` 传给 `menu.update(actions, busy)`，在宿主按钮点击时调用 `menu.open()`，选择后调用 `frame.perform(id)`。查看设置和缓存都会通过 `POST /api/{module}/get` 按需读取最新子树，再进入可返回的 JSON 详情子页；返回详情页不会触发额外读取，清空和重置设置通过 `/delete` 且仍要求确认。菜单组件提供遮罩、取消按钮、外部点击、Escape 与方向键操作，弹层挂载在文档根部，不依赖模块标题栏是否显示；宿主不访问 iframe 内部 DOM。
+`ModuleFrame` 只携带模块身份和取消信号。宿主通过 `change`、`confirm`、`notice` 事件同步标题、操作菜单、确认框和提示，不读取或改写 iframe 内部 DOM。项目主页、Bilibili JSBridge、原生导航和视觉样式仍由宿主负责。
 
 ## 构建与验证
 
-`npm run build` 生成无业务配置的 `dist/api.js`、`dist/web.js` 和公共前端模块；Release 工作流分别上传后端 API 与前端响应脚本。`build(boxjs, css?)` 仅输出 `settings/{module}/index.html`、公共 `settings/assets/index.mjs` 和可选模块 CSS，不复制配置、导航组件或重复 HTML。
+```sh
+npm run build
+npm run check
+npm run apifox:check
+npm pack --dry-run
+```
+
+构建生成 `dist/api.js`、`dist/web.js`、`dist/preference-panes.mjs` 和 `dist/module/` 通用页面资源。包不再提供按模块生成 HTML/CSS 的公开 `build()`。
 
-`npm run preview` 提供文件导入测试台，上传 JSON/CSS 后在隔离 iframe 预览；测试存储只在内存中。`npm run check` 检查代码、类型、行为；`npm run apifox:generate` 和 `npm run apifox:check` 维护原生接口文档。
+`npm run preview` 启动 JSON 文件导入测试台，使用同一通用页面、同源配置和内存存储验证模块行为。
 
-[接口规范](apifox/Specification.md) · [Apifox JSON](apifox/preference-panes.apifox.json)
+[接口规范](apifox/Specification.md) · [宿主集成](apifox/HostIntegration.md) · [Apifox JSON](apifox/preference-panes.apifox.json)

package/dist/api.js

@@ -1921,11 +1921,9 @@
         return parts;
     }
 
-    const MISSING = Symbol("missing");
-
     /**
-     * PreferencePanes 后端 API，只处理模块数据和持久化请求。
-     * PreferencePanes backend API handling only module data and persistence requests.
+     * PreferencePanes 后端 API，只转发模块配置并提供通用持久化操作。
+     * PreferencePanes backend API only relaying module configurations and providing generic persistence operations.
      */
     class API {
         /**
@@ -1947,153 +1945,107 @@
         }
 
         /**
-         * 处理 `/api/{module}` 及其动作，不接管页面或静态资源。
-         * Handle `/api/{module}` and its actions without intercepting pages or static assets.
+         * 处理模块配置 API 与固定存储动作，不接管页面或静态资源。
+         * Handle module configuration APIs and fixed storage 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" });
-            }
+            const action = /^\/api\/(get|set|delete)\/?$/.exec(url.pathname)?.[1];
+            if (action) return this.#store(request, action);
+            const module = /^\/api\/([a-zA-Z0-9_-]+)\/?$/.exec(url.pathname)?.[1];
+            if (!module) return;
+            if (!["HEAD", "GET"].includes(request.method)) return this.#response(request, 405, { error: "Use GET or HEAD for module configuration" });
+            return this.#configuration(request, `${url.origin}/configs/${module}`);
         }
 
-        #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) {
+        /**
+         * 从同源业务配置响应模块探测或原始 BoxJS JSON。
+         * Respond to a module probe or raw BoxJS JSON from the same-origin business configuration.
+         * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
+         * @param {string} configuration 同源配置地址 / Same-origin configuration URL.
+         * @returns {Promise<import("./index.js").SettingsResponse>} 配置响应 / Configuration response.
+         */
+        async #configuration(request, configuration) {
             let result;
             try {
-                result = await fetch({ url: configURL, method: "HEAD", timeout: 5000, headers: { Accept: "application/json" } });
+                result = await fetch({ url: configuration, method: request.method, 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 });
-                }
-            }
+            const contentType = this.#header(result.headers, "content-type") ?? "application/json; charset=utf-8";
+            return {
+                status: result.statusCode ?? result.status,
+                headers: { "Content-Type": contentType, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", ...(version ? { "X-PreferencePanes-Version": version } : {}) },
+                body: request.method === "HEAD" ? "" : typeof result.body === "string" ? result.body : new TextDecoder().decode(result.body),
+            };
         }
 
-        async #load(module, configURL) {
-            let result;
+        /**
+         * 使用唯一 form 字段中的完整 @root.path 执行存储操作。
+         * Execute a storage operation using the complete @root.path from the sole form field.
+         * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
+         * @param {"get" | "set" | "delete"} action 存储动作 / Storage action.
+         * @returns {import("./index.js").SettingsResponse} 操作响应 / Operation response.
+         */
+        #store(request, action) {
+            const reply = (status, data) => this.#response(request, status, data);
+            if (request.method !== "POST") return reply(405, { error: "Use POST with a form body" });
+            const headers = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
+            if (headers["content-type"]?.split(";")[0].trim().toLowerCase() !== "application/x-www-form-urlencoded") return reply(415, { error: "Expected application/x-www-form-urlencoded" });
+            if (typeof request.body !== "string" || request.body.length > 65536) return reply(400, { error: "Expected a form body up to 65536 characters" });
+            let parts, value;
             try {
-                result = await fetch({ url: configURL, method: "GET", timeout: 5000, headers: { Accept: "application/json" } });
+                const fields = request.body.split("&");
+                if (fields.length !== 1) throw new TypeError("Send exactly one storage key");
+                const separator = fields[0].indexOf("=");
+                if (separator < 0) throw new TypeError("Expected @root.path=value");
+                const key = decodeURIComponent(fields[0].slice(0, separator).replace(/\+/g, " "));
+                value = decodeURIComponent(fields[0].slice(separator + 1).replace(/\+/g, " "));
+                if (!key.startsWith("@")) throw new TypeError("Storage keys must start with @");
+                parts = validatePathParts(key.slice(1).split("."));
+                if (parts.length < 2) throw new TypeError("Specify a storage root and child path");
             } catch (error) {
-                throw Object.assign(new Error(`Configuration request failed: ${error.message}`), { status: 502 });
+                return reply(400, { error: error.message });
             }
-            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 (action === "set") {
+                try {
+                    value = JSON.parse(value);
+                } catch (error) {
+                    if (!(error instanceof SyntaxError)) throw error;
                 }
-                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 });
+            const [storageKey, ...path] = parts;
             try {
-                return JSON.parse(request.body);
+                const root = Storage.getItem(storageKey, {});
+                if (!isRecord(root)) throw new TypeError("Stored root must be an object");
+                const parent = storageParent(root, path, action === "set");
+                const key = path.at(-1);
+                switch (action) {
+                    case "get": {
+                        const result = parent ? Lodash.get(parent, [key]) : undefined;
+                        return result === undefined ? reply(404, { error: "Stored path does not exist" }) : reply(200, result);
+                    }
+                    case "set":
+                        Lodash.set(parent, [key], value);
+                        break;
+                    case "delete":
+                        if (parent) Lodash.unset(parent, [key]);
+                        break;
+                }
+                if (!Storage.setItem(storageKey, root)) throw new Error("Storage write failed");
+                return reply(200, action === "set" ? { saved: true } : { deleted: true });
             } 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 });
+                return reply(500, { error: error.message });
             }
         }
 
-        #response(request, status, body, extraHeaders = {}) {
+        #response(request, status, body) {
             return {
                 status,
-                headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", ...extraHeaders },
+                headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" },
                 body: request.method === "HEAD" ? "" : JSON.stringify(body),
             };
         }
@@ -2104,6 +2056,44 @@
         }
     }
 
+    /**
+     * 判断存储根是否为普通对象。
+     * Determine whether a storage root is a plain object.
+     * @param {unknown} value 待检查值 / Value to inspect.
+     * @returns {boolean} 是否为普通对象 / Whether this is a plain object.
+     */
+    function isRecord(value) {
+        return value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype;
+    }
+
+    /**
+     * 遍历父路径，并解码旧存储中的 JSON 字符串中间节点。
+     * Traverse parent paths and decode legacy intermediate nodes stored as JSON strings.
+     * @param {Record<string, unknown>} root 存储根 / Storage root.
+     * @param {string[]} parts 完整路径 / Complete path.
+     * @param {boolean} create 是否创建缺失节点 / Whether to create missing parents.
+     * @returns {object | undefined} 父节点或 undefined / Parent node or undefined.
+     */
+    function storageParent(root, parts, create) {
+        let parent = root;
+        for (const part of parts.slice(0, -1)) {
+            let next = Lodash.get(parent, [part]);
+            switch (typeof next) {
+                case "undefined":
+                    if (!create) return;
+                    next = {};
+                    break;
+                case "string":
+                    next = JSON.parse(next);
+                    break;
+            }
+            if (!isRecord(next) && !Array.isArray(next)) throw new TypeError("Stored parent is not an object or array");
+            Lodash.set(parent, [part], next);
+            parent = next;
+        }
+        return parent;
+    }
+
     new API().run();
 
 })();

package/dist/module/index.html

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