@nsnanocat/preference-panes 1.1.0 → 1.1.1

package/README.md

@@ -1,76 +1,94 @@
 # @nsnanocat/preference-panes
 
-PreferencePanes 分别提供具体模块的设置前端和本地持久化 API。`web.js` 只返回模块 HTML 与公共浏览器资源，`api.js` 只处理模块数据和持久化；业务模块自己发布版本对应的 BoxJS JSON。项目主页及其客户端 SDK 调用属于调用方，不进入本包。
+PreferencePanes 提供一个由 BoxJS JSON 驱动的通用设置前端，以及一个独立的代理持久化 API。业务模块只发布自己的 `/configs/{module}` 和 `/api/{module}`；通用 `/settings/**` 前端只需要安装一次。
 
-## 模块 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)` 完成。未接管的独立网页使用浏览器对话框；模块离开后到达的确认结果不会继续写入。
+```ts
+function mount(boxjs: BoxJSInput): MountedPreferences;
+interface MountedPreferences { destroy(): void }
+```
+
+```js
+import { mount } from "@nsnanocat/preference-panes/browser";
+
+const boxjs = await fetch("/configs/Module", {
+    cache: "no-store",
+    credentials: "omit",
+}).then(response => response.json());
+
+const preferences = mount(boxjs);
+preferences.destroy();
+```
+
+`mount()` 同步建立页面生命周期。BoxJS 规范化、默认值、已存值校验、加载状态和失败重试都由内部流程管理；不公开 API Model、视图 class、构建器或 CSS 第二参数。
+
+前端支持 BoxJS 字段数组、单个 app 和 apps 订阅，并要求输入恰好包含一个模块。模块名、存储根和 Settings 路径都从 `@Root.Module.Settings.key` 字段 ID 推导，不从 app 名称或调用参数补充。
+
+默认样式随包内置。嵌入页面只跟随宿主根元素的 `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`
 
-宿主也可监听 `notice` 事件，通过 `preventDefault()` 接管 `{kind, message}` 提示；被接管时模块不创建网页 Toast、不启用提示计时器。独立使用的通用面板仍提供默认通知。
+模块页面从 URL 或 `ModuleFrame` 的模块标记取得模块名，直接读取同源 `/configs/{module}`，然后调用 `mount(boxjs)`。页面不接受 JSON/CSS 查询参数、私有请求头或兼容资源别名。
 
-业务模块分别映射同一 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` 正文，兼容尚未更新的已安装模块，但不存在第二个页面入口实现。两者都不包含业务配置，也不需要额外安装独立设置插件。
+`api.js` 只处理：
 
-网页只调用模块 API：`HEAD /api/{module}` 探测模块，`GET /api/{module}` 取得原始 BoxJS 与当前已存值，`POST /api/{module}/get|set|delete` 执行持久化操作。`api.js` 负责取得 BoxJS、确认字段 ID 并把完整 `@root.path` 直接交给 util `Storage`；网页不直接请求配置 Mock，也不提交存储根。
+- `HEAD /api/{module}`：探测同源 `/configs/{module}`，透传状态与 `X-PreferencePanes-Version`。
+- `POST /api/{module}/get`：读取声明字段或 Settings、Caches、module 子树。
+- `POST /api/{module}/set`：写入当前 BoxJS 声明的字段。
+- `POST /api/{module}/delete`：删除声明字段或模块子树。
+
+`GET /api/{module}` 和其它未规定方法返回 `405`。API 每次动作都从 `/configs/{module}` 建立字段目录，只负责字段授权与 util `Storage` 读写，不解释控件、选项或默认值。
 
 ```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" }),
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+        key: "Enhanced.Settings.Home.Top_left",
+        value: "mine",
+    }),
 });
 ```
 
-模块 API 返回的 `boxjs` 保持上游原样，`values` 只含实际已存值，不补默认值或解释控件类型。Web 侧 `mount()` 独占控件、选项、默认值、展示元数据和已存值校验，再生成页面。写入成功后只更新当前页面快照，不追加读取。旧 `/api/get|set|delete` form 接口和 `/api/module/{module}` 草稿路径均移除。
+页面初始化时只执行一次 `POST /api/{module}/get` 读取 Settings 子树。写入成功后仅更新当前页面快照；查看 Settings/Caches 时按需读取，清空和重置通过 delete 动作完成。
 
-## 页面与输入
+## 宿主集成
 
 ```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();
-```
+import { ModuleFrame, ModuleStatus } from "@nsnanocat/preference-panes/navigation";
 
-浏览器生命周期依次由 `ModulePage`、`PreferencesView`、`PreferencesPanel` 和 `PreferencesClient` 管理：页面入口读取输入并请求初始模型，视图负责 BoxJS 解析、校验、样式与主题，面板负责控件和导航，客户端只负责 API 请求与页面值快照。`mount(model, css?)` 仍作为创建 `PreferencesView` 的便捷入口。
+const status = new ModuleStatus(statusElement);
+await status.check("/api/Module");
 
-API 支持字段数组、单 app 和 apps 订阅，只扫描 `@Root.Module.Settings.key` 形式的字段 ID。浏览器从 API 返回的同一份 BoxJS 解析控件、名称、图标和默认值；省略 CSS 使用内置样式。
-
-`/settings/{module}` 由独立 `web.js` 返回模块文档。页面可通过 json/css 查询参数或 X-PreferencePanes-JSON/CSS Header 指定资源 URL；默认 JSON 是 /configs/{module}，CSS 默认空。Header 分别优先。`web.js` 不访问网络或存储，浏览器执行其中的 `index.mjs` 后才调用 `api.js`。
-
-```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,
-});
+const frame = new ModuleFrame("/settings/Module", { signal });
 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 历史、滑动、滚动保留、加载取消及动画结束后释放；项目提供根页、子页工厂和布局。
-
-项目主页可按需使用导出的 `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 事件映射到原生界面。
-
-每次进入模块通过 API 取得 JSON 和设置一次，同时读取可选 CSS。二级多选返回复用内存缓存，修改经 Web 校验后提交 API；成功提示、失败回滚由公共组件处理。Caches 按需通过 API 查看/清空，重置只删除指定模块子树。
-
-标题栏只显示文字；嵌入模式隐藏模块自身标题栏，由宿主显示原生标题或自己的导航。模块数据操作位于标题栏右侧三点菜单，页面不再平铺维护按钮。`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

@@ -1957,31 +1957,21 @@
             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);
+            const configuration = `${url.origin}/configs/${module}`;
             switch (true) {
                 case !action && request.method === "HEAD":
-                    return this.#probe(request, configURL);
-                case !action && request.method === "GET":
-                    return this.#model(request, module, configURL);
+                    return this.#probe(request, configuration);
                 case Boolean(action) && request.method === "POST":
-                    return this.#action(request, module, action, configURL);
+                    return this.#action(request, module, action, configuration);
                 default:
-                    return this.#response(request, 405, { error: "Use GET or HEAD for module reads, POST for module actions" });
+                    return this.#response(request, 405, { error: "Use HEAD for module probes and 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) {
+        async #probe(request, configuration) {
             let result;
             try {
-                result = await fetch({ url: configURL, method: "HEAD", timeout: 5000, headers: { Accept: "application/json" } });
+                result = await fetch({ url: configuration, method: "HEAD", timeout: 5000, headers: { Accept: "application/json" } });
             } catch (error) {
                 return this.#response(request, 502, { error: error.message });
             }
@@ -1989,19 +1979,9 @@
             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) {
+        async #action(request, module, action, configuration) {
             const payload = this.#jsonBody(request);
-            const target = await this.#load(module, configURL);
+            const target = await this.#load(module, configuration);
             switch (action) {
                 case "get": {
                     const value = Storage.getItem(payload?.scope ? this.#scopePath(target, payload.scope) : this.#storagePath(target, payload?.key), MISSING);
@@ -2019,10 +1999,10 @@
             }
         }
 
-        async #load(module, configURL) {
+        async #load(module, configuration) {
             let result;
             try {
-                result = await fetch({ url: configURL, method: "GET", timeout: 5000, headers: { Accept: "application/json" } });
+                result = await fetch({ url: configuration, method: "GET", timeout: 5000, headers: { Accept: "application/json" } });
             } catch (error) {
                 throw Object.assign(new Error(`Configuration request failed: ${error.message}`), { status: 502 });
             }
@@ -2053,7 +2033,7 @@
                     }
                 }
                 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") };
+                return { entries, module, storageKey, version: this.#header(result.headers, "x-preferencepanes-version") };
             } catch (error) {
                 throw Object.assign(new Error(`Invalid BoxJS: ${error.message}`), { status: 422 });
             }

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.1"></script>
     </body>
 </html>

package/dist/module/index.mjs

@@ -1,21 +1,3 @@
-/**
- * 统一解析模块页的资源地址：Header 优先于查询参数，再使用模块约定。
- * Resolve module resource locations: headers override query parameters and module conventions.
- * @param {URL} url 已解析的页面请求地址 / Parsed page request URL.
- * @param {Record<string, string | undefined>} [headers] 请求头，名称不区分大小写 / Case-insensitive request headers.
- * @returns {{url: string, module: string, json: string, css: string}} 页面上下文与两个资源输入 / Page context and two resource inputs.
- */
-function pageInputs(url, headers = {}) {
-    const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(url.pathname);
-    if (!match) throw new TypeError("Open a concrete module URL");
-    const module = match[1];
-    const values = Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
-    const json = values["x-preferencepanes-json"] ?? url.searchParams.get("json") ?? `/configs/${module}`;
-    const css = values["x-preferencepanes-css"] ?? url.searchParams.get("css") ?? "";
-    if (!json.trim()) throw new TypeError("JSON resource URL is required");
-    return { url: url.href, module, json, css };
-}
-
 /**
  * 创建元素，所有展示文本通过 textContent 写入。
  * Create elements and assign display text through textContent only.
@@ -154,8 +136,8 @@ function normalizeBoxJs(config, module) {
             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 (modules.size !== 1) throw new TypeError("Import BoxJS JSON for exactly one module");
+    const target = modules.values().next().value ;
     if (!target) throw new TypeError(`No BoxJS settings for module: ${module}`);
     const metadata = normalizeMetadata(target.owners.size === 1 ? presentation([...target.owners][0]) : {});
     const fields = [];
@@ -446,28 +428,50 @@ class ActionMenu {
  */
 class PreferencesClient {
     #module;
-    #configURL;
     #definition;
     #request;
     #notify;
     #timeout;
     #session = new AbortController();
-    #values;
+    #values = {};
     #saving = false;
 
     /**
-     * 创建只调用模块 API、不读取或解析 BoxJS 的页面客户端。
-     * Create a 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.
+     * 创建从 BoxJS 定义读取和持久化设置的页面客户端。
+     * Create a page client that reads and persists settings from a BoxJS definition.
+     * @param {import("./client.mjs").PreferencesClientOptions} options 字段定义、请求与通知 / Field definition, requests, and notifications.
      */
-    constructor({ model, definition, fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 }) {
-        this.#module = model.module;
-        this.#configURL = model.configURL;
+    constructor({ definition, fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 }) {
+        this.#module = definition.module;
         this.#definition = definition;
         this.#request = request;
         this.#notify = notify;
         this.#timeout = timeout;
-        this.#values = structuredClone(model.values);
+    }
+
+    /**
+     * 读取一次 Settings 子树并建立页面值快照。
+     * Read the Settings subtree once and establish the page value snapshot.
+     * @returns {Promise<import("./client.mjs").ModuleSnapshot>} 页面快照 / Page snapshot.
+     */
+    async open() {
+        let subtree = await this.readSettings();
+        if (subtree === undefined) subtree = {};
+        if (typeof subtree === "string") subtree = JSON.parse(subtree);
+        if (!subtree || typeof subtree !== "object" || Array.isArray(subtree)) throw new TypeError("Expected a settings subtree object");
+        const values = {};
+        for (const field of this.#definition.fields) {
+            const stored = field.key
+                .split(".")
+                .slice(this.#definition.settingsPath.length)
+                .reduce((parent, part) => Object(parent)[part], subtree);
+            const value = normalizeStoredValue(field, stored === undefined ? field.defaultValue : stored);
+            if (value === undefined) continue;
+            if (!validValue(field, value)) throw new TypeError(`Invalid stored value: ${field.key}`);
+            values[field.key] = value;
+        }
+        this.#values = values;
+        return this.snapshot();
     }
 
     /**
@@ -566,7 +570,7 @@ class PreferencesClient {
                 credentials: "omit",
                 cache: "no-store",
                 signal: controller.signal,
-                headers: { "Content-Type": "application/json", "X-PreferencePanes-JSON": this.#configURL },
+                headers: { "Content-Type": "application/json" },
                 body: JSON.stringify(payload),
             });
             if (response.status !== 200 && !(action === "get" && response.status === 404)) throw new Error(`HTTP ${response.status}`);
@@ -590,6 +594,10 @@ class PreferencesClient {
         if (this.#saving) throw new Error("A settings write is already in progress");
         this.#saving = true;
         try {
+            if (operation === "write") {
+                const field = this.#definition.fields.find(candidate => candidate.key === key);
+                if (!field || !validValue(field, payload.value)) throw new TypeError("Invalid setting value");
+            }
             await this.#send(action, payload);
             switch (operation) {
                 case "write":
@@ -787,24 +795,23 @@ class PreferencesPanel {
     #release;
 
     /**
-     * 挂载 API 返回的模块模型表单。
-     * Mount the module form returned by the API.
+     * 挂载 BoxJS 定义对应的模块表单。
+     * Mount the module form described by a BoxJS definition.
      * @param {HTMLElement} root 包内挂载元素 / Internal mount element.
-     * @param {import("../index.js").ModuleModel & {definition: import("../index.js").ModuleDefinition}} model 已规范化模块模型 / Normalized module model.
+     * @param {import("../index.js").ModuleDefinition} definition 已规范化字段定义 / Normalized field definition.
      */
-    constructor(root, model) {
-        this.#release = this.#mount(root, model);
+    constructor(root, definition) {
+        this.#release = this.#mount(root, definition);
     }
 
     /**
      * 建立面板 DOM、交互和会话，并返回其释放操作。
      * Build panel DOM, interactions, and session, then return its release operation.
      * @param {HTMLElement} root 包内挂载元素 / Internal mount element.
-     * @param {import("../index.js").ModuleModel & {definition: import("../index.js").ModuleDefinition}} model 已规范化模块模型 / Normalized module model.
+     * @param {import("../index.js").ModuleDefinition} definition 已规范化字段定义 / Normalized field definition.
      * @returns {() => void} 释放操作 / Release operation.
      */
-    #mount(root, model) {
-        const { definition } = model;
+    #mount(root, definition) {
         const title = definition.metadata?.name ?? definition.module;
         const document = root.ownerDocument;
         const window = document.defaultView;
@@ -896,7 +903,7 @@ class PreferencesPanel {
                 toast.hidden = true;
             }, 2400);
         };
-        const client = new PreferencesClient({ model, definition, notify });
+        const client = new PreferencesClient({ definition, notify });
         /**
          * 两种菜单入口共用异步错误处理，包含宿主确认框错误。
          * Share async error handling between both menus, including host-dialog errors.
@@ -924,6 +931,7 @@ class PreferencesPanel {
             publishNavigation();
             viewport.replaceChildren(statusView("读取设置…"));
             try {
+                await client.open();
                 if (version === generation) controls();
             } catch (error) {
                 if (version !== generation) return;
@@ -1312,15 +1320,14 @@ function installDefaultStyles(document) {
 }
 
 /**
- * 管理模块设置视图的模型规范化、样式、主题同步和面板生命周期。
- * Manage model normalization, styles, theme synchronization, and panel lifecycle for a module settings view.
+ * 管理 BoxJS 规范化、主题同步和面板生命周期。
+ * Manage BoxJS normalization, theme synchronization, and panel lifecycle.
  */
 class PreferencesView {
     #existing;
     #root;
     #base;
     #ownsBase;
-    #custom;
     #previousTitle;
     #previousTheme;
     #systemTheme;
@@ -1330,22 +1337,12 @@ class PreferencesView {
     #panel;
 
     /**
-     * 使用模块 API 返回的模型挂载设置页。
-     * Mount a settings page from the model returned by the module API.
-     * @param {import("../index.js").ModuleModel} model API 返回的模块模型 / Module model returned by the API.
-     * @param {string} [css] 可选 CSS 正文 / Optional module-scoped CSS text.
+     * 使用原始 BoxJS JSON 挂载设置页。
+     * Mount a settings page from raw BoxJS JSON.
+     * @param {import("../index.js").BoxJSInput} boxjs 单模块 BoxJS JSON / Single-module BoxJS JSON.
      */
-    constructor(model, css = "") {
-        if (typeof css !== "string") throw new TypeError("CSS must be a string");
-        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 };
+    constructor(boxjs) {
+        const definition = normalizeBoxJs(boxjs);
         const metadata = definition.metadata ?? {};
         const image = metadata.icon || metadata.icons?.[1] || metadata.icons?.[0];
         if (image) resourceURL(image);
@@ -1360,9 +1357,6 @@ class PreferencesView {
         const styles = installDefaultStyles(document);
         this.#base = styles.element;
         this.#ownsBase = styles.owned;
-        this.#custom = element("style", "");
-        this.#custom.textContent = css;
-        document.head.append(this.#custom);
         this.#previousTitle = document.title;
         this.#previousTheme = document.documentElement.dataset.theme;
         this.#systemTheme = window.matchMedia("(prefers-color-scheme: dark)");
@@ -1377,7 +1371,7 @@ class PreferencesView {
         document.title = metadata.name ?? definition.module;
         try {
             this.#root.replaceChildren();
-            this.#panel = new PreferencesPanel(this.#root, rendered);
+            this.#panel = new PreferencesPanel(this.#root, definition);
         } catch (error) {
             this.destroy();
             throw error;
@@ -1405,7 +1399,6 @@ class PreferencesView {
         this.#systemTheme.removeEventListener("change", this.#syncAppearance);
         this.#panel?.destroy();
         if (this.#ownsBase) this.#base.remove();
-        this.#custom.remove();
         if (this.#existing) this.#root.replaceChildren();
         else this.#root.remove();
         document.title = this.#previousTitle;
@@ -1416,11 +1409,20 @@ class PreferencesView {
 }
 
 /**
- * 管理模块文档的页面输入、初始请求、重载和错误状态。
- * Manage page inputs, initial requests, reloads, and error states for a module document.
+ * 使用原始 BoxJS JSON 挂载设置页。
+ * Mount a settings page from raw BoxJS JSON.
+ * @param {import("../index.js").BoxJSInput} boxjs 单模块 BoxJS JSON / Single-module BoxJS JSON.
+ * @returns {import("./index.js").MountedPreferences} 模块视图 / Module view.
+ */
+function mount(boxjs) {
+    return new PreferencesView(boxjs);
+}
+
+/**
+ * 管理模块文档的配置请求、重载和错误状态。
+ * Manage configuration requests, reloads, and error states for a module document.
  */
 class ModulePage {
-    #document;
     #window;
     #root;
     #view;
@@ -1431,7 +1433,6 @@ class ModulePage {
      * @param {Document} document 模块文档 / Module document.
      */
     constructor(document) {
-        this.#document = document;
         this.#window = document.defaultView;
         this.#root = document.querySelector("#preferences");
         installDefaultStyles(document);
@@ -1439,8 +1440,8 @@ class ModulePage {
     }
 
     /**
-     * 从 URL 或代理传递的 Header 导入 JSON/CSS，支持独立文档与 srcdoc。
-     * Import JSON/CSS from the URL or proxy-carried headers in standalone and srcdoc documents.
+     * 从规范模块路径读取 BoxJS JSON 并挂载通用前端。
+     * Read BoxJS JSON from the conventional module path and mount the generic frontend.
      * @returns {Promise<void>} 启动完成 / Startup completion.
      */
     async start() {
@@ -1448,12 +1449,13 @@ class ModulePage {
             this.#view?.destroy();
             this.#view = undefined;
             this.#root.replaceChildren(statusView("读取设置…"));
-            const inputs = this.#readInputs();
-            const apiURL = new URL(`/api/${encodeURIComponent(inputs.module)}`, inputs.url).href;
-            const styleURL = this.#resourceURL(inputs.css, inputs.url);
-            const [style, modelResponse] = await Promise.all([styleURL ? fetch(styleURL, { 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}`);
-            this.#view = new PreferencesView(await modelResponse.json(), style ? await style.text() : "");
+            const embedded = this.#window.frameElement?.dataset.preferencePanesModule;
+            const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(this.#window.location.pathname);
+            const module = embedded ?? match?.[1];
+            if (!module) throw new TypeError("Open a concrete module URL");
+            const response = await fetch(`/configs/${encodeURIComponent(module)}`, { cache: "no-store", credentials: "omit", headers: { Accept: "application/json" } });
+            if (response.status !== 200) throw new Error(`HTTP ${response.status}`);
+            this.#view = mount(await response.json());
         } catch (error) {
             this.#root.replaceChildren(statusView(`加载失败：${error.message}`, () => this.start()));
         }
@@ -1470,39 +1472,6 @@ class ModulePage {
         this.#view = undefined;
     }
 
-    /**
-     * 读取嵌入参数、文档元数据或当前 URL 输入。
-     * Read embedded parameters, document metadata, or current URL inputs.
-     * @returns {ReturnType<typeof pageInputs>} 页面输入 / Page inputs.
-     */
-    #readInputs() {
-        const context = this.#document.querySelector('meta[name="preference-panes-inputs"]');
-        const embedded = this.#window.frameElement?.dataset.preferencePanes;
-        switch (true) {
-            case embedded !== undefined:
-                this.#document.documentElement.dataset.preferencePanesEmbedded = "";
-                return JSON.parse(embedded);
-            case context !== null:
-                return JSON.parse(decodeURIComponent(context.content));
-            default:
-                return pageInputs(new URL(this.#window.location.href));
-        }
-    }
-
-    /**
-     * 将可选页面资源限制为 HTTP(S) 地址。
-     * Restrict an optional page resource to an HTTP(S) URL.
-     * @param {string | undefined} source 资源地址 / Resource location.
-     * @param {string} baseURL 页面基准地址 / Page base URL.
-     * @returns {string | null} 绝对资源地址 / Absolute resource URL.
-     */
-    #resourceURL(source, baseURL) {
-        if (!source) return null;
-        const url = new URL(source, baseURL);
-        if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("Resources must use HTTP(S) URLs");
-        return url.href;
-    }
-
     /**
      * 从前进后退缓存恢复时重新加载模块。
      * Reload the module when restored from the back-forward cache.
@@ -1515,5 +1484,3 @@ class ModulePage {
 }
 
 new ModulePage(document).start();
-
-export { ModulePage };