@nsnanocat/preference-panes 0.7.2 → 0.8.1

package/package.json

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

package/src/Store.mjs

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

package/src/browser/ActionMenu.mjs

@@ -0,0 +1,115 @@
+/**
+ * 标题栏共用三点菜单；Shadow DOM 隔离项目样式，保留继承的主题色。
+ * Shared title-bar overflow menu; Shadow DOM isolates layout while inheriting theme colors.
+ */
+export class ActionMenu {
+    #button;
+    #popup;
+    #backdrop;
+    #select;
+    #document;
+    #key = event => {
+        if (event.key === "Escape" && !this.#popup.hidden) {
+            event.preventDefault();
+            this.close();
+            this.#button.focus();
+        }
+    };
+
+    /**
+     * 创建菜单，操作逻辑由调用方提供。
+     * Create a menu whose actions are handled by the caller.
+     * @param {(id: string) => void} select 菜单选择回调 / Selection callback.
+     */
+    constructor(select) {
+        this.#document = document;
+        this.#select = select;
+        this.element = document.createElement("span");
+        const root = this.element.attachShadow({ mode: "open" });
+        root.innerHTML = `<style>
+          :host{display:inline-flex;position:relative;width:44px;height:44px;color:inherit}
+          :host([hidden]),[hidden]{display:none!important}
+          button{font:inherit;cursor:pointer;border:0;color:inherit;background:none}
+          button:disabled{opacity:.4;cursor:default}
+          button:focus-visible{outline:2px solid currentColor;outline-offset:-3px}
+          #trigger{width:44px;height:44px;padding:10px;position:relative;z-index:3}
+          svg{display:block;width:24px;height:24px;fill:currentColor}
+          #backdrop{position:fixed;inset:0;z-index:1}
+          #items{position:absolute;right:0;top:46px;z-index:2;min-width:160px;padding:6px;background:var(--pp-surface,Canvas);color:var(--pp-text,CanvasText);border:1px solid var(--pp-border,#8884);border-radius:12px;box-shadow:0 8px 28px #0003}
+          #items button{display:block;text-align:left;white-space:nowrap;width:100%;padding:11px 14px;border-radius:8px;font:14px/1.4 system-ui,sans-serif}
+          #items button:hover{background:#8882}
+          #items button[data-danger]{color:#e45656}
+        </style><button id="trigger" type="button" aria-label="更多操作" aria-haspopup="menu" aria-expanded="false" aria-controls="items"><svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="4" cy="12" r="2"/><circle cx="12" cy="12" r="2"/><circle cx="20" cy="12" r="2"/></svg></button><button id="backdrop" type="button" tabindex="-1" aria-label="关闭菜单" hidden></button><div id="items" role="menu" hidden></div>`;
+        this.#button = root.querySelector("#trigger");
+        this.#popup = root.querySelector("#items");
+        this.#backdrop = root.querySelector("#backdrop");
+        this.#button.onclick = () => {
+            const open = this.#popup.hidden;
+            this.#popup.hidden = this.#backdrop.hidden = !open;
+            this.#button.setAttribute("aria-expanded", String(open));
+            if (open) this.#popup.firstElementChild.focus();
+        };
+        this.#backdrop.onclick = () => this.close();
+        this.#popup.onkeydown = event => {
+            if (event.key === "Tab") {
+                this.close();
+                return;
+            }
+            const items = [...this.#popup.children];
+            const index = items.indexOf(root.activeElement);
+            const offsets = { ArrowDown: 1, ArrowUp: -1 };
+            if (event.key in offsets) {
+                event.preventDefault();
+                items[(index + offsets[event.key] + items.length) % items.length].focus();
+            }
+        };
+        document.addEventListener("keydown", this.#key);
+        this.update([]);
+    }
+
+    /**
+     * 同步可用操作和忙碌状态，不重建菜单触发按钮。
+     * Update actions and busy state without replacing the trigger button.
+     * @param {Array<{id: string, label: string, destructive?: boolean}>} items 操作列表 / Actions.
+     * @param {boolean} [disabled] 是否忙碌 / Whether operations are busy.
+     * @returns {void} 无返回值 / No return value.
+     */
+    update(items, disabled = false) {
+        this.close();
+        this.#button.disabled = disabled || items.length === 0;
+        this.#popup.replaceChildren(
+            ...items.map(item => {
+                const button = this.#document.createElement("button");
+                button.type = "button";
+                button.setAttribute("role", "menuitem");
+                button.textContent = item.label;
+                button.toggleAttribute("data-danger", Boolean(item.destructive));
+                button.onclick = () => {
+                    this.close();
+                    this.#select(item.id);
+                };
+                return button;
+            }),
+        );
+    }
+
+    /**
+     * 关闭菜单。
+     * Close the menu.
+     * @returns {void} 无返回值 / No return value.
+     */
+    close() {
+        this.#popup.hidden = this.#backdrop.hidden = true;
+        this.#button.setAttribute("aria-expanded", "false");
+    }
+
+    /**
+     * 移除监听器与节点。
+     * Remove listeners and elements.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#document.removeEventListener("keydown", this.#key);
+        this.element.remove();
+    }
+}

package/src/browser/ModuleFrame.mjs

@@ -11,7 +11,7 @@ export class ModuleFrame extends EventTarget {
     #abort = () => this.destroy();
     #state;
     #change = event => {
-        this.#state = event.detail;
+        this.#state = { ...event.detail, actions: event.detail.actions ?? [] };
         this.dispatchEvent(new Event("change"));
     };
 
@@ -30,7 +30,7 @@ export class ModuleFrame extends EventTarget {
         this.element.title = `${inputs.module} 设置`;
         this.element.dataset.preferencePanes = JSON.stringify(inputs);
         this.element.addEventListener("preferencepanes:change", this.#change);
-        this.#state = { title: inputs.module, module: inputs.module, busy: false, canGoBack: true };
+        this.#state = { title: inputs.module, module: inputs.module, busy: false, canGoBack: true, actions: [] };
         options.signal?.addEventListener("abort", this.#abort, { once: true });
     }
 
@@ -70,6 +70,17 @@ export class ModuleFrame extends EventTarget {
         if (!this.#state.busy && this.#state.canGoBack) this.element.contentWindow.history.back();
     }
 
+    /**
+     * 向模块发送菜单操作，不让宿主访问内部 DOM 或存储客户端。
+     * Dispatch a menu action without host access to internal DOM or the storage client.
+     * @param {string} id 当前可用操作 / Available action identifier.
+     * @returns {void} 无返回值 / No return value.
+     */
+    perform(id) {
+        if (this.#state.busy || !this.#state.actions.some(action => action.id === id)) throw new Error("Action is not available");
+        this.element.dispatchEvent(new CustomEvent("preferencepanes:action", { detail: id }));
+    }
+
     /**
      * 取消加载与事件订阅；节点保留到 Navigation 的退出动画结束。
      * Cancel loading and subscriptions; Navigation retains the node until its exit animation ends.

package/src/browser/ModuleStatus.mjs

@@ -0,0 +1,86 @@
+/**
+ * 模块入口的固定状态行，只通过 HEAD 探测安装状态和业务版本。
+ * Fixed module status row, probing installation and business version with HEAD only.
+ */
+export class ModuleStatus extends EventTarget {
+    #element;
+    #controller;
+    #state = { status: "checking", version: null };
+
+    /**
+     * 绑定调用方提供的状态行。
+     * Bind a caller-owned status row.
+     * @param {HTMLElement} element 状态文字容器 / Status text container.
+     */
+    constructor(element) {
+        super();
+        this.#element = element;
+        this.#render("checking");
+    }
+
+    /**
+     * 当前安装状态与业务版本。
+     * Current installation state and business version.
+     */
+    get state() {
+        return { ...this.#state };
+    }
+
+    /**
+     * 每次进入重新探测，取消旧请求并忽略其迟到结果。
+     * Reprobe on entry, cancelling old requests and ignoring late results.
+     * @param {string | URL} url 配置 Mock 地址 / Configuration Mock URL.
+     * @returns {Promise<void>} 探测完成 / Probe completion.
+     */
+    async check(url) {
+        this.#controller?.abort();
+        const controller = (this.#controller = new AbortController());
+        this.#render("checking");
+        const timer = setTimeout(() => controller.abort(), 3500);
+        try {
+            const response = await fetch(url, { method: "HEAD", cache: "no-store", credentials: "omit", signal: controller.signal });
+            if (controller !== this.#controller) return;
+            const version = response.headers.get("X-PreferencePanes-Version")?.trim() || null;
+            this.#render(response.status === 200 ? "installed" : "missing", version);
+        } catch {
+            if (controller === this.#controller) this.#render("missing");
+        } finally {
+            clearTimeout(timer);
+        }
+    }
+
+    /**
+     * 更新状态标签，缺少版本时不伪造版本号。
+     * Render the label without inventing a missing version.
+     * @param {"checking" | "installed" | "missing"} status 状态 / State.
+     * @param {string | null} [version] 业务版本 / Business version.
+     * @returns {void} 无返回值 / No return value.
+     */
+    #render(status, version = null) {
+        this.#state = { status, version: status === "installed" ? version : null };
+        switch (status) {
+            case "checking":
+                this.#element.textContent = "检测中";
+                break;
+            case "installed":
+                this.#element.textContent = version ?? "版本未知";
+                break;
+            case "missing":
+                this.#element.textContent = "未安装";
+                break;
+        }
+        this.#element.dataset.state = status;
+        this.#element.title = this.#element.textContent;
+        this.dispatchEvent(new Event("change"));
+    }
+
+    /**
+     * 释放尚未完成的探测。
+     * Release pending probes.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#controller?.abort();
+        this.#controller = undefined;
+    }
+}

package/src/browser/Navigation.d.mts

@@ -19,7 +19,7 @@ export class ModuleFrame extends EventTarget {
      * change 事件对应的导航状态。
      * Navigation state exposed with change events.
      */
-    readonly state: { title: string; module: string; busy: boolean; canGoBack: boolean };
+    readonly state: { title: string; module: string; busy: boolean; canGoBack: boolean; actions: MenuAction[] };
     /**
      * 获取原始 HTML。
      * Fetch unmodified HTML.
@@ -32,6 +32,13 @@ export class ModuleFrame extends EventTarget {
      * @returns 无返回值 / No return value.
      */
     back(): void;
+    /**
+     * 执行模块提供的菜单操作。
+     * Perform a module-provided menu action.
+     * @param id 操作标识 / Action identifier.
+     * @returns 无返回值 / No return value.
+     */
+    perform(id: string): void;
     /**
      * 取消请求与事件订阅。
      * Cancel requests and subscriptions.
@@ -40,6 +47,97 @@ export class ModuleFrame extends EventTarget {
     destroy(): void;
 }
 
+/**
+ * 菜单操作描述。
+ * Menu action descriptor.
+ */
+export interface MenuAction {
+    /**
+     * 操作标识。
+     * Action identifier.
+     */
+    id: string;
+    /**
+     * 显示文字。
+     * Display text.
+     */
+    label: string;
+    /**
+     * 危险操作样式。
+     * Destructive action style.
+     */
+    destructive?: boolean;
+}
+
+/**
+ * 共用三点菜单。
+ * Shared overflow menu.
+ */
+export class ActionMenu {
+    /**
+     * 创建菜单。
+     * Create a menu.
+     * @param select 选择回调 / Selection callback.
+     */
+    constructor(select: (id: string) => void);
+    /**
+     * 菜单节点。
+     * Menu element.
+     */
+    readonly element: HTMLElement;
+    /**
+     * 更新操作列表。
+     * Update available actions.
+     * @param items 操作列表 / Actions.
+     * @param disabled 是否忙碌 / Busy state.
+     * @returns 无返回值 / No return value.
+     */
+    update(items: MenuAction[], disabled?: boolean): void;
+    /**
+     * 关闭菜单。
+     * Close the menu.
+     * @returns 无返回值 / No return value.
+     */
+    close(): void;
+    /**
+     * 释放组件。
+     * Release the component.
+     * @returns 无返回值 / No return value.
+     */
+    destroy(): void;
+}
+
+/**
+ * HEAD 探测的固定模块状态行。
+ * Fixed module status row backed by HEAD probes.
+ */
+export class ModuleStatus extends EventTarget {
+    /**
+     * 绑定状态行。
+     * Bind a status row.
+     * @param element 状态行节点 / Status row node.
+     */
+    constructor(element: HTMLElement);
+    /**
+     * 当前状态及模块版本。
+     * Current state and module version.
+     */
+    readonly state: { status: "checking" | "installed" | "missing"; version: string | null };
+    /**
+     * 探测配置 Mock。
+     * Probe a configuration Mock.
+     * @param url 配置地址 / Configuration URL.
+     * @returns 探测完成 / Probe completion.
+     */
+    check(url: string | URL): Promise<void>;
+    /**
+     * 取消探测。
+     * Cancel probes.
+     * @returns 无返回值 / No return value.
+     */
+    destroy(): void;
+}
+
 /**
  * 同一文档的根页/子页导航，不定义页面布局或模块业务。
  * Home/detail navigation within a document, without layout or module business rules.

package/src/browser/Navigation.mjs

@@ -1,4 +1,6 @@
+export { ActionMenu } from "./ActionMenu.mjs";
 export { ModuleFrame } from "./ModuleFrame.mjs";
+export { ModuleStatus } from "./ModuleStatus.mjs";
 
 /**
  * 同一文档内的主页/子页导航；iframe 各自的实例通过浏览器联合历史协作。

package/src/browser/client.d.mts

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

package/src/browser/client.mjs

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