@nsnanocat/preference-panes 1.0.0 → 1.1.1

package/README.md

@@ -1,74 +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` 只返回三类通用资源：
 
-宿主也可监听 `notice` 事件，通过 `preventDefault()` 接管 `{kind, message}` 提示；被接管时模块不创建网页 Toast、不启用提示计时器。独立使用的通用面板仍提供默认通知。
+- `GET /settings/{module}`
+- `GET /settings/assets/index.mjs`
+- `GET /settings/assets/navigation.mjs`
 
-业务模块分别映射同一 Release 的两个产物：`api.js` 只匹配 `/api/{module}` 及其动作，`web.js` 只匹配 `/settings/{module}`、`/settings/assets/app.mjs` 和 `/settings/assets/navigation.mjs`。两者都不包含业务配置，也不需要额外安装独立设置插件。
+模块页面从 URL 或 `ModuleFrame` 的模块标记取得模块名，直接读取同源 `/configs/{module}`，然后调用 `mount(boxjs)`。页面不接受 JSON/CSS 查询参数、私有请求头或兼容资源别名。
 
-网页只调用模块 API：`HEAD /api/{module}` 探测模块，`GET /api/{module}` 取得原始 BoxJS 与当前已存值，`POST /api/{module}/get|set|delete` 执行持久化操作。`api.js` 负责取得 BoxJS、确认字段 ID 并把完整 `@root.path` 直接交给 util `Storage`；网页不直接请求配置 Mock，也不提交存储根。
+`api.js` 只处理：
+
+- `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 { mount } from "@nsnanocat/preference-panes/browser";
-const model = await fetch("/api/Module", {
-    headers: { "X-PreferencePanes-JSON": "/configs/Module" },
-}).then(response => response.json());
-const page = mount(model, ".pp-panel { --pp-accent: #16866a; }");
-page.destroy();
-```
-
-API 支持字段数组、单 app 和 apps 订阅，只扫描 `@Root.Module.Settings.key` 形式的字段 ID。浏览器从 API 返回的同一份 BoxJS 解析控件、名称、图标和默认值；省略 CSS 使用内置样式。
+import { ModuleFrame, ModuleStatus } from "@nsnanocat/preference-panes/navigation";
 
-`/settings/{module}` 由独立 `web.js` 返回模块文档。页面可通过 json/css 查询参数或 X-PreferencePanes-JSON/CSS Header 指定资源 URL；默认 JSON 是 /configs/{module}，CSS 默认空。Header 分别优先。`web.js` 不访问网络或存储，浏览器执行其中的 `app.mjs` 后才调用 `api.js`。
+const status = new ModuleStatus(statusElement);
+await status.check("/api/Module");
 
-```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/app.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/app.mjs?v=1.0.0"></script>
+        <script type="module" src="/settings/assets/index.mjs?v=1.1.1"></script>
     </body>
 </html>