@nsnanocat/preference-panes 0.4.1 → 0.6.0

package/README.md

@@ -67,11 +67,11 @@ const panel = mountPreferencePanes({ element: document.querySelector("#preferenc
 
 模块页底部提供查看/刷新 Caches、清空 Caches 和重置模块。查看缓存按需 GET；清空和重置经确认后 DELETE，成功只更新本页状态。重置后控件显示当前 BoxJS 默认值，再次进入页面才重新读取。模块选择、设置值校验和默认值处理都在前端完成。
 
-主菜单、导航、控件和样式均由本包实现。调用项目只提供品牌与模块 JSON，不需要维护 HTML、页面 JS、CSS 或专用 Rollup 配置。未提供对应配置 Mock 的插件入口保持禁用。
+主菜单、导航、控件和样式均由本包实现。业务插件只提供 BoxJS JSON；品牌、菜单、图标与安装映射属于托管站点。插件不导入本包、不维护页面代码，也不把设置请求接入自己的业务 Request。未提供对应配置 Mock 的插件入口保持禁用。
 
 ## 零前端代码接入
 
-部署本包的 `dist/settings/` 到 `/settings/assets/`，将其中 index.html 同时用于 `/settings/` 与 `/settings/{module}`。根菜单读取同目录的 `site.boxjs.json`：
+托管站点安装本包，部署 `dist/settings/` 到 `/settings/assets/`，将其中 index.html 同时用于 `/settings/` 与 `/settings/{module}`。根菜单读取由站点维护的 `site.boxjs.json`，这份主菜单不放在业务插件仓库：
 
 ~~~json
 {
@@ -86,7 +86,23 @@ const panel = mountPreferencePanes({ element: document.querySelector("#preferenc
 
 根页面每次进入重新 HEAD 探测，菜单 JSON 在当前文档只读取一次；模块页直接打开时无需先读菜单。图片与额外样式由托管站点提供。
 
-代理优先使用原生 Mock 提供配置和页面。需要请求脚本响应静态资源的平台，直接使用本包的 PreferencesHandler，安装参数也可放在 JSON 中：
+代理优先使用原生 Mock 提供配置和页面。存储 API 和没有原生 Mock 的资源请求，由独立代理脚本处理。托管站点维护 installation JSON（origin/storageKey/module/resources），并用包内已经构建好的代理运行时生成安装文件：
+
+~~~js
+import { readFile, writeFile } from "node:fs/promises";
+
+const runtime = await readFile(new URL(import.meta.resolve("@nsnanocat/preference-panes/dist/preference-panes.proxy.js")), "utf8");
+const installation = JSON.parse(await readFile("installation.json", "utf8"));
+await writeFile("PreferencePanes.request.js", `${runtime}\nPreferencePanes.runPreferences(${JSON.stringify(installation)});\n`);
+~~~
+
+通用运行时由独立 PreferencePanes 代理模块安装一次，统一匹配 /api/ 与页面资源；业务插件不再安装读写或页面规则，只提供 /configs/{module} 的配置 Mock。安装映射的 module 可以是模块名数组，例如 ["Module", "Other"]，统一模块只能访问声明范围。生成文件不依赖 $argument，Quantumult X 也使用同一文件。API 不下载安装 JSON 或 BoxJS。
+
+独立模块不得匹配 /configs/，资源映射也不得为配置 Mock 提供兜底。主菜单每次进入只 HEAD 配置 Mock；HTTP 200 启用入口，打开后 GET 并解析 JSON。配置缺失、无有效字段或解析失败时不读取设置 API、不生成设置表单。API 可达不代表某个业务模块提供了设置界面。
+
+Surge/Loon 的业务插件使用原生 JSON Mock。需要脚本响应配置的平台，由托管站点将包内 dist/preference-panes.config.js 与 `PreferencePanes.mockConfiguration(BoxJS_JSON)` 拼接生成配置响应文件。该文件只支持 GET/HEAD，不包含存储、网络下载或页面处理；它只安装在业务插件的 /configs/{module} 规则中。关闭业务插件后 Mock 消失，独立通用模块继续启用也不会误判该设置入口可用。
+
+以下是包内部处理器接受的安装映射形状；也可供需要手动集成的宿主使用：
 
 ~~~js
 import { PreferencesHandler } from "@nsnanocat/preference-panes";
@@ -96,14 +112,13 @@ const handler = new PreferencesHandler({
   storageKey: "Root",
   module: "Module",
   resources: [
-    { pattern: "^/configs/Module$", source: "https://example.org/settings/assets/Module.boxjs.json", contentType: "application/json" },
     { pattern: "^/settings/(?:[a-zA-Z0-9_-]+/?)?$", source: "https://example.org/settings/assets/index.html", contentType: "text/html" }
   ]
 });
 const response = await handler.handle($request);
 ~~~
 
-资源 pattern 匹配 pathname，下载源必须避开拦截路径。只有命中静态资源的 GET/HEAD 才下载文件；API 由 SettingsHandler 直接处理，读写不会下载 BoxJS。接入方保留宿主请求入口和原生 Mock 规则，将响应交给现有 done 适配；无需自行实现路由、fetch、控件或持久化操作。
+资源 pattern 匹配 pathname，下载源必须避开拦截路径。只有命中静态资源的 GET/HEAD 才下载文件；API 由 SettingsHandler 直接处理，读写不会下载 BoxJS。业务插件只保留配置 Mock；页面与 API 安装规则全部属于独立 PreferencePanes 模块。
 
 ## BoxJS 兼容
 
@@ -129,6 +144,6 @@ npm run apifox:check
 npm pack --dry-run
 ~~~
 
-构建生成 dist/preference-panes.mjs、dist/preference-panes.request.js，以及可直接部署的 dist/settings/{index.html,app.mjs,panel.css,home.css}。静态文件也通过 `@nsnanocat/preference-panes/dist/settings/*` 导出，托管仓库直接从依赖包复制，不读取业务插件的前端构建目录。0.4.0 增加完整页面与资源处理器，保留 0.3.1 的存储契约和页面交互。
+构建生成 dist/preference-panes.mjs、读取宿主参数的 dist/preference-panes.request.js、供托管站点配置的 dist/preference-panes.proxy.js、仅返回配置的 dist/preference-panes.config.js，以及可直接部署的 dist/settings/{index.html,app.mjs,panel.css,home.css}。0.6.0 支持独立模块统一处理多个业务模块，并将配置 Mock 与通用读写安装彻底分开。
 
 [完整接口说明](apifox/guide.md) · [Apifox JSON](apifox/preference-panes.apifox.json) · [同步方式](apifox/README.md) · [发布工作流](.github/RELEASING.md)