@nsnanocat/preference-panes 0.1.0 → 0.3.0

package/browser/panel.mjs

@@ -1,233 +0,0 @@
-import { createPreferencesClient } from "./client.mjs";
-
-/**
- * 挂载从 BoxJS 实时生成的设置面板和短暂通知。
- * Mount runtime-generated BoxJS controls and transient notifications.
- * @param {import("../types/browser.js").PreferencesPanelOptions} options 容器与请求；页面路径 /settings/{module} 对应配置 / Container and requests; /settings/{module} selects config.
- * @returns {{destroy(): void}} 清理接口 / Cleanup handle.
- */
-export function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
-  const document = root.ownerDocument;
-  const window = document.defaultView;
-  const node = (tag, className, text) => {
-    const el = document.createElement(tag);
-    el.className = className;
-    if (text !== undefined) el.textContent = text;
-    return el;
-  };
-  const shell = node("div", "pp-panel");
-  const header = node("header", "pp-header");
-  const back = node("button", "pp-back", "返回");
-  back.type = "button";
-  const heading = node("h1", "pp-title", title);
-  const viewport = node("div", "pp-viewport");
-  const toast = node("div", "pp-toast");
-  toast.setAttribute("role", "status");
-  toast.hidden = true;
-  header.append(back, heading);
-  shell.append(header, viewport, toast);
-  root.append(shell);
-  let timer,
-    routedPath,
-    generation = 0,
-    active = null,
-    saving = false,
-    pendingRoute = false,
-    destroyed = false;
-  const notify = (event) => {
-    if (destroyed) return;
-    toast.textContent = event.kind === "error" ? `操作失败：${event.message}` : event.operation === "delete" ? "删除成功" : "修改成功";
-    toast.dataset.kind = event.kind;
-    toast.hidden = false;
-    clearTimeout(timer);
-    timer = setTimeout(() => {
-      toast.hidden = true;
-    }, 2400);
-  };
-  const client = createPreferencesClient({ ...(fetch ? { fetch } : {}), notify });
-  function replace(view, direction) {
-    const old = viewport.firstElementChild;
-    viewport.replaceChildren(view);
-    if (old && !document.defaultView.matchMedia("(prefers-reduced-motion: reduce)").matches)
-      view.animate(
-        [
-          { opacity: 0.4, transform: `translateX(${direction * 24}px)` },
-          { opacity: 1, transform: "translateX(0)" },
-        ],
-        { duration: 180, easing: "ease-out" },
-      );
-  }
-  async function open(module) {
-    const version = ++generation;
-    active = module;
-    back.disabled = window.history.length <= 1;
-    heading.textContent = module;
-    replace(node("p", "pp-loading", "读取设置…"), 1);
-    try {
-      await client.open(module);
-      if (version === generation) controls();
-    } catch (error) {
-      if (version !== generation) return;
-      const view = node("section", "pp-error");
-      view.append(node("p", "", `加载失败：${error.message}`));
-      const retry = node("button", "", "重新读取");
-      retry.onclick = () => open(module);
-      view.append(retry);
-      replace(view, 1);
-    }
-  }
-  function controls() {
-    const { definition, values } = client.snapshot(active);
-    const view = node("section", "pp-fields");
-    for (const field of definition.fields) {
-      const row = node("fieldset", "pp-field");
-      row.append(node("legend", "", field.name));
-      if (field.description) row.append(node("p", "pp-description", field.description));
-      const value = values[field.key];
-      let read, write;
-      if (field.options && field.type !== "array") {
-        const select = node("select", "pp-input");
-        select.setAttribute("aria-label", field.name);
-        field.options.forEach((option, index) => {
-          const item = node("option", "", option.label);
-          item.value = String(index);
-          select.append(item);
-        });
-        write = (value) => {
-          select.selectedIndex = field.options.findIndex((option) => option.key === value);
-        };
-        row.append(select);
-        read = () => field.options[select.selectedIndex]?.key;
-      } else if (field.type === "array" && field.options) {
-        const inputs = field.options.map((option) => {
-          const label = node("label", "pp-choice", option.label);
-          const input = node("input", "");
-          input.type = "checkbox";
-          input.checked = Array.isArray(value) && value.includes(option.key);
-          label.prepend(input);
-          row.append(label);
-          return { input, key: option.key };
-        });
-        read = () => inputs.filter((option) => option.input.checked).map((option) => option.key);
-        write = (value) => {
-          for (const option of inputs) option.input.checked = Array.isArray(value) && value.includes(option.key);
-        };
-      } else {
-        const input = node(field.type === "array" ? "textarea" : "input", "pp-input");
-        input.setAttribute("aria-label", field.name);
-        if (field.type === "boolean") {
-          input.type = "checkbox";
-          write = (value) => {
-            input.checked = value === true;
-          };
-          read = () => input.checked;
-        } else {
-          input.type = field.type === "number" ? "number" : "text";
-          write = (value) => {
-            input.value = field.type === "array" ? JSON.stringify(value ?? []) : (value ?? "");
-          };
-          read = () =>
-            field.type === "array"
-              ? JSON.parse(input.value)
-              : field.type === "number"
-                ? input.value === ""
-                  ? Number.NaN
-                  : Number(input.value)
-                : input.value;
-        }
-        row.append(input);
-      }
-      write(value);
-      const actions = node("div", "pp-actions");
-      for (const [operation, label] of [
-        ["write", "保存"],
-        ["delete", "删除覆盖值"],
-      ]) {
-        const button = node("button", "", label);
-        button.type = "button";
-        button.onclick = async () => {
-          if (saving) return;
-          saving = true;
-          back.disabled = true;
-          view.querySelectorAll("button,input,select,textarea").forEach((input) => {
-            input.disabled = true;
-          });
-          let success = false;
-          try {
-            if (operation === "delete") await client.remove(active, field.key);
-            else {
-              let value;
-              try {
-                value = read();
-              } catch (error) {
-                notify({ kind: "error", message: error.message });
-                throw error;
-              }
-              await client.set(active, field.key, value);
-            }
-            success = true;
-          } catch {
-            /* 客户端已显示错误通知 / Client already displayed an error notification. */
-          } finally {
-            saving = false;
-            back.disabled = window.history.length <= 1;
-            view.querySelectorAll("button,input,select,textarea").forEach((input) => {
-              input.disabled = false;
-            });
-            if (success && !destroyed) {
-              // 只更新当前控件，保留其它尚未保存的输入。
-              // Update this control without discarding other unsaved inputs.
-              write(client.snapshot(active).values[field.key]);
-            }
-            if (!destroyed && pendingRoute) route();
-          }
-        };
-        actions.append(button);
-      }
-      row.append(actions);
-      view.append(row);
-    }
-    viewport.replaceChildren(view);
-  }
-  function route() {
-    if (saving) {
-      pendingRoute = true;
-      return;
-    }
-    pendingRoute = false;
-    if (active) client.leave(active);
-    routedPath = window.location.pathname;
-    const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(routedPath);
-    if (!match) {
-      generation++;
-      active = null;
-      heading.textContent = title;
-      replace(node("p", "pp-error", "页面地址应为 /settings/模块标识。"), 1);
-      return;
-    }
-    open(match[1]);
-  }
-  const onPopState = () => {
-    if (window.location.pathname !== routedPath) route();
-  };
-  const onPageShow = (event) => {
-    if (event.persisted) route();
-  };
-  back.onclick = () => {
-    if (!saving) window.history.back();
-  };
-  window.addEventListener("popstate", onPopState);
-  window.addEventListener("pageshow", onPageShow);
-  route();
-  return {
-    destroy() {
-      destroyed = true;
-      window.removeEventListener("popstate", onPopState);
-      window.removeEventListener("pageshow", onPageShow);
-      generation++;
-      if (active) client.leave(active);
-      clearTimeout(timer);
-      shell.remove();
-    },
-  };
-}

package/index.mjs

@@ -1,3 +0,0 @@
-export { normalizeBoxJs } from "./lib/boxjs.mjs";
-export { createSettingsHandler } from "./lib/settings-handler.mjs";
-export { parseSettingsPath } from "./lib/settings-path.mjs";

package/lib/boxjs.mjs

@@ -1,90 +0,0 @@
-import { parseSettingsPath } from "./settings-path.mjs";
-
-/**
- * 将 BoxJS 数组、app 或订阅转换为模块字段，保留原文件为唯一字段来源。
- * Normalize a BoxJS array, app or subscription using the source JSON as the field authority.
- * @param {unknown} config BoxJS JSON / BoxJS document.
- * @param {string} module API 第一段模块名 / First API path segment.
- * @returns {import("../types/index.js").ModuleDefinition} 存储根和字段 / Storage root and fields.
- */
-export function normalizeBoxJs(config, module) {
-  parseSettingsPath(`https://example.invalid/api/${module}`);
-  const entries = Array.isArray(config) ? config : config?.apps ? config.apps.flatMap((app) => app.settings ?? []) : config?.settings;
-  if (!Array.isArray(entries)) throw new TypeError("Expected BoxJS settings array, app or subscription");
-  let storageKey;
-  const fields = [];
-  for (const entry of entries) {
-    if (typeof entry.id !== "string" || !entry.id.startsWith("@")) throw new TypeError("BoxJS settings require @root.path IDs");
-    const [root, ...parts] = entry.id.slice(1).split(".");
-    if (parts[0] !== module) continue;
-    if (parts.length < 2) throw new TypeError("A BoxJS setting must be below the module root");
-    parseSettingsPath(`https://example.invalid/api/${parts.map(encodeURIComponent).join("/")}`);
-    if (!root || (storageKey && root !== storageKey)) throw new TypeError("A module must use one storage root");
-    storageKey = root;
-    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}`);
-    const field = {
-      key: parts.join("."),
-      name: entry.name,
-      type: type === "select" ? typeof entry.val : type,
-      description: entry.desc ?? "",
-    };
-    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 (
-      typeof field.name !== "string" ||
-      fields.some((other) => other.key === field.key || other.key.startsWith(`${field.key}.`) || field.key.startsWith(`${other.key}.`))
-    )
-      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}`);
-    fields.push(field);
-  }
-  if (!fields.length) throw new TypeError(`No BoxJS settings for module: ${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, fields, settingsPath: common };
-}
-
-/**
- * 归一化 BoxJS 的字符串存储值，不改变普通文本内容。
- * Normalize BoxJS string persistence without changing free-text values.
- * @param {import("../types/index.js").SettingsField} field 字段 / Field.
- * @param {unknown} value 存储值 / Stored value.
- * @returns {unknown} 控件值 / Control value.
- */
-export function normalizeStoredValue(field, value) {
-  if (field.type === "boolean" && (value === "true" || value === "false")) return value === "true";
-  if (field.type === "number" && typeof value === "string" && value.trim() !== "") return Number(value);
-  if (field.type === "array" && typeof value === "string") value = value === "" || value === "[]" ? [] : value.split(",");
-  if (field.options) {
-    const match = (item) => field.options.find((option) => String(option.key) === String(item))?.key ?? item;
-    return field.type === "array" && Array.isArray(value) ? value.map(match) : match(value);
-  }
-  return value;
-}
-
-function scalar(value) {
-  return (
-    typeof value === "boolean" ||
-    (typeof value === "string" && value.length <= 2048) ||
-    (typeof value === "number" && Number.isFinite(value))
-  );
-}
-
-export function validValue(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;
-  return !field.options || (field.type === "array" ? value : [value]).every((item) => field.options.some((option) => option.key === item));
-}

package/lib/settings-handler.mjs

@@ -1,113 +0,0 @@
-import { Lodash as _ } from "@nsnanocat/util/polyfill/Lodash.mjs";
-import { Storage } from "@nsnanocat/util/polyfill/Storage";
-import { normalizeBoxJs, validValue } from "./boxjs.mjs";
-import { parseSettingsPath } from "./settings-path.mjs";
-
-/**
- * 创建通用读写处理器；字段通过 loadConfig 在运行时加载，不固化在脚本中。
- * Create a generic endpoint using runtime-loaded config, never compiled-in fields.
- * @param {import("../types/index.js").SettingsHandlerOptions} options 路由与配置加载器 / Routing and config loader.
- * @returns {(request: import("../types/index.js").SettingsRequest) => Promise<import("../types/index.js").SettingsResponse | undefined>} 异步处理器 / Async handler.
- */
-export function createSettingsHandler({ origin, loadConfig, requestHeader = "X-Settings-Client", resolveSettings }) {
-  const target = new URL(origin);
-  if (target.protocol !== "https:" || target.pathname !== "/" || target.search || target.hash || target.username || target.password)
-    throw new TypeError("origin must be an HTTPS origin");
-  if (typeof loadConfig !== "function") throw new TypeError("loadConfig is required");
-  if (!/^[a-z][a-z0-9-]*$/i.test(requestHeader)) throw new TypeError("Invalid requestHeader");
-  return async function handle(request) {
-    const url = new URL(request.url);
-    if (url.origin !== target.origin || !url.pathname.startsWith("/api/")) return;
-    const headers = { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" };
-    const reply = (status, data) => ({ status, headers, body: request.method === "HEAD" ? "" : JSON.stringify(data) });
-    let parts;
-    try {
-      parts = parseSettingsPath(request.url);
-    } catch (error) {
-      return reply(400, { error: error.message });
-    }
-    const requestHeaders = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
-    if (requestHeaders[requestHeader.toLowerCase()] !== "1" || (requestHeaders.origin && requestHeaders.origin !== target.origin))
-      return reply(403, { error: "Forbidden settings client" });
-    if (!["HEAD", "GET", "POST", "DELETE"].includes(request.method))
-      return { ...reply(405, { error: "Method not allowed" }), headers: { ...headers, Allow: "HEAD, GET, POST, DELETE" } };
-    let definition;
-    try {
-      definition = normalizeBoxJs(await loadConfig(parts[0]), parts[0]);
-    } catch (error) {
-      return reply(502, { error: `Module configuration unavailable: ${error.message}` });
-    }
-    const key = parts.join(".");
-    const field = definition.fields.find((field) => field.key === key);
-    const descendants = definition.fields.filter((field) => field.key.startsWith(`${key}.`));
-    if (!field && !descendants.length) return reply(404, { error: `Unknown setting path: ${key}` });
-    if (request.method === "HEAD") return reply(200, undefined);
-    if (request.method === "GET") {
-      const stored = Storage.getItem(definition.storageKey, {});
-      const effective = resolveSettings ? resolveSettings(stored, definition) : stored;
-      if (!isRecord(effective)) throw new TypeError("resolved settings must be a synchronous object");
-      if (field) {
-        const value = pathValue(effective, parts);
-        return value === undefined ? reply(404, { error: `Setting has no stored value: ${key}` }) : reply(200, value);
-      }
-      const subtree = {};
-      // 只返回配置文件公开的字段；默认值由浏览器用 BoxJS val 生成。
-      // Expose only declared fields; the browser renders defaults from BoxJS val.
-      for (const descendant of descendants) {
-        const fullPath = descendant.key.split(".");
-        const value = pathValue(effective, fullPath);
-        if (value !== undefined) _.set(subtree, fullPath.slice(parts.length), value);
-      }
-      return reply(200, subtree);
-    }
-    if (!field) return reply(405, { error: "Only individual declared keys can be modified" });
-    let value;
-    if (request.method === "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" });
-      }
-      if (!validValue(field, value)) return reply(400, { error: `Invalid setting value: ${key}` });
-    }
-    const saved = Storage.getItem(definition.storageKey, {});
-    if (!isRecord(saved)) throw new TypeError("stored settings must be an object");
-    const parent = settingsParent(saved, parts, request.method === "POST");
-    if (parent) {
-      if (request.method === "DELETE") _.unset(parent, [parts.at(-1)]);
-      else _.set(parent, [parts.at(-1)], value);
-    }
-    if (!Storage.setItem(definition.storageKey, saved)) return reply(500, { error: "Settings storage write failed" });
-    return reply(200, request.method === "DELETE" ? { deleted: true } : { saved: true });
-  };
-}
-
-function isRecord(value) {
-  return value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype;
-}
-
-function pathValue(root, parts) {
-  const parent = settingsParent(root, parts, false);
-  return parent ? _.get(parent, [parts.at(-1)]) : undefined;
-}
-
-// util 的 @root.path 允许序列化中间对象；统一解码并保留相邻键。
-// Decode util-serialized intermediate objects while retaining sibling keys.
-function settingsParent(root, parts, create) {
-  let parent = root;
-  for (const part of parts.slice(0, -1)) {
-    let next = _.get(parent, [part]);
-    if (next === undefined) {
-      if (!create) return;
-      next = {};
-    } else if (typeof next === "string") next = JSON.parse(next);
-    if (!isRecord(next)) throw new TypeError(`Stored path is not an object: ${part}`);
-    _.set(parent, [part], next);
-    parent = next;
-  }
-  return parent;
-}

package/lib/settings-path.mjs

@@ -1,20 +0,0 @@
-/**
- * 将 /api/ 后的 URL 路径转换为 util 的路径片段；非 API 路径不处理。
- * Convert URL segments after /api/ to util path segments; ignore non-API paths.
- * @param {string} url 请求完整 URL / Absolute request URL.
- * @returns {string[] | undefined} 键路径片段 / Key path segments.
- * @throws {TypeError} API 路径无效或包含危险片段 / Invalid or unsafe API path.
- */
-export function parseSettingsPath(url) {
-  const pathname = new URL(url).pathname;
-  if (!pathname.startsWith("/api/")) return;
-  let parts;
-  try {
-    parts = pathname.slice(5).replace(/\/$/, "").split("/").map(decodeURIComponent);
-  } catch {
-    throw new TypeError("Invalid encoded key path");
-  }
-  if (!parts.every((part) => /^[a-zA-Z0-9_-]+$/.test(part) && !["__proto__", "prototype", "constructor"].includes(part)))
-    throw new TypeError("Invalid key path");
-  return parts;
-}

package/proxy/request.mjs

@@ -1,36 +0,0 @@
-import { URL } from "@nsnanocat/url";
-import { $app } from "@nsnanocat/util/lib/app.mjs";
-import { done } from "@nsnanocat/util/lib/done.mjs";
-import { fetch } from "@nsnanocat/util/polyfill/fetch";
-import { qs } from "@nsnanocat/util/polyfill/qs.mjs";
-import { createSettingsHandler } from "../lib/settings-handler.mjs";
-
-// JavaScriptCore does not provide the browser URL global.
-// JavaScriptCore 不提供浏览器的 URL 全局对象。
-globalThis.URL ??= URL;
-
-(async () => {
-  let response;
-  try {
-    const { origin, configURL } = qs.parse(globalThis.$argument);
-    const source = new globalThis.URL(configURL);
-    if (source.protocol !== "https:") throw new TypeError("configURL must use HTTPS");
-    const handle = createSettingsHandler({
-      origin,
-      loadConfig: async () => {
-        const response = await fetch({ url: source.href, method: "GET", headers: { "Cache-Control": "no-cache" }, timeout: 5000 });
-        if (response.status !== 200) throw new Error(`BoxJS source HTTP ${response.status}`);
-        return JSON.parse(response.body);
-      },
-    });
-    response = await handle(globalThis.$request);
-  } catch (error) {
-    console.error(`PreferencePanes: ${error.message}`);
-    response = {
-      status: 500,
-      headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" },
-      body: globalThis.$request.method === "HEAD" ? "" : JSON.stringify({ error: "Settings execution failed" }),
-    };
-  }
-  done(response ? ($app === "Quantumult X" ? response : { response }) : {});
-})();

package/types/browser.d.ts

@@ -1,32 +0,0 @@
-import type { ModuleDefinition, SettingsScalar } from "./index.js";
-export interface Notification {
-  kind: "success" | "error";
-  operation: "write" | "delete";
-  module: string;
-  key: string;
-  message?: string;
-}
-export interface PreferencesClientOptions {
-  fetch?: typeof globalThis.fetch;
-  notify?: (notification: Notification) => void;
-  timeout?: number;
-}
-export interface ModuleSnapshot {
-  definition: ModuleDefinition;
-  values: Record<string, SettingsScalar | SettingsScalar[]>;
-}
-export interface PreferencesClient {
-  probe(module: string): Promise<boolean>;
-  open(module: string): Promise<ModuleSnapshot>;
-  snapshot(module: string): ModuleSnapshot;
-  leave(module: string): void;
-  set(module: string, key: string, value: SettingsScalar | SettingsScalar[]): Promise<void>;
-  remove(module: string, key: string): Promise<void>;
-}
-export interface PreferencesPanelOptions {
-  element: HTMLElement;
-  title?: string;
-  fetch?: typeof globalThis.fetch;
-}
-export function createPreferencesClient(options?: PreferencesClientOptions): PreferencesClient;
-export function mountPreferencePanes(options: PreferencesPanelOptions): { destroy(): void };

package/types/index.d.ts

@@ -1,52 +0,0 @@
-/** 字段标量 / Setting scalar. */
-export type SettingsScalar = string | number | boolean;
-export interface SettingsOption<T extends SettingsScalar = SettingsScalar> {
-  key: T;
-  label: string;
-}
-interface FieldBase {
-  key: string;
-  name: string;
-  description?: string;
-}
-/** 对齐 argument 配置字段 / Argument-compatible field. */
-export type SettingsField = FieldBase &
-  (
-    | { type: "boolean"; defaultValue?: boolean; options?: SettingsOption<boolean>[] }
-    | { type: "number"; defaultValue?: number; options?: SettingsOption<number>[] }
-    | { type: "string"; defaultValue?: string; options?: SettingsOption<string>[] }
-    | { type: "array"; defaultValue?: SettingsScalar[]; options?: SettingsOption[] }
-  );
-export interface SettingsRequest {
-  url: string;
-  method: string;
-  headers?: Record<string, string | undefined>;
-  /** POST 的正文为 JSON 值本身；DELETE 无正文 / POST contains the JSON value itself; DELETE has no body. */
-  body?: string;
-}
-export interface SettingsResponse {
-  status: number;
-  headers: Record<string, string>;
-  body: string;
-}
-export interface SettingsHandlerOptions {
-  /** 接管 /api/ 路径的 HTTPS 来源 / HTTPS origin serving /api/ paths. */
-  origin: string;
-  /** 运行时加载 BoxJS JSON / Load BoxJS JSON at runtime. */
-  loadConfig: (module: string) => unknown | Promise<unknown>;
-  /** 页面专用请求头，值为 1 / Dedicated header, value 1. */
-  requestHeader?: string;
-  /** 每次 GET 解析有效设置，默认读取持久化值；优先级由调用方决定。
-   * Resolve effective settings per GET; defaults to persisted values. Caller owns precedence. */
-  resolveSettings?: (stored: Record<string, unknown>, definition: ModuleDefinition) => Record<string, unknown>;
-}
-export interface ModuleDefinition {
-  module: string;
-  storageKey: string;
-  fields: SettingsField[];
-  settingsPath: string[];
-}
-export function normalizeBoxJs(config: unknown, module: string): ModuleDefinition;
-export function createSettingsHandler(options: SettingsHandlerOptions): (request: SettingsRequest) => Promise<SettingsResponse | undefined>;
-/** 解析 /api/ 后的 database 路径；非法路径抛错 / Parse database path after /api/; throws on unsafe paths. */
-export function parseSettingsPath(url: string): string[] | undefined;