@nsnanocat/preference-panes 1.2.3 → 1.2.5

package/README.md

@@ -2,7 +2,7 @@
 
 PreferencePanes 提供一个由 BoxJS JSON 驱动的通用设置前端，以及一个独立的代理持久化 API。业务模块直接将自己的 BoxJS JSON Mock 到 `/api/{module}`；通用 `/settings/**` 前端和固定存储 API 分别只需要安装一次。
 
-在 Biliverse 中，Enhanced 是唯一安装 `web.js` 的模块。Global、Redirect、ADBlock 不携带 `web.js`，它们的设置页仍由同一份通用前端读取各自 BoxJS 后渲染。
+在 Biliverse 中，Enhanced 统一映射 PreferencePanes 发布的静态模块 HTML、页面入口和导航组件。Global、Redirect、ADBlock 不重复携带页面资源，它们的设置页仍由同一份通用前端读取各自 BoxJS 后渲染。
 
 ## 浏览器入口
 
@@ -29,17 +29,17 @@ preferences.destroy();
 
 前端支持 BoxJS 字段数组、单个 app 和 apps 订阅，并要求输入恰好包含一个模块。模块名、存储根和 Settings 路径都从 `@Root.Module.Settings.key` 字段 ID 推导，不从 app 名称或调用参数补充。
 
-默认样式随包内置。动态模块 HTML 可通过 `css` 查询参数或优先级更高的 `X-PreferencePanes-CSS` Header 直接加载一个项目 stylesheet；未提供时只使用默认样式。项目 stylesheet 位于默认样式之后，可覆盖 `pp-*` 变量和组件规则。页面脚本不二次下载 CSS，也不识别客户端 User-Agent 或加载客户端 SDK。
+默认样式随包内置。静态模块页接受 `json`、`css` 查询参数；嵌入 `ModuleFrame` 时也可通过 `X-PreferencePanes-JSON`、`X-PreferencePanes-CSS` 选项传入两个资源 URL。未指定 JSON 时默认读取 `/api/{module}`，未指定 CSS 时只使用默认样式。项目 stylesheet 位于默认样式之后，可覆盖 `pp-*` 变量和组件规则。页面脚本不识别客户端 User-Agent，也不加载客户端 SDK。
 
 ## 页面与 API
 
-`web.js` 只返回三类通用资源：
+Release 分别提供三项可直接映射的页面资源：
 
 - `GET /settings/{module}`
 - `GET /settings/assets/index.mjs`
 - `GET /settings/assets/navigation.mjs`
 
-模块页面从 URL 或 `ModuleFrame` 的模块标记取得模块名，通过同源 `/api/{module}` 读取原始 BoxJS，然后调用 `mount(boxjs)`。`web.js` 只在生成 HTML 时解析可选 CSS 地址并写入 `<link data-preference-panes-stylesheet>`；CSS 地址必须解析为 HTTP(S)。页面不接受 JSON 输入或兼容资源别名，也不直接访问 `/configs/**`。
+模块 HTML、页面入口和导航组件分别对应 Release 的 `index.html`、`index.mjs`、`navigation.mjs`，不得再打包进代理响应脚本。模块页面从 URL 或 `ModuleFrame` 的模块标记取得模块名，读取 BoxJS 资源后调用 `mount(boxjs)`。BoxJS 与可选 CSS 地址必须解析为 HTTP(S)；未声明 BoxJS 时回退同源 `/api/{module}`，页面不直接访问 `/configs/**`。
 
 业务模块模板直接处理：
 
@@ -76,13 +76,16 @@ await status.check("/api/Module");
 
 const frame = new ModuleFrame("/settings/Module", {
     signal,
-    headers: { "X-PreferencePanes-CSS": "https://example.org/theme.css" },
+    headers: {
+        "X-PreferencePanes-JSON": "https://example.org/Module.boxjs.json",
+        "X-PreferencePanes-CSS": "https://example.org/theme.css",
+    },
 });
 container.append(frame.element);
 await frame.load();
 ```
 
-`ModuleFrame` 接受 `{ signal?: AbortSignal; headers?: HeadersInit }`，使用这些选项发送一次 GET，并将返回 HTML 原样设置为 `iframe.srcdoc`。iframe dataset 只保存模块身份，不保存 CSS 地址。宿主通过 `change`、`confirm`、`notice`、`open-url` 事件同步标题、操作菜单、确认框、提示和链接跳转，不读取或改写 iframe 内部 DOM。项目主页、Bilibili JSBridge、原生导航和视觉样式仍由宿主负责。
+`ModuleFrame` 接受 `{ signal?: AbortSignal; headers?: HeadersInit }`。`X-PreferencePanes-JSON` 与 `X-PreferencePanes-CSS` 只用于校验并写入 iframe 数据属性，不作为网络请求 Header；静态 HTML 仍以普通 GET 获取并原样设置为 `iframe.srcdoc`。宿主通过 `change`、`confirm`、`notice`、`open-url` 事件同步标题、操作菜单、确认框、提示和链接跳转，不读取或改写 iframe 内部 DOM。项目主页、Bilibili JSBridge、原生导航和视觉样式仍由宿主负责。
 
 ## 构建与验证
 
@@ -93,8 +96,16 @@ npm run apifox:check
 npm pack --dry-run
 ```
 
-构建生成 `dist/api.js`、`dist/web.js`、`dist/preference-panes.mjs` 和 `dist/module/` 通用页面资源。包不再提供按模块生成 HTML/CSS 的公开 `build()`。
+构建生成 `dist/api.js`、`dist/preference-panes.mjs` 和 `dist/module/index.html`、`index.mjs`、`navigation.mjs`。包不提供 `web.js`，也不提供按模块生成 HTML/CSS 的公开 `build()`。
 
-`npm run preview` 启动 JSON 文件导入测试台，使用同一通用页面、同源配置和内存存储验证模块行为。
+### 内置演示
+
+```sh
+npm run preview
+```
+
+预览入口会自动加载 `examples/Module.boxjs.json`，覆盖 `boolean`、`selects`、`checkboxes`、`text`、`textarea`、`number` 和 `url` 全部受支持控件。顶端 CSS 选择器默认使用包内置 CSS，也可切换 `examples/theme.css` 或导入本地 CSS 文件。预览服务器直接提供正式构建的静态模块页和 JS 文件，通过 `json`、`css` 查询参数传入资源地址，并使用固定存储 API 与独立内存存储，不维护演示专用渲染器。
+
+内置存储会提供已移除选项和格式错误值，用于直接核对字段级黄色警告及非阻断加载；URL 字段还会携带同路径旧存储值，验证只读链接始终使用 BoxJS `val`。测试台同时保留上传其它 BoxJS JSON 并生成隔离预览的能力。
 
 [接口规范](apifox/Specification.md) · [宿主集成](apifox/HostIntegration.md) · [Apifox JSON](apifox/preference-panes.apifox.json)

package/dist/module/index.html

@@ -4,12 +4,13 @@
         <meta charset="utf-8">
         <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
         <meta name="color-scheme" content="light dark">
+        
         <title>Module Preferences</title>
         <style>body { margin: 0; }</style>
         
     </head>
     <body>
         <main id="preferences"></main>
-        <script type="module" src="/settings/assets/index.mjs?v=1.2.3"></script>
+        <script type="module" src="/settings/assets/index.mjs?v=1.2.5"></script>
     </body>
 </html>

package/dist/module/index.mjs

@@ -1561,8 +1561,8 @@ class ModulePage {
     }
 
     /**
-     * 通过模块 API 读取 BoxJS JSON 并挂载通用前端。
-     * Read BoxJS JSON through the module API and mount the generic frontend.
+     * 读取页面声明的 BoxJS JSON 并挂载通用前端。
+     * Read the BoxJS JSON declared by the page and mount the generic frontend.
      * @returns {Promise<void>} 启动完成 / Startup completion.
      */
     async start() {
@@ -1574,7 +1574,23 @@ class ModulePage {
             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(`/api/${encodeURIComponent(module)}`, { cache: "no-store", credentials: "omit", headers: { Accept: "application/json" } });
+            const frame = this.#window.frameElement?.dataset;
+            const base = frame?.preferencePanesBase ?? this.#window.location.href;
+            this.#window.document.querySelector("link[data-preference-panes-stylesheet]")?.remove();
+            const stylesheetSource = frame?.preferencePanesStylesheet ?? new URLSearchParams(this.#window.location.search).get("css")?.trim();
+            if (stylesheetSource) {
+                const stylesheet = new URL(stylesheetSource, base);
+                if (!["http:", "https:"].includes(stylesheet.protocol)) throw new TypeError("CSS resource must use HTTP(S)");
+                const link = this.#window.document.createElement("link");
+                link.dataset.preferencePanesStylesheet = "true";
+                link.rel = "stylesheet";
+                link.href = stylesheet.href;
+                this.#window.document.head.append(link);
+            }
+            const jsonSource = frame?.preferencePanesJson ?? new URLSearchParams(this.#window.location.search).get("json")?.trim();
+            const source = new URL(jsonSource || `/api/${encodeURIComponent(module)}`, base);
+            if (!["http:", "https:"].includes(source.protocol)) throw new TypeError("BoxJS resource must use HTTP(S)");
+            const response = await fetch(source, { cache: "no-store", credentials: "omit", headers: { Accept: "application/json" } });
             if (response.status !== 200) throw new Error(`HTTP ${response.status}`);
             const boxjs = await response.json();
             normalizeBoxJs(boxjs, module);

package/dist/module/navigation.mjs

@@ -147,8 +147,8 @@ class ActionMenu {
 }
 
 /**
- * 模块文档容器：发送 GET 请求并将原始 HTML 交给 iframe，只在元素上标记模块身份。
- * Module document container: send a GET request, preserve HTML verbatim and mark only the module identity on the iframe.
+ * 模块文档容器：获取静态 HTML，并通过 iframe 数据属性传递页面资源输入。
+ * Module document container: fetch static HTML and pass page resource inputs through iframe data attributes.
  */
 class ModuleFrame extends EventTarget {
     #url;
@@ -178,11 +178,27 @@ class ModuleFrame extends EventTarget {
         this.#url = new URL(url, document.baseURI);
         const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(this.#url.pathname);
         if (!match) throw new TypeError("Open a concrete module URL");
-        this.#options = { signal: options.signal, headers: options.headers };
+        this.#options = { signal: options.signal };
         this.element = document.createElement("iframe");
         this.element.title = `${match[1]} 设置`;
         this.element.dataset.preferencePanes = "true";
         this.element.dataset.preferencePanesModule = match[1];
+        this.element.dataset.preferencePanesBase = this.#url.href;
+        const headers = new Headers(options.headers);
+        for (const [header, property, kind] of [
+            ["X-PreferencePanes-JSON", "preferencePanesJson", "BoxJS"],
+            ["X-PreferencePanes-CSS", "preferencePanesStylesheet", "CSS"],
+        ]) {
+            if (!headers.has(header)) continue;
+            const source = headers.get(header)?.trim();
+            if (!source) {
+                if (kind === "BoxJS") throw new TypeError("BoxJS resource URL is required");
+                continue;
+            }
+            const resource = new URL(source, this.#url);
+            if (!["http:", "https:"].includes(resource.protocol)) throw new TypeError(`${kind} resource must use HTTP(S)`);
+            this.element.dataset[property] = resource.href;
+        }
         this.element.addEventListener("preferencepanes:change", this.#change);
         this.element.addEventListener("preferencepanes:confirm", this.#confirmation);
         this.element.addEventListener("preferencepanes:notice", this.#notice);
@@ -208,7 +224,7 @@ class ModuleFrame extends EventTarget {
         if (this.#options.signal?.aborted) this.destroy();
         const timer = setTimeout(() => this.#controller.abort(), 10000);
         try {
-            const response = await fetch(this.#url, { method: "GET", cache: "no-store", credentials: "omit", headers: this.#options.headers, signal: this.#controller.signal });
+            const response = await fetch(this.#url, { method: "GET", cache: "no-store", credentials: "omit", signal: this.#controller.signal });
             if (response.status !== 200) throw new Error(`HTTP ${response.status}`);
             const html = await response.text();
             this.#controller.signal.throwIfAborted();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nsnanocat/preference-panes",
-    "version": "1.2.3",
+    "version": "1.2.5",
     "description": "Generic BoxJS settings frontend and persistence API for JavaScript proxy modules",
     "author": "VirgilClyne <Virgil@nanocat.me>",
     "homepage": "https://NSNanoCat.github.io/preference-panes",

package/src/browser/ModuleFrame.mjs

@@ -1,6 +1,6 @@
 /**
- * 模块文档容器：发送 GET 请求并将原始 HTML 交给 iframe，只在元素上标记模块身份。
- * Module document container: send a GET request, preserve HTML verbatim and mark only the module identity on the iframe.
+ * 模块文档容器：获取静态 HTML，并通过 iframe 数据属性传递页面资源输入。
+ * Module document container: fetch static HTML and pass page resource inputs through iframe data attributes.
  */
 export class ModuleFrame extends EventTarget {
     #url;
@@ -30,11 +30,27 @@ export class ModuleFrame extends EventTarget {
         this.#url = new URL(url, document.baseURI);
         const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(this.#url.pathname);
         if (!match) throw new TypeError("Open a concrete module URL");
-        this.#options = { signal: options.signal, headers: options.headers };
+        this.#options = { signal: options.signal };
         this.element = document.createElement("iframe");
         this.element.title = `${match[1]} 设置`;
         this.element.dataset.preferencePanes = "true";
         this.element.dataset.preferencePanesModule = match[1];
+        this.element.dataset.preferencePanesBase = this.#url.href;
+        const headers = new Headers(options.headers);
+        for (const [header, property, kind] of [
+            ["X-PreferencePanes-JSON", "preferencePanesJson", "BoxJS"],
+            ["X-PreferencePanes-CSS", "preferencePanesStylesheet", "CSS"],
+        ]) {
+            if (!headers.has(header)) continue;
+            const source = headers.get(header)?.trim();
+            if (!source) {
+                if (kind === "BoxJS") throw new TypeError("BoxJS resource URL is required");
+                continue;
+            }
+            const resource = new URL(source, this.#url);
+            if (!["http:", "https:"].includes(resource.protocol)) throw new TypeError(`${kind} resource must use HTTP(S)`);
+            this.element.dataset[property] = resource.href;
+        }
         this.element.addEventListener("preferencepanes:change", this.#change);
         this.element.addEventListener("preferencepanes:confirm", this.#confirmation);
         this.element.addEventListener("preferencepanes:notice", this.#notice);
@@ -60,7 +76,7 @@ export class ModuleFrame extends EventTarget {
         if (this.#options.signal?.aborted) this.destroy();
         const timer = setTimeout(() => this.#controller.abort(), 10000);
         try {
-            const response = await fetch(this.#url, { method: "GET", cache: "no-store", credentials: "omit", headers: this.#options.headers, signal: this.#controller.signal });
+            const response = await fetch(this.#url, { method: "GET", cache: "no-store", credentials: "omit", signal: this.#controller.signal });
             if (response.status !== 200) throw new Error(`HTTP ${response.status}`);
             const html = await response.text();
             this.#controller.signal.throwIfAborted();

package/src/browser/Navigation.d.mts

@@ -1,6 +1,6 @@
 /**
- * 原始 HTML 的模块 iframe 容器；请求选项不写入元素上下文。
- * Iframe container preserving module HTML without writing request options to element context.
+ * 静态 HTML 的模块 iframe 容器；页面资源输入写入 iframe 数据属性。
+ * Static HTML module iframe whose resource inputs are written to iframe data attributes.
  * confirm 事件可 preventDefault 后通过 detail.resolve/reject 完成宿主确认。
  * Prevent default on confirm events and settle host dialogs through detail.resolve/reject.
  * notice 事件可 preventDefault 后交由宿主显示，模块不再创建网页 Toast。
@@ -13,7 +13,7 @@ export class ModuleFrame extends EventTarget {
      * 创建容器。
      * Create a container.
      * @param url 模块地址 / Module URL.
-     * @param options GET 请求选项 / GET request options.
+     * @param options 静态页面请求与资源输入 / Static page request and resource inputs.
      */
     constructor(url: string | URL, options?: { signal?: AbortSignal; headers?: HeadersInit });
     /**

package/src/browser/index.mjs

@@ -25,8 +25,8 @@ class ModulePage {
     }
 
     /**
-     * 通过模块 API 读取 BoxJS JSON 并挂载通用前端。
-     * Read BoxJS JSON through the module API and mount the generic frontend.
+     * 读取页面声明的 BoxJS JSON 并挂载通用前端。
+     * Read the BoxJS JSON declared by the page and mount the generic frontend.
      * @returns {Promise<void>} 启动完成 / Startup completion.
      */
     async start() {
@@ -38,7 +38,23 @@ class ModulePage {
             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(`/api/${encodeURIComponent(module)}`, { cache: "no-store", credentials: "omit", headers: { Accept: "application/json" } });
+            const frame = this.#window.frameElement?.dataset;
+            const base = frame?.preferencePanesBase ?? this.#window.location.href;
+            this.#window.document.querySelector("link[data-preference-panes-stylesheet]")?.remove();
+            const stylesheetSource = frame?.preferencePanesStylesheet ?? new URLSearchParams(this.#window.location.search).get("css")?.trim();
+            if (stylesheetSource) {
+                const stylesheet = new URL(stylesheetSource, base);
+                if (!["http:", "https:"].includes(stylesheet.protocol)) throw new TypeError("CSS resource must use HTTP(S)");
+                const link = this.#window.document.createElement("link");
+                link.dataset.preferencePanesStylesheet = "true";
+                link.rel = "stylesheet";
+                link.href = stylesheet.href;
+                this.#window.document.head.append(link);
+            }
+            const jsonSource = frame?.preferencePanesJson ?? new URLSearchParams(this.#window.location.search).get("json")?.trim();
+            const source = new URL(jsonSource || `/api/${encodeURIComponent(module)}`, base);
+            if (!["http:", "https:"].includes(source.protocol)) throw new TypeError("BoxJS resource must use HTTP(S)");
+            const response = await fetch(source, { cache: "no-store", credentials: "omit", headers: { Accept: "application/json" } });
             if (response.status !== 200) throw new Error(`HTTP ${response.status}`);
             const boxjs = await response.json();
             normalizeBoxJs(boxjs, module);

package/src/browser/module.html

@@ -4,6 +4,7 @@
         <meta charset="utf-8">
         <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
         <meta name="color-scheme" content="light dark">
+        <!--__PREFERENCE_PANES_JSON__-->
         <title>Module Preferences</title>
         <style>body { margin: 0; }</style>
         <!--__PREFERENCE_PANES_STYLESHEET__-->