@nsnanocat/preference-panes 0.7.1 → 0.8.0

package/src/Store.mjs

@@ -2,83 +2,70 @@ import { URL } from "@nsnanocat/url";
 import { Lodash as _ } from "@nsnanocat/util/polyfill/Lodash.mjs";
 import { Storage } from "@nsnanocat/util/polyfill/Storage";
 import { response } from "./lib/response.mjs";
-import { parseSettingsPathname } from "./lib/settings-path.mjs";
+import { validatePathParts } from "./lib/settings-path.mjs";
 
 /**
- * 根据 BoxJS 目录桥接持久化存储，不下载配置或解析控件。
- * Bridge persistence using the BoxJS catalog without downloading configuration or interpreting controls.
+ * 无配置绑定的本地存储桥接；form 字段名就是完整 @root.path。
+ * Unbound local storage bridge; the form field name is the complete @root.path.
  */
 export class Store {
-    #catalog;
-
-    /**
-     * 复用包内已解析的目录，构造时不访问网络或存储。
-     * Reuse the parsed internal catalog without network or persistence access during construction.
-     * @param {import("./BoxJS.mjs").BoxJS} catalog BoxJS 路径目录 / BoxJS path catalog.
-     */
-    constructor(catalog) {
-        this.#catalog = catalog;
-    }
-
     /**
-     * GET 返回指定值，POST 替换指定值，DELETE 删除指定键或整个模块。
-     * GET returns a value, POST replaces it, and DELETE removes a key or the entire module.
+     * POST /api/get、set、delete；不下载配置、不解析控件、不鉴权。
+     * POST /api/get, set or delete without config downloads, control parsing or authentication.
      * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
-     * @param {URL} [url] 包内复用的已解析地址 / Parsed URL reused within the package.
-     * @returns {Promise<import("./index.js").SettingsResponse | undefined>} 响应或非接管请求 / Response, or undefined for an unhandled request.
+     * @param {URL} [url] 已解析地址 / Parsed URL.
+     * @returns {Promise<import("./index.js").SettingsResponse | undefined>} 操作结果 / Operation result.
      */
     async handle(request, url = new URL(request.url)) {
         if (!url.pathname.startsWith("/api/")) return;
         const reply = (status, data) => response(request, status, data);
-        let parts;
+        const action = url.pathname.slice(5);
+        if (!["get", "set", "delete"].includes(action)) return reply(404, { error: "Unknown action" });
+        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 {
-            parts = parseSettingsPathname(url.pathname);
+            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) {
             return reply(400, { error: error.message });
         }
-        const binding = this.#catalog.modules.get(parts[0]);
-        if (!binding) return reply(404, { error: "Module is not declared in BoxJS" });
-        const requestHeaders = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
-        if (requestHeaders["x-settings-client"] !== "1" || (requestHeaders.origin && requestHeaders.origin !== url.origin)) return reply(403, { error: "Forbidden settings client" });
-        let value;
-        switch (request.method) {
-            case "HEAD":
-                return reply(200, undefined);
-            case "GET":
-            case "DELETE":
-                break;
-            case "POST":
-                if (requestHeaders["content-type"]?.split(";")[0].trim().toLowerCase() !== "application/json") return reply(415, { error: "Expected application/json" });
-                if (typeof request.body !== "string") return reply(400, { error: "Expected a JSON string body" });
-                if (request.body.length > 65536) return reply(413, { error: "Body exceeds 65536 UTF-16 code units" });
-                try {
-                    value = JSON.parse(request.body);
-                } catch {
-                    return reply(400, { error: "Invalid JSON" });
-                }
-                break;
-            default:
-                return { ...reply(405, { error: "Method not allowed" }), headers: { ...reply(405).headers, Allow: "HEAD, GET, POST, DELETE" } };
+        if (action === "set") {
+            try {
+                value = JSON.parse(value);
+            } catch (error) {
+                if (!(error instanceof SyntaxError)) throw error;
+            }
         }
+        const [storageKey, ...path] = parts;
         try {
-            const root = Storage.getItem(binding.storageKey, {});
-            if (!isRecord(root)) throw new TypeError("stored root must be an object");
-            const parent = storageParent(root, parts, request.method === "POST");
-            const key = parts.at(-1);
-            switch (request.method) {
-                case "GET": {
+            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 ? _.get(parent, [key]) : undefined;
                     return result === undefined ? reply(404, { error: "Stored path does not exist" }) : reply(200, result);
                 }
-                case "POST":
+                case "set":
                     _.set(parent, [key], value);
                     break;
-                case "DELETE":
+                case "delete":
                     if (parent) _.unset(parent, [key]);
                     break;
             }
-            if (!Storage.setItem(binding.storageKey, root)) throw new Error("Storage write failed");
-            return reply(200, request.method === "POST" ? { saved: true } : { deleted: true });
+            if (!Storage.setItem(storageKey, root)) throw new Error("Storage write failed");
+            return reply(200, action === "set" ? { saved: true } : { deleted: true });
         } catch (error) {
             return reply(500, { error: error.message });
         }

package/src/browser/ModuleFrame.mjs

@@ -0,0 +1,83 @@
+import { pageInputs } from "../lib/page-inputs.mjs";
+
+/**
+ * 模块文档容器：原始 HTML 不改写，请求上下文随 iframe 元素传递。
+ * Module document container: preserve HTML verbatim and carry request context on the iframe element.
+ */
+export class ModuleFrame extends EventTarget {
+    #url;
+    #options;
+    #controller = new AbortController();
+    #abort = () => this.destroy();
+    #state;
+    #change = event => {
+        this.#state = event.detail;
+        this.dispatchEvent(new Event("change"));
+    };
+
+    /**
+     * 建立 iframe 与请求输入；调用方挂载 element 后调用 load。
+     * Create the iframe and request inputs; callers mount element and then call load.
+     * @param {string | URL} url 模块请求地址 / Module request URL.
+     * @param {RequestInit} [options] 原生请求头和取消信号 / Native headers and cancellation signal.
+     */
+    constructor(url, options = {}) {
+        super();
+        this.#url = new URL(url, document.baseURI);
+        this.#options = { ...options, headers: new Headers(options.headers) };
+        const inputs = pageInputs(this.#url, Object.fromEntries(this.#options.headers));
+        this.element = document.createElement("iframe");
+        this.element.title = `${inputs.module} 设置`;
+        this.element.dataset.preferencePanes = JSON.stringify(inputs);
+        this.element.addEventListener("preferencepanes:change", this.#change);
+        this.#state = { title: inputs.module, module: inputs.module, busy: false, canGoBack: true };
+        options.signal?.addEventListener("abort", this.#abort, { once: true });
+    }
+
+    /**
+     * 当前模块导航状态。
+     * Current module navigation state.
+     */
+    get state() {
+        return { ...this.#state };
+    }
+
+    /**
+     * 获取原始 HTML；晚到响应在退出后不得重新挂载。
+     * Fetch unmodified HTML; a late response must not remount after departure.
+     * @returns {Promise<void>} HTML 已交给 iframe；表单状态通过 change 事件提供 / HTML assigned; form state is reported through change.
+     */
+    async load() {
+        if (this.#options.signal?.aborted) this.destroy();
+        const timer = setTimeout(() => this.#controller.abort(), 10000);
+        try {
+            const response = await fetch(this.#url, { cache: "no-store", credentials: "omit", ...this.#options, signal: this.#controller.signal });
+            if (response.status !== 200) throw new Error(`HTTP ${response.status}`);
+            const html = await response.text();
+            this.#controller.signal.throwIfAborted();
+            this.element.srcdoc = html;
+        } finally {
+            clearTimeout(timer);
+        }
+    }
+
+    /**
+     * 使用 iframe 的联合历史返回；写入期间不导航。
+     * Navigate joint iframe history back, except while a write is pending.
+     * @returns {void} 无返回值 / No return value.
+     */
+    back() {
+        if (!this.#state.busy && this.#state.canGoBack) this.element.contentWindow.history.back();
+    }
+
+    /**
+     * 取消加载与事件订阅；节点保留到 Navigation 的退出动画结束。
+     * Cancel loading and subscriptions; Navigation retains the node until its exit animation ends.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#controller.abort();
+        this.#options.signal?.removeEventListener("abort", this.#abort);
+        this.element.removeEventListener("preferencepanes:change", this.#change);
+    }
+}

package/src/browser/Navigation.d.mts

@@ -1,3 +1,45 @@
+/**
+ * 原始 HTML 的模块 iframe 容器；通过元素传递请求上下文。
+ * Iframe container preserving module HTML and carrying context on the element.
+ */
+export class ModuleFrame extends EventTarget {
+    /**
+     * 创建容器。
+     * Create a container.
+     * @param url 模块地址 / Module URL.
+     * @param options 原生请求参数 / Native request options.
+     */
+    constructor(url: string | URL, options?: RequestInit);
+    /**
+     * 宿主挂载节点。
+     * Host-mounted element.
+     */
+    readonly element: HTMLIFrameElement;
+    /**
+     * change 事件对应的导航状态。
+     * Navigation state exposed with change events.
+     */
+    readonly state: { title: string; module: string; busy: boolean; canGoBack: boolean };
+    /**
+     * 获取原始 HTML。
+     * Fetch unmodified HTML.
+     * @returns 加载完成 / Load completion.
+     */
+    load(): Promise<void>;
+    /**
+     * 沿模块历史返回。
+     * Go back through module history.
+     * @returns 无返回值 / No return value.
+     */
+    back(): void;
+    /**
+     * 取消请求与事件订阅。
+     * Cancel requests and subscriptions.
+     * @returns 无返回值 / No return value.
+     */
+    destroy(): void;
+}
+
 /**
  * 同一文档的根页/子页导航，不定义页面布局或模块业务。
  * Home/detail navigation within a document, without layout or module business rules.

package/src/browser/Navigation.mjs

@@ -1,3 +1,5 @@
+export { ModuleFrame } from "./ModuleFrame.mjs";
+
 /**
  * 同一文档内的主页/子页导航；iframe 各自的实例通过浏览器联合历史协作。
  * Navigate home/detail views within a document; iframe instances cooperate through joint browser history.

package/src/browser/app.mjs

@@ -14,7 +14,19 @@ async function start() {
         view?.destroy();
         view = undefined;
         const context = document.querySelector('meta[name="preference-panes-inputs"]');
-        const inputs = context ? JSON.parse(decodeURIComponent(context.content)) : pageInputs(new URL(location.href));
+        const embedded = window.frameElement?.dataset.preferencePanes;
+        let inputs;
+        switch (true) {
+            case embedded !== undefined:
+                inputs = JSON.parse(embedded);
+                document.documentElement.dataset.preferencePanesEmbedded = "";
+                break;
+            case context !== null:
+                inputs = JSON.parse(decodeURIComponent(context.content));
+                break;
+            default:
+                inputs = pageInputs(new URL(location.href));
+        }
         const resources = [inputs.json, inputs.css].map(source => {
             if (!source) return null;
             const url = new URL(source, inputs.url);

package/src/browser/client.d.mts

@@ -111,8 +111,8 @@ export interface PreferencesClient {
      */
     set(module: string, key: string, value: SettingsScalar | SettingsScalar[]): Promise<void>;
     /**
-     * DELETE 单个覆盖值，HTTP 200 后显示默认值，不追加 GET。
-     * DELETE an override and display its default after HTTP 200, without a follow-up GET.
+     * POST /api/delete 删除覆盖值，200 后显示默认值，不追加读取。
+     * POST /api/delete removes an override and displays its default after 200, without rereading.
      * @param module 已打开的模块 / Open module.
      * @param key 完整点分字段路径 / Complete dotted field path.
      * @returns 操作完成 / Completion of the operation.

package/src/browser/client.mjs

@@ -24,31 +24,31 @@ export function createPreferencesClient({ catalog, fetch: request = globalThis.f
      */
     const sessions = new Map();
     /**
-     * 发送同源请求，处理超时与取消；数据 GET 的 404 交给调用方处理。
-     * Send a same-origin request with timeout and cancellation; callers handle missing-data GET responses.
-     * @param {string} path 相对请求路径 / Relative request path.
-     * @param {"HEAD" | "GET" | "POST" | "DELETE"} method HTTP 方法 / HTTP method.
-     * @param {unknown} body POST 值，其它方法忽略 / POST value, ignored by other methods.
+     * 用 form 发送完整存储键；读取 404 交给调用方处理。
+     * Send a complete storage key as form data; callers handle missing reads.
+     * @param {string} path 完整 @root.path / Complete @root.path.
+     * @param {"get" | "set" | "delete"} action 存储操作 / Storage operation.
+     * @param {unknown} body set 值，其它操作忽略 / Set value, ignored by other operations.
      * @param {AbortSignal | undefined} signal 会话取消信号 / Session cancellation signal.
      * @returns {Promise<Response>} 未消费正文的响应 / Response with an unread body.
      * @throws {Error} 非 200 且非数据 GET 404、超时、取消或网络错误 / Non-200 status except missing-data GETs, timeout, cancellation or network error.
      */
-    async function send(path, method, body, signal) {
+    async function send(path, action, body, signal) {
         const controller = new AbortController();
         const abort = () => controller.abort();
         if (signal?.aborted) abort();
         signal?.addEventListener("abort", abort, { once: true });
         const timer = setTimeout(abort, timeout);
         try {
-            const response = await request(path, {
-                method,
+            const response = await request(`/api/${action}`, {
+                method: "POST",
                 credentials: "omit",
                 cache: "no-store",
                 signal: controller.signal,
-                headers: { "X-Settings-Client": "1", ...(method === "POST" ? { "Content-Type": "application/json" } : {}) },
-                ...(method === "POST" ? { body: JSON.stringify(body) } : {}),
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: new URLSearchParams([[path, action === "set" ? JSON.stringify(body) : ""]]).toString(),
             });
-            if (response.status !== 200 && !(method === "GET" && response.status === 404)) throw new Error(`HTTP ${response.status}`);
+            if (response.status !== 200 && !(action === "get" && response.status === 404)) throw new Error(`HTTP ${response.status}`);
             return response;
         } finally {
             clearTimeout(timer);
@@ -72,21 +72,21 @@ export function createPreferencesClient({ catalog, fetch: request = globalThis.f
      * Serialize single-key mutations and update a still-active session only after success.
      * @param {string} module 已打开模块 / Open module.
      * @param {string} key 完整点分字段路径 / Complete dotted field path.
-     * @param {"POST" | "DELETE"} method 写入或删除 / Write or delete.
+     * @param {"set" | "delete"} action 写入或删除 / Write or delete.
      * @param {unknown} value 写入值，删除时忽略 / Write value, ignored for deletion.
      * @param {"write" | "delete" | "clearCaches" | "reset"} [operation] 操作类型 / Operation kind.
      * @returns {Promise<void>} 操作完成 / Operation completion.
      * @throws {Error} 会话、字段、值或请求错误 / Session, field, value or request error.
      */
-    async function change(module, key, method, value, operation = method === "POST" ? "write" : "delete") {
+    async function change(module, key, action, value, operation = action === "set" ? "write" : "delete") {
         const state = sessions.get(module);
         if (!state?.definition) throw new Error("Open the module first");
         if (state.saving) throw new Error("A settings write is already in progress");
         const field = state.definition.fields.find(field => field.key === key);
         state.saving = true;
         try {
-            if ((operation === "write" || operation === "delete") && (!field || (method === "POST" && !validValue(field, value)))) throw new TypeError("Invalid setting value");
-            await send(`/api/${key.split(".").map(encodeURIComponent).join("/")}`, method, value);
+            if ((operation === "write" || operation === "delete") && (!field || (action === "set" && !validValue(field, value)))) throw new TypeError("Invalid setting value");
+            await send(`@${state.definition.storageKey}.${key}`, action, value);
             if (sessions.get(module) === state) {
                 switch (operation) {
                     case "write":
@@ -129,7 +129,7 @@ export function createPreferencesClient({ catalog, fetch: request = globalThis.f
             sessions.set(module, state);
             try {
                 const definition = normalizeBoxJs(catalog.select(module), module);
-                const response = await send(`/api/${definition.settingsPath.map(encodeURIComponent).join("/")}/`, "GET", undefined, state.controller.signal);
+                const response = await send(`@${definition.storageKey}.${definition.settingsPath.join(".")}`, "get", undefined, state.controller.signal);
                 let subtree = response.status === 404 ? {} : await response.json();
                 if (typeof subtree === "string") subtree = JSON.parse(subtree);
                 if (!subtree || typeof subtree !== "object" || Array.isArray(subtree)) throw new TypeError("Expected a settings subtree object");
@@ -159,7 +159,7 @@ export function createPreferencesClient({ catalog, fetch: request = globalThis.f
         async readCaches(module) {
             const state = sessions.get(module);
             if (!state?.definition) throw new Error("Open the module first");
-            const response = await send(`/api/${encodeURIComponent(module)}/Caches`, "GET", undefined, state.controller.signal);
+            const response = await send(`@${state.definition.storageKey}.${module}.Caches`, "get", undefined, state.controller.signal);
             return response.status === 404 ? undefined : response.json();
         },
         /**
@@ -168,14 +168,14 @@ export function createPreferencesClient({ catalog, fetch: request = globalThis.f
          * @param {string} module 已打开模块 / Open module.
          * @returns {Promise<void>} 清理完成 / Cleanup completion.
          */
-        clearCaches: module => change(module, `${module}.Caches`, "DELETE", undefined, "clearCaches"),
+        clearCaches: module => change(module, `${module}.Caches`, "delete", undefined, "clearCaches"),
         /**
          * 删除整个模块持久化节点，以当前 BoxJS 默认值重置页面缓存。
          * Delete module persistence and reset the page cache using current BoxJS defaults.
          * @param {string} module 已打开模块 / Open module.
          * @returns {Promise<void>} 重置完成 / Reset completion.
          */
-        reset: module => change(module, module, "DELETE", undefined, "reset"),
+        reset: module => change(module, module, "delete", undefined, "reset"),
         /**
          * 取消读取并清除会话，不撤销已发送的写入。
          * Abort reads and clear the session without undoing dispatched writes.
@@ -194,7 +194,7 @@ export function createPreferencesClient({ catalog, fetch: request = globalThis.f
          * @param {import("../index.js").SettingsScalar | import("../index.js").SettingsScalar[]} value 字段值 / Field value.
          * @returns {Promise<void>} 写入完成 / Write completion.
          */
-        set: (module, key, value) => change(module, key, "POST", value),
+        set: (module, key, value) => change(module, key, "set", value),
         /**
          * 删除单键覆盖值并显示默认值。
          * Delete one override and display its default value.
@@ -202,6 +202,6 @@ export function createPreferencesClient({ catalog, fetch: request = globalThis.f
          * @param {string} key 点分字段路径 / Dotted field path.
          * @returns {Promise<void>} 删除完成 / Delete completion.
          */
-        remove: (module, key) => change(module, key, "DELETE"),
+        remove: (module, key) => change(module, key, "delete"),
     };
 }

package/src/browser/panel.css

@@ -91,10 +91,19 @@
     height: calc(100vh - 52px - env(safe-area-inset-top));
     overflow: hidden;
 }
+:root[data-preference-panes-embedded] .pp-header {
+    display: none;
+}
+:root[data-preference-panes-embedded] .pp-viewport {
+    height: 100vh;
+}
 @supports (height: 100dvh) {
     .pp-viewport {
         height: calc(100dvh - 52px - env(safe-area-inset-top));
     }
+    :root[data-preference-panes-embedded] .pp-viewport {
+        height: 100dvh;
+    }
 }
 .pp-fields,
 .pp-choice-page {

package/src/browser/panel.mjs

@@ -33,6 +33,17 @@ export function mountPanel(root, catalog) {
     header.append(back, brand, node("span", "pp-nav-spacer"));
     shell.append(header, viewport, toast);
     root.append(shell);
+    // 嵌入模式向宿主发布导航状态，宿主不读取或修改模块内部 DOM。
+    // Embedded mode publishes navigation state without host reads or mutations of the module DOM.
+    const publishNavigation = () => {
+        const frame = window.frameElement;
+        if (!frame?.dataset.preferencePanes) return;
+        frame.dispatchEvent(
+            new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:change", {
+                detail: { title: heading.textContent, module: catalog.module.module, busy: saving, canGoBack: !back.disabled },
+            }),
+        );
+    };
     let timer,
         navigation,
         generation = 0,
@@ -83,6 +94,7 @@ export function mountPanel(root, catalog) {
         active = module;
         back.disabled = window.history.length <= 1;
         heading.textContent = module;
+        publishNavigation();
         viewport.replaceChildren(node("p", "pp-loading", "读取设置…"));
         try {
             await client.open(module);
@@ -90,6 +102,7 @@ export function mountPanel(root, catalog) {
         } catch (error) {
             if (version !== generation) return;
             viewport.replaceChildren(errorView(error, () => open(module)));
+            publishNavigation();
         }
     }
     /**
@@ -121,6 +134,7 @@ export function mountPanel(root, catalog) {
             const editor = editors.get(navigation.current);
             heading.textContent = editor?.title ?? definition.metadata?.name ?? active;
             back.disabled = saving || !navigation.canGoBack;
+            publishNavigation();
         };
         /**
          * 串行执行模块操作，保持输入可编辑。
@@ -134,6 +148,7 @@ export function mountPanel(root, catalog) {
             pendingWrites++;
             saving = true;
             back.disabled = true;
+            publishNavigation();
             return (queue = queue
                 .then(action)
                 .then(() => {
@@ -149,6 +164,7 @@ export function mountPanel(root, catalog) {
                     saving = pendingWrites > 0;
                     if (destroyed && !saving) client.leave(active);
                     back.disabled = saving || !navigation.canGoBack;
+                    publishNavigation();
                 }));
         }
         const metadata = definition.metadata;

package/src/build.mjs

@@ -2,8 +2,8 @@ import { readFile } from "node:fs/promises";
 import { BoxJS } from "./BoxJS.mjs";
 
 /**
- * 从两个配置输入生成一个模块页及其读写与配置 Mock，不生成项目主页。
- * Build one module page, its storage script and config Mock without a project landing page.
+ * 仅生成模块前端文件，不复制配置或生成绑定业务的读写脚本。
+ * Build module frontend files without copying configuration or generating bound storage scripts.
  * @param {unknown} boxjs 仅包含一个模块的 BoxJS JSON / BoxJS JSON containing exactly one module.
  * @param {string} [css] 可选自定义 CSS 正文 / Optional custom CSS text.
  * @returns {Promise<Record<string, string>>} 相对路径到文件正文的映射 / Relative file paths mapped to file contents.
@@ -12,22 +12,12 @@ export async function build(boxjs, css = "") {
     if (typeof css !== "string") throw new TypeError("CSS must be a string");
     const catalog = new BoxJS(boxjs);
     const module = catalog.module.module;
-    const [html, app, navigation, proxy, mock] = await Promise.all([
-        readFile(new URL("../dist/module/index.html", import.meta.url), "utf8"),
-        readFile(new URL("../dist/module/app.mjs", import.meta.url), "utf8"),
-        readFile(new URL("../dist/module/navigation.mjs", import.meta.url), "utf8"),
-        readFile(new URL("../dist/preference-panes.proxy.js", import.meta.url), "utf8"),
-        readFile(new URL("../dist/preference-panes.config.js", import.meta.url), "utf8"),
-    ]);
-    const config = JSON.stringify(catalog.select(module));
+    const [html, app, navigation] = await Promise.all([readFile(new URL("../dist/module/index.html", import.meta.url), "utf8"), readFile(new URL("../dist/module/app.mjs", import.meta.url), "utf8"), readFile(new URL("../dist/module/navigation.mjs", import.meta.url), "utf8")]);
     return {
         [`settings/${module}/index.html`]: html,
         [`settings/assets/${module}.html`]: html,
         "settings/assets/app.mjs": app,
         "settings/assets/navigation.mjs": navigation,
-        [`settings/assets/${module}.boxjs.json`]: config,
         [`settings/assets/${module}.css`]: css,
-        [`settings/assets/${module}.request.js`]: `${proxy}\nPreferencePanes.run(${config},${JSON.stringify(css)});\n`,
-        [`settings/assets/${module}.config.js`]: `${mock}\nPreferencePanes.mock(${config});\n`,
     };
 }

package/src/index.d.ts

@@ -92,8 +92,8 @@ export interface SettingsRequest {
      */
     headers?: Record<string, string | undefined>;
     /**
-     * POST 的正文为 JSON 值本身；DELETE 无正文
-     * POST contains the JSON value itself; DELETE has no body.
+     * POST 的正文为一个 form 字段，字段名是完整 @root.path
+     * POST contains one form field whose name is the complete @root.path.
      */
     body?: string;
 }
@@ -113,8 +113,8 @@ export interface SettingsResponse {
      */
     headers: Record<string, string>;
     /**
-     * JSON 文本；HEAD 始终为空字符串
-     * JSON text; always an empty string for HEAD.
+     * JSON 或页面资源正文
+     * JSON or page resource body.
      */
     body: string;
 }
@@ -269,8 +269,8 @@ export interface BoxJSSubscription extends BoxJSMetadata {
  */
 export type BoxJSInput = BoxJSSetting[] | BoxJSApp | BoxJSSubscription;
 /**
- * 生成具体模块的页面、代理和配置 Mock，不生成项目入口页。
- * Build a concrete module's page, proxy and config Mock without a project landing page.
+ * 生成模块前端文件，不复制配置、不生成绑定模块的代理脚本。
+ * Build module frontend files without copying configuration or producing bound proxy scripts.
  * @param boxjs 恰好包含一个模块的 BoxJS JSON / BoxJS JSON describing exactly one module.
  * @param css 可选 CSS 正文 / Optional CSS text.
  * @returns 相对路径到文件内容的映射 / Relative paths mapped to file contents.

package/src/lib/page-inputs.mjs

@@ -11,7 +11,7 @@ export function pageInputs(url, headers = {}) {
     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") ?? `/settings/assets/${module}.css`;
+    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 };
 }

package/src/lib/settings-path.mjs

@@ -1,21 +1,3 @@
-/**
- * 解析已经取得的 pathname，避免重复构造 URL。
- * Parse an existing pathname without constructing another URL.
- * @param {string} pathname 以 / 开头的 URL pathname / URL pathname beginning with /.
- * @returns {string[] | undefined} 解码后的路径，非 API 路径不处理 / Decoded path, or undefined outside /api/.
- * @throws {TypeError} 转义编码或路径片段非法 / Invalid percent encoding or path segments.
- */
-export function parseSettingsPathname(pathname) {
-    if (!pathname.startsWith("/api/")) return;
-    let parts;
-    try {
-        parts = pathname.slice(5).replace(/\/$/, "").split("/").map(decodeURIComponent);
-    } catch {
-        throw new TypeError("Invalid encoded key path");
-    }
-    return validatePathParts(parts);
-}
-
 /**
  * 校验原始路径片段，不进行 URL 编码转换。
  * Validate raw path segments without URL encoding conversion.