@nsnanocat/preference-panes 0.9.16 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nsnanocat/preference-panes",
-    "version": "0.9.16",
+    "version": "1.1.0",
     "description": "Shared settings API runtime for JavaScript proxy modules",
     "author": "VirgilClyne <Virgil@nanocat.me>",
     "homepage": "https://NSNanoCat.github.io/preference-panes",

package/src/api.mjs

@@ -0,0 +1,191 @@
+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 { 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.
+ */
+class API {
+    /**
+     * 处理当前代理请求并将结果交给宿主。
+     * Handle the current proxy request and deliver its result to the host.
+     * @returns {Promise<void>} 响应已交给代理宿主 / Response delivered to the proxy host.
+     */
+    async run() {
+        const request = globalThis.$request;
+        let result;
+        try {
+            result = await this.handle(request);
+        } catch (error) {
+            console.error(`PreferencePanes: ${error.message}`);
+            result = this.#response(request, error.status ?? 500, { error: error.message });
+        }
+        if (!result) done({});
+        else done($app === "Quantumult X" ? result : { response: result });
+    }
+
+    /**
+     * 处理 `/api/{module}` 及其动作，不接管页面或静态资源。
+     * Handle `/api/{module}` and its 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" });
+        }
+    }
+
+    #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) {
+        let result;
+        try {
+            result = await transport({ url: configURL, method: "HEAD", 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 });
+            }
+        }
+    }
+
+    async #load(module, configURL) {
+        let result;
+        try {
+            result = await transport({ url: configURL, method: "GET", timeout: 5000, headers: { Accept: "application/json" } });
+        } catch (error) {
+            throw Object.assign(new Error(`Configuration request failed: ${error.message}`), { status: 502 });
+        }
+        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 (!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 });
+        try {
+            return JSON.parse(request.body);
+        } 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 });
+        }
+    }
+
+    #response(request, status, body, extraHeaders = {}) {
+        return {
+            status,
+            headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", ...extraHeaders },
+            body: request.method === "HEAD" ? "" : JSON.stringify(body),
+        };
+    }
+
+    #header(headers, name) {
+        const entry = Object.entries(headers ?? {}).find(([key]) => key.toLowerCase() === name);
+        return entry?.[1] === undefined ? undefined : String(entry[1]).trim();
+    }
+}
+
+new API().run();

package/src/browser/ModuleStatus.mjs

@@ -4,24 +4,25 @@
  * @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.
  */
 
 /**
- * 通过模块 JSON Mock 的 HEAD 响应检测安装状态和业务版本。
- * Probe installation and business version from the native HEAD response of a module JSON Mock.
- * @param {string | URL} url 配置 Mock 地址 / Configuration Mock URL.
+ * 通过模块 API 的 HEAD 响应检测安装状态和业务版本。
+ * Probe installation and business version from the module API HEAD response.
+ * @param {string | URL} url 模块 API 地址 / Module API URL.
  * @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, signal, timeout = 3500 } = {}) {
+export async function probeModule(url, { fetch: request = globalThis.fetch, json, 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 });
+        return await request(url, { method: "HEAD", cache: "no-store", credentials: "omit", signal: controller.signal, headers: json ? { "X-PreferencePanes-JSON": json } : undefined });
     } finally {
         clearTimeout(timer);
         signal?.removeEventListener("abort", abort);
@@ -59,7 +60,7 @@ export class ModuleStatus extends EventTarget {
     /**
      * 每次进入重新探测，取消旧请求并忽略其迟到结果。
      * Reprobe on entry, cancelling old requests and ignoring late results.
-     * @param {string | URL} url 配置 Mock 地址 / Configuration Mock URL.
+     * @param {string | URL} url 模块 API 地址 / Module API URL.
      * @param {ModuleProbeOptions} [options] 请求选项 / Request options.
      * @returns {Promise<Response | undefined>} 原始响应；被取消时无返回值 / Native response; undefined when cancelled.
      */

package/src/browser/Navigation.d.mts

@@ -169,14 +169,16 @@ 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;
 }
 
 /**
- * 通过模块 JSON Mock 的 HEAD 响应检测安装状态和业务版本。
- * Probe installation and business version from a module JSON Mock HEAD response.
- * @param url 配置 Mock 地址 / Configuration Mock URL.
+ * 通过模块 API 的 HEAD 响应检测安装状态和业务版本。
+ * Probe installation and business version from a module API HEAD response.
+ * @param url 模块 API 地址 / Module API URL.
  * @param options 请求选项 / Request options.
  * @returns 原始 HTTP 响应 / Native HTTP response.
  */
@@ -199,9 +201,9 @@ export class ModuleStatus extends EventTarget {
      */
     readonly state: { status: "checking" | "installed" | "missing"; version: string | null };
     /**
-     * 探测配置 Mock。
-     * Probe a configuration Mock.
-     * @param url 配置地址 / Configuration URL.
+     * 探测模块 API。
+     * Probe the module API.
+     * @param url 模块 API 地址 / Module API URL.
      * @param options 请求选项 / Request options.
      * @returns 原始 HTTP 响应；网络错误时状态行显示“未安装” / Native HTTP response; network errors render “未安装”.
      */

package/src/{lib → browser}/boxjs.mjs

@@ -1,22 +1,46 @@
-import { BoxJS } from "../BoxJS.mjs";
-import { validatePathParts } from "./settings-path.mjs";
+import { validatePathParts } from "../lib/settings-path.mjs";
 
 /**
- * 将 BoxJS 数组、app 或订阅转换为模块字段，保留原文件为唯一字段来源。
- * Normalize a BoxJS array, app or subscription using the source JSON as the field authority.
- * @param {unknown | BoxJS} config BoxJS JSON 或已解析目录 / BoxJS document or parsed catalog.
- * @param {string} module API 第一段模块名 / First API path segment.
- * @returns {import("../index.js").ModuleDefinition} 存储根和字段 / Storage root and fields.
- * @throws {TypeError} 配置结构、字段路径、默认值或展示属性无效 / Invalid configuration, field path, default or presentation attribute.
+ * 将 BoxJS 数组、app 或订阅转换为浏览器字段定义。
+ * Normalize a BoxJS array, app or subscription into browser field definitions.
+ * @param {unknown} config 原始 BoxJS JSON / Raw BoxJS JSON.
+ * @param {string} [module] API 模块路径段；省略时要求输入只有一个模块 / API module path segment; omission requires exactly one module.
+ * @returns {import("../index.js").ModuleDefinition} 浏览器字段定义 / Browser field definition.
  */
 export function normalizeBoxJs(config, module) {
-    validatePathParts([module]);
-    const catalog = config instanceof BoxJS ? config : new BoxJS(config);
-    const target = catalog.modules.get(module);
+    if (!config || typeof config !== "object") throw new TypeError("Expected BoxJS JSON");
+    const document = JSON.parse(JSON.stringify(config));
+    const apps = Array.isArray(document) ? [{ settings: document }] : (document.apps ?? [document]);
+    if (!Array.isArray(apps)) throw new TypeError("Expected BoxJS apps array");
+    const 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(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 name = parts[0];
+            let target = modules.get(name);
+            if (!target) {
+                target = { module: name, storageKey, entries: [], owners: new Set() };
+                modules.set(name, target);
+            }
+            if (target.storageKey !== storageKey) throw new TypeError(`A module must use one storage root: ${name}`);
+            target.entries.push(entry);
+            target.owners.add(app);
+        }
+    }
+    if (module === undefined && modules.size !== 1) throw new TypeError("Import BoxJS JSON for exactly one module");
+    const target = module === undefined ? modules.values().next().value : modules.get(module);
     if (!target) throw new TypeError(`No BoxJS settings for module: ${module}`);
-    const { entries, storageKey, metadata } = target;
+    const metadata = normalizeMetadata(target.owners.size === 1 ? presentation([...target.owners][0]) : {});
     const fields = [];
-    for (const entry of entries) {
+    for (const entry of target.entries) {
         const parts = entry.id.slice(1).split(".").slice(1);
         const type = { boolean: "boolean", checkboxes: "array", selects: "select", text: "string", textarea: "string", number: "number" }[entry.type];
         if (!type) throw new TypeError(`Unsupported BoxJS control: ${entry.type}`);
@@ -46,18 +70,50 @@ export function normalizeBoxJs(config, module) {
         if (Object.hasOwn(field, "defaultValue") && !validValue(field, field.defaultValue)) throw new TypeError(`Invalid BoxJS val: ${entry.id}`);
         fields.push(field);
     }
-    if (!fields.length) throw new TypeError(`No BoxJS settings for module: ${module}`);
+    if (!fields.length) throw new TypeError(`No BoxJS settings for module: ${target.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,
+        module: target.module,
+        storageKey: target.storageKey,
         fields,
         settingsPath: common,
         ...(Object.keys(metadata).length ? { metadata } : {}),
     };
 }
 
+/**
+ * 保留字段所属 app 的原始展示信息。
+ * Retain raw presentation metadata from the app owning the fields.
+ * @param {object} source BoxJS app / BoxJS app.
+ * @returns {Record<string, unknown>} 原始展示信息 / Raw presentation metadata.
+ */
+function presentation(source) {
+    const result = {};
+    for (const key of ["id", "name", "author", "repo", "script", "icon", "description", "desc", "icons", "descs"]) {
+        if (source[key] === undefined) continue;
+        result[key] = source[key];
+    }
+    return result;
+}
+
+/**
+ * 校验供浏览器展示的标准 BoxJS 元数据。
+ * Validate standard BoxJS metadata used by the browser renderer.
+ * @param {Record<string, unknown>} source 原始展示元数据 / Raw presentation metadata.
+ * @returns {import("../index.js").BoxJSMetadata} 规范化展示元数据 / Normalized presentation metadata.
+ */
+function normalizeMetadata(source) {
+    const result = {};
+    for (const [key, value] of Object.entries(source)) {
+        const multiple = key === "icons" || key === "descs";
+        const values = multiple ? value : [value];
+        if (!Array.isArray(values) || values.some(item => typeof item !== "string")) throw new TypeError(`Invalid BoxJS app ${key}`);
+        result[key] = multiple ? [...values] : value;
+    }
+    return result;
+}
+
 /**
  * 归一化 BoxJS 的字符串存储值，不改变普通文本内容。
  * Normalize BoxJS string persistence without changing free-text values.

package/src/browser/client.d.mts

@@ -1,157 +1,67 @@
-import type { ModuleDefinition, SettingsScalar } from "../index.js";
+import type { ModuleDefinition, ModuleModel, SettingsScalar } from "../index.js";
 /**
- * 单键写入或删除的通知事件，携带对应模块与点分键路径。
- * Notification for a single-key write or delete, including module and dotted key path.
+ * 单键写入或删除的通知事件。
+ * Notification for a single-key write or delete.
  */
 export interface Notification {
-    /**
-     * 结果类别
-     * Result kind.
-     */
+    /** 结果类别 / Result kind. */
     kind: "success" | "error";
-    /**
-     * 操作类别
-     * Operation kind.
-     */
+    /** 操作类别 / Operation kind. */
     operation: "write" | "delete" | "clearCaches" | "reset";
-    /**
-     * 模块标识
-     * Module identifier.
-     */
+    /** 模块标识 / Module identifier. */
     module: string;
-    /**
-     * 含模块名、不含存储根的点分路径
-     * Dotted path including the module but excluding the storage root.
-     */
-    key: string;
-    /**
-     * 失败原因，仅错误事件提供
-     * Failure reason, provided for errors only.
-     */
+    /** 字段路径 / Field path. */
+    key?: string;
+    /** 失败原因 / Failure reason. */
     message?: string;
 }
 /**
- * 浏览器会话客户端选项。
- * Options for the browser session client.
+ * 浏览器页面客户端选项；模型由 API 提供。
+ * Browser page client options; the model is supplied by the API.
  */
 export interface PreferencesClientOptions {
-    /**
-     * 包内从 BoxJS 推导的目录。
-     * Internal catalog derived from BoxJS.
-     */
-    catalog: { modules: ReadonlyMap<string, { storageKey: string }>; select(module: string): unknown };
-    /**
-     * 默认使用浏览器 fetch，可注入同签名传输
-     * Defaults to browser fetch; an equivalent transport may be supplied.
-     */
+    /** API 返回的模块模型 / Module model returned by the API. */
+    model: ModuleModel;
+    /** 用于渲染的归一化字段定义 / Normalized field definition for rendering. */
+    definition: ModuleDefinition;
+    /** 默认使用浏览器 fetch / Defaults to browser fetch. */
     fetch?: typeof globalThis.fetch;
-    /**
-     * 成功写入或失败时调用，不用于读取事件
-     * Called for successful mutations or failures, not reads.
-     */
+    /** 操作通知 / Mutation notifications. */
     notify?: (notification: Notification) => void;
-    /**
-     * 单次请求超时，单位毫秒，默认 10000
-     * Per-request timeout in milliseconds; defaults to 10000.
-     */
+    /** 请求超时毫秒数 / Request timeout in milliseconds. */
     timeout?: number;
 }
 /**
- * 会话的深拷贝快照，调用方修改不会影响缓存。
- * Deep-cloned session snapshot; caller changes cannot alter the cache.
+ * 会话的深拷贝快照。
+ * Deep-cloned session snapshot.
  */
 export interface ModuleSnapshot {
-    /**
-     * 当前配置生成的模块定义
-     * Module definition generated from current config.
-     */
+    /** 当前模块字段定义 / Current module field definition. */
     definition: ModuleDefinition;
-    /**
-     * 点分键到显示值的映射，已包含适用的默认值；持久化 null 原样保留。
-     * Dotted keys mapped to display values including applicable defaults; persisted null is preserved.
-     */
+    /** 当前页面值 / Current page values. */
     values: Record<string, SettingsScalar | SettingsScalar[] | null>;
 }
 /**
- * 只在页面存活期间维护模块缓存的通用客户端。
- * Generic client maintaining module caches only during the page lifetime.
+ * 管理单模块页面的 API 请求、值快照和会话终止。
+ * Manage API requests, value snapshots, and session termination for one module page.
  */
-export interface PreferencesClient {
-    /**
-     * 使用已导入的 JSON 替换会话，只读取一次设置值。
-     * Replace the session from imported JSON and read stored settings once.
-     * @param module 模块标识 / Module identifier.
-     * @returns 新会话的独立快照 / Independent snapshot of the new session.
-     * @throws {Error} 写入进行中、请求或配置无效、会话被替换 / Active write, invalid request or config, or replaced session.
-     */
-    open(module: string): Promise<ModuleSnapshot>;
-    /**
-     * 获取已打开模块的快照，不发请求。
-     * Get a snapshot of an open module without network requests.
-     * @param module 模块标识 / Module identifier.
-     * @returns 深拷贝快照 / Deep-cloned snapshot.
-     * @throws {Error} 模块尚未打开 / Module has not been opened.
-     */
-    snapshot(module: string): ModuleSnapshot;
-    /**
-     * 取消未完成的读取并移除缓存，不撤销已发送的写入。
-     * Abort pending reads and discard the cache without undoing dispatched writes.
-     * @param module 模块标识 / Module identifier.
-     * @returns 无返回值 / No return value.
-     */
-    leave(module: string): void;
-    /**
-     * POST 单个字段，HTTP 200 后更新缓存，不追加 GET。
-     * POST one field and update its cache only on HTTP 200, without a follow-up GET.
-     * @param module 已打开的模块 / Open module.
-     * @param key 完整点分字段路径 / Complete dotted field path.
-     * @param value 符合字段类型和选项的值 / Value matching the field type and choices.
-     * @returns 操作完成 / Completion of the operation.
-     * @throws {Error} 会话、值、并发写入或网络错误 / Session, value, concurrent-write or network error.
-     */
-    set(module: string, key: string, value: SettingsScalar | SettingsScalar[]): Promise<void>;
-    /**
-     * 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.
-     * @throws {Error} 会话、路径、并发写入或网络错误 / Session, path, concurrent-write or network error.
-     */
-    remove(module: string, key: string): Promise<void>;
-    /**
-     * 按需重新读取整个模块 Settings，不更新页面会话缓存。
-     * Reread all module Settings on demand without updating the page-session cache.
-     * @param module 已打开模块 / Open module.
-     * @returns 设置 JSON 值，缺失时为 undefined / Settings JSON value, or undefined when absent.
-     */
-    readSettings(module: string): Promise<unknown>;
-    /**
-     * 按需读取整个模块 Caches，不刷新设置。
-     * Read all module Caches on demand without refreshing settings.
-     * @param module 已打开模块 / Open module.
-     * @returns 缓存 JSON 值，缺失时为 undefined / Cache JSON value, or undefined when absent.
-     */
-    readCaches(module: string): Promise<unknown>;
-    /**
-     * 删除模块 Caches 并更新相关页面状态，不追加 GET。
-     * Delete module Caches and update related page state without a follow-up GET.
-     * @param module 已打开模块 / Open module.
-     * @returns 清理完成 / Cleanup completion.
-     */
-    clearCaches(module: string): Promise<void>;
-    /**
-     * 删除整个模块持久化数据，页面使用当前 BoxJS 默认值。
-     * Delete all module persistence and use current BoxJS defaults on the page.
-     * @param module 已打开模块 / Open module.
-     * @returns 重置完成 / Reset completion.
-     */
-    reset(module: string): Promise<void>;
+export class PreferencesClient {
+    /** 创建页面客户端 / Create the page client. */
+    constructor(options: PreferencesClientOptions);
+    /** 获取页面快照，不发请求 / Get a page snapshot without a request. */
+    snapshot(): ModuleSnapshot;
+    /** 读取 Settings 子树 / Read the Settings subtree. */
+    readSettings(): Promise<unknown>;
+    /** 读取 Caches 子树 / Read the Caches subtree. */
+    readCaches(): Promise<unknown>;
+    /** 删除 Caches / Delete Caches. */
+    clearCaches(): Promise<void>;
+    /** 删除整个模块数据并恢复默认值 / Delete module data and restore defaults. */
+    reset(): Promise<void>;
+    /** 取消请求 / Cancel requests. */
+    leave(): void;
+    /** 写入单个字段 / Write one field. */
+    set(key: string, value: SettingsScalar | SettingsScalar[]): Promise<void>;
+    /** 删除单个字段覆盖值 / Delete one field override. */
+    remove(key: string): Promise<void>;
 }
-/**
- * 创建包内客户端，接管请求和会话。
- * Create an internal client for requests and sessions.
- * @param options 包内目录与运行环境 / Internal catalog and runtime environment.
- * @returns 会话客户端 / Session client.
- */
-export function createPreferencesClient(options: PreferencesClientOptions): PreferencesClient;