@nsnanocat/preference-panes 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,23 @@
 # @nsnanocat/preference-panes
 
-尚未发布的通用设置面板和代理存储 API，基于 `@nsnanocat/util`。字段直接来自运行时加载的 BoxJS JSON，页面、缓存与读写逻辑不包含具体项目的选项。
+通用设置面板和代理存储 API，基于 `@nsnanocat/util`，首版 `0.1.0` 已发布到 npm 和 GitHub Packages。字段直接来自运行时加载的 BoxJS JSON，页面、缓存与读写逻辑不包含具体项目的选项。
+
+## 目录结构
+
+| 目录 | 内容 |
+| --- | --- |
+| `src/` | 包入口、实现及同目录的 TypeScript 声明 |
+| `src/SettingsHandler.mjs` | 通用代理处理类：下载配置、校验与存储读写 |
+| `src/browser/` | 浏览器面板、会话缓存和样式 |
+| `src/lib/` | BoxJS 解析和路径解析 |
+| `src/proxy/` | 代理宿主的独立打包入口 |
+| `test/` | 持续回归测试、类型契约和测试数据 |
+| `examples/` | 可复用的最小集成示例 |
+| `apifox/` | 接口定义、说明和原生 JSON 生成器 |
+| `.github/` | CI、发布工作流和发布说明 |
+| `dist/` | 构建产物，不提交 Git |
+
+公开包路径仍为 `@nsnanocat/preference-panes`、`@nsnanocat/preference-panes/browser` 和 `@nsnanocat/preference-panes/browser/panel.css`，由 package.json 的 exports 映射到源码目录。
 
 ## 工作方式
 
@@ -56,23 +73,22 @@ const panel = mountPreferencePanes({
 ## 代理读写组件
 
 ```js
-import { createSettingsHandler } from "@nsnanocat/preference-panes";
-import { fetch } from "@nsnanocat/util/polyfill/fetch";
+import { SettingsHandler } from "@nsnanocat/preference-panes";
 
-const handle = createSettingsHandler({
+const handler = new SettingsHandler({
   origin: "https://example.org",
-  loadConfig: async module => {
-    const response = await fetch(`https://assets.example.org/${module}.boxjs.json`);
-    if (response.status !== 200) throw new Error(`BoxJS HTTP ${response.status}`);
-    return JSON.parse(response.body);
-  }
+  configURL: "https://assets.example.org/Module.boxjs.json"
 });
-const response = await handle($request);
+const response = await handler.handle($request);
 // 接入现有平台的 done 适配；或直接使用下述打包入口。
 ```
 
 每个支持面板的模块都携带自己的配置 Mock，并引用同一个通用读写脚本。脚本正则只匹配各自 `/api/<模块>` 的数据路径，配置 Mock 则只匹配 `/configs/`。处理器每次键值请求运行时加载配置，仅允许操作已声明的字段。
 
+`SettingsHandler` 自身使用 util `fetch` 下载 configURL，要求 HTTP 200、解析 JSON 并按 URL 中的模块归一化 BoxJS。下载、HTTP 状态、JSON 或配置错误返回 502，不读取存储；HEAD 只加载配置验证声明，不读取存储。类不缓存配置，各次 handle 请求加载一次；浏览器仍按页面会话缓存设置。configURL 可指向单模块配置或包含多个模块的 BoxJS 订阅，字段所属模块由 `/api/` 后第一段选择。
+
+此 class API 属于 dev 中的下一版变更，替换 0.1.0 的 `createSettingsHandler({ loadConfig })` 工厂；已发布的 0.1.0 尚不导出 SettingsHandler。接入方只需构造实例并调用 handle，不再自行实现配置请求。
+
 持久化 GET 调用一次 util `Storage.getItem`；POST/DELETE 在写入前重新读取最新根对象，再用 util `Lodash.set/unset` 修改单键并 `Storage.setItem` 写回，保留其它模块、隐藏字段和缓存。这是代理端必要的读改写，浏览器不会因此重新 GET 整个模块。多个独立脚本上下文同时写同一根键仍受代理存储无事务能力的限制。
 
 `resolveSettings(stored, definition)` 是可选的 GET 解析器，用来按模块既有规则合并 database、argument、持久化值。默认只返回持久化覆盖值，控件缺值时使用 BoxJS `val`。本包不修改插件原有的配置优先级；删除后不重新计算 resolver，而是在下次进入/刷新时重新读取。
@@ -81,6 +97,21 @@ const response = await handle($request);
 
 支持 settings 数组、单个 app 的 `settings`、订阅的 `apps[].settings`；控件类型支持 boolean、selects、checkboxes、text、textarea、number。不执行 BoxJS 脚本或 HTML。
 
+复用 [BoxJs 原版配置格式](https://github.com/chavyleung/scripts/tree/master/box) 的字段语义，不加载原版 HTML/Vue 应用：
+
+| 字段 | 用途 |
+| --- | --- |
+| `name`、`val`、`type`、`desc`、`items` | 控件标题、默认值、类型、说明和选项 |
+| `placeholder` | 文本和数字输入框的占位提示 |
+| `rows`、`autoGrow` | 多行文本框的基础行数和自动高度；保存值仍为字符串 |
+| app 的 `name`、`author`、`desc`、`descs`、`repo` | 页面名称、作者、多段说明及项目链接 |
+| app 的 `icon`、`icons` | 显式图标优先；否则取彩色版 `icons[1]`，单个图标则用 `icons[0]` |
+| app 的 `id`、`script` | 保留在 `definition.metadata` 中，不参与路径映射或脚本执行 |
+
+原版 `icons` 表示透明/彩色变体，不是亮暗模式顺序。显示名称和说明使用纯文本。一个模块的字段来自唯一 app 时，才采用该 app 的元数据；多个 app 合并声明同一模块时不任意选取其中一个的元数据。app 的 id/name 不决定模块归属，始终由字段 ID 选择；因此订阅里无关应用的旧扁平 ID 不会参与该模块渲染。
+
+`keys`、脚本执行、`desc_html`/`descs_html`、动态字符串形式的 `items` 及 slider/radios/modalSelects/colorpicker 不属于当前支持范围。不会给旧扁平 ID 猜测存储根；本地读写仍由现有 util Storage/Lodash 完成，不引入原版 Env 的另一套存储实现。这些兼容增强位于 dev，尚未发布。
+
 设置 ID 必须为 `@存储根.模块.子路径.键`。同一模块使用一个存储根，字段路径不得重复或父子重叠。为了用一次 GET 获取设置，字段必须具有模块根以下的公共父路径，例如 `Enhanced.Settings` 或 `Weather.Preferences`；公共路径自动计算，不固定为 Settings。不满足条件或遇到不支持的控件会报错。
 
 ## 打包与示例
@@ -90,11 +121,11 @@ npm ci --registry=https://registry.npmjs.org/ --@nsnanocat:registry=https://regi
 npm run build
 npm run check
 npm run apifox:generate
-node scripts/generate-apifox.mjs --check
+npm run apifox:check
 npm pack --dry-run
 ```
 
-构建生成可直接加载的 `dist/preference-panes.mjs` 和代理 IIFE `dist/preference-panes.request.js`，公共样式位于 `browser/panel.css`。代理包包括 util 的平台适配和 `@nsnanocat/url`，不依赖 Node 内置模块。
+构建生成可直接加载的 `dist/preference-panes.mjs` 和代理 IIFE `dist/preference-panes.request.js`，公共样式源码位于 `src/browser/panel.css`。代理包包括 util 的平台适配和 `@nsnanocat/url`，不依赖 Node 内置模块。
 
 [Surge 模板](examples/surge.sgmodule)使用原生 Map Local 提供静态资源，http-request 提供持久化 API。模板中的域名均为占位，尚未部署；需要把源码资源和 dist 产物发布到自己的资源地址。其 `argument` 只配置 `origin` 和 `configURL`，不会固化字段。Map Local 下载缓存的更新时机由代理管理；浏览器 no-store 不会强制 Surge 更新资源缓存。配置 Mock 与脚本 configURL 应引用同一版本的 BoxJS。
 
@@ -104,6 +135,6 @@ Quantumult X 等不能通过模板传递 `$argument` 的平台，需要在构建
 
 - [完整请求、返回与缓存时序说明](apifox/guide.md)
 - [Apifox 原生 JSON](apifox/preference-panes.apifox.json)
-- [Apifox 项目](https://app.apifox.com/project/8803052)、[Git 数据源绑定记录](apifox/sync.md)
+- [Apifox 项目](https://app.apifox.com/project/8803052)、[文档维护与同步](apifox/README.md)
 
-main/dev 普通推送与手动 CI 只验证并生成候选 tgz；两套 v* tag workflow 分别发布 npm 与 GitHub Packages。首版拟定为 `0.1.0`，发布步骤、首次 npm 注册与 Trusted Publisher 配置见 [RELEASING.md](RELEASING.md)。Enhanced 可先用候选 tgz 验证，正式依赖及 lockfile 必须在 registry 首发成功后生成。
+main/dev 普通推送与手动 CI 只验证并生成候选 tgz；两套 v* tag workflow 分别发布 npm 与 GitHub Packages。首版为 `0.1.0`，发布步骤与 Trusted Publisher 配置见 [发布说明](.github/RELEASING.md)。Enhanced 通过 GitHub Packages 安装正式依赖，lockfile 使用 registry 下载地址。

package/dist/preference-panes.mjs

@@ -266,6 +266,346 @@ class Lodash {
 	}
 }
 
+class URLSearchParams {
+    constructor(params, onUpdate) {
+        switch (typeof params) {
+            case "string": {
+                if (params.length === 0)
+                    break;
+                if (params.startsWith("?"))
+                    params = params.slice(1);
+                const pairs = params.split("&").map(pair => {
+                    const separator = pair.indexOf("=");
+                    return separator < 0 ? [pair, ""] : [pair.slice(0, separator), pair.slice(separator + 1)];
+                });
+                pairs.forEach(([key, value]) => {
+                    this.#params.push(key ? this.#decodeQueryComponent(key) : key);
+                    this.#values.push(this.#decodeQueryComponent(value));
+                });
+                break;
+            }
+            case "object":
+                if (Array.isArray(params)) {
+                    Object.entries(params).forEach(([key, value]) => {
+                        this.#params.push(key);
+                        this.#values.push(value);
+                    });
+                }
+                else if (Symbol.iterator in Object(params)) {
+                    for (const [key, value] of params) {
+                        this.#params.push(key);
+                        this.#values.push(value);
+                    }
+                }
+                break;
+        }
+        this.#updateSearchString(this.#params, this.#values);
+        this.#onUpdate = onUpdate;
+    }
+    // Create 2 seperate arrays for the params and values to make management and lookup easier.
+    #param = "";
+    #params = [];
+    #values = [];
+    #onUpdate;
+    #decodeQueryComponent(str) {
+        return decodeURIComponent(str.replace(/\+/g, " "));
+    }
+    #encodeQueryComponent(str) {
+        return encodeURIComponent(str)
+            .replace(/%20/g, "+")
+            .replace(/[!'()~]/g, character => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+    }
+    // Update the search property of the URL instance with the new params and values.
+    #updateSearchString(params, values) {
+        if (params.length === 0)
+            this.#param = "";
+        else
+            this.#param = params
+                .map((param, index) => {
+                switch (typeof values[index]) {
+                    case "object":
+                        return `${this.#encodeQueryComponent(param)}=${this.#encodeQueryComponent(JSON.stringify(values[index]))}`;
+                    case "boolean":
+                    case "number":
+                    case "string":
+                        return `${this.#encodeQueryComponent(param)}=${this.#encodeQueryComponent(values[index])}`;
+                    case "undefined":
+                    default:
+                        return this.#encodeQueryComponent(param);
+                }
+            })
+                .join("&");
+        this.#onUpdate?.(this.#param);
+    }
+    // Add a given param with a given value to the end.
+    append(name, value) {
+        this.#params.push(name);
+        this.#values.push(value);
+        this.#updateSearchString(this.#params, this.#values);
+    }
+    // Remove all occurances of a given param
+    delete(name, value) {
+        while (this.#params.indexOf(name) > -1) {
+            this.#values.splice(this.#params.indexOf(name), 1);
+            this.#params.splice(this.#params.indexOf(name), 1);
+        }
+        this.#updateSearchString(this.#params, this.#values);
+    }
+    // Return an array to be structured in this way: [[param1, value1], [param2, value2]] to mimic the native method's ES6 iterator.
+    entries() {
+        return this.#params.map((param, index) => [param, this.#values[index]]);
+    }
+    // Return the value matched to the first occurance of a given param.
+    get(name) {
+        return this.#values[this.#params.indexOf(name)];
+    }
+    // Return all values matched to all occurances of a given param.
+    getAll(name) {
+        return this.#values.filter((value, index) => this.#params[index] === name);
+    }
+    // Return a boolean to indicate whether a given param exists.
+    has(name, value) {
+        return this.#params.indexOf(name) > -1;
+    }
+    // Return an array of the param names to mimic the native method's ES6 iterator.
+    keys() {
+        return this.#params;
+    }
+    // Set a given param to a given value.
+    set(name, value) {
+        if (this.#params.indexOf(name) === -1) {
+            this.append(name, value); // If the given param doesn't already exist, append it.
+        }
+        else {
+            let first = true;
+            const newValues = [];
+            // If the param already exists, change the value of the first occurance and remove any remaining occurances.
+            this.#params = this.#params.filter((currentParam, index) => {
+                if (currentParam !== name) {
+                    newValues.push(this.#values[index]);
+                    return true;
+                    // If the currentParam matches the one being changed and it's the first one, keep the param and change its value to the given one.
+                }
+                else if (first) {
+                    first = false;
+                    newValues.push(value);
+                    return true;
+                }
+                // If the currentParam matches the one being changed, but it's not the first, remove it.
+                return false;
+            });
+            this.#values = newValues;
+            this.#updateSearchString(this.#params, this.#values);
+        }
+    }
+    // Sort all key/value pairs, if any, by their keys then by their values.
+    sort() {
+        // Call entries to make sorting easier, then rewrite the params and values in the new order.
+        const sortedPairs = this.entries().sort();
+        this.#params = [];
+        this.#values = [];
+        sortedPairs.forEach(pair => {
+            this.#params.push(pair[0]);
+            this.#values.push(pair[1]);
+        });
+        this.#updateSearchString(this.#params, this.#values);
+    }
+    // Return the search string without the '?'.
+    toString = () => this.#param;
+    // Return and array of the param values to mimic the native method's ES6 iterator..
+    values = () => this.#values.values();
+}
+
+class URL {
+    constructor(url, base) {
+        switch (typeof url) {
+            case "string": {
+                const urlIsValid = /^(blob:|file:)?[a-zA-z]+:\/\/.*/.test(url);
+                const baseIsValid = base ? /^(blob:|file:)?[a-zA-z]+:\/\/.*/.test(base) : false;
+                // If a string is passed for url instead of location or link, then set the properties of the URL instance.
+                if (urlIsValid)
+                    this.href = url;
+                // If the url isn't valid, but the base is, then prepend the base to the url.
+                else if (baseIsValid)
+                    this.href = base + url;
+                // If no valid url or base is given, then throw a type error.
+                else
+                    throw new TypeError('URL string is not valid. If using a relative url, a second argument needs to be passed representing the base URL. Example: new URL("relative/path", "http://www.example.com");');
+                break;
+            }
+            case "object":
+                break;
+            default:
+                throw new TypeError("Invalid argument type.");
+        }
+    }
+    #url = {
+        hash: "",
+        host: "",
+        hostname: "",
+        href: "",
+        password: "",
+        pathname: "",
+        port: Number.NaN,
+        protocol: "",
+        search: "",
+        searchParams: new URLSearchParams(""),
+        username: "",
+    };
+    // refer: http://www.ietf.org/rfc/rfc3986.txt
+    static #URLRegExp = /^(?<scheme>([^:\/?#]+):)?(?:\/\/(?<authority>[^\/?#]*))?(?<path>[^?#]*)(?<query>\?([^#]*))?(?<hash>#(.*))?$/;
+    static #AuthorityRegExp = /^(?<authentication>(?<username>[^:]*)(:(?<password>[^@]*))?@)?(?<hostname>[^:]+)(:(?<port>\d+))?$/;
+    get hash() {
+        return this.#url.hash;
+    }
+    set hash(value) {
+        if (value.length !== 0) {
+            if (value.startsWith("#"))
+                value = value.slice(1);
+            this.#url.hash = `#${encodeURIComponent(value)}`;
+        }
+    }
+    get host() {
+        return this.port.length > 0 ? `${this.hostname}:${this.port}` : this.hostname;
+    }
+    set host(value) {
+        [this.hostname, this.port] = value.split(":", 2);
+    }
+    get hostname() {
+        return encodeURIComponent(this.#url.hostname);
+    }
+    set hostname(value) {
+        this.#url.hostname = value ?? "";
+    }
+    get href() {
+        let authority = "";
+        if (this.username.length > 0) {
+            authority += this.username;
+            if (this.password.length > 0)
+                authority += `:${this.password}`;
+            authority += "@";
+        }
+        return `${this.protocol}//${authority}${this.host}${this.pathname}${this.search}${this.hash}`;
+    }
+    set href(value) {
+        if (value.startsWith("blob:") || value.startsWith("file:"))
+            value = value.slice(5);
+        const urlMatch = value.match(URL.#URLRegExp);
+        if (!urlMatch)
+            throw new TypeError("Invalid URL format.");
+        this.protocol = urlMatch.groups.scheme ?? "";
+        const authorityMatch = urlMatch.groups.authority.match(URL.#AuthorityRegExp);
+        this.username = authorityMatch.groups.username ?? "";
+        this.password = authorityMatch.groups.password ?? "";
+        this.hostname = authorityMatch.groups.hostname ?? "";
+        this.port = authorityMatch.groups.port ?? "";
+        this.pathname = urlMatch.groups.path ?? "";
+        this.search = urlMatch.groups.query ?? "";
+        this.hash = urlMatch.groups.hash ?? "";
+    }
+    get origin() {
+        return `${this.protocol}//${this.host}`;
+    }
+    get password() {
+        return encodeURIComponent(this.#url.password);
+    }
+    set password(value) {
+        if (this.username.length > 0)
+            this.#url.password = value ?? "";
+    }
+    get pathname() {
+        return `/${this.#url.pathname}`;
+    }
+    set pathname(value) {
+        value = `${value}`;
+        if (value.startsWith("/"))
+            value = value.slice(1);
+        this.#url.pathname = value;
+    }
+    get port() {
+        if (Number.isNaN(this.#url.port))
+            return "";
+        const port = this.#url.port.toString();
+        if (this.protocol === "ftp:" && port === "21")
+            return "";
+        if (this.protocol === "http:" && port === "80")
+            return "";
+        if (this.protocol === "https:" && port === "443")
+            return "";
+        return port;
+    }
+    set port(value) {
+        switch (value) {
+            case "":
+                this.#url.port = Number.NaN;
+                break;
+            default: {
+                const port = Number.parseInt(value, 10);
+                if (port >= 0 && port < 65535)
+                    this.#url.port = port;
+            }
+        }
+    }
+    get protocol() {
+        return `${this.#url.protocol}:`;
+    }
+    set protocol(value) {
+        if (value.endsWith(":"))
+            value = value.slice(0, -1);
+        this.#url.protocol = value;
+    }
+    get search() {
+        if (this.#url.search.length > 0)
+            return `?${this.#url.search}`;
+        else
+            return "";
+    }
+    set search(value) {
+        value = `${value}`;
+        if (value.startsWith("?"))
+            value = value.slice(1);
+        this.#url.search = value;
+        this.#url.searchParams = new URLSearchParams(this.#url.search, search => {
+            this.#url.search = search;
+        });
+    }
+    get searchParams() {
+        return this.#url.searchParams;
+    }
+    get username() {
+        return encodeURIComponent(this.#url.username);
+    }
+    set username(value) {
+        this.#url.username = value ?? "";
+    }
+    static parse = (url, base) => new URL(url, base);
+    /**
+     * Returns the string representation of the URL.
+     *
+     * @returns {string} The href of the URL.
+     */
+    toString = () => this.href;
+    /**
+     * Converts the URL object properties to a JSON string.
+     *
+     * @returns {string} A JSON string representation of the URL object.
+     */
+    toJSON = () => JSON.stringify({
+        hash: this.hash,
+        host: this.host,
+        hostname: this.hostname,
+        href: this.href,
+        origin: this.origin,
+        password: this.password,
+        pathname: this.pathname,
+        port: this.port,
+        protocol: this.protocol,
+        search: this.search,
+        searchParams: this.searchParams,
+        username: this.username,
+    });
+}
+
 /**
  * 将 /api/ 后的 URL 路径转换为 util 的路径片段；非 API 路径不处理。
  * Convert URL segments after /api/ to util path segments; ignore non-API paths.
@@ -292,11 +632,23 @@ function parseSettingsPath(url) {
  * Normalize a BoxJS array, app or subscription using the source JSON as the field authority.
  * @param {unknown} config BoxJS JSON / BoxJS document.
  * @param {string} module API 第一段模块名 / First API path segment.
- * @returns {import("../types/index.js").ModuleDefinition} 存储根和字段 / Storage root and fields.
+ * @returns {import("../index.js").ModuleDefinition} 存储根和字段 / Storage root and fields.
  */
 function normalizeBoxJs(config, module) {
   parseSettingsPath(`https://example.invalid/api/${module}`);
-  const entries = Array.isArray(config) ? config : config?.apps ? config.apps.flatMap((app) => app.settings ?? []) : config?.settings;
+  const apps = Array.isArray(config) ? [] : (config?.apps ?? [config]);
+  if (!Array.isArray(apps)) throw new TypeError("Expected BoxJS apps array");
+  for (const candidate of apps) {
+    if (!candidate || typeof candidate !== "object") throw new TypeError("Expected BoxJS app object");
+    if (candidate.settings !== undefined && !Array.isArray(candidate.settings)) throw new TypeError("Expected BoxJS settings array");
+  }
+  const owners = apps.filter((candidate) =>
+    candidate.settings?.some(
+      (entry) => typeof entry.id === "string" && entry.id.startsWith("@") && entry.id.slice(1).split(".")[1] === module,
+    ),
+  );
+  const entries = Array.isArray(config) ? config : owners.flatMap((candidate) => candidate.settings);
+  const app = owners.length === 1 ? owners[0] : undefined;
   if (!Array.isArray(entries)) throw new TypeError("Expected BoxJS settings array, app or subscription");
   let storageKey;
   const fields = [];
@@ -317,6 +669,10 @@ function normalizeBoxJs(config, module) {
       name: entry.name,
       type: type === "select" ? typeof entry.val : type,
       description: entry.desc ?? "",
+      control: entry.type,
+      ...(entry.placeholder === undefined ? {} : { placeholder: entry.placeholder }),
+      ...(entry.rows === undefined ? {} : { rows: entry.rows }),
+      ...(entry.autoGrow === undefined ? {} : { autoGrow: entry.autoGrow }),
     };
     if (type === "select" && !["string", "number", "boolean"].includes(field.type))
       throw new TypeError(`Select requires a scalar val: ${entry.id}`);
@@ -324,6 +680,9 @@ function normalizeBoxJs(config, module) {
     if (Object.hasOwn(entry, "val")) field.defaultValue = normalizeStoredValue(field, entry.val);
     if (
       typeof field.name !== "string" ||
+      (field.placeholder !== undefined && typeof field.placeholder !== "string") ||
+      (field.rows !== undefined && (!Number.isInteger(field.rows) || field.rows < 1)) ||
+      (field.autoGrow !== undefined && typeof field.autoGrow !== "boolean") ||
       fields.some((other) => other.key === field.key || other.key.startsWith(`${field.key}.`) || field.key.startsWith(`${other.key}.`))
     )
       throw new TypeError(`Invalid or overlapping BoxJS field: ${entry.id}`);
@@ -340,13 +699,32 @@ function normalizeBoxJs(config, module) {
   if (!fields.length) throw new TypeError(`No BoxJS settings for module: ${module}`);
   const common = fields[0].key.split(".").slice(0, -1);
   for (const field of fields) while (!field.key.startsWith(`${common.join(".")}.`)) common.pop();
-  return { module, storageKey, fields, settingsPath: common };
+  const metadata = {};
+  if (app) {
+    for (const key of ["id", "name", "author", "repo", "script", "icon", "description", "desc"]) {
+      if (app[key] === undefined) continue;
+      if (typeof app[key] !== "string") throw new TypeError(`Invalid BoxJS app ${key}`);
+      metadata[key] = app[key];
+    }
+    for (const key of ["icons", "descs"]) {
+      if (app[key] === undefined) continue;
+      if (!Array.isArray(app[key]) || app[key].some((item) => typeof item !== "string")) throw new TypeError(`Invalid BoxJS app ${key}`);
+      metadata[key] = [...app[key]];
+    }
+  }
+  return {
+    module,
+    storageKey,
+    fields,
+    settingsPath: common,
+    ...(Object.keys(metadata).length ? { metadata } : {}),
+  };
 }
 
 /**
  * 归一化 BoxJS 的字符串存储值，不改变普通文本内容。
  * Normalize BoxJS string persistence without changing free-text values.
- * @param {import("../types/index.js").SettingsField} field 字段 / Field.
+ * @param {import("../index.js").SettingsField} field 字段 / Field.
  * @param {unknown} value 存储值 / Stored value.
  * @returns {unknown} 控件值 / Control value.
  */
@@ -379,8 +757,8 @@ function validValue(field, value) {
 /**
  * 创建页面会话缓存；打开时重读，选项操作仅在 HTTP 200 后更新缓存。
  * Create a page-session cache; reload on open and mutate cache only after HTTP 200.
- * @param {import("../types/browser.js").PreferencesClientOptions} options 请求与通知 / Requests and notifications.
- * @returns {import("../types/browser.js").PreferencesClient} 通用客户端 / Generic client.
+ * @param {import("./index.js").PreferencesClientOptions} options 请求与通知 / Requests and notifications.
+ * @returns {import("./index.js").PreferencesClient} 通用客户端 / Generic client.
  */
 function createPreferencesClient({ fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 } = {}) {
   const sessions = new Map();
@@ -488,7 +866,7 @@ function createPreferencesClient({ fetch: request = globalThis.fetch.bind(global
 /**
  * 挂载从 BoxJS 实时生成的设置面板和短暂通知。
  * Mount runtime-generated BoxJS controls and transient notifications.
- * @param {import("../types/browser.js").PreferencesPanelOptions} options 容器与请求；页面路径 /settings/{module} 对应配置 / Container and requests; /settings/{module} selects config.
+ * @param {import("./index.js").PreferencesPanelOptions} options 容器与请求；页面路径 /settings/{module} 对应配置 / Container and requests; /settings/{module} selects config.
  * @returns {{destroy(): void}} 清理接口 / Cleanup handle.
  */
 function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
@@ -563,7 +941,38 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
   }
   function controls() {
     const { definition, values } = client.snapshot(active);
+    heading.textContent = definition.metadata?.name || active;
     const view = node("section", "pp-fields");
+    const growingInputs = [];
+    const metadata = definition.metadata;
+    if (metadata) {
+      const info = node("div", "pp-module-info");
+      const iconURL = metadata.icon || metadata.icons?.[1] || metadata.icons?.[0];
+      const resourceURL = (value) => {
+        const url = new window.URL(value, window.location.href);
+        if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("Module metadata URLs must use HTTP or HTTPS");
+        return url.href;
+      };
+      if (iconURL) {
+        const image = node("img", "pp-module-icon");
+        image.src = resourceURL(iconURL);
+        image.alt = "";
+        info.append(image);
+      }
+      const details = node("div", "pp-module-details");
+      if (metadata.author) details.append(node("p", "pp-description", metadata.author));
+      for (const description of [metadata.desc ?? metadata.description, ...(metadata.descs ?? [])])
+        if (description) details.append(node("p", "pp-description", description));
+      if (metadata.repo) {
+        const link = node("a", "pp-module-source", "项目主页");
+        link.href = resourceURL(metadata.repo);
+        link.target = "_blank";
+        link.rel = "noopener noreferrer";
+        details.append(link);
+      }
+      info.append(details);
+      view.append(info);
+    }
     for (const field of definition.fields) {
       const row = node("fieldset", "pp-field");
       row.append(node("legend", "", field.name));
@@ -598,8 +1007,23 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
           for (const option of inputs) option.input.checked = Array.isArray(value) && value.includes(option.key);
         };
       } else {
-        const input = node(field.type === "array" ? "textarea" : "input", "pp-input");
+        const multiline = field.control === "textarea" || field.type === "array";
+        const input = node(multiline ? "textarea" : "input", "pp-input");
         input.setAttribute("aria-label", field.name);
+        if (field.placeholder) input.placeholder = field.placeholder;
+        if (multiline && field.rows) input.rows = field.rows;
+        const grow = () => {
+          if (!multiline || !field.autoGrow || !input.isConnected) return;
+          input.style.height = "auto";
+          const baseline = input.getBoundingClientRect().height;
+          const style = window.getComputedStyle(input);
+          const borders = parseFloat(style.borderTopWidth) + parseFloat(style.borderBottomWidth);
+          input.style.height = `${Math.max(baseline, input.scrollHeight + borders)}px`;
+        };
+        if (multiline && field.autoGrow) {
+          input.addEventListener("input", grow);
+          growingInputs.push(grow);
+        }
         if (field.type === "boolean") {
           input.type = "checkbox";
           write = (value) => {
@@ -607,9 +1031,10 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
           };
           read = () => input.checked;
         } else {
-          input.type = field.type === "number" ? "number" : "text";
+          if (!multiline) input.type = field.type === "number" ? "number" : "text";
           write = (value) => {
             input.value = field.type === "array" ? JSON.stringify(value ?? []) : (value ?? "");
+            grow();
           };
           read = () =>
             field.type === "array"
@@ -673,6 +1098,7 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
       view.append(row);
     }
     viewport.replaceChildren(view);
+    for (const grow of growingInputs) grow();
   }
   function route() {
     if (saving) {