@nsnanocat/preference-panes 1.2.5 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nsnanocat/preference-panes",
-    "version": "1.2.5",
+    "version": "1.3.1",
     "description": "Generic BoxJS settings frontend and persistence API for JavaScript proxy modules",
     "author": "VirgilClyne <Virgil@nanocat.me>",
     "homepage": "https://NSNanoCat.github.io/preference-panes",
@@ -28,7 +28,7 @@
         },
         "./navigation": {
             "types": "./src/browser/Navigation.d.mts",
-            "import": "./dist/module/navigation.mjs"
+            "import": "./dist/navigation.mjs"
         }
     },
     "types": "src/index.d.ts",
@@ -52,7 +52,8 @@
     },
     "files": [
         "src",
-        "dist"
+        "dist",
+        "CHANGELOG.md"
     ],
     "devDependencies": {
         "@biomejs/biome": "2.1.4",

package/src/browser/ActionMenu.mjs

@@ -1,6 +1,6 @@
 /**
- * 独立页面的三点按钮和底部操作菜单；嵌入页面由宿主提供对应界面。
- * Overflow trigger and bottom action sheet for standalone pages; embedded pages use host-provided chrome.
+ * 共用菜单按钮和底部操作菜单；原生宿主可通过 MORE 调用。
+ * Shared menu trigger and bottom action sheet; native hosts may invoke it through MORE.
  */
 export class ActionMenu {
     #button;
@@ -28,13 +28,14 @@ export class ActionMenu {
         this.element = document.createElement("span");
         const triggerRoot = this.element.attachShadow({ mode: "open" });
         triggerRoot.innerHTML = `<style>
-          :host{display:inline-flex;width:44px;height:44px;color:inherit}
+          :host{display:inline-flex;flex:none;width:37px;height:37px;color:inherit}
           :host([hidden]){display:none!important}
-          button{width:44px;height:44px;padding:10px;font:inherit;cursor:pointer;border:0;color:inherit;background:none}
+          button{box-sizing:border-box;width:37px;height:37px;padding:8px;border-radius:4px;font:inherit;cursor:pointer;border:0;color:inherit;background:none;transition:background-color .3s}
+          button:hover{background:var(--pp-field,#8882)}
           button:disabled{opacity:.4;cursor:default}
           button:focus-visible{outline:2px solid currentColor;outline-offset:-3px}
-          svg{display:block;width:24px;height:24px;fill:currentColor}
-        </style><button type="button" aria-label="更多操作" aria-haspopup="menu" aria-expanded="false"><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>`;
+          svg{display:block;width:21px;height:21px;fill:none}
+        </style><button type="button" aria-label="更多操作" aria-haspopup="menu" aria-expanded="false"><svg viewBox="0 0 21 21" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.667" d="M3.645 5.225h13.333M3.645 10.225h13.333M3.645 15.225h13.333"/></svg></button>`;
         this.#button = triggerRoot.querySelector("button");
         this.#layer = document.createElement("span");
         const layerRoot = this.#layer.attachShadow({ mode: "open" });

package/src/browser/Navigation.d.mts

@@ -1,84 +1,3 @@
-/**
- * 静态 HTML 的模块 iframe 容器；页面资源输入写入 iframe 数据属性。
- * Static HTML module iframe whose resource inputs are written to iframe data attributes.
- * confirm 事件可 preventDefault 后通过 detail.resolve/reject 完成宿主确认。
- * Prevent default on confirm events and settle host dialogs through detail.resolve/reject.
- * notice 事件可 preventDefault 后交由宿主显示，模块不再创建网页 Toast。
- * Prevent default on notice events to display them in the host without a module web Toast.
- * open-url 事件可 preventDefault 后交由宿主打开 URL，模块不再执行链接默认导航。
- * Prevent default on open-url events to open the URL in the host instead of navigating the module.
- */
-export class ModuleFrame extends EventTarget {
-    /**
-     * 创建容器。
-     * Create a container.
-     * @param url 模块地址 / Module URL.
-     * @param options 静态页面请求与资源输入 / Static page request and resource inputs.
-     */
-    constructor(url: string | URL, options?: { signal?: AbortSignal; headers?: HeadersInit });
-    /**
-     * 宿主挂载节点。
-     * Host-mounted element.
-     */
-    readonly element: HTMLIFrameElement;
-    /**
-     * change 事件对应的导航状态。
-     * Navigation state exposed with change events.
-     */
-    readonly state: { title: string; module: string; busy: boolean; canGoBack: boolean; actions: MenuAction[] };
-    /**
-     * 获取原始 HTML。
-     * Fetch unmodified HTML.
-     * @returns 加载完成 / Load completion.
-     */
-    load(): Promise<void>;
-    /**
-     * 沿模块历史返回。
-     * Go back through module history.
-     * @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.
-     * @returns 无返回值 / No return value.
-     */
-    destroy(): void;
-}
-
-/**
- * 宿主确认事件的数据。
- * Host confirmation event detail.
- */
-export interface ConfirmationRequest {
-    /**
-     * 确认内容。
-     * Confirmation message.
-     */
-    message: string;
-    /**
-     * 返回选择。
-     * Return the user's choice.
-     * @param confirmed 是否确认 / Whether confirmed.
-     * @returns 无返回值 / No return value.
-     */
-    resolve(confirmed: boolean): void;
-    /**
-     * 返回失败。
-     * Return a failure.
-     * @param error 错误 / Error.
-     * @returns 无返回值 / No return value.
-     */
-    reject(error: Error): void;
-}
-
 /**
  * 操作结果通知。
  * Operation result notice.
@@ -96,18 +15,6 @@ export interface Notice {
     message: string;
 }
 
-/**
- * 宿主 URL 导航请求。
- * Host URL navigation request.
- */
-export interface OpenURLRequest {
-    /**
-     * 完整目标地址。
-     * Absolute target URL.
-     */
-    url: string;
-}
-
 /**
  * 菜单操作描述。
  * Menu action descriptor.
@@ -131,8 +38,8 @@ export interface MenuAction {
 }
 
 /**
- * 共用三点菜单。
- * Shared overflow menu.
+ * 共用操作菜单。
+ * Shared action menu.
  */
 export class ActionMenu {
     /**
@@ -258,6 +165,8 @@ export class Navigation extends EventTarget {
      * @returns 无返回值 / No return value.
      */
     open(key: string): void;
+    /** 更新当前挂载视图，不增加历史 / Refresh the mounted view without adding history. */
+    refresh(): void;
     /**
      * 沿联合历史后退。
      * Go back through joint history.

package/src/browser/Navigation.mjs

@@ -1,10 +1,9 @@
 export { ActionMenu } from "./ActionMenu.mjs";
-export { ModuleFrame } from "./ModuleFrame.mjs";
 export { ModuleStatus, probeModule } from "./ModuleStatus.mjs";
 
 /**
- * 同一文档内的主页/子页导航；iframe 各自的实例通过浏览器联合历史协作。
- * Navigate home/detail views within a document; iframe instances cooperate through joint browser history.
+ * 同一文档内的首页、模块及字段子页导航。
+ * Navigate homepage, module and field views within one document.
  */
 export class Navigation extends EventTarget {
     #container;
@@ -16,7 +15,7 @@ export class Navigation extends EventTarget {
     #retiring;
     #controller;
     #animation;
-    #scroll = new WeakMap();
+    #scroll = new Map();
     #onHistory = () => this.#route();
     #onPageShow = event => {
         if (event.persisted) this.#route(true);
@@ -59,28 +58,37 @@ export class Navigation extends EventTarget {
     }
 
     /**
-     * 加入子页历史；使用文档自身 URL，避免 srcdoc 按宿主 base URL 跳转。
-     * Push a detail using the document URL, avoiding srcdoc navigation against the host base URL.
+     * 加入模块或字段子页历史，保留路由中的层级分隔符。
+     * Push a module or field view while retaining route hierarchy separators.
      * @param {string} key 子页键 / Detail key.
      * @returns {void} 无返回值 / No return value.
      */
     open(key) {
         if (key === this.#key) return;
         const url = new URL(this.#window.location.href);
-        url.hash = encodeURIComponent(key);
+        url.hash = key.split("/").map(encodeURIComponent).join("/");
         this.#window.history.pushState({ ...this.#window.history.state, preferencePanesRoute: key }, "", url.href);
         this.#route();
     }
 
     /**
-     * 沿浏览器联合历史返回，根页可退回宿主或上个文档。
-     * Go back through joint history, including a host or previous document from home.
+     * 沿文档历史返回，根页可退回上个文档。
+     * Go back through document history, including the previous document from home.
      * @returns {void} 无返回值 / No return value.
      */
     back() {
         if (this.canGoBack) this.#window.history.back();
     }
 
+    /**
+     * 更新当前页的挂载视图，保留路由和滚动位置。
+     * Refresh the mounted view while retaining route and scroll position.
+     * @returns {void} 无返回值 / No return value.
+     */
+    refresh() {
+        this.#route(true);
+    }
+
     /**
      * 解析 URL 并统一处理页面切换、加载取消与动画结束后的释放。
      * Resolve the URL and coordinate transitions, cancellation and release after animation.
@@ -97,28 +105,42 @@ export class Navigation extends EventTarget {
             key = "";
         }
         if (!reload && key === this.#key) return;
+        if (key !== this.#key) this.#scroll.set(this.#key, (this.#view ?? this.#home).scrollTop);
         this.#controller?.abort();
         this.#controller = new AbortController();
         const next = key ? this.#create(key, this.#controller.signal) : undefined;
         if (!next) key = "";
         const history = this.#window.history;
-        // 直接打开子页时建立一次主页历史；刷新不重复堆叠。
-        // Seed home history once for direct details, without stacking entries on reload.
+        // 直接打开字段页时补齐首页和模块历史；刷新不重复堆叠。
+        // Seed homepage and module history for direct field links without stacking on reload.
         if (url.hash && history.state?.preferencePanesRoute !== key) {
             url.hash = "";
             history.replaceState({ ...history.state, preferencePanesRoute: "" }, "", url.href);
             if (key) {
-                url.hash = encodeURIComponent(key);
+                const module = key.split("/")[0];
+                if (key.includes("/") && module !== "$link") {
+                    url.hash = encodeURIComponent(module);
+                    history.pushState({ ...history.state, preferencePanesRoute: module }, "", url.href);
+                }
+                url.hash = key.split("/").map(encodeURIComponent).join("/");
                 history.pushState({ ...history.state, preferencePanesRoute: key }, "", url.href);
             }
         }
         const previous = this.#view;
+        if (previous === next && this.#key === key) {
+            if (previous && this.#scroll.has(key)) {
+                previous.scrollTop = this.#scroll.get(key);
+                this.#scroll.delete(key);
+            }
+            this.dispatchEvent(new Event("change"));
+            return;
+        }
+        const scroll = this.#scroll.get(key) ?? (key === this.#key ? (previous?.scrollTop ?? 0) : 0);
         const position = previous ? this.#window.getComputedStyle(previous).transform : "none";
         this.#animation?.cancel();
         this.#retiring?.remove();
         this.#retiring = previous;
         if (previous) {
-            this.#scroll.set(previous, previous.scrollTop);
             previous.inert = true;
         }
         this.#key = key;
@@ -127,7 +149,14 @@ export class Navigation extends EventTarget {
         if (next) {
             next.inert = false;
             this.#container.append(next);
-            next.scrollTop = this.#scroll.get(next) ?? 0;
+            next.scrollTop = scroll;
+            // 加载占位页可能无法滚到原位置；配置与控件就绪后的 refresh 再恢复一次。
+            // A loading placeholder may clamp scrolling; restore once more when config and controls refresh.
+            if (next.scrollTop === scroll) this.#scroll.delete(key);
+        }
+        if (!next) {
+            this.#home.scrollTop = this.#scroll.get("") ?? 0;
+            this.#scroll.delete("");
         }
         const moving = next ?? previous;
         if (moving) {

package/src/browser/boxjs.mjs

@@ -17,6 +17,7 @@ export function normalizeBoxJs(config, module) {
         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");
+            entry.id = entry.id.replace(/\[(0|[1-9]\d*)\]$/, ".$1");
             if (!entry.id.startsWith("@")) {
                 if (Array.isArray(document)) throw new TypeError("BoxJS settings require @root.path IDs");
                 continue;
@@ -58,7 +59,7 @@ export function normalizeBoxJs(config, module) {
         };
         if (type === "select" && !["string", "number", "boolean"].includes(field.type)) throw new TypeError(`Select requires a scalar val: ${entry.id}`);
         if (entry.items) field.options = entry.items.map(item => ({ key: item.key, label: item.label }));
-        if (Object.hasOwn(entry, "val")) field.defaultValue = normalizeStoredValue(field, entry.val);
+        if (Object.prototype.hasOwnProperty.call(entry, "val")) field.defaultValue = normalizeStoredValue(field, entry.val);
         if (
             typeof field.name !== "string" ||
             (field.placeholder !== undefined && typeof field.placeholder !== "string") ||
@@ -68,18 +69,42 @@ export function normalizeBoxJs(config, module) {
         )
             throw new TypeError(`Invalid or overlapping BoxJS field: ${entry.id}`);
         if (field.options && (new Set(field.options.map(item => item.key)).size !== field.options.length || field.options.some(item => !scalar(item.key) || typeof item.label !== "string"))) throw new TypeError(`Invalid options: ${entry.id}`);
-        if (Object.hasOwn(field, "defaultValue") && !validValue(field, field.defaultValue)) throw new TypeError(`Invalid BoxJS val: ${entry.id}`);
-        if (field.control === "url" && !Object.hasOwn(field, "defaultValue")) throw new TypeError(`URL BoxJS settings require a val: ${entry.id}`);
+        if (Object.prototype.hasOwnProperty.call(field, "defaultValue") && !validValue(field, field.defaultValue)) throw new TypeError(`Invalid BoxJS val: ${entry.id}`);
+        if (field.control === "url" && !Object.prototype.hasOwnProperty.call(field, "defaultValue")) throw new TypeError(`URL BoxJS settings require a val: ${entry.id}`);
         fields.push(field);
     }
     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) {
+        const indexed = /^(.*)\.(\d+)$/.exec(field.key);
+        if (!indexed) continue;
+        const siblings = fields.filter(candidate => candidate.key.startsWith(`${indexed[1]}.`) && /^\d+$/.test(candidate.key.slice(indexed[1].length + 1)));
+        if (fields.some(candidate => candidate.key.startsWith(`${indexed[1]}.`) && !siblings.includes(candidate))) throw new TypeError(`Indexed settings cannot mix array entries and named children: ${indexed[1]}`);
+        if (siblings.some(candidate => !Object.prototype.hasOwnProperty.call(candidate, "defaultValue")) || !siblings.some(candidate => candidate.key === `${indexed[1]}.${siblings.length - 1}`) || siblings.some(candidate => Number(candidate.key.slice(indexed[1].length + 1)) >= siblings.length))
+            throw new TypeError(`Indexed settings require contiguous indices and defaults: ${indexed[1]}`);
+    }
+    const owner = target.owners.size === 1 ? [...target.owners][0] : undefined;
+    const cachePath = owner?.cachePath ?? `@${target.storageKey}.${target.module}.Caches`;
+    if (typeof cachePath !== "string" || !cachePath.startsWith(`@${target.storageKey}.`)) throw new TypeError("cachePath must use the module storage root");
+    const cacheParts = validatePathParts(cachePath.slice(target.storageKey.length + 2).split("."));
+    if (cacheParts.length !== 2 || cacheParts[1] !== "Caches") throw new TypeError("cachePath must identify a module Caches subtree");
+    if (owner?.resetPaths !== undefined) {
+        if (!Array.isArray(owner.resetPaths) || !owner.resetPaths.length) throw new TypeError("resetPaths must be a nonempty array");
+        for (const path of owner.resetPaths) {
+            if (typeof path !== "string" || !path.startsWith(`@${target.storageKey}.${target.module}.Settings.`)) throw new TypeError("resetPaths must stay in this module's Settings");
+            validatePathParts(path.slice(target.storageKey.length + 2).split("."));
+        }
+        if (fields.some(field => !owner.resetPaths.some(path => `@${target.storageKey}.${field.key}` === path || `@${target.storageKey}.${field.key}`.startsWith(`${path}.`)))) throw new TypeError("resetPaths must cover the page settings");
+    }
+    const firstIndexed = /^(.*)\.(\d+)$/.exec(fields[0].key);
+    const common = (firstIndexed ? firstIndexed[1] : fields[0].key).split(".").slice(0, -1);
     for (const field of fields) while (!field.key.startsWith(`${common.join(".")}.`)) common.pop();
     return {
         module: target.module,
         storageKey: target.storageKey,
         fields,
         settingsPath: common,
+        ...(owner?.cachePath === undefined ? {} : { cachePath }),
+        ...(owner?.resetPaths === undefined ? {} : { resetPaths: [...owner.resetPaths] }),
         ...(Object.keys(metadata).length ? { metadata } : {}),
     };
 }
@@ -171,9 +196,14 @@ function scalar(value) {
  * @returns {boolean} 是否可由控件表示 / Whether the control can represent the value.
  */
 function validValueShape(field, value) {
-    if (field.type === "array") {
-        if (!Array.isArray(value) || value.some(item => !scalar(item)) || new Set(value).size !== value.length) return false;
-    } else if (typeof value !== field.type || !scalar(value)) return false;
+    switch (field.type) {
+        case "array":
+            if (!Array.isArray(value) || value.some(item => !scalar(item)) || new Set(value).size !== value.length) return false;
+            break;
+        default:
+            if (typeof value !== field.type || !scalar(value)) return false;
+            break;
+    }
     if (field.control === "url" && (!/^[a-z][a-z\d+.-]*:/i.test(value) || /^(?:javascript|data|vbscript):/i.test(value))) return false;
     return true;
 }
@@ -203,7 +233,7 @@ export function resolveStoredValue(field, stored) {
     if (value === undefined) return {};
     if (!validValueShape(field, value)) {
         return {
-            ...(Object.hasOwn(field, "defaultValue") ? { value: field.defaultValue } : {}),
+            ...(Object.prototype.hasOwnProperty.call(field, "defaultValue") ? { value: field.defaultValue } : {}),
             warning: { kind: "invalid-value", values: [stored] },
         };
     }

package/src/browser/client.d.mts

@@ -66,11 +66,11 @@ export class PreferencesClient {
     readSettings(): Promise<unknown>;
     /** 读取 Caches 子树 / Read the Caches subtree. */
     readCaches(): Promise<unknown>;
-    /** 删除 Caches / Delete Caches. */
+    /** 删除声明的 Caches 子树 / Delete the declared Caches subtree. */
     clearCaches(): Promise<void>;
-    /** 删除整个模块数据并恢复默认值 / Delete module data and restore defaults. */
+    /** 删除声明的设置路径，默认整个模块数据，并恢复默认值 / Delete declared setting paths, defaulting to module data, and restore defaults. */
     reset(): Promise<void>;
-    /** 取消请求 / Cancel requests. */
+    /** 取消读取，已开始的写入继续完成 / Cancel reads while allowing started writes to finish. */
     leave(): void;
     /** 写入单个字段 / Write one field. */
     set(key: string, value: SettingsScalar | SettingsScalar[]): Promise<void>;

package/src/browser/client.mjs

@@ -14,6 +14,7 @@ export class PreferencesClient {
     #values = {};
     #warnings = {};
     #saving = false;
+    #arrays = new Map();
 
     /**
      * 创建从 BoxJS 定义读取和持久化设置的页面客户端。
@@ -40,13 +41,22 @@ export class PreferencesClient {
         if (!subtree || typeof subtree !== "object" || Array.isArray(subtree)) throw new TypeError("Expected a settings subtree object");
         const values = {};
         const warnings = {};
+        this.#arrays.clear();
         for (const field of this.#definition.fields) {
+            const indexed = /^(.*)\.(\d+)$/.exec(field.key);
+            if (indexed && !this.#arrays.has(indexed[1])) {
+                const storedArray = indexed[1]
+                    .split(".")
+                    .slice(this.#definition.settingsPath.length)
+                    .reduce((parent, part) => Object(parent)[part], subtree);
+                this.#arrays.set(indexed[1], Array.isArray(storedArray) ? [...storedArray] : []);
+            }
             const stored = field.key
                 .split(".")
                 .slice(this.#definition.settingsPath.length)
                 .reduce((parent, part) => Object(parent)[part], subtree);
             const resolved = resolveStoredValue(field, stored);
-            if (Object.hasOwn(resolved, "value")) values[field.key] = resolved.value;
+            if (Object.prototype.hasOwnProperty.call(resolved, "value")) values[field.key] = resolved.value;
             if (resolved.warning) warnings[field.key] = resolved.warning;
         }
         this.#values = values;
@@ -60,7 +70,7 @@ export class PreferencesClient {
      * @returns {import("./client.mjs").ModuleSnapshot} 会话快照 / Session snapshot.
      */
     snapshot() {
-        return structuredClone({ definition: this.#definition, values: this.#values, warnings: this.#warnings });
+        return JSON.parse(JSON.stringify({ definition: this.#definition, values: this.#values, warnings: this.#warnings }));
     }
 
     /**
@@ -79,22 +89,23 @@ export class PreferencesClient {
      * @returns {Promise<unknown>} Caches 内容或 undefined / Caches content or undefined.
      */
     async readCaches() {
-        const response = await this.#send("get", `@${this.#definition.storageKey}.${this.#module}.Caches`);
+        const response = await this.#send("get", this.#definition.cachePath ?? `@${this.#definition.storageKey}.${this.#module}.Caches`);
         return response.status === 404 ? undefined : response.json();
     }
 
     /**
-     * 删除当前模块的 Caches 子树。
-     * Delete the current module Caches subtree.
+     * 删除声明的缓存子树，默认当前模块 Caches。
+     * Delete the declared cache subtree, defaulting to the current module Caches.
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     clearCaches() {
-        return this.#change("delete", `${this.#module}.Caches`, undefined, "clearCaches");
+        const path = this.#definition.cachePath?.slice(this.#definition.storageKey.length + 2) ?? `${this.#module}.Caches`;
+        return this.#change("delete", path, undefined, "clearCaches");
     }
 
     /**
-     * 删除当前模块数据并恢复页面默认值。
-     * Delete current module data and restore page defaults.
+     * 删除声明的设置子树，默认删除当前模块数据，并恢复页面默认值。
+     * Delete declared settings subtrees, defaulting to current module data, and restore page defaults.
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     reset() {
@@ -102,8 +113,8 @@ export class PreferencesClient {
     }
 
     /**
-     * 终止当前页面仍在进行的请求。
-     * Abort requests still owned by the current page.
+     * 终止当前页面的读取；已开始的持久化写入继续完成。
+     * Abort reads owned by the current page while allowing started persistence writes to finish.
      * @returns {void} 无返回值 / No return value.
      */
     leave() {
@@ -142,8 +153,10 @@ export class PreferencesClient {
     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 });
+        if (action === "get") {
+            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/${action}`, {
@@ -175,30 +188,49 @@ export class PreferencesClient {
         if (this.#saving) throw new Error("A settings write is already in progress");
         this.#saving = true;
         try {
-            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(value);
-                    delete this.#warnings[key];
-                    break;
                 case "delete": {
-                    delete this.#values[key];
-                    delete this.#warnings[key];
-                    if (Object.hasOwn(field, "defaultValue")) this.#values[key] = structuredClone(field.defaultValue);
+                    const field = this.#definition.fields.find(candidate => candidate.key === key);
+                    if (!field || (operation === "write" && !validValue(field, value))) throw new TypeError("Invalid setting value");
+                    const indexed = /^(.*)\.(\d+)$/.exec(key);
+                    if (indexed) {
+                        const array = [...(this.#arrays.get(indexed[1]) ?? [])];
+                        for (const sibling of this.#definition.fields) {
+                            if (sibling.key.startsWith(`${indexed[1]}.`) && /^\d+$/.test(sibling.key.slice(indexed[1].length + 1))) {
+                                const index = Number(sibling.key.slice(indexed[1].length + 1));
+                                if (array[index] === undefined) array[index] = this.#values[sibling.key] ?? sibling.defaultValue;
+                            }
+                        }
+                        array[Number(indexed[2])] = operation === "delete" ? field.defaultValue : value;
+                        await this.#send("set", `@${this.#definition.storageKey}.${indexed[1]}`, array);
+                        this.#arrays.set(indexed[1], array);
+                    } else await this.#send(action, `@${this.#definition.storageKey}.${key}`, value);
+                    switch (operation) {
+                        case "write":
+                            this.#values[key] = JSON.parse(JSON.stringify(value));
+                            delete this.#warnings[key];
+                            break;
+                        case "delete":
+                            delete this.#values[key];
+                            delete this.#warnings[key];
+                            if (Object.prototype.hasOwnProperty.call(field, "defaultValue")) this.#values[key] = JSON.parse(JSON.stringify(field.defaultValue));
+                            break;
+                    }
                     break;
                 }
                 case "clearCaches":
+                    await this.#send(action, `@${this.#definition.storageKey}.${key}`, value);
                     break;
                 case "reset":
+                    if (this.#definition.resetPaths) {
+                        for (const path of this.#definition.resetPaths) await this.#send("delete", path);
+                    } else await this.#send(action, `@${this.#definition.storageKey}.${key}`, value);
+                    this.#arrays.clear();
                     this.#warnings = {};
                     for (const field of this.#definition.fields) {
                         delete this.#values[field.key];
-                        if (Object.hasOwn(field, "defaultValue")) this.#values[field.key] = structuredClone(field.defaultValue);
+                        if (Object.prototype.hasOwnProperty.call(field, "defaultValue")) this.#values[field.key] = JSON.parse(JSON.stringify(field.defaultValue));
                     }
                     break;
             }

package/src/browser/components.mjs

@@ -36,18 +36,6 @@ export function fieldControl(control) {
     return control;
 }
 
-/**
- * 元数据地址只允许 HTTP(S) 和相对地址。
- * Allow only HTTP(S) and relative metadata addresses.
- * @param {string} value 元数据地址 / Metadata address.
- * @returns {string} 完整地址 / Absolute address.
- */
-export function resourceURL(value) {
-    const url = new URL(value, document.baseURI);
-    if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("Metadata URLs must use HTTP(S)");
-    return url.href;
-}
-
 /**
  * 创建覆盖可用内容区的通用读取状态，失败时可附加重试动作。
  * Create a shared status view that fills the available content area and may include retry.
@@ -70,35 +58,3 @@ export function statusView(message, retry) {
     }
     return view;
 }
-
-/**
- * 请求宿主确认；独立网页使用浏览器对话框。
- * Request confirmation from the host, using the browser dialog for standalone pages.
- * @param {Window} host 模块窗口 / Module window.
- * @param {string} message 确认内容 / Confirmation message.
- * @returns {Promise<boolean>} 用户是否确认 / Whether the user confirmed.
- */
-export function requestConfirmation(host, message) {
-    return new Promise((resolve, reject) => {
-        const frame = host.frameElement;
-        if (frame) {
-            const event = new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:confirm", { cancelable: true, detail: { message, resolve, reject } });
-            if (!frame.dispatchEvent(event)) return;
-        }
-        resolve(host.confirm(message));
-    });
-}
-
-/**
- * 请求宿主打开 URL；未被接管时保留链接默认导航。
- * Request host URL navigation while preserving the link default when unhandled.
- * @param {Window} host 模块窗口 / Module window.
- * @param {string} url 完整目标地址 / Absolute target URL.
- * @returns {boolean} 宿主是否接管导航 / Whether the host accepted navigation ownership.
- */
-export function requestURLNavigation(host, url) {
-    const frame = host.frameElement;
-    if (!frame) return false;
-    const event = new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:open-url", { cancelable: true, detail: { url } });
-    return !frame.dispatchEvent(event);
-}