@nsnanocat/preference-panes 0.5.0 → 0.7.0

package/package.json

@@ -1,68 +1,64 @@
 {
-	"name": "@nsnanocat/preference-panes",
-	"version": "0.5.0",
-	"description": "Shared settings API runtime for JavaScript proxy modules",
-	"author": "VirgilClyne <Virgil@nanocat.me>",
-	"homepage": "https://NSNanoCat.github.io/preference-panes",
-	"keywords": [
-		"loon",
-		"quantumult",
-		"surge",
-		"shadowrocket",
-		"stash",
-		"egern",
-		"settings"
-	],
-	"license": "Apache-2.0",
-	"bugs": "https://github.com/NSNanoCat/PreferencePanes/issues",
-	"type": "module",
-	"main": "src/index.mjs",
-	"exports": {
-		".": {
-			"types": "./src/index.d.ts",
-			"import": "./src/index.mjs"
-		},
-		"./browser": {
-			"types": "./src/browser/index.d.ts",
-			"import": "./src/browser/index.mjs"
-		},
-		"./browser/panel.css": "./src/browser/panel.css",
-		"./dist/preference-panes.mjs": "./dist/preference-panes.mjs",
-		"./dist/preference-panes.request.js": "./dist/preference-panes.request.js",
-		"./dist/preference-panes.proxy.js": "./dist/preference-panes.proxy.js",
-		"./dist/settings/*": "./dist/settings/*"
-	},
-	"types": "src/index.d.ts",
-	"scripts": {
-		"test": "node --test test/*.test.mjs",
-		"check": "npm run lint && npm run typecheck && npm test",
-		"lint": "biome check .",
-		"format": "biome check --write .",
-		"typecheck": "tsc --noEmit",
-		"build": "rollup -c",
-		"prepack": "npm run build",
-		"apifox:generate": "node apifox/generate.mjs",
-		"apifox:check": "node apifox/generate.mjs --check"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/NSNanoCat/PreferencePanes.git"
-	},
-	"files": [
-		"src",
-		"dist"
-	],
-	"dependencies": {
-		"@nsnanocat/url": "^1.2.6",
-		"@nsnanocat/util": "^2.7.4"
-	},
-	"devDependencies": {
-		"@biomejs/biome": "2.4.6",
-		"@rollup/plugin-node-resolve": "^16.0.3",
-		"rollup": "^4.63.1",
-		"typescript": "^5.9.3"
-	},
-	"publishConfig": {
-		"access": "public"
-	}
+    "name": "@nsnanocat/preference-panes",
+    "version": "0.7.0",
+    "description": "Shared settings API runtime for JavaScript proxy modules",
+    "author": "VirgilClyne <Virgil@nanocat.me>",
+    "homepage": "https://NSNanoCat.github.io/preference-panes",
+    "keywords": [
+        "loon",
+        "quantumult",
+        "surge",
+        "shadowrocket",
+        "stash",
+        "egern",
+        "settings"
+    ],
+    "license": "Apache-2.0",
+    "bugs": "https://github.com/NSNanoCat/PreferencePanes/issues",
+    "type": "module",
+    "main": "src/index.mjs",
+    "exports": {
+        ".": {
+            "types": "./src/index.d.ts",
+            "import": "./src/index.mjs"
+        },
+        "./browser": {
+            "types": "./src/browser/index.d.ts",
+            "import": "./dist/preference-panes.mjs"
+        }
+    },
+    "types": "src/index.d.ts",
+    "scripts": {
+        "test": "node --test test/*.test.mjs",
+        "pretest": "npm run build",
+        "check": "npm run lint && npm run typecheck && npm test",
+        "lint": "biome check .",
+        "format": "biome check --write .",
+        "typecheck": "tsc --noEmit",
+        "build": "rollup -c",
+        "prebuild": "node --input-type=module -e \"import { rm } from 'node:fs/promises'; await rm('dist', { recursive: true, force: true });\"",
+        "prepack": "npm run build",
+        "preview": "npm run build && node examples/preview.mjs",
+        "apifox:generate": "node apifox/generate.mjs",
+        "apifox:check": "node apifox/generate.mjs --check"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/NSNanoCat/PreferencePanes.git"
+    },
+    "files": [
+        "src",
+        "dist"
+    ],
+    "devDependencies": {
+        "@biomejs/biome": "2.1.4",
+        "@nsnanocat/url": "^1.2.6",
+        "@nsnanocat/util": "^2.7.4",
+        "@rollup/plugin-node-resolve": "^16.0.3",
+        "rollup": "^4.63.1",
+        "typescript": "^5.9.3"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
 }

package/src/BoxJS.mjs

@@ -0,0 +1,86 @@
+import { validatePathParts } from "./lib/settings-path.mjs";
+
+/**
+ * BoxJS 的共同目录：模块、存储根和展示元数据都来自同一份 JSON。
+ * Shared BoxJS catalog deriving modules, storage roots and metadata from one JSON document.
+ */
+export class BoxJS {
+    /**
+     * 建立路径索引，不解析控件类型，也不读写持久化存储。
+     * Index field paths without interpreting controls or accessing persistence.
+     * @param {unknown} input 字段数组、单个 app 或 apps 订阅 / Field array, app or apps subscription.
+     */
+    constructor(input) {
+        if (!input || typeof input !== "object") throw new TypeError("Expected BoxJS JSON");
+        this.document = JSON.parse(JSON.stringify(input));
+        const apps = Array.isArray(this.document) ? [{ settings: this.document }] : (this.document.apps ?? [this.document]);
+        if (!Array.isArray(apps)) throw new TypeError("Expected BoxJS apps array");
+        this.modules = new Map();
+        for (const app of apps) {
+            if (!app || !Array.isArray(app.settings)) throw new TypeError("Expected BoxJS settings array");
+            for (const entry of app.settings) {
+                if (typeof entry.id !== "string") throw new TypeError("BoxJS settings require string IDs");
+                if (!entry.id.startsWith("@")) {
+                    if (Array.isArray(this.document)) throw new TypeError("BoxJS settings require @root.path IDs");
+                    continue;
+                }
+                const [storageKey, ...parts] = entry.id.slice(1).split(".");
+                if (!storageKey || storageKey.startsWith("@") || parts.length < 2) throw new TypeError("A BoxJS setting must be below a literal storage root and module");
+                validatePathParts(parts);
+                const module = parts[0];
+                let target = this.modules.get(module);
+                if (!target) {
+                    target = { module, storageKey, entries: [], owners: new Set() };
+                    this.modules.set(module, target);
+                }
+                if (target.storageKey !== storageKey) throw new TypeError(`A module must use one storage root: ${module}`);
+                target.entries.push(entry);
+                target.owners.add(app);
+            }
+        }
+        this.metadata = metadata(Array.isArray(this.document) ? {} : this.document);
+        for (const target of this.modules.values()) target.metadata = target.owners.size === 1 ? metadata([...target.owners][0]) : {};
+    }
+
+    /**
+     * 提取一个模块的原生 BoxJS，保留所属 app 的元数据。
+     * Select a module's native BoxJS while retaining owning-app metadata.
+     * @param {string} module 模块标识 / Module identifier.
+     * @returns {unknown} 可直接用作配置 Mock 的 JSON / JSON suitable for a configuration Mock.
+     */
+    select(module) {
+        const target = this.modules.get(module);
+        if (!target) throw new TypeError(`No BoxJS settings for module: ${module}`);
+        if (Array.isArray(this.document)) return target.entries;
+        const apps = [...target.owners].map(app => ({ ...app, settings: app.settings.filter(entry => target.entries.includes(entry)) }));
+        return this.document.apps ? { ...this.document, apps } : apps[0];
+    }
+
+    /**
+     * 取得本次导入的唯一模块，避免把模块数据变成项目目录。
+     * Get the single imported module without turning module data into a project directory.
+     * @returns {object} 唯一模块的目录项 / The single module entry.
+     */
+    get module() {
+        if (this.modules.size !== 1) throw new TypeError("Import BoxJS JSON for exactly one module");
+        return this.modules.values().next().value;
+    }
+}
+
+/**
+ * 保留标准 BoxJS 展示信息；script 仅为元数据，不执行。
+ * Retain standard BoxJS presentation data; script is metadata only and never executed.
+ * @param {object} source BoxJS app 或订阅 / BoxJS app or subscription.
+ * @returns {object} 经过类型检查的展示信息 / Type-checked presentation metadata.
+ */
+function metadata(source) {
+    const result = {};
+    for (const key of ["id", "name", "author", "repo", "script", "icon", "description", "desc", "icons", "descs"]) {
+        if (source[key] === undefined) continue;
+        const multiple = key === "icons" || key === "descs";
+        const values = multiple ? source[key] : [source[key]];
+        if (!Array.isArray(values) || values.some(item => typeof item !== "string")) throw new TypeError(`Invalid BoxJS app ${key}`);
+        result[key] = multiple ? [...values] : source[key];
+    }
+    return result;
+}

package/src/Store.mjs

@@ -0,0 +1,127 @@
+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";
+
+/**
+ * 根据 BoxJS 目录桥接持久化存储，不下载配置或解析控件。
+ * Bridge persistence using the BoxJS catalog without downloading configuration or interpreting controls.
+ */
+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.
+     * @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.
+     */
+    async handle(request, url = new URL(request.url)) {
+        if (!url.pathname.startsWith("/api/")) return;
+        const reply = (status, data) => response(request, status, data);
+        let parts;
+        try {
+            parts = parseSettingsPathname(url.pathname);
+        } 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" } };
+        }
+        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 result = parent ? _.get(parent, [key]) : undefined;
+                    return result === undefined ? reply(404, { error: "Stored path does not exist" }) : reply(200, result);
+                }
+                case "POST":
+                    _.set(parent, [key], value);
+                    break;
+                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 });
+        } catch (error) {
+            return reply(500, { error: error.message });
+        }
+    }
+}
+
+/**
+ * 判断根节点是否为普通对象。
+ * Determine whether a root node is a plain object.
+ * @param {unknown} value 待检查值 / Value to inspect.
+ * @returns {boolean} 是否为普通对象 / Whether this is a plain object.
+ */
+function isRecord(value) {
+    return value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+/**
+ * 遍历父路径，兼容旧存储中 JSON 字符串形式的中间节点。
+ * Traverse parents, supporting legacy intermediate nodes serialized as JSON strings.
+ * @param {Record<string, unknown>} root 存储根 / Storage root.
+ * @param {string[]} parts 完整路径 / Complete path.
+ * @param {boolean} create 是否创建缺失节点 / Whether to create missing parents.
+ * @returns {object | undefined} 父节点，缺失且不创建时为 undefined / Parent, or undefined when absent and not creating.
+ * @throws {TypeError} 无法继续遍历标量节点 / A scalar node cannot be traversed.
+ */
+function storageParent(root, parts, create) {
+    let parent = root;
+    for (const part of parts.slice(0, -1)) {
+        let next = _.get(parent, [part]);
+        switch (typeof next) {
+            case "undefined":
+                if (!create) return;
+                next = {};
+                break;
+            case "string":
+                next = JSON.parse(next);
+                break;
+            default:
+                break;
+        }
+        if (!isRecord(next) && !Array.isArray(next)) throw new TypeError("Stored parent is not an object or array");
+        _.set(parent, [part], next);
+        parent = next;
+    }
+    return parent;
+}

package/src/browser/app.mjs

@@ -1,154 +1,30 @@
-import { validatePathParts } from "../lib/settings-path.mjs";
-import { createPreferencesClient } from "./client.mjs";
-import { mountPreferencePanes } from "./panel.mjs";
+import { BoxJS } from "../BoxJS.mjs";
+import { errorView } from "./components.mjs";
+import { mount } from "./index.mjs";
 
+let view;
 /**
- * 自包含页面入口，业务名称、图标和入口全部从站点 BoxJS JSON 读取。
- * Self-contained page entry reading all branding, icons and navigation from site BoxJS JSON.
- * @module @nsnanocat/preference-panes/site
+ * 在具体模块地址导入 JSON 与 CSS，再交给模块渲染器。
+ * Import JSON and CSS at a concrete module URL and pass them to the module renderer.
+ * @returns {Promise<void>} 启动完成 / Startup completion.
  */
-const root = document.querySelector("#preferences");
-const client = createPreferencesClient({ timeout: 3500 });
-const theme = navigator.userAgent.match(/themeId\/(\d+)/)?.[1];
-if (theme) document.documentElement.dataset.theme = theme === "2" ? "dark" : "light";
-let panel,
-	menu,
-	revision = 0,
-	routedPath;
-
-/**
- * 创建只含纯文本的元素。
- * Create an element containing plain text only.
- * @param {string} tag 标签 / Tag.
- * @param {string} className 样式 / CSS class.
- * @param {string} [text] 文本 / Text.
- * @returns {HTMLElement} 元素 / Element.
- */
-function node(tag, className, text) {
-	const element = document.createElement(tag);
-	element.className = className;
-	if (text !== undefined) element.textContent = text;
-	return element;
+async function start() {
+    try {
+        view?.destroy();
+        view = undefined;
+        const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(location.pathname);
+        if (!match) throw new Error("Open a concrete module URL");
+        const module = match[1];
+        const [data, style] = await Promise.all([fetch(`/configs/${module}`, { cache: "no-store" }), fetch(`/settings/assets/${module}.css`, { cache: "no-store" })]);
+        if (data.status !== 200 || style.status !== 200) throw new Error(`HTTP ${data.status !== 200 ? data.status : style.status}`);
+        const boxjs = await data.json();
+        if (new BoxJS(boxjs).module.module !== module) throw new Error("Imported JSON does not match the module URL");
+        view = mount(boxjs, await style.text());
+    } catch (error) {
+        document.querySelector("#preferences").replaceChildren(errorView(error, start));
+    }
 }
-
-/**
- * 按站点 JSON 显示图标；iconDark 是明确的暗色扩展，不改变 BoxJS icons 语义。
- * Display configured icons; iconDark is an explicit dark variant without changing BoxJS icons semantics.
- * @param {{icon?:string,iconDark?:string,icons?:string[]}} metadata 图标数据 / Icon data.
- * @param {string} className 样式 / CSS class.
- * @returns {HTMLPictureElement} 图片元素 / Picture element.
- */
-function icon(metadata, className) {
-	const picture = node("picture", className),
-		image = node("img", "");
-	if (metadata.iconDark) {
-		const source = node("source", "");
-		source.media = theme ? (theme === "2" ? "all" : "not all") : "(prefers-color-scheme: dark)";
-		source.srcset = resourceURL(metadata.iconDark);
-		picture.append(source);
-	}
-	const selected = metadata.icon || metadata.icons?.[1] || metadata.icons?.[0];
-	if (selected) image.src = resourceURL(selected);
-	image.alt = "";
-	picture.append(image);
-	return picture;
-}
-
-/**
- * 校验配置中的资源 URL。
- * Validate resource URLs in site configuration.
- * @param {string} value 地址 / Address.
- * @returns {string} 完整 URL / Absolute URL.
- */
-function resourceURL(value) {
-	const url = new URL(value, location.href);
-	if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("Resources must use HTTP(S)");
-	return url.href;
-}
-
-/**
- * 挂载通用设置或站点菜单，每次进入菜单都重新 HEAD 探测。
- * Mount settings or the site menu, repeating HEAD probes on every menu entry.
- * @returns {Promise<void>} 挂载完成 / Mount completion.
- */
-async function render() {
-	routedPath = location.pathname;
-	const version = ++revision;
-	panel?.destroy();
-	panel = undefined;
-	root.replaceChildren();
-	if (routedPath !== "/settings/") {
-		document.title = routedPath.split("/")[2] || "Preferences";
-		panel = mountPreferencePanes({ element: root });
-		return;
-	}
-	try {
-		if (!menu) {
-			const response = await fetch("/settings/assets/site.boxjs.json", { cache: "no-store", credentials: "omit" });
-			if (response.status !== 200) throw new Error(`Site config HTTP ${response.status}`);
-			const data = await response.json();
-			if (typeof data.name !== "string" || !Array.isArray(data.apps)) throw new TypeError("Invalid site BoxJS JSON");
-			for (const app of data.apps) validatePathParts([app.module]);
-			const localStyles = document.head.querySelector('link[rel="stylesheet"]');
-			for (const href of data.stylesheets ?? []) {
-				const link = document.createElement("link");
-				link.rel = "stylesheet";
-				link.href = resourceURL(href);
-				document.head.insertBefore(link, localStyles);
-			}
-			menu = data;
-		}
-		if (version !== revision) return;
-		document.title = menu.name;
-		const home = node("section", "pp-home");
-		home.append(icon(menu, "brand-logo"), node("h1", "", menu.name));
-		const section = node("section", "self-panel is-zh");
-		section.append(node("h2", "header", menu.sectionTitle ?? "模块"));
-		const container = node("div", "container"),
-			scrollView = node("div", "scroll-view"),
-			rows = node("div", "scroll");
-		scrollView.append(rows);
-		container.append(scrollView);
-		section.append(container);
-		home.append(section);
-		if (menu.desc) home.append(node("p", "settings-note", menu.desc));
-		root.append(home);
-		for (const app of menu.apps) {
-			const button = node("button", "self-item is-zh"),
-				status = node("span", "module-status", "检测中");
-			button.type = "button";
-			button.disabled = true;
-			button.dataset.module = app.module;
-			button.append(icon(app, "logo"), node("span", "name", app.name ?? app.module), status);
-			rows.append(button);
-			button.onclick = () => {
-				history.pushState(null, "", `/settings/${app.module}`);
-				render();
-				if (!matchMedia("(prefers-reduced-motion: reduce)").matches) root.animate([{ transform: "translateX(100%)" }, { transform: "translateX(0)" }], { duration: 260, easing: "ease-out" });
-			};
-			client.probe(app.module).then(available => {
-				if (revision !== version) return;
-				button.disabled = !available;
-				status.textContent = available ? "" : "未响应";
-			});
-		}
-	} catch (error) {
-		if (version === revision) {
-			const retry = node("button", "", "重新读取");
-			retry.type = "button";
-			retry.onclick = render;
-			root.replaceChildren(node("p", "pp-site-error", `加载失败：${error.message}`), retry);
-		}
-	}
-}
-
-window.addEventListener("popstate", () => {
-	if (routedPath !== location.pathname) {
-		render();
-		if (location.pathname === "/settings/" && !matchMedia("(prefers-reduced-motion: reduce)").matches) root.animate([{ transform: "translateX(-100%)" }, { transform: "translateX(0)" }], { duration: 260, easing: "ease-out" });
-	}
-});
+start();
 window.addEventListener("pageshow", event => {
-	if (event.persisted && location.pathname === "/settings/") render();
+    if (event.persisted) start();
 });
-render();