From 3dc95edf2eefb9fd92efc49d7e64c0aa8b552814 Mon Sep 17 00:00:00 2001
From: stqfdyr <89149493+stqfdyr@users.noreply.github.com>
Date: Wed, 23 Sep 2026 13:10:04 +0800
Subject: [PATCH 1/4] =?UTF-8?q?feat:=20=E4=B8=BB=E9=A2=98=E8=AE=BE?=
 =?UTF-8?q?=E7=BD=AE=E2=80=94=E2=80=94theme.json=20=E5=A3=B0=E6=98=8E?=
 =?UTF-8?q?=EF=BC=8C=E9=9D=A2=E6=9D=BF=E7=BC=96=E8=BE=91=EF=BC=8Chub=20?=
 =?UTF-8?q?=E6=8C=89=E4=B8=BB=E9=A2=98=E4=BF=9D=E5=AD=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

主题在 theme.json 的 config 里声明设置项（单行/多行文本、数字、开关、下拉，外加不存值的
分组标题），面板主题卡片上出现设置按钮并按声明画表单。值存在数据库的 setting 表里，按主题
short 区分，更新、重装、删除主题都不影响，备份也带着。

GET /api/themes/{short}/config 返回站长改过的项，可见范围同 /api/nodes；PUT 要管理员登录，
主题须已安装，整个对象受路由 64 KiB 请求体上限约束。面板只保存与默认值不同的项，并保留
表单不认识的 key。
---
 src/api.rs                         |  79 +++++++++++++++++
 src/frontend.rs                    |   8 +-
 src/main.rs                        |   2 +
 web-admin/src/components/Admin.tsx | 133 ++++++++++++++++++++++++++++-
 web-admin/src/lib/api.test.ts      |  29 ++++++-
 web-admin/src/lib/api.ts           |  85 ++++++++++++++++++
 6 files changed, 330 insertions(+), 6 deletions(-)

diff --git a/src/api.rs b/src/api.rs
index 3a1f37c5..043fb148 100644
--- a/src/api.rs
+++ b/src/api.rs
@@ -1509,6 +1509,57 @@ pub async fn delete_theme(_: Admin, State(app): State<Shared>, Path(short): Path
     }
 }
 
+/// Where a theme's saved settings live. Keyed by `short` in the database rather
+/// than stored beside the theme, so updating, reinstalling or deleting the
+/// theme leaves them in place, and a backup carries them.
+fn theme_config_key(short: &str) -> String {
+    format!("theme_config:{short}")
+}
+
+/// The settings saved for one theme in the panel: only the fields changed from
+/// the defaults its `theme.json` declares, which the theme fills in itself.
+/// Any theme may be named, installed or not, so a theme under development
+/// reads its own settings from whichever hub it proxies to.
+///
+/// Anonymous, under the same condition as `/api/nodes`. One request is one
+/// primary-key read answering at most 64 KiB, the router's body limit having
+/// bounded the write. That is the cost class of `/api/me`, so there is no gate:
+/// on a three-core hub (debug build), 120 concurrent requests for a 60 KiB
+/// value held the panel's `/api/nodes` at a 230 ms median, against 160 ms
+/// under the same load on `/api/me`.
+pub async fn theme_config(
+    State(app): State<Shared>,
+    headers: HeaderMap,
+    Path(short): Path<String>,
+) -> Response {
+    if !authed(&app, &headers) && !app.public_page() {
+        return (StatusCode::UNAUTHORIZED, "sign-in required").into_response();
+    }
+    if !crate::frontend::valid_short(&short) {
+        return StatusCode::NOT_FOUND.into_response();
+    }
+    let saved = app.db.get(&theme_config_key(&short)).unwrap_or_else(|| "{}".into());
+    ([(header::CONTENT_TYPE, "application/json")], saved).into_response()
+}
+
+/// Replaces a theme's saved settings. Values are not checked against the
+/// theme's declared fields: the theme must validate what it reads regardless,
+/// since a value saved under one version of the theme meets the next.
+pub async fn save_theme_config(
+    _: Admin,
+    State(app): State<Shared>,
+    Path(short): Path<String>,
+    Json(values): Json<serde_json::Map<String, Value>>,
+) -> Response {
+    if !crate::frontend::valid_short(&short) || !crate::frontend::selectable(&app, &short) {
+        return bad("theme is not installed");
+    }
+    match app.db.set(&theme_config_key(&short), &Value::Object(values).to_string()) {
+        Ok(()) => StatusCode::NO_CONTENT.into_response(),
+        Err(e) => fail(e),
+    }
+}
+
 pub async fn themes(_: Admin, State(app): State<Shared>) -> Response {
     match crate::frontend::themes(&app) {
         Ok(themes) => Json(json!({"themes": themes})).into_response(),
@@ -2242,6 +2293,34 @@ mod tests {
         assert!(app.agents.read().unwrap().is_empty(), "the node must read as offline at once");
     }
 
+    /// What the panel saves is what an anonymous visitor reads, under the same
+    /// condition as the node list, and only an installed theme takes a write.
+    #[tokio::test]
+    async fn saved_theme_settings_reach_visitors_while_the_status_page_is_open() {
+        let app = std::sync::Arc::new(app());
+        let state = || axum::extract::State(app.clone());
+        let read = |short: &str| theme_config(state(), HeaderMap::new(), Path(short.to_owned()));
+        let body = |r: Response| async { axum::body::to_bytes(r.into_body(), usize::MAX).await.unwrap() };
+
+        assert_eq!(&body(read("default").await).await[..], b"{}", "nothing saved reads as no overrides");
+        let values = json!({"notice": "维护中", "show_price": false}).as_object().unwrap().clone();
+        let saved = save_theme_config(Admin, state(), Path("default".into()), Json(values.clone())).await;
+        assert_eq!(saved.status(), StatusCode::NO_CONTENT);
+        let read_back: Value = serde_json::from_slice(&body(read("default").await).await).unwrap();
+        assert_eq!(read_back, Value::Object(values.clone()));
+
+        let missing = save_theme_config(Admin, state(), Path("aurora".into()), Json(values.clone())).await;
+        assert_eq!(missing.status(), StatusCode::BAD_REQUEST, "a theme that is not installed takes no write");
+        assert_eq!(read("../etc").await.status(), StatusCode::NOT_FOUND);
+
+        app.db.set("public_page", "off").unwrap();
+        assert_eq!(
+            read("default").await.status(),
+            StatusCode::UNAUTHORIZED,
+            "a closed status page hides them too"
+        );
+    }
+
     /// A write naming a node that no longer exists, such as one deleted from
     /// another tab, is refused rather than reported as saved.
     #[tokio::test]
diff --git a/src/frontend.rs b/src/frontend.rs
index 4525a885..9f06ba6e 100644
--- a/src/frontend.rs
+++ b/src/frontend.rs
@@ -41,6 +41,12 @@ pub struct Theme {
     pub version: String,
     pub author: String,
     pub url: String,
+    /// The settings form the panel draws for this theme. Passed through
+    /// unparsed: a malformed field costs that one field in the panel rather than
+    /// removing the whole theme from the list, and a hub predating the field
+    /// ignores it.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub config: Option<serde_json::Value>,
     #[serde(default)]
     pub selected: bool,
     /// Set only for the copy embedded in the binary. Never read from a manifest:
@@ -162,7 +168,7 @@ fn read_inside(root: &Path, relative: &str) -> Option<Vec<u8>> {
 /// name and anything carrying a path separator. `default` is admitted: an
 /// installed copy of the built-in theme takes that name and is served in its
 /// place, leaving the embedded one as the fallback beneath it.
-fn valid_short(short: &str) -> bool {
+pub fn valid_short(short: &str) -> bool {
     !short.is_empty() && short.bytes().all(|c| c.is_ascii_alphanumeric() || c == b'-' || c == b'_')
 }
 
diff --git a/src/main.rs b/src/main.rs
index 807dbb66..6f61900b 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -442,6 +442,7 @@ async fn main() -> Result<()> {
         .route("/api/nodes", get(api::nodes))
         .route("/api/nodes/{id}/metrics", get(api::metrics))
         .route("/api/ws", get(api::live_ws))
+        .route("/api/themes/{short}/config", get(api::theme_config))
         // Sign-in.
         .route("/api/auth/login", post(auth::login))
         .route("/api/auth/logout", post(auth::logout))
@@ -465,6 +466,7 @@ async fn main() -> Result<()> {
         .route("/api/themes/{short}", delete(api::delete_theme))
         .route("/api/themes/{short}/preview", get(api::theme_preview))
         .route("/api/themes/{short}/update", post(api::update_theme))
+        .route("/api/themes/{short}/config", put(api::save_theme_config))
         .route("/api/db", get(api::db_stats))
         .route("/api/db/backup", get(api::db_backup))
         .route("/api/db/vacuum", post(api::db_vacuum))
diff --git a/web-admin/src/components/Admin.tsx b/web-admin/src/components/Admin.tsx
index a25162ea..81697206 100644
--- a/web-admin/src/components/Admin.tsx
+++ b/web-admin/src/components/Admin.tsx
@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react"
 import { flushSync } from "react-dom"
-import { ArrowUpCircle, Bell, CalendarClock, ChevronRight, Copy, Database, Download, GripVertical, Palette, Pencil, Plus, Radio, RefreshCw, Search, Send, Server, Settings, Shield, Trash2, Upload } from "lucide-react"
+import { ArrowUpCircle, Bell, CalendarClock, ChevronRight, Copy, Database, Download, GripVertical, Palette, Pencil, Plus, Radio, RefreshCw, Search, Send, Server, Settings, Shield, SlidersHorizontal, Trash2, Upload } from "lucide-react"
 import { toast } from "sonner"
 
 import { Badge } from "@/components/ui/badge"
@@ -12,7 +12,7 @@ import { Label } from "@/components/ui/label"
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"
 import { Switch } from "@/components/ui/switch"
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"
-import { addresses, api, badIfaceName, behind, changes, currentIface, GIB, ifaceChoice, ifaceSpec, outdatedAgents, provisioningSite, trafficCorrection, upload, type IfaceChoice, type Node, type PingTask, type Source } from "@/lib/api"
+import { addresses, api, badIfaceName, behind, changes, configFields, configForm, configOverrides, configValues, currentIface, GIB, ifaceChoice, ifaceSpec, outdatedAgents, provisioningSite, trafficCorrection, upload, type ConfigField, type IfaceChoice, type Node, type PingTask, type Source } from "@/lib/api"
 import { bytes, CYCLES, FOREVER, money, uptime } from "@/lib/format"
 
 // Counters the panel can correct after migration or an accounting error.
@@ -1302,6 +1302,112 @@ type Theme = {
   // 内置主题在二进制里，没有目录可删。装上一份同名的会顶替它，那一份就是普通
   // 主题，删掉之后内置的重新顶上。
   builtin: boolean
+  // theme.json 里声明的设置表单，原样转过来，由 configFields 挑出能画的字段。
+  config?: unknown
+}
+
+// 主题在 theme.json 里声明的设置。hub 只存与默认值不同的项，其余由主题用自己的默认值补上，
+// 所以主题作者日后改了某个默认值，没动过这一项的站点会跟着变。
+function ThemeSettings({ theme, saved, onClose }: {
+  theme: Theme
+  saved: Record<string, unknown>
+  onClose: () => void
+}) {
+  const form = configForm(theme.config)
+  const fields = configFields(theme.config)
+  const [values, setValues] = useState(() => configValues(fields, saved))
+  const [saving, setSaving] = useState(false)
+  const set = (key: string, value: unknown) => setValues((old) => ({ ...old, [key]: value }))
+  const label = (field: ConfigField) => field.label || field.key
+
+  async function save(e: React.FormEvent) {
+    e.preventDefault()
+    // 数字框编辑时存的是输入框里的原文；是否为空、是否越界已由浏览器按 required/min/max 拦下。
+    const typed = Object.fromEntries(
+      fields.map((f) => [f.key, f.type === "number" ? Number(values[f.key]) : values[f.key]]),
+    )
+    setSaving(true)
+    try {
+      await api(`/themes/${theme.short}/config`, {
+        method: "PUT",
+        body: JSON.stringify(configOverrides(fields, saved, typed)),
+      })
+      toast.success("主题设置已保存，公开页刷新后生效")
+      onClose()
+    } catch (e) {
+      toast.error((e as Error).message)
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  return (
+    <Dialog open onOpenChange={(open) => !open && onClose()}>
+      <DialogContent onOpenAutoFocus={(e) => e.preventDefault()} className="sm:max-w-lg">
+        <DialogHeader>
+          <DialogTitle>{theme.name} 设置</DialogTitle>
+          <DialogDescription className="leading-relaxed">
+            保存后公开页刷新即生效，更新、重装主题都不会丢失。这里填的内容所有访客都能看到，不要填密码或密钥。
+          </DialogDescription>
+        </DialogHeader>
+        <form className="space-y-4" onSubmit={save}>
+          {form.map((field, index) =>
+            field.type === "title" ? (
+              <h3 key={`title-${index}`} className="pt-2 text-sm font-semibold first:pt-0">{field.label}</h3>
+            ) : field.type === "boolean" ? (
+              <OptionRow key={field.key} title={label(field)} hint={field.help} toggle>
+                <Switch checked={values[field.key] as boolean} onCheckedChange={(v) => set(field.key, v)} />
+              </OptionRow>
+            ) : (
+              <Field key={field.key} label={label(field)} hint={field.help}>
+                {field.type === "text" ? (
+                  <textarea
+                    rows={4}
+                    className={`${TEXT_BOX} text-sm`}
+                    value={values[field.key] as string}
+                    onChange={(e) => set(field.key, e.target.value)}
+                  />
+                ) : field.type === "select" ? (
+                  <Select value={values[field.key] as string} onValueChange={(v) => set(field.key, v)}>
+                    <SelectTrigger className="w-full"><SelectValue /></SelectTrigger>
+                    <SelectContent>
+                      {field.options!.map((o) => (
+                        <SelectItem key={o.value} value={o.value}>{o.label || o.value}</SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                ) : field.type === "number" ? (
+                  <Input
+                    type="number"
+                    required
+                    step="any"
+                    min={field.min}
+                    max={field.max}
+                    value={String(values[field.key])}
+                    onChange={(e) => set(field.key, e.target.value)}
+                  />
+                ) : (
+                  <Input value={values[field.key] as string} onChange={(e) => set(field.key, e.target.value)} />
+                )}
+              </Field>
+            ),
+          )}
+          <DialogFooter className="border-t pt-4">
+            <Button
+              type="button"
+              variant="ghost"
+              className="sm:mr-auto"
+              onClick={() => setValues(Object.fromEntries(fields.map((f) => [f.key, f.default])))}
+            >
+              恢复默认
+            </Button>
+            <Button type="button" variant="ghost" onClick={onClose}>取消</Button>
+            <Button type="submit" disabled={saving}>保存</Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  )
 }
 
 function Themes() {
@@ -1309,6 +1415,7 @@ function Themes() {
   const [busy, setBusy] = useState("")
   const [doomed, setDoomed] = useState<Theme | null>(null)
   const [zoomed, setZoomed] = useState<Theme | null>(null)
+  const [configuring, setConfiguring] = useState<{ theme: Theme; saved: Record<string, unknown> } | null>(null)
   const picker = useRef<HTMLInputElement>(null)
 
   const load = () =>
@@ -1360,6 +1467,16 @@ function Themes() {
     }
   }
 
+  // Read on opening rather than inside the dialog, so the form starts from what
+  // is saved instead of flashing the defaults first.
+  async function configure(theme: Theme) {
+    try {
+      setConfiguring({ theme, saved: await api(`/themes/${theme.short}/config`) })
+    } catch (e) {
+      toast.error((e as Error).message)
+    }
+  }
+
   async function remove(theme: Theme) {
     setBusy("delete")
     try {
@@ -1445,6 +1562,11 @@ function Themes() {
                 <Button size="sm" variant={theme.selected ? "secondary" : "default"} disabled={theme.selected} onClick={() => select(theme.short)}>
                   {theme.selected ? "使用中" : "使用"}
                 </Button>
+                {configFields(theme.config).length > 0 && (
+                  <Button size="icon" variant="ghost" title="主题设置" onClick={() => configure(theme)}>
+                    <SlidersHorizontal />
+                  </Button>
+                )}
                 {updatable(theme) && (
                   <Button
                     size="icon"
@@ -1492,6 +1614,8 @@ function Themes() {
         </Dialog>
       )}
 
+      {configuring && <ThemeSettings {...configuring} onClose={() => setConfiguring(null)} />}
+
       {doomed && (
         <ConfirmDialog
           title={`删除 ${doomed.name}？`}
@@ -1605,8 +1729,9 @@ function SettingsTab() {
   )
 }
 
-const TEXTAREA =
-  "w-full min-w-0 rounded-md border border-input bg-transparent px-3 py-2 font-mono text-xs shadow-xs outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 dark:bg-input/30"
+const TEXT_BOX =
+  "w-full min-w-0 rounded-md border border-input bg-transparent px-3 py-2 shadow-xs outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 dark:bg-input/30"
+const TEXTAREA = `${TEXT_BOX} font-mono text-xs`
 
 // One offline alert, filled in the way the hub fills a template: in a single pass,
 // JSON-escaped for the webhook body. Previews only; nothing here is sent.
diff --git a/web-admin/src/lib/api.test.ts b/web-admin/src/lib/api.test.ts
index 03c6c8f1..ad89a8b1 100644
--- a/web-admin/src/lib/api.test.ts
+++ b/web-admin/src/lib/api.test.ts
@@ -1,6 +1,6 @@
 /// <reference types="node" />
 import assert from "node:assert/strict"
-import { addresses, badIfaceName, behind, changes, currentIface, GIB, ifaceChoice, ifaceSpec, isPublic, loopbackOrigin, outdatedAgents, provisionRefusal, provisioningSite, trafficCorrection } from "./api.ts"
+import { addresses, badIfaceName, behind, changes, configFields, configForm, configOverrides, configValues, currentIface, fits, GIB, ifaceChoice, ifaceSpec, isPublic, loopbackOrigin, outdatedAgents, provisionRefusal, provisioningSite, trafficCorrection } from "./api.ts"
 
 assert.deepEqual(changes({ public: true, price: 5 }, { price: 20 }), { price: 20 })
 assert.deepEqual(changes({ total_rx: "100", month_tx: "2" }, { total_rx: "100", month_tx: "3" }), { month_tx: "3" })
@@ -108,3 +108,30 @@ assert.equal(ifaceSpec(ifaceChoice("enp1s0,-enp5s0")), "enp1s0,-enp5s0")
 assert.equal(currentIface({ metrics: null }), undefined)
 assert.equal(currentIface({ metrics: {} as never }), "")
 assert.equal(currentIface({ metrics: { iface: "eth1,-eth0" } as never }), "eth1,-eth0")
+
+// A theme's form: malformed fields drop out one by one, a saved value the field
+// can no longer hold shows the default, and only changes from a default are stored.
+const entries = [
+  { type: "title", label: "外观" },
+  { key: "notice", type: "text", default: "" },
+  { key: "layout", type: "select", default: "grid", options: [{ value: "grid" }, { value: "table" }] },
+  { key: "refresh", type: "number", default: 5, min: 1, max: 60 },
+  { key: "dark", type: "boolean", default: false },
+  { key: "notice", type: "string", default: "duplicate" },
+  { key: "odd", type: "color", default: "#000" },
+  { key: "bare", type: "select", default: "a" },
+  { key: "blank", type: "select", default: "", options: [{ value: "" }, { value: "a" }] },
+  { key: "wrong", type: "boolean", default: "yes" },
+  { key: "range", type: "number", default: 0, min: 1 },
+  "not a field",
+  { type: "title" },
+]
+assert.deepEqual(configForm(entries).map((f) => (f.type === "title" ? `# ${f.label}` : f.key)), ["# 外观", "notice", "layout", "refresh", "dark"])
+const form = configFields(entries)
+assert.deepEqual(form.map((f) => f.key), ["notice", "layout", "refresh", "dark"])
+assert.deepEqual(configFields({ notice: "x" }), [])
+const saved = { layout: "cards", refresh: 10, legacy: 1 }
+const initial = configValues(form, saved)
+assert.deepEqual(initial, { notice: "", layout: "grid", refresh: 10, dark: false })
+assert.equal(fits(form[2], 61), false)
+assert.deepEqual(configOverrides(form, saved, { ...initial, refresh: 5, dark: true }), { legacy: 1, dark: true })
diff --git a/web-admin/src/lib/api.ts b/web-admin/src/lib/api.ts
index db2531a4..bf3e5592 100644
--- a/web-admin/src/lib/api.ts
+++ b/web-admin/src/lib/api.ts
@@ -83,6 +83,91 @@ export function changes<T extends object>(initial: T, values: Partial<T>): Parti
   return Object.fromEntries(Object.entries(values).filter(([key, value]) => value !== initial[key as keyof T])) as Partial<T>
 }
 
+/** One field of the settings form a theme declares under `config` in its `theme.json`. */
+export type ConfigField = {
+  key: string
+  type: "string" | "text" | "number" | "boolean" | "select"
+  label?: string
+  help?: string
+  default: unknown
+  options?: { value: string; label?: string }[]
+  min?: number
+  max?: number
+}
+
+/** A heading between fields. It holds no value. */
+export type ConfigTitle = { type: "title"; label: string }
+
+const CONFIG_TYPES = ["string", "text", "number", "boolean", "select"]
+
+/** Whether `value` is one the field can hold, the same test a theme applies to what it reads. */
+export function fits(field: ConfigField, value: unknown): boolean {
+  switch (field.type) {
+    case "boolean":
+      return typeof value === "boolean"
+    case "number":
+      return typeof value === "number" && Number.isFinite(value)
+        && (field.min === undefined || value >= field.min) && (field.max === undefined || value <= field.max)
+    case "select":
+      return !!field.options?.some((option) => option.value === value)
+    default:
+      return typeof value === "string"
+  }
+}
+
+/**
+ * The entries of a theme's form the panel can draw, headings included, in the
+ * manifest's order. The manifest is the theme author's, so a malformed entry is
+ * left out rather than failing the form: a heading without a label, a
+ * duplicate key, an unknown type, a select whose options are not all non-empty
+ * strings (the dropdown cannot hold an empty value), or a default the field
+ * could not hold.
+ */
+export function configForm(config: unknown): (ConfigField | ConfigTitle)[] {
+  if (!Array.isArray(config)) return []
+  const seen = new Set<string>()
+  return config.filter((field): field is ConfigField | ConfigTitle => {
+    if (typeof field !== "object" || field === null) return false
+    if (field.type === "title") return typeof field.label === "string" && field.label !== ""
+    const { key, type, options, min, max } = field
+    const ok = typeof key === "string" && key !== "" && !seen.has(key) && CONFIG_TYPES.includes(type)
+      && (type !== "select" || (Array.isArray(options) && options.every((o) => typeof o?.value === "string" && o.value !== "")))
+      && [min, max].every((bound) => bound === undefined || typeof bound === "number")
+      && fits(field, field.default)
+    if (ok) seen.add(key)
+    return ok
+  })
+}
+
+/** The entries of the form that hold a value. */
+export function configFields(config: unknown): ConfigField[] {
+  return configForm(config).filter((entry): entry is ConfigField => entry.type !== "title")
+}
+
+/** The value each field shows: the saved one while the field can still hold it, else the default. */
+export function configValues(fields: ConfigField[], saved: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(fields.map((f) => [f.key, fits(f, saved[f.key]) ? saved[f.key] : f.default]))
+}
+
+/**
+ * What the panel stores: only the fields that differ from their defaults, so a
+ * default the theme changes later reaches every site that never altered it.
+ * Keys the current form does not declare are kept -- a field a newer version
+ * dropped returns with a downgrade.
+ */
+export function configOverrides(
+  fields: ConfigField[],
+  saved: Record<string, unknown>,
+  values: Record<string, unknown>,
+): Record<string, unknown> {
+  const next = { ...saved }
+  for (const field of fields) {
+    if (values[field.key] === field.default) delete next[field.key]
+    else next[field.key] = values[field.key]
+  }
+  return next
+}
+
 export const GIB = 1024 ** 3
 
 /**

From 7c33acbaed66e808e58646b71d80a5a8c9e25d8c Mon Sep 17 00:00:00 2001
From: stqfdyr <89149493+stqfdyr@users.noreply.github.com>
Date: Wed, 23 Sep 2026 13:30:19 +0800
Subject: [PATCH 2/4] =?UTF-8?q?feat:=20=E8=AE=BE=E7=BD=AE=E9=A1=B9?=
 =?UTF-8?q?=E5=A4=9A=E6=97=B6=E6=8C=89=E5=88=86=E7=BB=84=E5=88=86=E6=A0=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

超过 6 项时对话框加宽、固定高度：按分组标题分节，左侧切换（手机上是横向一排），右侧两列，
多行文本占整行；有改动的节在导航上带一个点。未显示的节里的数字在保存时由面板校验，越界就
切回那一节并提示。6 项以内保持原来的单列。
---
 web-admin/src/components/Admin.tsx | 162 ++++++++++++++++++++---------
 web-admin/src/lib/api.test.ts      |   9 +-
 web-admin/src/lib/api.ts           |  17 +++
 3 files changed, 135 insertions(+), 53 deletions(-)

diff --git a/web-admin/src/components/Admin.tsx b/web-admin/src/components/Admin.tsx
index 81697206..c3f3d738 100644
--- a/web-admin/src/components/Admin.tsx
+++ b/web-admin/src/components/Admin.tsx
@@ -12,7 +12,7 @@ import { Label } from "@/components/ui/label"
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"
 import { Switch } from "@/components/ui/switch"
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"
-import { addresses, api, badIfaceName, behind, changes, configFields, configForm, configOverrides, configValues, currentIface, GIB, ifaceChoice, ifaceSpec, outdatedAgents, provisioningSite, trafficCorrection, upload, type ConfigField, type IfaceChoice, type Node, type PingTask, type Source } from "@/lib/api"
+import { addresses, api, badIfaceName, behind, changes, configFields, configForm, configOverrides, configSections, configValues, currentIface, fits, GIB, ifaceChoice, ifaceSpec, outdatedAgents, provisioningSite, trafficCorrection, upload, type ConfigField, type IfaceChoice, type Node, type PingTask, type Source } from "@/lib/api"
 import { bytes, CYCLES, FOREVER, money, uptime } from "@/lib/format"
 
 // Counters the panel can correct after migration or an accounting error.
@@ -1308,6 +1308,9 @@ type Theme = {
 
 // 主题在 theme.json 里声明的设置。hub 只存与默认值不同的项，其余由主题用自己的默认值补上，
 // 所以主题作者日后改了某个默认值，没动过这一项的站点会跟着变。
+//
+// 字段不多时是一列；多了改成宽对话框：按分组标题分节，左侧切换，右侧两列，
+// 否则几十项排成一条细长的列表。有改动的节在导航上带一个点。
 function ThemeSettings({ theme, saved, onClose }: {
   theme: Theme
   saved: Record<string, unknown>
@@ -1315,22 +1318,37 @@ function ThemeSettings({ theme, saved, onClose }: {
 }) {
   const form = configForm(theme.config)
   const fields = configFields(theme.config)
+  const sections = configSections(form)
+  const large = fields.length > 6
+  const paged = large && sections.length > 1
+  const [current, setCurrent] = useState(0)
   const [values, setValues] = useState(() => configValues(fields, saved))
   const [saving, setSaving] = useState(false)
   const set = (key: string, value: unknown) => setValues((old) => ({ ...old, [key]: value }))
   const label = (field: ConfigField) => field.label || field.key
+  // A number box holds its text while being edited.
+  const typed = (f: ConfigField) => (f.type === "number" ? Number(values[f.key]) : values[f.key])
+  const differs = (f: ConfigField) => typed(f) !== f.default
 
   async function save(e: React.FormEvent) {
     e.preventDefault()
-    // 数字框编辑时存的是输入框里的原文；是否为空、是否越界已由浏览器按 required/min/max 拦下。
-    const typed = Object.fromEntries(
-      fields.map((f) => [f.key, f.type === "number" ? Number(values[f.key]) : values[f.key]]),
-    )
+    // The browser checks required/min/max only on the boxes on screen; a
+    // section switched away from is no longer rendered, so its numbers are
+    // checked here and the offending one brought back into view.
+    const invalid = fields.find((f) => f.type === "number" && (values[f.key] === "" || !fits(f, typed(f))))
+    if (invalid) {
+      setCurrent(Math.max(0, sections.findIndex((section) => section.fields.includes(invalid))))
+      const range =
+        invalid.min !== undefined && invalid.max !== undefined ? `${invalid.min}–${invalid.max} 之间的`
+        : invalid.min !== undefined ? `不小于 ${invalid.min} 的`
+        : invalid.max !== undefined ? `不大于 ${invalid.max} 的` : ""
+      return toast.error(`「${label(invalid)}」要填${range}数字`)
+    }
     setSaving(true)
     try {
       await api(`/themes/${theme.short}/config`, {
         method: "PUT",
-        body: JSON.stringify(configOverrides(fields, saved, typed)),
+        body: JSON.stringify(configOverrides(fields, saved, Object.fromEntries(fields.map((f) => [f.key, typed(f)])))),
       })
       toast.success("主题设置已保存，公开页刷新后生效")
       onClose()
@@ -1341,65 +1359,105 @@ function ThemeSettings({ theme, saved, onClose }: {
     }
   }
 
+  const input = (field: ConfigField) =>
+    field.type === "boolean" ? (
+      <OptionRow key={field.key} title={label(field)} hint={field.help} toggle>
+        <Switch checked={values[field.key] as boolean} onCheckedChange={(v) => set(field.key, v)} />
+      </OptionRow>
+    ) : (
+      <Field key={field.key} label={label(field)} hint={field.help} className={large && field.type === "text" ? "sm:col-span-2" : ""}>
+        {field.type === "text" ? (
+          <textarea
+            rows={4}
+            className={`${TEXT_BOX} text-sm`}
+            value={values[field.key] as string}
+            onChange={(e) => set(field.key, e.target.value)}
+          />
+        ) : field.type === "select" ? (
+          <Select value={values[field.key] as string} onValueChange={(v) => set(field.key, v)}>
+            <SelectTrigger className="w-full"><SelectValue /></SelectTrigger>
+            <SelectContent>
+              {field.options!.map((o) => (
+                <SelectItem key={o.value} value={o.value}>{o.label || o.value}</SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        ) : field.type === "number" ? (
+          <Input
+            type="number"
+            required
+            step="any"
+            min={field.min}
+            max={field.max}
+            value={String(values[field.key])}
+            onChange={(e) => set(field.key, e.target.value)}
+          />
+        ) : (
+          <Input value={values[field.key] as string} onChange={(e) => set(field.key, e.target.value)} />
+        )}
+      </Field>
+    )
+
   return (
     <Dialog open onOpenChange={(open) => !open && onClose()}>
-      <DialogContent onOpenAutoFocus={(e) => e.preventDefault()} className="sm:max-w-lg">
+      <DialogContent
+        onOpenAutoFocus={(e) => e.preventDefault()}
+        className={large ? "flex h-[min(46rem,calc(100dvh-2rem))] flex-col overflow-hidden sm:max-w-4xl" : "sm:max-w-lg"}
+      >
         <DialogHeader>
           <DialogTitle>{theme.name} 设置</DialogTitle>
           <DialogDescription className="leading-relaxed">
             保存后公开页刷新即生效，更新、重装主题都不会丢失。这里填的内容所有访客都能看到，不要填密码或密钥。
           </DialogDescription>
         </DialogHeader>
-        <form className="space-y-4" onSubmit={save}>
-          {form.map((field, index) =>
-            field.type === "title" ? (
-              <h3 key={`title-${index}`} className="pt-2 text-sm font-semibold first:pt-0">{field.label}</h3>
-            ) : field.type === "boolean" ? (
-              <OptionRow key={field.key} title={label(field)} hint={field.help} toggle>
-                <Switch checked={values[field.key] as boolean} onCheckedChange={(v) => set(field.key, v)} />
-              </OptionRow>
-            ) : (
-              <Field key={field.key} label={label(field)} hint={field.help}>
-                {field.type === "text" ? (
-                  <textarea
-                    rows={4}
-                    className={`${TEXT_BOX} text-sm`}
-                    value={values[field.key] as string}
-                    onChange={(e) => set(field.key, e.target.value)}
-                  />
-                ) : field.type === "select" ? (
-                  <Select value={values[field.key] as string} onValueChange={(v) => set(field.key, v)}>
-                    <SelectTrigger className="w-full"><SelectValue /></SelectTrigger>
-                    <SelectContent>
-                      {field.options!.map((o) => (
-                        <SelectItem key={o.value} value={o.value}>{o.label || o.value}</SelectItem>
-                      ))}
-                    </SelectContent>
-                  </Select>
-                ) : field.type === "number" ? (
-                  <Input
-                    type="number"
-                    required
-                    step="any"
-                    min={field.min}
-                    max={field.max}
-                    value={String(values[field.key])}
-                    onChange={(e) => set(field.key, e.target.value)}
-                  />
-                ) : (
-                  <Input value={values[field.key] as string} onChange={(e) => set(field.key, e.target.value)} />
-                )}
-              </Field>
-            ),
-          )}
-          <DialogFooter className="border-t pt-4">
+        <form className="flex min-h-0 flex-1 flex-col gap-4" onSubmit={save}>
+          <div className="flex min-h-0 flex-1 flex-col gap-4 sm:flex-row">
+            {paged && (
+              <nav className="-mx-1 flex shrink-0 gap-1 overflow-x-auto px-1 pb-1 sm:mx-0 sm:w-48 sm:flex-col sm:overflow-y-auto sm:px-0">
+                {sections.map((section, index) => (
+                  <button
+                    key={index}
+                    type="button"
+                    aria-current={index === current}
+                    onClick={() => setCurrent(index)}
+                    className={`flex shrink-0 items-center gap-2 rounded-md px-3 py-1.5 text-left text-sm transition-colors ${
+                      index === current ? "bg-muted font-medium" : "text-muted-foreground hover:bg-muted/60 hover:text-foreground"
+                    }`}
+                  >
+                    <span className="whitespace-nowrap sm:whitespace-normal">{section.label}</span>
+                    {section.fields.some(differs) && (
+                      <span className="ml-auto size-1.5 shrink-0 rounded-full bg-primary" title="有改动" />
+                    )}
+                  </button>
+                ))}
+              </nav>
+            )}
+            <div className={`min-h-0 flex-1 ${large ? "overflow-y-auto pr-1" : ""}`}>
+              <div className={`grid items-start gap-4 ${large ? "sm:grid-cols-2" : ""}`}>
+                {paged
+                  ? sections[current].fields.map(input)
+                  : form.map((entry, index) =>
+                      entry.type === "title" ? (
+                        <h3 key={`title-${index}`} className={`pt-2 text-sm font-semibold first:pt-0 ${large ? "sm:col-span-2" : ""}`}>
+                          {entry.label}
+                        </h3>
+                      ) : (
+                        input(entry)
+                      ),
+                    )}
+              </div>
+            </div>
+          </div>
+          {/* One row on a phone as well: stacked, the three buttons would take a
+              third of the height the fields have. */}
+          <DialogFooter className="flex-row items-center border-t pt-4">
             <Button
               type="button"
               variant="ghost"
-              className="sm:mr-auto"
+              className="mr-auto"
               onClick={() => setValues(Object.fromEntries(fields.map((f) => [f.key, f.default])))}
             >
-              恢复默认
+              {paged ? "全部恢复默认" : "恢复默认"}
             </Button>
             <Button type="button" variant="ghost" onClick={onClose}>取消</Button>
             <Button type="submit" disabled={saving}>保存</Button>
diff --git a/web-admin/src/lib/api.test.ts b/web-admin/src/lib/api.test.ts
index ad89a8b1..148b25b3 100644
--- a/web-admin/src/lib/api.test.ts
+++ b/web-admin/src/lib/api.test.ts
@@ -1,6 +1,6 @@
 /// <reference types="node" />
 import assert from "node:assert/strict"
-import { addresses, badIfaceName, behind, changes, configFields, configForm, configOverrides, configValues, currentIface, fits, GIB, ifaceChoice, ifaceSpec, isPublic, loopbackOrigin, outdatedAgents, provisionRefusal, provisioningSite, trafficCorrection } from "./api.ts"
+import { addresses, badIfaceName, behind, changes, configFields, configForm, configOverrides, configSections, configValues, currentIface, fits, GIB, ifaceChoice, ifaceSpec, isPublic, loopbackOrigin, outdatedAgents, provisionRefusal, provisioningSite, trafficCorrection } from "./api.ts"
 
 assert.deepEqual(changes({ public: true, price: 5 }, { price: 20 }), { price: 20 })
 assert.deepEqual(changes({ total_rx: "100", month_tx: "2" }, { total_rx: "100", month_tx: "3" }), { month_tx: "3" })
@@ -135,3 +135,10 @@ const initial = configValues(form, saved)
 assert.deepEqual(initial, { notice: "", layout: "grid", refresh: 10, dark: false })
 assert.equal(fits(form[2], 61), false)
 assert.deepEqual(configOverrides(form, saved, { ...initial, refresh: 5, dark: true }), { legacy: 1, dark: true })
+// Headings split the form; leading fields get a section, empty headings none.
+assert.deepEqual(
+  configSections(configForm([{ key: "a", type: "string", default: "" }, { type: "title", label: "空" }, { type: "title", label: "外观" }, { key: "b", type: "boolean", default: true }]))
+    .map((s) => [s.label, s.fields.map((f) => f.key)]),
+  [["通用", ["a"]], ["外观", ["b"]]],
+)
+
diff --git a/web-admin/src/lib/api.ts b/web-admin/src/lib/api.ts
index bf3e5592..efb93f36 100644
--- a/web-admin/src/lib/api.ts
+++ b/web-admin/src/lib/api.ts
@@ -144,6 +144,23 @@ export function configFields(config: unknown): ConfigField[] {
   return configForm(config).filter((entry): entry is ConfigField => entry.type !== "title")
 }
 
+/**
+ * The form split at its headings. Fields ahead of the first heading form a
+ * section of their own, and a heading with no field under it is dropped, so
+ * every section listed has something to show.
+ */
+export function configSections(form: (ConfigField | ConfigTitle)[]): { label: string; fields: ConfigField[] }[] {
+  const sections: { label: string; fields: ConfigField[] }[] = []
+  for (const entry of form) {
+    if (entry.type === "title") sections.push({ label: entry.label, fields: [] })
+    else {
+      if (!sections.length) sections.push({ label: "通用", fields: [] })
+      sections[sections.length - 1].fields.push(entry)
+    }
+  }
+  return sections.filter((section) => section.fields.length)
+}
+
 /** The value each field shows: the saved one while the field can still hold it, else the default. */
 export function configValues(fields: ConfigField[], saved: Record<string, unknown>): Record<string, unknown> {
   return Object.fromEntries(fields.map((f) => [f.key, fits(f, saved[f.key]) ? saved[f.key] : f.default]))

From 06c0e236dfde51514407671b8025a2ce60d3c4a1 Mon Sep 17 00:00:00 2001
From: stqfdyr <89149493+stqfdyr@users.noreply.github.com>
Date: Wed, 23 Sep 2026 17:13:29 +0800
Subject: [PATCH 3/4] =?UTF-8?q?fix:=20=E4=B8=BB=E9=A2=98=E8=AE=BE=E7=BD=AE?=
 =?UTF-8?q?=E8=B7=B3=E8=BF=87=E9=9D=9E=E5=AD=97=E7=AC=A6=E4=B8=B2=E7=9A=84?=
 =?UTF-8?q?=20label/help=20=E4=B8=8E=E7=A9=BA=E5=88=86=E7=BB=84=E6=A0=87?=
 =?UTF-8?q?=E9=A2=98=EF=BC=8C=E8=AF=BB=E5=BA=93=E5=A4=B1=E8=B4=A5=E4=B8=8D?=
 =?UTF-8?q?=E5=86=8D=E5=BD=93=E4=BD=9C=E6=9C=AA=E4=BF=9D=E5=AD=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- label、help、选项的 label 不是字符串时跳过该字段，否则打开设置时渲染对象抛错，整个面板白屏
- 下面没有设置项的分组标题在 configForm 里统一去掉，单列排版不再留下空标题
- GET /api/themes/{short}/config 读库失败答 500，不再答 {} 让面板在空对象上保存、冲掉已存的项
- 清空的数字框不再被当成 0
---
 src/api.rs                         | 12 ++++++++++--
 src/db.rs                          | 13 +++++++++----
 web-admin/src/components/Admin.tsx | 10 ++++++----
 web-admin/src/lib/api.test.ts      |  5 +++++
 web-admin/src/lib/api.ts           | 28 ++++++++++++++++++----------
 5 files changed, 48 insertions(+), 20 deletions(-)

diff --git a/src/api.rs b/src/api.rs
index 043fb148..840803ce 100644
--- a/src/api.rs
+++ b/src/api.rs
@@ -1527,6 +1527,9 @@ fn theme_config_key(short: &str) -> String {
 /// on a three-core hub (debug build), 120 concurrent requests for a 60 KiB
 /// value held the panel's `/api/nodes` at a 230 ms median, against 160 ms
 /// under the same load on `/api/me`.
+///
+/// A failed read answers 500 rather than `{}`: the panel saves on top of what
+/// it reads, so an empty answer would erase every saved override.
 pub async fn theme_config(
     State(app): State<Shared>,
     headers: HeaderMap,
@@ -1538,8 +1541,13 @@ pub async fn theme_config(
     if !crate::frontend::valid_short(&short) {
         return StatusCode::NOT_FOUND.into_response();
     }
-    let saved = app.db.get(&theme_config_key(&short)).unwrap_or_else(|| "{}".into());
-    ([(header::CONTENT_TYPE, "application/json")], saved).into_response()
+    match app.db.lookup(&theme_config_key(&short)) {
+        Ok(saved) => {
+            let saved = saved.unwrap_or_else(|| "{}".into());
+            ([(header::CONTENT_TYPE, "application/json")], saved).into_response()
+        }
+        Err(e) => fail(e),
+    }
 }
 
 /// Replaces a theme's saved settings. Values are not checked against the
diff --git a/src/db.rs b/src/db.rs
index 260fd7e7..992fc80a 100644
--- a/src/db.rs
+++ b/src/db.rs
@@ -576,11 +576,16 @@ impl Db {
     // ---- settings ----
 
     pub fn get(&self, key: &str) -> Option<String> {
-        self.conn()
+        self.lookup(key).ok().flatten()
+    }
+
+    /// As [`Db::get`], with a failed read kept apart from an absent key, for a
+    /// caller that would otherwise act on "nothing saved".
+    pub fn lookup(&self, key: &str) -> Result<Option<String>> {
+        Ok(self
+            .conn()
             .query_row("SELECT value FROM setting WHERE key = ?1", [key], |r| r.get(0))
-            .optional()
-            .ok()
-            .flatten()
+            .optional()?)
     }
 
     pub fn set(&self, key: &str, value: &str) -> Result<()> {
diff --git a/web-admin/src/components/Admin.tsx b/web-admin/src/components/Admin.tsx
index c3f3d738..b5567957 100644
--- a/web-admin/src/components/Admin.tsx
+++ b/web-admin/src/components/Admin.tsx
@@ -1317,7 +1317,7 @@ function ThemeSettings({ theme, saved, onClose }: {
   onClose: () => void
 }) {
   const form = configForm(theme.config)
-  const fields = configFields(theme.config)
+  const fields = form.filter((entry): entry is ConfigField => entry.type !== "title")
   const sections = configSections(form)
   const large = fields.length > 6
   const paged = large && sections.length > 1
@@ -1326,8 +1326,10 @@ function ThemeSettings({ theme, saved, onClose }: {
   const [saving, setSaving] = useState(false)
   const set = (key: string, value: unknown) => setValues((old) => ({ ...old, [key]: value }))
   const label = (field: ConfigField) => field.label || field.key
-  // A number box holds its text while being edited.
-  const typed = (f: ConfigField) => (f.type === "number" ? Number(values[f.key]) : values[f.key])
+  // A number box holds its text while being edited; an empty one holds no
+  // number, where Number("") would read as 0.
+  const typed = (f: ConfigField) =>
+    f.type !== "number" ? values[f.key] : values[f.key] === "" ? NaN : Number(values[f.key])
   const differs = (f: ConfigField) => typed(f) !== f.default
 
   async function save(e: React.FormEvent) {
@@ -1335,7 +1337,7 @@ function ThemeSettings({ theme, saved, onClose }: {
     // The browser checks required/min/max only on the boxes on screen; a
     // section switched away from is no longer rendered, so its numbers are
     // checked here and the offending one brought back into view.
-    const invalid = fields.find((f) => f.type === "number" && (values[f.key] === "" || !fits(f, typed(f))))
+    const invalid = fields.find((f) => f.type === "number" && !fits(f, typed(f)))
     if (invalid) {
       setCurrent(Math.max(0, sections.findIndex((section) => section.fields.includes(invalid))))
       const range =
diff --git a/web-admin/src/lib/api.test.ts b/web-admin/src/lib/api.test.ts
index 148b25b3..8f030fe7 100644
--- a/web-admin/src/lib/api.test.ts
+++ b/web-admin/src/lib/api.test.ts
@@ -123,8 +123,13 @@ const entries = [
   { key: "blank", type: "select", default: "", options: [{ value: "" }, { value: "a" }] },
   { key: "wrong", type: "boolean", default: "yes" },
   { key: "range", type: "number", default: 0, min: 1 },
+  { key: "i18n", type: "string", default: "", label: { zh: "公告", en: "Notice" } },
+  { key: "hinted", type: "boolean", default: true, help: 1 },
+  { key: "labelled", type: "select", default: "a", options: [{ value: "a", label: { zh: "甲" } }] },
   "not a field",
   { type: "title" },
+  { type: "title", label: "空" },
+  { type: "title", label: "末尾" },
 ]
 assert.deepEqual(configForm(entries).map((f) => (f.type === "title" ? `# ${f.label}` : f.key)), ["# 外观", "notice", "layout", "refresh", "dark"])
 const form = configFields(entries)
diff --git a/web-admin/src/lib/api.ts b/web-admin/src/lib/api.ts
index efb93f36..ccab4237 100644
--- a/web-admin/src/lib/api.ts
+++ b/web-admin/src/lib/api.ts
@@ -118,25 +118,33 @@ export function fits(field: ConfigField, value: unknown): boolean {
 /**
  * The entries of a theme's form the panel can draw, headings included, in the
  * manifest's order. The manifest is the theme author's, so a malformed entry is
- * left out rather than failing the form: a heading without a label, a
- * duplicate key, an unknown type, a select whose options are not all non-empty
- * strings (the dropdown cannot hold an empty value), or a default the field
- * could not hold.
+ * left out rather than failing the form: a heading without a label or without
+ * a field under it, a duplicate key, an unknown type, a label or help that is
+ * not text (rendering one would throw and blank the panel), a select whose
+ * options are not all non-empty strings (the dropdown cannot hold an empty
+ * value), or a default the field could not hold.
  */
 export function configForm(config: unknown): (ConfigField | ConfigTitle)[] {
   if (!Array.isArray(config)) return []
   const seen = new Set<string>()
-  return config.filter((field): field is ConfigField | ConfigTitle => {
+  const text = (value: unknown) => value === undefined || typeof value === "string"
+  const drawable = config.filter((field): field is ConfigField | ConfigTitle => {
     if (typeof field !== "object" || field === null) return false
     if (field.type === "title") return typeof field.label === "string" && field.label !== ""
-    const { key, type, options, min, max } = field
+    const { key, type, label, help, options, min, max } = field
     const ok = typeof key === "string" && key !== "" && !seen.has(key) && CONFIG_TYPES.includes(type)
-      && (type !== "select" || (Array.isArray(options) && options.every((o) => typeof o?.value === "string" && o.value !== "")))
+      && text(label) && text(help)
+      && (type !== "select" || (Array.isArray(options)
+        && options.every((o) => typeof o?.value === "string" && o.value !== "" && text(o.label))))
       && [min, max].every((bound) => bound === undefined || typeof bound === "number")
       && fits(field, field.default)
     if (ok) seen.add(key)
     return ok
   })
+  return drawable.filter((entry, i) => {
+    const next = drawable[i + 1]
+    return entry.type !== "title" || (next !== undefined && next.type !== "title")
+  })
 }
 
 /** The entries of the form that hold a value. */
@@ -146,8 +154,8 @@ export function configFields(config: unknown): ConfigField[] {
 
 /**
  * The form split at its headings. Fields ahead of the first heading form a
- * section of their own, and a heading with no field under it is dropped, so
- * every section listed has something to show.
+ * section of their own; `configForm` has already dropped every heading with no
+ * field under it, so every section has something to show.
  */
 export function configSections(form: (ConfigField | ConfigTitle)[]): { label: string; fields: ConfigField[] }[] {
   const sections: { label: string; fields: ConfigField[] }[] = []
@@ -158,7 +166,7 @@ export function configSections(form: (ConfigField | ConfigTitle)[]): { label: st
       sections[sections.length - 1].fields.push(entry)
     }
   }
-  return sections.filter((section) => section.fields.length)
+  return sections
 }
 
 /** The value each field shows: the saved one while the field can still hold it, else the default. */

From 2f7d9fac4b2d9afce9dd7f64a3fc3c55276b7e5c Mon Sep 17 00:00:00 2001
From: stqfdyr <89149493+stqfdyr@users.noreply.github.com>
Date: Wed, 23 Sep 2026 17:28:15 +0800
Subject: [PATCH 4/4] =?UTF-8?q?feat:=20=E4=B8=BB=E9=A2=98=E8=AE=BE?=
 =?UTF-8?q?=E7=BD=AE=E6=81=A2=E5=A4=8D=E9=BB=98=E8=AE=A4=E5=90=8E=E4=BF=9D?=
 =?UTF-8?q?=E5=AD=98=EF=BC=8C=E8=BF=9E=E5=90=8C=E8=A1=A8=E5=8D=95=E6=9C=AA?=
 =?UTF-8?q?=E5=A3=B0=E6=98=8E=E7=9A=84=20key=20=E4=B8=80=E8=B5=B7=E6=B8=85?=
 =?UTF-8?q?=E6=8E=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 web-admin/src/components/Admin.tsx | 11 +++++++++--
 web-admin/src/lib/api.test.ts      |  2 ++
 web-admin/src/lib/api.ts           |  4 ++--
 3 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/web-admin/src/components/Admin.tsx b/web-admin/src/components/Admin.tsx
index b5567957..4a7b405d 100644
--- a/web-admin/src/components/Admin.tsx
+++ b/web-admin/src/components/Admin.tsx
@@ -1323,6 +1323,10 @@ function ThemeSettings({ theme, saved, onClose }: {
   const paged = large && sections.length > 1
   const [current, setCurrent] = useState(0)
   const [values, setValues] = useState(() => configValues(fields, saved))
+  // What the save builds on. Keys the form does not declare are kept, except
+  // after 恢复默认: that also clears them, the only way from the panel to drop
+  // a value, publicly readable, left by a field the theme has since removed.
+  const [base, setBase] = useState(saved)
   const [saving, setSaving] = useState(false)
   const set = (key: string, value: unknown) => setValues((old) => ({ ...old, [key]: value }))
   const label = (field: ConfigField) => field.label || field.key
@@ -1350,7 +1354,7 @@ function ThemeSettings({ theme, saved, onClose }: {
     try {
       await api(`/themes/${theme.short}/config`, {
         method: "PUT",
-        body: JSON.stringify(configOverrides(fields, saved, Object.fromEntries(fields.map((f) => [f.key, typed(f)])))),
+        body: JSON.stringify(configOverrides(fields, base, Object.fromEntries(fields.map((f) => [f.key, typed(f)])))),
       })
       toast.success("主题设置已保存，公开页刷新后生效")
       onClose()
@@ -1457,7 +1461,10 @@ function ThemeSettings({ theme, saved, onClose }: {
               type="button"
               variant="ghost"
               className="mr-auto"
-              onClick={() => setValues(Object.fromEntries(fields.map((f) => [f.key, f.default])))}
+              onClick={() => {
+                setValues(Object.fromEntries(fields.map((f) => [f.key, f.default])))
+                setBase({})
+              }}
             >
               {paged ? "全部恢复默认" : "恢复默认"}
             </Button>
diff --git a/web-admin/src/lib/api.test.ts b/web-admin/src/lib/api.test.ts
index 8f030fe7..983c63e7 100644
--- a/web-admin/src/lib/api.test.ts
+++ b/web-admin/src/lib/api.test.ts
@@ -140,6 +140,8 @@ const initial = configValues(form, saved)
 assert.deepEqual(initial, { notice: "", layout: "grid", refresh: 10, dark: false })
 assert.equal(fits(form[2], 61), false)
 assert.deepEqual(configOverrides(form, saved, { ...initial, refresh: 5, dark: true }), { legacy: 1, dark: true })
+// 恢复默认 builds on nothing, so undeclared keys go with the overrides.
+assert.deepEqual(configOverrides(form, {}, Object.fromEntries(form.map((f) => [f.key, f.default]))), {})
 // Headings split the form; leading fields get a section, empty headings none.
 assert.deepEqual(
   configSections(configForm([{ key: "a", type: "string", default: "" }, { type: "title", label: "空" }, { type: "title", label: "外观" }, { key: "b", type: "boolean", default: true }]))
diff --git a/web-admin/src/lib/api.ts b/web-admin/src/lib/api.ts
index ccab4237..33faa0a1 100644
--- a/web-admin/src/lib/api.ts
+++ b/web-admin/src/lib/api.ts
@@ -177,8 +177,8 @@ export function configValues(fields: ConfigField[], saved: Record<string, unknow
 /**
  * What the panel stores: only the fields that differ from their defaults, so a
  * default the theme changes later reaches every site that never altered it.
- * Keys the current form does not declare are kept -- a field a newer version
- * dropped returns with a downgrade.
+ * Keys in `saved` the current form does not declare are kept -- a field a
+ * newer version dropped returns with a downgrade; an empty `saved` clears them.
  */
 export function configOverrides(
   fields: ConfigField[],