@nsnanocat/preference-panes 1.1.0 → 1.1.2

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@nsnanocat/preference-panes",
-    "version": "1.1.0",
-    "description": "Shared settings API runtime for JavaScript proxy modules",
+    "version": "1.1.2",
+    "description": "Generic BoxJS settings frontend and persistence API for JavaScript proxy modules",
     "author": "VirgilClyne <Virgil@nanocat.me>",
     "homepage": "https://NSNanoCat.github.io/preference-panes",
     "keywords": [

package/src/api.mjs

@@ -2,14 +2,13 @@ import { URL } from "@nsnanocat/url";
 import { fetch as transport } from "@nsnanocat/util";
 import { $app } from "@nsnanocat/util/lib/app.mjs";
 import { done } from "@nsnanocat/util/lib/done.mjs";
+import { Lodash as _ } from "@nsnanocat/util/polyfill/Lodash.mjs";
 import { Storage } from "@nsnanocat/util/polyfill/Storage";
 import { validatePathParts } from "./lib/settings-path.mjs";
 
-const MISSING = Symbol("missing");
-
 /**
- * PreferencePanes 后端 API，只处理模块数据和持久化请求。
- * PreferencePanes backend API handling only module data and persistence requests.
+ * PreferencePanes 后端 API，只转发模块配置并提供通用持久化操作。
+ * PreferencePanes backend API only relaying module configurations and providing generic persistence operations.
  */
 class API {
     /**
@@ -31,153 +30,107 @@ class API {
     }
 
     /**
-     * 处理 `/api/{module}` 及其动作，不接管页面或静态资源。
-     * Handle `/api/{module}` and its actions without intercepting pages or static assets.
+     * 处理模块配置 API 与固定存储动作，不接管页面或静态资源。
+     * Handle module configuration APIs and fixed storage actions without intercepting pages or static assets.
      * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
      * @returns {Promise<import("./index.js").SettingsResponse | undefined>} API 响应或未接管 / API response or pass-through.
      */
     async handle(request) {
         const url = new URL(request.url);
-        const match = /^\/api\/([a-zA-Z0-9_-]+)(?:\/(get|set|delete))?\/?$/.exec(url.pathname);
-        if (!match) return;
-        const [, module, action] = match;
-        const configURL = this.#configURL(request, url, module);
-        switch (true) {
-            case !action && request.method === "HEAD":
-                return this.#probe(request, configURL);
-            case !action && request.method === "GET":
-                return this.#model(request, module, configURL);
-            case Boolean(action) && request.method === "POST":
-                return this.#action(request, module, action, configURL);
-            default:
-                return this.#response(request, 405, { error: "Use GET or HEAD for module reads, POST for module actions" });
-        }
+        const action = /^\/api\/(get|set|delete)\/?$/.exec(url.pathname)?.[1];
+        if (action) return this.#store(request, action);
+        const module = /^\/api\/([a-zA-Z0-9_-]+)\/?$/.exec(url.pathname)?.[1];
+        if (!module) return;
+        if (!["HEAD", "GET"].includes(request.method)) return this.#response(request, 405, { error: "Use GET or HEAD for module configuration" });
+        return this.#configuration(request, `${url.origin}/configs/${module}`);
     }
 
-    #configURL(request, url, module) {
-        const headers = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
-        const source = headers["x-preferencepanes-json"] ?? `/configs/${module}`;
-        if (/^https?:\/\//i.test(source)) return source;
-        if (/^[a-zA-Z][a-zA-Z\d+.-]*:/.test(source)) throw Object.assign(new TypeError("BoxJS resources must use HTTP(S) URLs"), { status: 400 });
-        return `${url.origin}/${source.replace(/^\/+/, "")}`;
-    }
-
-    async #probe(request, configURL) {
+    /**
+     * 从同源业务配置响应模块探测或原始 BoxJS JSON。
+     * Respond to a module probe or raw BoxJS JSON from the same-origin business configuration.
+     * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
+     * @param {string} configuration 同源配置地址 / Same-origin configuration URL.
+     * @returns {Promise<import("./index.js").SettingsResponse>} 配置响应 / Configuration response.
+     */
+    async #configuration(request, configuration) {
         let result;
         try {
-            result = await transport({ url: configURL, method: "HEAD", timeout: 5000, headers: { Accept: "application/json" } });
+            result = await transport({ url: configuration, method: request.method, timeout: 5000, headers: { Accept: "application/json" } });
         } catch (error) {
             return this.#response(request, 502, { error: error.message });
         }
         const version = this.#header(result.headers, "x-preferencepanes-version");
-        return this.#response(request, result.statusCode ?? result.status, undefined, version ? { "X-PreferencePanes-Version": version } : {});
-    }
-
-    async #model(request, module, configURL) {
-        const loaded = await this.#load(module, configURL);
-        const values = {};
-        for (const entry of loaded.entries) {
-            const value = Storage.getItem(entry.id, MISSING);
-            if (value !== MISSING) values[entry.id.slice(loaded.storageKey.length + 2)] = value;
-        }
-        return this.#response(request, 200, { module, boxjs: loaded.boxjs, values, configURL }, loaded.version ? { "X-PreferencePanes-Version": loaded.version } : {});
-    }
-
-    async #action(request, module, action, configURL) {
-        const payload = this.#jsonBody(request);
-        const target = await this.#load(module, configURL);
-        switch (action) {
-            case "get": {
-                const value = Storage.getItem(payload?.scope ? this.#scopePath(target, payload.scope) : this.#storagePath(target, payload?.key), MISSING);
-                return value === MISSING ? this.#response(request, 404, { error: "Stored path does not exist" }) : this.#response(request, 200, value);
-            }
-            case "set":
-                if (!Object.hasOwn(payload ?? {}, "value")) throw Object.assign(new TypeError("A value is required"), { status: 400 });
-                if (!Storage.setItem(this.#storagePath(target, payload.key), payload.value)) throw new Error("Storage write failed");
-                return this.#response(request, 200, { saved: true });
-            case "delete": {
-                const path = payload?.scope ? this.#scopePath(target, payload.scope) : this.#storagePath(target, payload?.key);
-                if (!Storage.removeItem(path)) throw new Error("Storage write failed");
-                return this.#response(request, 200, { deleted: true });
-            }
-        }
+        const contentType = this.#header(result.headers, "content-type") ?? "application/json; charset=utf-8";
+        return {
+            status: result.statusCode ?? result.status,
+            headers: { "Content-Type": contentType, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", ...(version ? { "X-PreferencePanes-Version": version } : {}) },
+            body: request.method === "HEAD" ? "" : typeof result.body === "string" ? result.body : new TextDecoder().decode(result.body),
+        };
     }
 
-    async #load(module, configURL) {
-        let result;
+    /**
+     * 使用唯一 form 字段中的完整 @root.path 执行存储操作。
+     * Execute a storage operation using the complete @root.path from the sole form field.
+     * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
+     * @param {"get" | "set" | "delete"} action 存储动作 / Storage action.
+     * @returns {import("./index.js").SettingsResponse} 操作响应 / Operation response.
+     */
+    #store(request, action) {
+        const reply = (status, data) => this.#response(request, status, data);
+        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 {
-            result = await transport({ url: configURL, method: "GET", timeout: 5000, headers: { Accept: "application/json" } });
+            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) {
-            throw Object.assign(new Error(`Configuration request failed: ${error.message}`), { status: 502 });
+            return reply(400, { error: error.message });
         }
-        const status = result.statusCode ?? result.status;
-        if (status !== 200) throw Object.assign(new Error(`Configuration HTTP ${status}`), { status });
-        try {
-            const body = typeof result.body === "string" ? result.body : new TextDecoder().decode(result.body);
-            const boxjs = JSON.parse(body);
-            const apps = Array.isArray(boxjs) ? [{ settings: boxjs }] : (boxjs.apps ?? [boxjs]);
-            if (!Array.isArray(apps)) throw new TypeError("Expected BoxJS apps array");
-            const entries = [];
-            let storageKey;
-            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(boxjs)) throw new TypeError("BoxJS settings require @root.path IDs");
-                        continue;
-                    }
-                    const [root, ...parts] = entry.id.slice(1).split(".");
-                    if (!root || root.startsWith("@") || parts.length < 2) throw new TypeError("A BoxJS setting must be below a literal storage root and module");
-                    validatePathParts(parts);
-                    if (parts[0] !== module) continue;
-                    if (storageKey && storageKey !== root) throw new TypeError(`A module must use one storage root: ${module}`);
-                    storageKey = root;
-                    entries.push(entry);
-                }
+        if (action === "set") {
+            try {
+                value = JSON.parse(value);
+            } catch (error) {
+                if (!(error instanceof SyntaxError)) throw error;
             }
-            if (!entries.length) throw new TypeError(`No BoxJS settings for module: ${module}`);
-            return { boxjs, entries, module, storageKey, version: this.#header(result.headers, "x-preferencepanes-version") };
-        } catch (error) {
-            throw Object.assign(new Error(`Invalid BoxJS: ${error.message}`), { status: 422 });
         }
-    }
-
-    #jsonBody(request) {
-        const headers = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
-        if (headers["content-type"]?.split(";")[0].trim().toLowerCase() !== "application/json") throw Object.assign(new TypeError("Expected application/json"), { status: 415 });
-        if (typeof request.body !== "string" || request.body.length > 65536) throw Object.assign(new TypeError("Expected a JSON body up to 65536 characters"), { status: 400 });
+        const [storageKey, ...path] = parts;
         try {
-            return JSON.parse(request.body);
+            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 "set":
+                    _.set(parent, [key], value);
+                    break;
+                case "delete":
+                    if (parent) _.unset(parent, [key]);
+                    break;
+            }
+            if (!Storage.setItem(storageKey, root)) throw new Error("Storage write failed");
+            return reply(200, action === "set" ? { saved: true } : { deleted: true });
         } catch (error) {
-            throw Object.assign(error, { status: 400 });
-        }
-    }
-
-    #storagePath(target, key) {
-        if (typeof key !== "string") throw Object.assign(new TypeError("A BoxJS field path is required"), { status: 400 });
-        const path = `@${target.storageKey}.${key}`;
-        if (!target.entries.some(entry => entry.id === path)) throw Object.assign(new TypeError(`Unknown BoxJS field: ${key}`), { status: 400 });
-        return path;
-    }
-
-    #scopePath(target, scope) {
-        switch (scope) {
-            case "settings":
-                return `@${target.storageKey}.${target.module}.Settings`;
-            case "caches":
-                return `@${target.storageKey}.${target.module}.Caches`;
-            case "module":
-                return `@${target.storageKey}.${target.module}`;
-            default:
-                throw Object.assign(new TypeError("Scope must be settings, caches or module"), { status: 400 });
+            return reply(500, { error: error.message });
         }
     }
 
-    #response(request, status, body, extraHeaders = {}) {
+    #response(request, status, body) {
         return {
             status,
-            headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", ...extraHeaders },
+            headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" },
             body: request.method === "HEAD" ? "" : JSON.stringify(body),
         };
     }
@@ -188,4 +141,44 @@ class API {
     }
 }
 
+/**
+ * 判断存储根是否为普通对象。
+ * Determine whether a storage root 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 parent paths and decode legacy intermediate nodes stored 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 node or undefined.
+ */
+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;
+}
+
 new API().run();

package/src/browser/ModuleFrame.mjs

@@ -1,8 +1,6 @@
-import { pageInputs } from "../lib/page-inputs.mjs";
-
 /**
- * 模块文档容器：原始 HTML 不改写，请求上下文随 iframe 元素传递。
- * Module document container: preserve HTML verbatim and carry request context on the iframe element.
+ * 模块文档容器：原始 HTML 不改写，只向 iframe 标记模块身份。
+ * Module document container: preserve HTML verbatim and mark only the module identity on the iframe.
  */
 export class ModuleFrame extends EventTarget {
     #url;
@@ -24,23 +22,25 @@ export class ModuleFrame extends EventTarget {
     };
 
     /**
-     * 建立 iframe 与请求输入；调用方挂载 element 后调用 load。
-     * Create the iframe and request inputs; callers mount element and then call load.
+     * 建立 iframe；调用方挂载 element 后调用 load。
+     * Create the iframe; callers mount element and then call load.
      * @param {string | URL} url 模块请求地址 / Module request URL.
-     * @param {RequestInit} [options] 原生请求头和取消信号 / Native headers and cancellation signal.
+     * @param {{signal?: AbortSignal}} [options] 外部取消信号 / External 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));
+        const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(this.#url.pathname);
+        if (!match) throw new TypeError("Open a concrete module URL");
+        this.#options = options;
         this.element = document.createElement("iframe");
-        this.element.title = `${inputs.module} 设置`;
-        this.element.dataset.preferencePanes = JSON.stringify(inputs);
+        this.element.title = `${match[1]} 设置`;
+        this.element.dataset.preferencePanes = "true";
+        this.element.dataset.preferencePanesModule = match[1];
         this.element.addEventListener("preferencepanes:change", this.#change);
         this.element.addEventListener("preferencepanes:confirm", this.#confirmation);
         this.element.addEventListener("preferencepanes:notice", this.#notice);
-        this.#state = { title: inputs.module, module: inputs.module, busy: false, canGoBack: true, actions: [] };
+        this.#state = { title: match[1], module: match[1], busy: false, canGoBack: true, actions: [] };
         options.signal?.addEventListener("abort", this.#abort, { once: true });
     }
 
@@ -61,7 +61,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, { cache: "no-store", credentials: "omit", ...this.#options, signal: this.#controller.signal });
+            const response = await fetch(this.#url, { 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/ModuleStatus.mjs

@@ -4,7 +4,6 @@
  * @typedef {object} ModuleProbeOptions
  * @property {typeof globalThis.fetch} [fetch] 可注入的 fetch / Injectable fetch.
  * @property {AbortSignal} [signal] 外部取消信号 / External cancellation signal.
- * @property {string} [json] BoxJS JSON 来源，将随探测请求头传递 / BoxJS JSON source sent in the probe header.
  * @property {number} [timeout] 超时毫秒数，默认 3500 / Timeout in milliseconds, defaults to 3500.
  */
 
@@ -15,14 +14,14 @@
  * @param {ModuleProbeOptions} [options] 请求选项 / Request options.
  * @returns {Promise<Response>} 原始 HTTP 响应，可直接读取 status 和响应头 / Native HTTP response; read status and headers directly.
  */
-export async function probeModule(url, { fetch: request = globalThis.fetch, json, signal, timeout = 3500 } = {}) {
+export async function probeModule(url, { fetch: request = globalThis.fetch, signal, timeout = 3500 } = {}) {
     const controller = new AbortController();
     const abort = () => controller.abort();
     if (signal?.aborted) abort();
     signal?.addEventListener("abort", abort, { once: true });
     const timer = setTimeout(() => controller.abort(), timeout);
     try {
-        return await request(url, { method: "HEAD", cache: "no-store", credentials: "omit", signal: controller.signal, headers: json ? { "X-PreferencePanes-JSON": json } : undefined });
+        return await request(url, { method: "HEAD", cache: "no-store", credentials: "omit", signal: controller.signal });
     } finally {
         clearTimeout(timer);
         signal?.removeEventListener("abort", abort);

package/src/browser/Navigation.d.mts

@@ -11,9 +11,9 @@ export class ModuleFrame extends EventTarget {
      * 创建容器。
      * Create a container.
      * @param url 模块地址 / Module URL.
-     * @param options 原生请求参数 / Native request options.
+     * @param options 外部取消选项 / External cancellation options.
      */
-    constructor(url: string | URL, options?: RequestInit);
+    constructor(url: string | URL, options?: { signal?: AbortSignal });
     /**
      * 宿主挂载节点。
      * Host-mounted element.
@@ -169,8 +169,6 @@ export interface ModuleProbeOptions {
     fetch?: typeof globalThis.fetch;
     /** 外部取消信号 / External cancellation signal. */
     signal?: AbortSignal;
-    /** 传给模块 API 的 BoxJS JSON 来源 / BoxJS JSON source sent to the module API. */
-    json?: string;
     /** 超时毫秒数，默认 3500 / Timeout in milliseconds, defaults to 3500. */
     timeout?: number;
 }

package/src/browser/client.d.mts

@@ -1,4 +1,4 @@
-import type { ModuleDefinition, ModuleModel, SettingsScalar } from "../index.js";
+import type { ModuleDefinition, SettingsScalar } from "../index.js";
 /**
  * 单键写入或删除的通知事件。
  * Notification for a single-key write or delete.
@@ -16,12 +16,10 @@ export interface Notification {
     message?: string;
 }
 /**
- * 浏览器页面客户端选项；模型由 API 提供。
- * Browser page client options; the model is supplied by the API.
+ * 浏览器页面客户端选项；字段定义来自 BoxJS。
+ * Browser page client options; the field definition comes from BoxJS.
  */
 export interface PreferencesClientOptions {
-    /** API 返回的模块模型 / Module model returned by the API. */
-    model: ModuleModel;
     /** 用于渲染的归一化字段定义 / Normalized field definition for rendering. */
     definition: ModuleDefinition;
     /** 默认使用浏览器 fetch / Defaults to browser fetch. */
@@ -48,6 +46,8 @@ export interface ModuleSnapshot {
 export class PreferencesClient {
     /** 创建页面客户端 / Create the page client. */
     constructor(options: PreferencesClientOptions);
+    /** 读取设置并建立页面快照 / Read settings and establish the page snapshot. */
+    open(): Promise<ModuleSnapshot>;
     /** 获取页面快照，不发请求 / Get a page snapshot without a request. */
     snapshot(): ModuleSnapshot;
     /** 读取 Settings 子树 / Read the Settings subtree. */

package/src/browser/client.mjs

@@ -1,31 +1,55 @@
+import { normalizeStoredValue, validValue } from "./boxjs.mjs";
+
 /**
  * 管理单模块页面的 API 请求、值快照和会话终止。
  * Manage API requests, value snapshots, and session termination for one module page.
  */
 export class PreferencesClient {
     #module;
-    #configURL;
     #definition;
     #request;
     #notify;
     #timeout;
     #session = new AbortController();
-    #values;
+    #values = {};
     #saving = false;
 
     /**
-     * 创建只调用模块 API、不读取或解析 BoxJS 的页面客户端。
-     * Create a page client that only calls the module API and never reads or parses BoxJS.
-     * @param {import("./client.mjs").PreferencesClientOptions} options API 模型、请求与通知 / API model, requests, and notifications.
+     * 创建从 BoxJS 定义读取和持久化设置的页面客户端。
+     * Create a page client that reads and persists settings from a BoxJS definition.
+     * @param {import("./client.mjs").PreferencesClientOptions} options 字段定义、请求与通知 / Field definition, requests, and notifications.
      */
-    constructor({ model, definition, fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 }) {
-        this.#module = model.module;
-        this.#configURL = model.configURL;
+    constructor({ definition, fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 }) {
+        this.#module = definition.module;
         this.#definition = definition;
         this.#request = request;
         this.#notify = notify;
         this.#timeout = timeout;
-        this.#values = structuredClone(model.values);
+    }
+
+    /**
+     * 读取一次 Settings 子树并建立页面值快照。
+     * Read the Settings subtree once and establish the page value snapshot.
+     * @returns {Promise<import("./client.mjs").ModuleSnapshot>} 页面快照 / Page snapshot.
+     */
+    async open() {
+        let subtree = await this.readSettings();
+        if (subtree === undefined) subtree = {};
+        if (typeof subtree === "string") subtree = JSON.parse(subtree);
+        if (!subtree || typeof subtree !== "object" || Array.isArray(subtree)) throw new TypeError("Expected a settings subtree object");
+        const values = {};
+        for (const field of this.#definition.fields) {
+            const stored = field.key
+                .split(".")
+                .slice(this.#definition.settingsPath.length)
+                .reduce((parent, part) => Object(parent)[part], subtree);
+            const value = normalizeStoredValue(field, stored === undefined ? field.defaultValue : stored);
+            if (value === undefined) continue;
+            if (!validValue(field, value)) throw new TypeError(`Invalid stored value: ${field.key}`);
+            values[field.key] = value;
+        }
+        this.#values = values;
+        return this.snapshot();
     }
 
     /**
@@ -43,7 +67,7 @@ export class PreferencesClient {
      * @returns {Promise<unknown>} Settings 内容或 undefined / Settings content or undefined.
      */
     async readSettings() {
-        const response = await this.#send("get", { scope: "settings" });
+        const response = await this.#send("get", `@${this.#definition.storageKey}.${this.#definition.settingsPath.join(".")}`);
         return response.status === 404 ? undefined : response.json();
     }
 
@@ -53,7 +77,7 @@ export class PreferencesClient {
      * @returns {Promise<unknown>} Caches 内容或 undefined / Caches content or undefined.
      */
     async readCaches() {
-        const response = await this.#send("get", { scope: "caches" });
+        const response = await this.#send("get", `@${this.#definition.storageKey}.${this.#module}.Caches`);
         return response.status === 404 ? undefined : response.json();
     }
 
@@ -63,7 +87,7 @@ export class PreferencesClient {
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     clearCaches() {
-        return this.#change("delete", { scope: "caches" }, "clearCaches");
+        return this.#change("delete", `${this.#module}.Caches`, undefined, "clearCaches");
     }
 
     /**
@@ -72,7 +96,7 @@ export class PreferencesClient {
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     reset() {
-        return this.#change("delete", { scope: "module" }, "reset");
+        return this.#change("delete", this.#module, undefined, "reset");
     }
 
     /**
@@ -92,7 +116,7 @@ export class PreferencesClient {
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     set(key, value) {
-        return this.#change("set", { key, value }, "write", key);
+        return this.#change("set", key, value, "write");
     }
 
     /**
@@ -102,30 +126,31 @@ export class PreferencesClient {
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     remove(key) {
-        return this.#change("delete", { key }, "delete", key);
+        return this.#change("delete", key, undefined, "delete");
     }
 
     /**
-     * 向模块 API 发送 JSON 动作。
-     * Send a JSON action to the module API.
-     * @param {"get" | "set" | "delete"} action 模块动作 / Module action.
-     * @param {unknown} payload JSON 请求体 / JSON request body.
+     * 向固定存储 API 发送完整路径的 form 动作。
+     * Send a complete-path form action to the fixed storage API.
+     * @param {"get" | "set" | "delete"} action 存储动作 / Storage action.
+     * @param {string} path 完整 @root.path / Complete @root.path.
+     * @param {unknown} [value] set 写入值 / Value written by set.
      * @returns {Promise<Response>} 原始响应 / Raw response.
      */
-    async #send(action, payload) {
+    async #send(action, path, value) {
         const controller = new AbortController();
         const abort = () => controller.abort();
         if (this.#session.signal.aborted) abort();
         this.#session.signal.addEventListener("abort", abort, { once: true });
         const timer = setTimeout(abort, this.#timeout);
         try {
-            const response = await this.#request(`/api/${encodeURIComponent(this.#module)}/${action}`, {
+            const response = await this.#request(`/api/${action}`, {
                 method: "POST",
                 credentials: "omit",
                 cache: "no-store",
                 signal: controller.signal,
-                headers: { "Content-Type": "application/json", "X-PreferencePanes-JSON": this.#configURL },
-                body: JSON.stringify(payload),
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: new URLSearchParams([[path, action === "set" ? JSON.stringify(value) : ""]]).toString(),
             });
             if (response.status !== 200 && !(action === "get" && response.status === 404)) throw new Error(`HTTP ${response.status}`);
             return response;
@@ -139,24 +164,28 @@ export class PreferencesClient {
      * 执行写入动作；成功后只更新当前页面值。
      * Execute a mutation and update only the current page values after success.
      * @param {"set" | "delete"} action API 动作 / API action.
-     * @param {Record<string, unknown>} payload JSON 请求体 / JSON request body.
+     * @param {string} key 不含存储根的路径 / Path without the storage root.
+     * @param {unknown} value set 写入值 / Value written by set.
      * @param {"write" | "delete" | "clearCaches" | "reset"} operation 通知操作 / Notification operation.
-     * @param {string} [key] 字段路径 / Field path.
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
-    async #change(action, payload, operation, key) {
+    async #change(action, key, value, operation) {
         if (this.#saving) throw new Error("A settings write is already in progress");
         this.#saving = true;
         try {
-            await this.#send(action, payload);
+            let field;
+            if (operation === "write" || operation === "delete") {
+                field = this.#definition.fields.find(candidate => candidate.key === key);
+                if (!field || (operation === "write" && !validValue(field, value))) throw new TypeError("Invalid setting value");
+            }
+            await this.#send(action, `@${this.#definition.storageKey}.${key}`, value);
             switch (operation) {
                 case "write":
-                    this.#values[key] = structuredClone(payload.value);
+                    this.#values[key] = structuredClone(value);
                     break;
                 case "delete": {
-                    const field = this.#definition.fields.find(candidate => candidate.key === key);
                     delete this.#values[key];
-                    if (field && Object.hasOwn(field, "defaultValue")) this.#values[key] = structuredClone(field.defaultValue);
+                    if (Object.hasOwn(field, "defaultValue")) this.#values[key] = structuredClone(field.defaultValue);
                     break;
                 }
                 case "clearCaches":