From 0315c76092369c5795e8d1a6b5ec1528c711b633 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:01:46 +0800
Subject: [PATCH 01/64] docs(spec): custom widget system + theme consolidation
 design

---
 .../2026-05-28-custom-widget-system-design.md | 476 ++++++++++++++++++
 1 file changed, 476 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-28-custom-widget-system-design.md

diff --git a/docs/superpowers/specs/2026-05-28-custom-widget-system-design.md b/docs/superpowers/specs/2026-05-28-custom-widget-system-design.md
new file mode 100644
index 00000000..36486e9b
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-28-custom-widget-system-design.md
@@ -0,0 +1,476 @@
+# Custom Widget System Design
+
+**Status:** Draft
+**Date:** 2026-05-28
+**Branch:** `minnetonka-v5`
+**Related:** SPA Themes (`docs/superpowers/specs/2026-05-26-custom-spa-themes-design.md`), existing dashboard widget system in `apps/web/src/components/dashboard/`, color theme system in `apps/web/src/themes/`.
+
+## Goal
+
+Replace the hard-coded 14-widget catalog and the three coexisting color-theme mechanisms with a single, pluggable **Widget Module** abstraction. Users — primarily admins — should be able to (a) write their own widgets as a single `.widget.js` file with a stable SDK, (b) install widgets from a URL or by uploading a file/zip, and (c) author SPA Themes that bundle CSS variables and widget collections in one package.
+
+The end state has one mental model: a Widget Module is an ESM file that calls `defineWidget({ ... })`. Built-in widgets, URL-installed widgets, and uploaded widgets are all the same shape. SPA Themes become the single delivery channel for both visual customization (CSS variables) and bundled widgets.
+
+## Non-goals
+
+- Official Marketplace / community widget registry (a curated documentation page lists examples instead).
+- Sandboxed execution (iframe / ShadowRealm). Widgets run in the main page context under a **trusted admin** model, equivalent to admin replacing the bundled SPA on disk.
+- Data migration. Project is in dev; old `dashboard_widget.widget_type` values, old `custom_theme` rows, and old localStorage keys are dropped without conversion.
+- Per-user widget installation. Widget modules are system-wide; only admins can install/uninstall.
+- Hot-reload during widget development (rely on rebuild + reinstall cycle; doc site shows a local dev workflow).
+- Backwards compatibility shims for the legacy `themes/` directory or `custom_theme` entity.
+
+---
+
+## 1. Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Source                                                       │
+│    • Builtin (rust-embed, registered on server boot)          │
+│    • URL     (admin pastes https://.../foo.widget.js)         │
+│    • Upload  (admin drops .js or .zip collection)             │
+└────────────────────────┬─────────────────────────────────────┘
+                         │ stored as BLOB in widget_module table
+                         ▼
+┌──────────────────────────────────────────────────────────────┐
+│  Backend: widget_module table + /api/widgets/* + /api/widgets │
+│  /{id}/code.js (raw ESM with cache-control + sha256 etag)     │
+└────────────────────────┬─────────────────────────────────────┘
+                         │ on SPA boot: GET /api/widgets
+                         ▼
+┌──────────────────────────────────────────────────────────────┐
+│  Browser Loader                                               │
+│    for each module:                                           │
+│      fetch(code_url)                                          │
+│      blob = new Blob([code], {type:'text/javascript'})        │
+│      mod  = await import(URL.createObjectURL(blob))           │
+│      Registry.register(mod.default)  // = WidgetModule        │
+└────────────────────────┬─────────────────────────────────────┘
+                         │
+                         ▼
+┌──────────────────────────────────────────────────────────────┐
+│  Widget Registry (singleton in SPA)                           │
+│    get(id) / list() / register(module) / unregister(id)       │
+└────────────────────────┬─────────────────────────────────────┘
+                         │ resolved at render time
+                         ▼
+┌──────────────────────────────────────────────────────────────┐
+│  Dashboard Grid (react-grid-layout, unchanged)                │
+│    instance = { id, module_id, config_json, grid_x/y/w/h }    │
+│    WidgetRenderer: Registry.get(module_id) → render via SDK   │
+└──────────────────────────────────────────────────────────────┘
+
+                              ▲
+                              │ stable hook API
+                              │
+┌──────────────────────────────────────────────────────────────┐
+│  Widget SDK (@serverbee/widget-sdk)                           │
+│    defineWidget({...})                                        │
+│    useServers() useServer(id) useMetric(id, path)             │
+│    useHistory(id, path, range) useCapability(id, cap)         │
+│    useTheme() useConfigUpdate()                               │
+│    z.* — schema for configSchema → auto ConfigDialog          │
+│                                                               │
+│  Runtime injection via import-map:                            │
+│    @serverbee/widget-sdk → /runtime/widget-sdk.js (shim)      │
+│      shim re-exports globalThis.__SERVERBEE_SDK__             │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Key replacements
+
+| Old | New |
+|---|---|
+| `apps/web/src/lib/widget-types.ts` with 14 hard-coded types | One `.widget.tsx` module file per built-in widget, registered at server boot via rust-embed |
+| `dashboard_widget.widget_type` (free string) | `dashboard_widget.module_id` (FK-like string referencing `widget_module.id`) |
+| `apps/web/src/themes/` (8 preset CSS files + `preset-vars.ts`) | **Deleted.** CSS variables are declared inside a SPA Theme manifest |
+| `custom_theme` entity + OKLCH editor + `/api/settings/themes` | **Deleted.** Authoring happens by writing `manifest.json` |
+| Three coexisting theme mechanisms (preset / custom / SPA) | One: SPA Theme |
+| Data subscriptions duplicated in every widget | All data flows through SDK hooks |
+
+---
+
+## 2. Widget SDK
+
+The SDK is the single contract between widget authors and the host. Stability of this surface is the project's primary long-term commitment to widget authors.
+
+### 2.1 `defineWidget`
+
+```ts
+// @serverbee/widget-sdk
+import { defineWidget, z, useMetric } from '@serverbee/widget-sdk'
+
+const ConfigSchema = z.object({
+  serverId: z.serverId().describe('Target server'),
+  metric: z.metricPath().default('cpu.usage'),
+  threshold: z.number().min(0).max(100).default(80),
+})
+
+export default defineWidget({
+  id: 'com.example.cpu-gauge',          // reverse-DNS, globally unique
+  name: 'CPU Gauge',
+  version: '1.0.0',
+  category: 'Real-time',                // 'Real-time' | 'Charts' | 'Status'
+  sizing: {
+    defaultW: 3, defaultH: 3,
+    minW: 2, minH: 2,
+    strategy: 'aspect-square',           // 'fixed' | 'free' | 'aspect-square' | 'content-height'
+  },
+  requiredCaps: [],                      // e.g. ['CAP_DOCKER']
+  configSchema: ConfigSchema,
+  component: ({ config }) => {
+    const value = useMetric(config.serverId, config.metric)
+    return <Gauge value={value ?? 0} max={100} warn={config.threshold} />
+  },
+})
+```
+
+`defineWidget` returns a `WidgetModule` value. The loader expects each `.widget.js` to `export default` exactly one `WidgetModule`. A `.zip` collection may contain many files, each one widget.
+
+### 2.2 Data subscription hooks
+
+| Hook | Returns | Underlying source |
+|---|---|---|
+| `useServers()` | `ServerSummary[]` (id, name, online, lastSeen) | Reuses `useServersWs` store |
+| `useServer(id)` | Full `ServerMetrics \| undefined` for one server | WS broadcast |
+| `useMetric(id, path)` | Single value extracted by dot/bracket path (`'cpu.usage'`, `'disks[0].used'`) | Derived from `useServer` |
+| `useHistory(id, path, range)` | `{ ts, value }[]` time series | TanStack Query → REST historical endpoint |
+| `useCapability(id, cap)` | `boolean` | Derived from `useServer` capability bitmask |
+| `useTheme()` | `{ mode: 'light' \| 'dark', cssVar: (name) => string }` | ThemeProvider context |
+| `useConfigUpdate()` | `(patch: Partial<TConfig>) => void` | Dispatches into dashboard editor state |
+
+All hooks accept `serverId | 'aggregate' | null`. With `null` they return `undefined`, letting components render a uniform placeholder.
+
+### 2.3 `configSchema` → auto-generated form
+
+The SDK ships a Zod-like mini-validator (`z`) with the standard primitives plus four widget-specific extensions:
+
+- `z.serverId()` — renders a server picker
+- `z.metricPath()` — renders a metric-path picker (browses the live ServerMetrics shape)
+- `z.color()` — renders a color picker
+- `z.duration()` — renders a duration input (e.g. `5m`, `1h`)
+
+`renderConfigForm(schema, value, onChange)` consumes the schema and produces the entire ConfigDialog UI. Widget authors write no form code.
+
+Rationale for not pulling full `zod`: keeps SDK runtime under ~10KB gzipped, avoids two zod versions colliding when authors also use zod in their own code.
+
+### 2.4 Component contract
+
+```ts
+type WidgetProps<TConfig> = {
+  config: TConfig                        // validated + defaulted
+  size: { w: number; h: number }         // current grid pixel size
+  isEditing: boolean                     // dashboard is in edit mode
+}
+```
+
+No additional globals. All host capabilities are exposed through SDK hooks. Widgets may freely use React 19, JSX, and any pure-frontend npm dependencies they bundle themselves.
+
+### 2.5 SDK runtime injection
+
+```html
+<!-- index.html -->
+<script type="importmap">
+{ "imports": { "@serverbee/widget-sdk": "/runtime/widget-sdk.js" } }
+</script>
+```
+
+`/runtime/widget-sdk.js` is a thin shim emitted during SPA build that re-exports `globalThis.__SERVERBEE_SDK__`. The shim's URL is versioned (`/runtime/widget-sdk-{hash}.js`) so SPA upgrades invalidate the import-map entry deterministically.
+
+Effect:
+- Widget authors `import { ... } from '@serverbee/widget-sdk'` like any npm package, with full TypeScript type-completion.
+- At runtime each loaded widget shares the host's React/SDK singletons — no duplicate React copies, no hook-rule violations.
+- Updating the SDK ships once with the main SPA; all widgets follow.
+
+### 2.6 Version compatibility
+
+Each `defineWidget` call implicitly carries the `sdkVersion` it was built against (injected by the SDK build). The Registry validates on registration:
+
+- Major mismatch → reject load, surface error in admin UI ("widget built for SDK v2, host is v3 — please update widget").
+- Minor older → load with `console.warn`.
+- Patch difference → silent.
+
+Deprecations live for at least one minor cycle before removal.
+
+---
+
+## 3. Distribution & Installation
+
+### 3.1 `widget_module` table
+
+```rust
+pub struct Model {
+    pub id: String,                  // 'com.example.cpu-gauge'
+    pub version: String,             // semver
+    pub source_type: SourceType,     // Builtin | Url | Upload
+    pub source_url: Option<String>,  // original URL for Url, original filename for Upload
+    pub manifest_json: String,       // cached metadata extracted at install time
+    pub code_sha256: String,         // content fingerprint
+    pub code_blob: Vec<u8>,          // ESM bytes; empty for Builtin (served via rust-embed)
+    pub installed_by: Option<i64>,   // user_id, null for Builtin
+    pub installed_at: DateTimeWithTimeZone,
+    pub enabled: bool,
+}
+```
+
+Decision: **widget code lives in SQLite, not on a remote CDN.** This keeps offline VPS installs functional, lets the backend serve with cache headers, prevents silent upstream tampering after install, and gives admins one place to audit.
+
+### 3.2 Loader sequence
+
+```
+1. SPA boots → GET /api/widgets
+   → returns [{ id, version, manifest, code_url, sha256 }, ...]
+2. For each module in parallel:
+     fetch(code_url)                          // cache-friendly, etag = sha256
+     blob = new Blob([text], { type: 'text/javascript' })
+     mod  = await import(URL.createObjectURL(blob))
+     Registry.register(mod.default)
+3. Failures are isolated: a broken module surfaces in the admin UI as
+   "Failed to load" without blocking other widgets or the dashboard.
+```
+
+### 3.3 Installation paths
+
+| Source | Admin UX | Backend behavior |
+|---|---|---|
+| **Builtin** | n/a — registered at server boot from rust-embed | `INSERT … ON CONFLICT(id) DO UPDATE` on every boot |
+| **URL** | Settings → Widgets → "Add by URL" → paste raw JS URL → backend fetches → preview manifest → confirm install | Server-side fetch with allowlist for `http(s)`, body size cap, MIME check; static ESM parse (via `oxc` or `swc`) to extract `defineWidget({...})` literal for manifest |
+| **Upload (.js)** | Settings → Widgets → drag file → preview manifest → confirm install | Same parse pipeline as URL, skipping fetch |
+| **Upload (.zip)** | Settings → Widgets → drag zip → preview collection (list of widgets) → confirm install | Unzip with zip-slip guard, read `collection.json`, register each listed `.widget.js` |
+
+### 3.4 Zip collection format
+
+```
+my-collection.zip
+├── collection.json
+├── widgets/
+│   ├── cpu-gauge.widget.js
+│   ├── mem-chart.widget.js
+│   └── disk-io.widget.js
+└── assets/                  # optional static assets (icons etc.)
+    └── icon.svg
+```
+
+`collection.json`:
+
+```json
+{
+  "id": "com.example.my-pack",
+  "name": "Example Widget Pack",
+  "version": "1.0.0",
+  "author": "Jane Doe",
+  "description": "CPU, memory, and disk widgets.",
+  "widgets": [
+    "widgets/cpu-gauge.widget.js",
+    "widgets/mem-chart.widget.js",
+    "widgets/disk-io.widget.js"
+  ],
+  "license": "MIT"
+}
+```
+
+Each listed file must be valid ESM exporting a single `defineWidget({ id, version, ... })`. The backend extracts the id and version statically and refuses zips with duplicate ids.
+
+### 3.5 Permissions
+
+- **Admin** — install, uninstall, enable/disable widget modules; install via URL or upload.
+- **Member** — see installed widgets in the picker, use them on dashboards. Cannot install/uninstall.
+- `requiredCaps` is enforced at render time. When the selected server lacks a capability, the widget renders a disabled placeholder card explaining which capability is missing.
+
+### 3.6 Marketplace (out of scope)
+
+No official marketplace. Documentation maintains a hand-curated "Community Widgets" page with example URLs. Future extension point: a `marketplace_url` setting whose JSON manifest the SPA can iterate over for browsing — not built now.
+
+---
+
+## 4. Theme System Consolidation
+
+### 4.1 What gets deleted
+
+| Path | Action |
+|---|---|
+| `apps/web/src/themes/` (entire directory: 8 preset `.css` files, `preset-vars.ts`, `index.ts`) | Delete |
+| `apps/web/src/api/themes.ts` | Delete |
+| `apps/web/src/components/theme/` (theme-card, theme-editor, theme-preview, oklch-picker, delete-theme-dialog) | Delete |
+| `apps/web/src/routes/_authed/settings/appearance/themes.*` (all custom-theme subroutes) | Delete |
+| `apps/web/src/lib/theme-ref.ts` (the `preset:` / `custom:` prefix parser) | Delete |
+| `crates/server/src/entity/custom_theme.rs` | Delete |
+| Custom theme CRUD in `crates/server/src/router/api/theme.rs` | Delete (leave file if it still hosts unrelated handlers; otherwise remove) |
+| sea-orm migration to `DROP TABLE custom_theme` | New migration; `down()` is a no-op per project convention |
+
+### 4.2 What stays
+
+- `apps/web/src/components/spa-theme/` (SPA Theme admin UI) — primary path going forward
+- `apps/web/src/api/spa-themes.ts`
+- `crates/server/src/entity/spa_theme.rs`
+- `ThemeProvider` — heavily simplified
+
+### 4.3 SPA Theme manifest, extended
+
+```json
+{
+  "id": "com.example.dark-night",
+  "name": "Dark Night",
+  "version": "1.2.0",
+  "author": "Jane Doe",
+  "description": "Dark monochrome with custom gauge widgets.",
+
+  "cssVars": {
+    "light": {
+      "--background": "oklch(1 0 0)",
+      "--foreground": "oklch(0.145 0 0)",
+      "--primary":    "oklch(0.205 0 0)"
+    },
+    "dark": {
+      "--background": "oklch(0.145 0 0)",
+      "--foreground": "oklch(0.985 0 0)",
+      "--primary":    "oklch(0.985 0 0)"
+    }
+  },
+
+  "widgets": [
+    "widgets/special-gauge.widget.js"
+  ],
+
+  "preview": "preview.png"
+}
+```
+
+A theme may declare **only** `cssVars` (pure recolor), **only** `widgets` (a widget pack), or both. This unifies the two contributor mental models — "I want a different look" and "I want new widgets" — into a single artifact and a single upload UX.
+
+Zip structure:
+
+```
+my-theme.zip
+├── manifest.json
+├── preview.png            (optional)
+└── widgets/               (optional, present when manifest.widgets non-empty)
+    └── special-gauge.widget.js
+```
+
+### 4.4 Simplified `ThemeProvider`
+
+```ts
+type ThemeContext = {
+  mode: 'light' | 'dark' | 'system'      // localStorage 'theme-mode'
+  setMode: (m) => void
+  activeSpaThemeId: string | null         // server-side via /api/settings/active-spa-theme
+}
+```
+
+Activation flow:
+
+1. SPA boots → `GET /api/settings/active-spa-theme` → load manifest.
+2. Inject `manifest.cssVars.light` into `<style>` keyed under `:root`.
+3. Inject `manifest.cssVars.dark` keyed under `.dark`.
+4. If no SPA theme is active, fall back to the SPA's built-in default CSS variables (in `apps/web/src/index.css`, unchanged).
+5. Light/dark switching toggles `html.dark`; variables are already in place.
+
+Complexity removed:
+
+- `theme-ref.ts` `preset:foo` / `custom:bar` dual-prefix resolver — gone, single uuid space.
+- Dynamic loading of `themes/{id}.css` files — gone, vars come from manifest.
+- OKLCH editor and `custom_theme` CRUD — gone.
+- Two-layer activation state (mode × colorTheme) — collapsed to one (active SPA theme already carries both light and dark variable sets).
+
+---
+
+## 5. Built-in Widget Rewrite
+
+All 14 built-in widgets are rewritten to the new SDK shape:
+
+`stat-number`, `metric-card`, `server-cards`, `gauge`, `line-chart`, `multi-line`, `top-n`, `alert-list`, `service-status`, `traffic-bar`, `disk-io`, `server-map`, `markdown`, `uptime-timeline`.
+
+Each becomes a `.widget.tsx` file in `apps/web/src/builtin-widgets/`, exporting `default defineWidget({...})`. At server startup, `rust-embed` includes them, and the boot routine upserts a `widget_module` row per file with `source_type = Builtin`.
+
+The rewrite serves two purposes:
+
+1. **Dogfooding the SDK** — if any of the 14 existing widgets cannot be expressed cleanly via `defineWidget` + the hook surface, the SDK API is wrong and must be extended.
+2. **Eliminating the dual code path** — once rewritten, the old `widget-types.ts` registry, `widget-renderer.tsx` type switching, and `widget-config-dialog.tsx` per-type forms are deleted.
+
+Per project convention (no data migrations during dev), the `dashboard_widget.widget_type` column is renamed to `module_id` in a schema-only migration. No conversion of existing rows is performed; developers re-create their local dashboards after the rename.
+
+---
+
+## 6. Documentation Deliverables (`apps/docs`)
+
+Bilingual (zh / en), one MDX file per language under `apps/docs/content/docs/{cn,en}/`:
+
+| Doc | Contents |
+|---|---|
+| `widgets/overview.mdx` | Widget system overview: module concept, source types, builtin vs custom, SDK conceptual diagram |
+| `widgets/single-file-guide.mdx` | **Approach B full tutorial** — write a `.widget.js` from scratch: `npm init` → install SDK → `defineWidget` → local dev/preview → install into ServerBee via URL. Linked runnable example repo |
+| `widgets/collection-guide.mdx` | **Approach C full tutorial** — zip collection structure, `collection.json` schema, sharing utils across widgets, local packing script, upload & install flow |
+| `widgets/sdk-reference.mdx` | Full SDK API reference: `defineWidget` signature, every hook signature + return type + example, every `z.*` type + extensions |
+| `widgets/configuration-schema.mdx` | `configSchema` deep dive: using `z.serverId()` / `z.metricPath()` / `z.color()` / `z.duration()` to get auto-generated forms |
+| `widgets/sizing.mdx` | Sizing strategy guide (`fixed` / `free` / `aspect-square` / `content-height`) with use-case examples |
+| `widgets/capabilities.mdx` | `requiredCaps` usage and the "capability missing on this server" rendering contract |
+| `widgets/publishing.mdx` | Sharing a widget: hosting raw JS (GitHub raw / Gist / self-hosted), versioning, getting listed on the community page |
+| `themes/spa-theme-guide.mdx` | Rewritten SPA Theme docs: complete manifest field reference, combined `cssVars` + `widgets` usage, relationship with widget collections |
+
+Side-bar navigation is restructured to introduce a top-level **Widgets** section. Existing pages referencing the deleted preset/custom-theme features are rewritten or removed.
+
+**Example repo:** a separate `serverbee-widget-examples` GitHub repository hosts three reference widgets: `hello-world.widget.js`, `metric-gauge.widget.js`, and a small `example-pack.zip` collection. The documentation links to it.
+
+---
+
+## 7. Testing Strategy
+
+| Layer | Coverage |
+|---|---|
+| SDK unit tests (vitest, `apps/web`) | `defineWidget` validation, `renderConfigForm` snapshot tests, `z` schema parsing, SDK version compatibility decisions |
+| Widget Registry unit tests | `register` / `get` / `list` / `unregister`, id collision, version conflict, enable/disable |
+| Loader unit tests | Blob URL generation, import failure isolation, import-map shim resolving to host SDK |
+| Backend unit tests (Rust) | `widget_module` CRUD, URL fetch path validation (allowlist + size cap), zip extraction safety (zip-slip), ESM static parse extracting `defineWidget({...})` metadata |
+| Backend integration tests | Full lifecycle: upload zip → list → activate → render via SPA → uninstall |
+| Built-in widget regression | One minimal render test per rewritten widget (mock SDK hooks) to guard against regressions during the rewrite |
+| E2E manual checklist | `tests/dashboard-widgets-v2.md`: URL install, zip upload, configure widget, all 14 built-ins render, theme switch does not break loaded widgets |
+
+**Not in scope:** iframe sandbox tests (trusted-admin model, no sandbox); marketplace tests (no marketplace).
+
+---
+
+## 8. Implementation Phasing
+
+Detailed in separate plan documents under `docs/superpowers/plans/`. Preview:
+
+1. **Plan 1 — SDK + Registry foundation**
+   - `@serverbee/widget-sdk` package skeleton, type definitions, `defineWidget`, `z` mini-validator
+   - Frontend Registry + Loader + import-map shim
+   - Backend `widget_module` entity + migration + boot-time builtin registration
+   - Unit-test coverage of the new surfaces
+
+2. **Plan 2 — Rewrite the 14 built-in widgets**
+   - One `.widget.tsx` per widget under `apps/web/src/builtin-widgets/`
+   - Rename `dashboard_widget.widget_type` → `module_id` (schema only, no data migration)
+   - Rewrite `WidgetRenderer` against the Registry; delete `widget-types.ts`, the old `widget-config-dialog.tsx` per-type forms
+   - One render snapshot per widget
+
+3. **Plan 3 — Custom widget install + SPA Theme manifest extension + delete legacy theme code**
+   - URL install + .js upload + .zip collection install UX
+   - Backend: URL fetch with allowlist, zip parsing with zip-slip guard, static ESM parse for manifest extraction
+   - Extend SPA Theme manifest with `cssVars` + `widgets`; update activation pipeline
+   - Simplify `ThemeProvider`
+   - Delete `apps/web/src/themes/`, `custom_theme` entity, theme editor UI, related routes/APIs
+
+4. **Plan 4 — Documentation + example repo**
+   - The 9 MDX pages above, in both `cn` and `en`
+   - First version of `serverbee-widget-examples` repo with 3 examples
+   - Docs site sidebar restructure
+
+Order: Plan 1 → Plan 2 → Plan 3. Plan 4 can proceed in parallel with Plan 3.
+
+---
+
+## 9. Risks & Mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Older browsers do not support import-maps | Require Chrome ≥ 89 / Safari ≥ 16.4 / Firefox ≥ 108. Document in install requirements. Current ServerBee user base already runs modern browsers |
+| A broken custom widget could break the dashboard | `WidgetRenderer` wraps each instance in an error boundary; loader catches `import()` failures per module and surfaces a placeholder card so other widgets keep rendering |
+| SDK API churn breaks already-installed widgets | Strict SemVer on `sdkVersion`; loader rejects major-mismatch with a clear admin message; deprecations live for at least one minor version |
+| Rewriting the 14 widgets introduces visual regressions | A render snapshot per widget is written **before** the rewrite begins; reviewer diffs snapshots after rewrite |
+| Static ESM parse cannot extract `defineWidget({...})` from minified code | Documented requirement: published widgets ship as unminified ESM with the `defineWidget` call at top-level (the bundling examples in `single-file-guide.mdx` emit this format) |
+| Remote URL install could be abused for SSRF | Allowlist `http(s)` only; reject private/loopback ranges; cap body size; record `installed_by` |
+| Zip-slip on collection upload | Use a vetted zip crate that validates entry names; reject any entry whose canonicalised path escapes the extraction root |

From 9bd0d05f286ee8d72192268b4682f7cbc13e011d Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:06:49 +0800
Subject: [PATCH 02/64] docs(spec): revise custom widget system per review (v2)

Address review feedback:
- add action/mutation model (useApiQuery, useApiMutation, actions[])
- replace Blob URL loader with server-path serving (/api/widget-modules/{id}/{*path})
- externalise react, react-dom, react/jsx-runtime in import-map
- switch manifest extraction to JSDoc literal block (no AST eval)
- add Vite multi-entry build pipeline section for builtins
- add first-class domain hooks (useAlerts, useServiceMonitors, useTraffic, useUptime, useGeoIp)
- delete full-SPA-replacement spa_theme system; reclaim Theme name
- chunk Plan 2 (2A/2B/2C) and Plan 3 (3A/3B/3C)
- add security-and-trust, troubleshooting, data-and-recipes docs
---
 .../2026-05-28-custom-widget-system-design.md | 728 ++++++++++++------
 1 file changed, 487 insertions(+), 241 deletions(-)

diff --git a/docs/superpowers/specs/2026-05-28-custom-widget-system-design.md b/docs/superpowers/specs/2026-05-28-custom-widget-system-design.md
index 36486e9b..27c5edd5 100644
--- a/docs/superpowers/specs/2026-05-28-custom-widget-system-design.md
+++ b/docs/superpowers/specs/2026-05-28-custom-widget-system-design.md
@@ -1,104 +1,136 @@
 # Custom Widget System Design
 
-**Status:** Draft
+**Status:** Draft (v2, post-review)
 **Date:** 2026-05-28
 **Branch:** `minnetonka-v5`
-**Related:** SPA Themes (`docs/superpowers/specs/2026-05-26-custom-spa-themes-design.md`), existing dashboard widget system in `apps/web/src/components/dashboard/`, color theme system in `apps/web/src/themes/`.
+**Supersedes:** `2026-05-26-custom-spa-themes-design.md` (full-SPA-replacement model is deleted in this redesign)
+**Related:** existing dashboard widgets in `apps/web/src/components/dashboard/`, color theme system in `apps/web/src/themes/`.
 
 ## Goal
 
-Replace the hard-coded 14-widget catalog and the three coexisting color-theme mechanisms with a single, pluggable **Widget Module** abstraction. Users — primarily admins — should be able to (a) write their own widgets as a single `.widget.js` file with a stable SDK, (b) install widgets from a URL or by uploading a file/zip, and (c) author SPA Themes that bundle CSS variables and widget collections in one package.
+Replace the hard-coded 14-widget catalog and the three coexisting color-theme mechanisms with a single, pluggable **Widget Module** abstraction. Admins should be able to (a) write their own widgets as a single `.widget.js` file using a stable SDK, (b) install widgets from a URL or by uploading a file/zip, and (c) author **Themes** that bundle CSS variables and widget collections in one package.
 
-The end state has one mental model: a Widget Module is an ESM file that calls `defineWidget({ ... })`. Built-in widgets, URL-installed widgets, and uploaded widgets are all the same shape. SPA Themes become the single delivery channel for both visual customization (CSS variables) and bundled widgets.
+The end state has one mental model: a Widget Module is an ESM file that calls `defineWidget({ ... })`. Built-in widgets, URL-installed widgets, and uploaded widgets are all the same shape. Themes are the single delivery channel for visual customization (CSS variables) plus bundled widgets.
 
 ## Non-goals
 
 - Official Marketplace / community widget registry (a curated documentation page lists examples instead).
-- Sandboxed execution (iframe / ShadowRealm). Widgets run in the main page context under a **trusted admin** model, equivalent to admin replacing the bundled SPA on disk.
-- Data migration. Project is in dev; old `dashboard_widget.widget_type` values, old `custom_theme` rows, and old localStorage keys are dropped without conversion.
+- Sandboxed execution (iframe / ShadowRealm). Widgets run in the main page context under a **trusted admin** model.
+- Full-SPA replacement. The existing `spa_theme` mechanism (upload `.sbtheme` zip that supplants the entire frontend through the catch-all route) is **removed** as part of this work.
+- Data migration. Project is in dev; old `dashboard_widget.widget_type` values, old `custom_theme` rows, and old `spa_theme` rows are dropped without conversion.
 - Per-user widget installation. Widget modules are system-wide; only admins can install/uninstall.
-- Hot-reload during widget development (rely on rebuild + reinstall cycle; doc site shows a local dev workflow).
-- Backwards compatibility shims for the legacy `themes/` directory or `custom_theme` entity.
+- Hot-reload during widget development (rebuild + reinstall cycle).
+- Per-widget API permission whitelisting. Widgets run with the current logged-in user's identity and can call any endpoint that identity can call. The trust model is "admin-installed widget = trusted code, equivalent to replacing the bundled SPA on disk."
 
 ---
 
 ## 1. Architecture
 
 ```
-┌──────────────────────────────────────────────────────────────┐
-│  Source                                                       │
-│    • Builtin (rust-embed, registered on server boot)          │
-│    • URL     (admin pastes https://.../foo.widget.js)         │
-│    • Upload  (admin drops .js or .zip collection)             │
-└────────────────────────┬─────────────────────────────────────┘
-                         │ stored as BLOB in widget_module table
+┌──────────────────────────────────────────────────────────────────┐
+│  Source                                                           │
+│    • Builtin (Vite multi-entry → embedded into server binary)     │
+│    • URL     (admin pastes https://.../foo.widget.js)             │
+│    • Upload  (admin drops .js single file or .zip collection)     │
+│    • Bundled in a Theme (theme install registers contained widgets)│
+└────────────────────────┬─────────────────────────────────────────┘
+                         │ stored in widget_module table (BLOB)
                          ▼
-┌──────────────────────────────────────────────────────────────┐
-│  Backend: widget_module table + /api/widgets/* + /api/widgets │
-│  /{id}/code.js (raw ESM with cache-control + sha256 etag)     │
-└────────────────────────┬─────────────────────────────────────┘
-                         │ on SPA boot: GET /api/widgets
+┌──────────────────────────────────────────────────────────────────┐
+│  Backend                                                          │
+│    /api/widget-modules            list / install / uninstall      │
+│    /api/widget-modules/{id}/...   serve module bundle + assets   │
+│    /api/themes                    list / upload / activate        │
+│    /api/themes/{id}/preview       preview image                   │
+└────────────────────────┬─────────────────────────────────────────┘
+                         │ on SPA boot: GET /api/widget-modules
                          ▼
-┌──────────────────────────────────────────────────────────────┐
-│  Browser Loader                                               │
-│    for each module:                                           │
-│      fetch(code_url)                                          │
-│      blob = new Blob([code], {type:'text/javascript'})        │
-│      mod  = await import(URL.createObjectURL(blob))           │
-│      Registry.register(mod.default)  // = WidgetModule        │
-└────────────────────────┬─────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────┐
+│  Browser Loader                                                   │
+│    for each enabled module:                                       │
+│      mod = await import('/api/widget-modules/' + id + '/' + entry)│
+│      Registry.register(mod.default)                               │
+│    Relative imports and assets inside a module resolve through    │
+│    the same /api/widget-modules/{id}/... path naturally.          │
+└────────────────────────┬─────────────────────────────────────────┘
                          │
                          ▼
-┌──────────────────────────────────────────────────────────────┐
-│  Widget Registry (singleton in SPA)                           │
-│    get(id) / list() / register(module) / unregister(id)       │
-└────────────────────────┬─────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────┐
+│  Widget Registry (singleton in SPA)                               │
+│    get(id) / list() / register(module) / unregister(id)           │
+└────────────────────────┬─────────────────────────────────────────┘
                          │ resolved at render time
                          ▼
-┌──────────────────────────────────────────────────────────────┐
-│  Dashboard Grid (react-grid-layout, unchanged)                │
-│    instance = { id, module_id, config_json, grid_x/y/w/h }    │
-│    WidgetRenderer: Registry.get(module_id) → render via SDK   │
-└──────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────┐
+│  Dashboard Grid (react-grid-layout, unchanged shell)              │
+│    instance = { id, module_id, config_json, grid_x/y/w/h }        │
+│    WidgetRenderer: Registry.get(module_id) → render via SDK       │
+└──────────────────────────────────────────────────────────────────┘
 
                               ▲
-                              │ stable hook API
+                              │ stable hook + action API
                               │
-┌──────────────────────────────────────────────────────────────┐
-│  Widget SDK (@serverbee/widget-sdk)                           │
-│    defineWidget({...})                                        │
-│    useServers() useServer(id) useMetric(id, path)             │
-│    useHistory(id, path, range) useCapability(id, cap)         │
-│    useTheme() useConfigUpdate()                               │
-│    z.* — schema for configSchema → auto ConfigDialog          │
-│                                                               │
-│  Runtime injection via import-map:                            │
-│    @serverbee/widget-sdk → /runtime/widget-sdk.js (shim)      │
-│      shim re-exports globalThis.__SERVERBEE_SDK__             │
-└──────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────┐
+│  Widget SDK (@serverbee/widget-sdk)                               │
+│    defineWidget({...})                                            │
+│                                                                   │
+│  Live metrics (WS):                                               │
+│    useServers() useServer(id) useMetric(id, path)                 │
+│    useCapability(id, cap)                                         │
+│                                                                   │
+│  Domain data (REST + cache):                                      │
+│    useHistory(id, path, range)                                    │
+│    useAlerts() useServiceMonitors()                               │
+│    useTraffic(id, range) useUptime(id, days) useGeoIp()           │
+│                                                                   │
+│  Escape hatch (any endpoint):                                     │
+│    useApiQuery(path, params)                                      │
+│    useApiMutation(method, path)                                   │
+│                                                                   │
+│  Host context:                                                    │
+│    useTheme() useConfigUpdate()                                   │
+│                                                                   │
+│  Schema mini-validator: z.*                                       │
+│                                                                   │
+│  Runtime injection via import-map:                                │
+│    react, react-dom, react/jsx-runtime, @serverbee/widget-sdk     │
+│      → /runtime/{name}.js shims re-exporting host singletons      │
+└──────────────────────────────────────────────────────────────────┘
 ```
 
 ### Key replacements
 
 | Old | New |
 |---|---|
-| `apps/web/src/lib/widget-types.ts` with 14 hard-coded types | One `.widget.tsx` module file per built-in widget, registered at server boot via rust-embed |
-| `dashboard_widget.widget_type` (free string) | `dashboard_widget.module_id` (FK-like string referencing `widget_module.id`) |
-| `apps/web/src/themes/` (8 preset CSS files + `preset-vars.ts`) | **Deleted.** CSS variables are declared inside a SPA Theme manifest |
-| `custom_theme` entity + OKLCH editor + `/api/settings/themes` | **Deleted.** Authoring happens by writing `manifest.json` |
-| Three coexisting theme mechanisms (preset / custom / SPA) | One: SPA Theme |
-| Data subscriptions duplicated in every widget | All data flows through SDK hooks |
+| `apps/web/src/lib/widget-types.ts` (14 hard-coded types) | One `.widget.tsx` per built-in widget under `apps/web/src/builtin-widgets/`, compiled via Vite multi-entry |
+| `dashboard_widget.widget_type` (free string) | `dashboard_widget.module_id` (references `widget_module.id`) |
+| `apps/web/src/themes/` (8 preset CSS + `preset-vars.ts`) | **Deleted.** CSS variables come from Theme manifest |
+| `custom_theme` entity + OKLCH editor + `/api/settings/themes` | **Deleted.** |
+| `spa_theme` full-SPA-replacement (28 files, see §6.1) | **Deleted.** Name "Theme" is reclaimed for the new cssVars + widgets concept |
+| Per-widget data subscriptions scattered everywhere | All data flows through SDK hooks |
 
 ---
 
 ## 2. Widget SDK
 
-The SDK is the single contract between widget authors and the host. Stability of this surface is the project's primary long-term commitment to widget authors.
+The SDK is the single contract between widget authors and the host. Stability of this surface is the project's primary long-term commitment to authors.
 
-### 2.1 `defineWidget`
+### 2.1 Widget file layout
+
+A widget file has two pieces: a JSDoc manifest block at the top (extracted statically by the backend at install time) and a `defineWidget` default export (executed at runtime).
 
 ```ts
-// @serverbee/widget-sdk
+/**
+ * @serverbee-widget {
+ *   "id": "com.example.cpu-gauge",
+ *   "version": "1.0.0",
+ *   "name": "CPU Gauge",
+ *   "category": "Real-time",
+ *   "sizing": { "defaultW": 3, "defaultH": 3, "minW": 2, "minH": 2, "strategy": "aspect-square" },
+ *   "requiredCaps": [],
+ *   "sdkVersion": "^1.0.0"
+ * }
+ */
 import { defineWidget, z, useMetric } from '@serverbee/widget-sdk'
 
 const ConfigSchema = z.object({
@@ -108,16 +140,6 @@ const ConfigSchema = z.object({
 })
 
 export default defineWidget({
-  id: 'com.example.cpu-gauge',          // reverse-DNS, globally unique
-  name: 'CPU Gauge',
-  version: '1.0.0',
-  category: 'Real-time',                // 'Real-time' | 'Charts' | 'Status'
-  sizing: {
-    defaultW: 3, defaultH: 3,
-    minW: 2, minH: 2,
-    strategy: 'aspect-square',           // 'fixed' | 'free' | 'aspect-square' | 'content-height'
-  },
-  requiredCaps: [],                      // e.g. ['CAP_DOCKER']
   configSchema: ConfigSchema,
   component: ({ config }) => {
     const value = useMetric(config.serverId, config.metric)
@@ -126,23 +148,77 @@ export default defineWidget({
 })
 ```
 
-`defineWidget` returns a `WidgetModule` value. The loader expects each `.widget.js` to `export default` exactly one `WidgetModule`. A `.zip` collection may contain many files, each one widget.
+The JSDoc block is **the** source of truth for everything the backend needs to know about the module before its code runs (id, version, sizing, required capabilities, SDK version). The `defineWidget` call carries the runtime-only pieces (configSchema, component, optional actions). This split is what makes installation safe and reliable — see §3.4.
 
 ### 2.2 Data subscription hooks
 
-| Hook | Returns | Underlying source |
-|---|---|---|
-| `useServers()` | `ServerSummary[]` (id, name, online, lastSeen) | Reuses `useServersWs` store |
-| `useServer(id)` | Full `ServerMetrics \| undefined` for one server | WS broadcast |
-| `useMetric(id, path)` | Single value extracted by dot/bracket path (`'cpu.usage'`, `'disks[0].used'`) | Derived from `useServer` |
-| `useHistory(id, path, range)` | `{ ts, value }[]` time series | TanStack Query → REST historical endpoint |
-| `useCapability(id, cap)` | `boolean` | Derived from `useServer` capability bitmask |
-| `useTheme()` | `{ mode: 'light' \| 'dark', cssVar: (name) => string }` | ThemeProvider context |
-| `useConfigUpdate()` | `(patch: Partial<TConfig>) => void` | Dispatches into dashboard editor state |
+**Live metric hooks** — reuse the existing `useServersWs` WebSocket store:
+
+| Hook | Returns |
+|---|---|
+| `useServers()` | `ServerSummary[]` — id, name, online, lastSeen, capabilities |
+| `useServer(id)` | Full `ServerMetrics \| undefined` for one server |
+| `useMetric(id, path)` | Single value extracted by dot/bracket path (`'cpu.usage'`, `'disks[0].used'`) |
+| `useCapability(id, cap)` | `boolean` |
+
+**Domain hooks** — first-class wrappers around concrete REST endpoints used by today's built-in widgets. Each one already has a known query key, cache strategy, and TS shape. They exist so the common cases don't need raw `useApiQuery`.
+
+| Hook | Endpoint |
+|---|---|
+| `useHistory(id, path, range)` | Time-series for a metric path |
+| `useAlerts({ limit })` | `GET /api/alert-events` |
+| `useServiceMonitors()` | `GET /api/service-monitors` |
+| `useTraffic(id, range)` | `GET /api/servers/{id}/traffic` (per-server) or `GET /api/traffic/overview/daily` (global) |
+| `useUptime(id, days)` | `GET /api/servers/{id}/uptime-daily` |
+| `useGeoIp()` | `GET /api/geoip/status` + `POST /api/geoip/download` (returns `{ status, download }` pair) |
+
+**Escape hatch** — for anything not yet promoted to a first-class hook, or for custom widgets that call new endpoints:
+
+```ts
+const { data, error, isLoading } = useApiQuery<MyType>('/api/some/endpoint', { params: {...} })
+const mutation = useApiMutation<MyResp, MyReq>('POST', '/api/some/action')
+mutation.mutate(body)
+```
+
+These wrap TanStack Query with the host's `api-client.ts` (auto-unwraps `{ data: T }`, attaches credentials, sends `X-API-Key` or session cookie). They run with **the current logged-in user's identity** — there is no per-widget permission whitelist (see Non-goals).
+
+**Host context:**
+
+| Hook | Returns |
+|---|---|
+| `useTheme()` | `{ mode: 'light' \| 'dark', cssVar: (name) => string }` |
+| `useConfigUpdate()` | `(patch: Partial<TConfig>) => void` — lets a widget mutate its own config (e.g. "save view") |
+
+### 2.3 Actions: declarative buttons
+
+Many real widgets need a button: "Download GeoIP database", "Restart service", "Acknowledge alert". The SDK provides a declarative `actions` array on `defineWidget`, which renders standard buttons with confirm-dialog, loading state, success/error toast, and emits to the audit log — without each widget reinventing it.
+
+```ts
+export default defineWidget({
+  configSchema: ConfigSchema,
+  actions: [
+    {
+      id: 'download-geoip',
+      label: 'Download database',
+      icon: 'download',
+      confirm: { title: 'Download GeoIP database?', body: 'This may take ~30s.' },
+      run: async ({ apiMutation }) => {
+        await apiMutation('POST', '/api/geoip/download')
+      },
+    },
+  ],
+  component: ({ config, actions }) => (
+    <div>
+      <GeoIpStatus />
+      {actions.render('download-geoip')}
+    </div>
+  ),
+})
+```
 
-All hooks accept `serverId | 'aggregate' | null`. With `null` they return `undefined`, letting components render a uniform placeholder.
+Actions are optional. Widgets that prefer can call `useApiMutation` directly and roll their own UI.
 
-### 2.3 `configSchema` → auto-generated form
+### 2.4 `configSchema` → auto-generated form
 
 The SDK ships a Zod-like mini-validator (`z`) with the standard primitives plus four widget-specific extensions:
 
@@ -151,47 +227,58 @@ The SDK ships a Zod-like mini-validator (`z`) with the standard primitives plus
 - `z.color()` — renders a color picker
 - `z.duration()` — renders a duration input (e.g. `5m`, `1h`)
 
-`renderConfigForm(schema, value, onChange)` consumes the schema and produces the entire ConfigDialog UI. Widget authors write no form code.
+`renderConfigForm(schema, value, onChange)` consumes the schema and produces the entire ConfigDialog UI. Widget authors write no form code for typical configs.
 
-Rationale for not pulling full `zod`: keeps SDK runtime under ~10KB gzipped, avoids two zod versions colliding when authors also use zod in their own code.
+Rationale for not pulling full `zod`: keeps the SDK runtime under ~10KB gzipped, avoids two zod versions colliding when authors also use zod elsewhere.
 
-### 2.4 Component contract
+### 2.5 Component contract
 
 ```ts
 type WidgetProps<TConfig> = {
   config: TConfig                        // validated + defaulted
   size: { w: number; h: number }         // current grid pixel size
   isEditing: boolean                     // dashboard is in edit mode
+  actions: {
+    render: (id: string) => ReactNode    // mount a declared action button
+  }
 }
 ```
 
-No additional globals. All host capabilities are exposed through SDK hooks. Widgets may freely use React 19, JSX, and any pure-frontend npm dependencies they bundle themselves.
+No additional globals. All host capabilities are exposed through SDK hooks and the `actions` injector.
 
-### 2.5 SDK runtime injection
+### 2.6 Runtime injection — React/SDK singletons
 
 ```html
 <!-- index.html -->
 <script type="importmap">
-{ "imports": { "@serverbee/widget-sdk": "/runtime/widget-sdk.js" } }
+{
+  "imports": {
+    "@serverbee/widget-sdk": "/runtime/widget-sdk-{hash}.js",
+    "react":                  "/runtime/react-{hash}.js",
+    "react-dom":              "/runtime/react-dom-{hash}.js",
+    "react/jsx-runtime":      "/runtime/react-jsx-runtime-{hash}.js"
+  }
+}
 </script>
 ```
 
-`/runtime/widget-sdk.js` is a thin shim emitted during SPA build that re-exports `globalThis.__SERVERBEE_SDK__`. The shim's URL is versioned (`/runtime/widget-sdk-{hash}.js`) so SPA upgrades invalidate the import-map entry deterministically.
+Each `/runtime/*.js` is a thin shim re-exporting the host's instance from `globalThis`. The hash is the SPA build's content hash, so an SPA upgrade invalidates them deterministically.
 
-Effect:
-- Widget authors `import { ... } from '@serverbee/widget-sdk'` like any npm package, with full TypeScript type-completion.
-- At runtime each loaded widget shares the host's React/SDK singletons — no duplicate React copies, no hook-rule violations.
-- Updating the SDK ships once with the main SPA; all widgets follow.
+This is required because:
 
-### 2.6 Version compatibility
+- JSX compilation emits `import { jsx } from 'react/jsx-runtime'` — without externalising, every widget bundles its own React copy, hooks collapse.
+- Authors will write `import { useMemo } from 'react'` — same failure mode.
+- Two SDK copies would mean two `WidgetRegistry` singletons — registration races.
 
-Each `defineWidget` call implicitly carries the `sdkVersion` it was built against (injected by the SDK build). The Registry validates on registration:
+The SDK package's `peerDependencies` declares `react`, `react-dom`. Widget bundler templates (Vite, Rollup) in the docs ship pre-configured with these externals plus `@serverbee/widget-sdk`. CI in the example repo verifies the produced bundle declares no React copy.
 
-- Major mismatch → reject load, surface error in admin UI ("widget built for SDK v2, host is v3 — please update widget").
-- Minor older → load with `console.warn`.
-- Patch difference → silent.
+### 2.7 Version compatibility
 
-Deprecations live for at least one minor cycle before removal.
+The JSDoc manifest's `sdkVersion` field is a semver range. The Registry validates on registration:
+
+- Major mismatch (host outside range) → reject load, surface error in admin UI ("widget needs SDK ^2.x, host is 3.x").
+- Allowed range, but newer minor available → load silently.
+- Deprecated hooks emit a `console.warn` for at least one minor cycle before removal.
 
 ---
 
@@ -201,45 +288,80 @@ Deprecations live for at least one minor cycle before removal.
 
 ```rust
 pub struct Model {
-    pub id: String,                  // 'com.example.cpu-gauge'
-    pub version: String,             // semver
-    pub source_type: SourceType,     // Builtin | Url | Upload
-    pub source_url: Option<String>,  // original URL for Url, original filename for Upload
-    pub manifest_json: String,       // cached metadata extracted at install time
-    pub code_sha256: String,         // content fingerprint
-    pub code_blob: Vec<u8>,          // ESM bytes; empty for Builtin (served via rust-embed)
-    pub installed_by: Option<i64>,   // user_id, null for Builtin
+    pub id: String,                       // 'com.example.cpu-gauge'
+    pub version: String,                  // semver
+    pub source_type: SourceType,          // Builtin | Url | Upload | BundledByTheme
+    pub source_url: Option<String>,       // original URL for Url; filename for Upload
+    pub bundled_by_theme_id: Option<String>, // when source_type = BundledByTheme; deletes cascade
+    pub manifest_json: String,            // JSDoc-extracted metadata (id, version, sizing, ...)
+    pub code_sha256: String,              // entry file fingerprint
+    pub entry_path: String,               // e.g. "index.js" for single-file; "widgets/cpu.js" for collection
+    pub package_blob: Option<Vec<u8>>,    // packed archive (single-file or zip); empty for Builtin
+    pub installed_by: Option<i64>,        // user_id, null for Builtin
     pub installed_at: DateTimeWithTimeZone,
     pub enabled: bool,
 }
 ```
 
-Decision: **widget code lives in SQLite, not on a remote CDN.** This keeps offline VPS installs functional, lets the backend serve with cache headers, prevents silent upstream tampering after install, and gives admins one place to audit.
+Decision: widget code lives in SQLite, not on a remote CDN — keeps offline VPS installs functional, lets the backend cache-control responses, prevents silent upstream tampering after install, and gives admins one place to audit.
 
-### 3.2 Loader sequence
+### 3.2 Asset serving
 
 ```
-1. SPA boots → GET /api/widgets
-   → returns [{ id, version, manifest, code_url, sha256 }, ...]
-2. For each module in parallel:
-     fetch(code_url)                          // cache-friendly, etag = sha256
-     blob = new Blob([text], { type: 'text/javascript' })
-     mod  = await import(URL.createObjectURL(blob))
-     Registry.register(mod.default)
-3. Failures are isolated: a broken module surfaces in the admin UI as
-   "Failed to load" without blocking other widgets or the dashboard.
+GET /api/widget-modules
+  → [{ id, version, manifest, entry_path, code_sha256 }, ...]
+
+GET /api/widget-modules/{id}/{*asset_path}
+  → serves any file inside the module's package
+  → cache: ETag = "{version}-{sha256_prefix}", Cache-Control: public, max-age=86400, immutable
+  → content-type by extension (js → text/javascript, svg/png/css/json/...)
+  → 404 on path-traversal attempts
 ```
 
-### 3.3 Installation paths
+For a Builtin module, "package" is the Vite-emitted directory under `dist/builtin-widgets/{id}/`. For Upload (single file), package is a one-file archive. For Upload (zip) or BundledByTheme, package is the original zip. The server unpacks to a temp directory at startup for fast serving, or streams from the BLOB with a small in-process LRU cache.
+
+### 3.3 Loader sequence
+
+```js
+// in SPA boot
+const modules = await fetch('/api/widget-modules').then(r => r.json())
+await Promise.allSettled(modules.map(async m => {
+  try {
+    const url = `/api/widget-modules/${m.id}/${m.entry_path}`
+    const mod = await import(/* @vite-ignore */ url)
+    Registry.register(m.id, mod.default, m.manifest)
+  } catch (err) {
+    Registry.recordLoadFailure(m.id, err)   // shown in admin UI; other widgets keep loading
+  }
+}))
+```
+
+Native `import(url)` — no Blob URL. This is what lets relative imports inside a module (`import './utils.js'`, `<img src="./icon.svg" />`) resolve naturally through the same `/api/widget-modules/{id}/...` path.
+
+### 3.4 Three install paths
 
 | Source | Admin UX | Backend behavior |
 |---|---|---|
-| **Builtin** | n/a — registered at server boot from rust-embed | `INSERT … ON CONFLICT(id) DO UPDATE` on every boot |
-| **URL** | Settings → Widgets → "Add by URL" → paste raw JS URL → backend fetches → preview manifest → confirm install | Server-side fetch with allowlist for `http(s)`, body size cap, MIME check; static ESM parse (via `oxc` or `swc`) to extract `defineWidget({...})` literal for manifest |
-| **Upload (.js)** | Settings → Widgets → drag file → preview manifest → confirm install | Same parse pipeline as URL, skipping fetch |
-| **Upload (.zip)** | Settings → Widgets → drag zip → preview collection (list of widgets) → confirm install | Unzip with zip-slip guard, read `collection.json`, register each listed `.widget.js` |
+| **Builtin** | n/a — registered at server boot | At boot, read `dist/builtin-widgets/manifest.json`, upsert one `widget_module` per entry with `source_type = Builtin` |
+| **URL** | Settings → Widgets → "Add by URL" → paste raw JS URL → preview JSDoc manifest → confirm | Server-side fetch (http(s) only, reject private/loopback ranges, 1 MB body cap) → extract JSDoc → validate → store |
+| **Upload (.js)** | Drop single `.js` → preview → confirm | Read JSDoc → validate → store as one-file package (`entry_path = "index.js"`) |
+| **Upload (.zip)** | Drop `.zip` → preview `collection.json` → confirm | Unzip with zip-slip guard, read `collection.json`, extract JSDoc from each listed entry, register one `widget_module` per entry |
+
+### 3.5 JSDoc manifest extraction
 
-### 3.4 Zip collection format
+Backend extraction is a single, deterministic step:
+
+1. Locate the first JSDoc block matching `/\*\*[\s\S]*?@serverbee-widget\s+(\{[\s\S]*?\})[\s\S]*?\*/`.
+2. Strip leading `* ` line decorations.
+3. Parse the captured `{...}` with `serde_json`.
+4. Validate against the `WidgetManifest` Rust struct (required: `id`, `version`, `name`, `category`, `sizing`, `sdkVersion`).
+5. Reject if missing, malformed, or if `id` collides with an existing module that has a different `source_type`.
+
+This is robust because the manifest is a pure JSON literal in a comment — no AST traversal, no variable resolution, no spread / computed values to worry about. The runtime `defineWidget({...})` call may use any variables, helper functions, dynamic imports, etc.
+
+A second-layer validation runs **at SPA load time**: the Registry checks that the executed `defineWidget` returned a `WidgetModule` whose internal fields (configSchema, component) are well-formed, and that any optional `actions[]` parse correctly. Failures here surface as "broken widget" cards without blocking the dashboard.
+
+### 3.6 Zip collection format
 
 ```
 my-collection.zip
@@ -248,7 +370,7 @@ my-collection.zip
 │   ├── cpu-gauge.widget.js
 │   ├── mem-chart.widget.js
 │   └── disk-io.widget.js
-└── assets/                  # optional static assets (icons etc.)
+└── assets/                  # optional shared static assets
     └── icon.svg
 ```
 
@@ -270,43 +392,178 @@ my-collection.zip
 }
 ```
 
-Each listed file must be valid ESM exporting a single `defineWidget({ id, version, ... })`. The backend extracts the id and version statically and refuses zips with duplicate ids.
+Each listed file must have a `@serverbee-widget` JSDoc block. The zip extraction step refuses collections with duplicate widget ids and any zip entry whose canonicalised path escapes the extraction root (zip-slip).
 
-### 3.5 Permissions
+### 3.7 Permissions & trust
 
-- **Admin** — install, uninstall, enable/disable widget modules; install via URL or upload.
-- **Member** — see installed widgets in the picker, use them on dashboards. Cannot install/uninstall.
-- `requiredCaps` is enforced at render time. When the selected server lacks a capability, the widget renders a disabled placeholder card explaining which capability is missing.
+- **Admin** — install / uninstall / enable / disable widget modules; install via URL or upload.
+- **Member** — see installed widgets in the picker; use them on dashboards. Cannot install.
+- `requiredCaps` is enforced at render time. When the selected server lacks a capability, the widget renders a disabled placeholder explaining which capability is missing.
+- Widgets run with the **current logged-in user's** session/API-key identity, in the same JavaScript context as the host SPA. They can call any same-origin API that identity can call, read DOM, read storage. The trust model: admin-installed widget code is treated as trusted, comparable to installing a browser extension on a colleague's machine — there is no per-widget allowlist and no sandbox. Members using a dashboard cannot install widgets, but they execute whatever widgets admins have installed.
 
-### 3.6 Marketplace (out of scope)
+### 3.8 Marketplace (out of scope)
 
-No official marketplace. Documentation maintains a hand-curated "Community Widgets" page with example URLs. Future extension point: a `marketplace_url` setting whose JSON manifest the SPA can iterate over for browsing — not built now.
+No official marketplace. Documentation maintains a hand-curated "Community Widgets" section inside `publishing.mdx` listing example URLs. Future extension point: a `marketplace_url` setting whose JSON manifest the SPA could iterate over — not built now.
 
 ---
 
-## 4. Theme System Consolidation
+## 4. Built-in Widget Build Pipeline
+
+The 14 built-in widgets need to compile to ESM modules that the host can serve and the loader can `import()`.
+
+### 4.1 Source layout
 
-### 4.1 What gets deleted
+```
+apps/web/src/builtin-widgets/
+├── cpu-gauge.widget.tsx
+├── line-chart.widget.tsx
+├── ...                          (one file per builtin)
+└── _shared/                     (internal helpers, not widgets)
+    └── format.ts
+```
+
+Each `*.widget.tsx` file has the JSDoc manifest block + `export default defineWidget({...})` — same shape as a user-written widget. They are not special.
+
+### 4.2 Vite multi-entry
+
+Extend `apps/web/vite.config.ts`:
+
+```ts
+import { globSync } from 'tinyglobby'
+
+const builtinWidgets = Object.fromEntries(
+  globSync('src/builtin-widgets/*.widget.tsx').map(p => {
+    const id = path.basename(p, '.widget.tsx')                       // 'cpu-gauge'
+    return [`builtin-widgets/${id}/index`, p]
+  })
+)
+
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      input: { main: 'index.html', ...builtinWidgets },
+      external: ['react', 'react-dom', 'react/jsx-runtime', '@serverbee/widget-sdk'],
+      output: {
+        entryFileNames: assetInfo =>
+          assetInfo.name?.startsWith('builtin-widgets/')
+            ? `${assetInfo.name}.js`
+            : 'assets/[name]-[hash].js',
+      },
+    },
+  },
+})
+```
+
+Output:
+
+```
+apps/web/dist/
+├── (main SPA assets, unchanged)
+└── builtin-widgets/
+    ├── manifest.json          # generated by a vite plugin (id → entry_path map)
+    ├── cpu-gauge/
+    │   └── index.js
+    ├── line-chart/
+    │   └── index.js
+    └── ...
+```
+
+A small Vite plugin reads each `*.widget.tsx`'s JSDoc block at build time and writes `dist/builtin-widgets/manifest.json`:
+
+```json
+[
+  { "id": "com.serverbee.cpu-gauge",  "version": "1.0.0", "entry_path": "cpu-gauge/index.js",  "manifest": { ... full JSDoc ... } },
+  { "id": "com.serverbee.line-chart", "version": "1.0.0", "entry_path": "line-chart/index.js", "manifest": { ... } }
+]
+```
+
+### 4.3 Server boot registration
+
+`crates/server/src/router/static_files.rs` already embeds `apps/web/dist` via `rust-embed`. At server boot, a new `builtin_widgets::register_all(&db)` routine:
+
+1. Reads embedded `builtin-widgets/manifest.json`.
+2. For each entry, computes `code_sha256` of the entry file's bytes.
+3. Upserts `widget_module` row with `source_type = Builtin`, `package_blob = None` (served directly from the embedded FS).
+4. Removes any stale Builtin rows whose `id` is not in the new manifest.
+
+The asset-serving route (§3.2) special-cases `source_type = Builtin` to serve from `rust_embed` instead of the BLOB.
+
+---
+
+## 5. Built-in Widget Rewrite
+
+All 14 widgets are rewritten to the new shape:
+
+`stat-number`, `metric-card`, `server-cards`, `gauge`, `line-chart`, `multi-line`, `top-n`, `alert-list`, `service-status`, `traffic-bar`, `disk-io`, `server-map`, `markdown`, `uptime-timeline`.
+
+Rewrite serves two purposes:
+
+1. **Dogfooding** — if any of the 14 cannot be expressed cleanly via `defineWidget` + SDK hooks + `actions`, the SDK is wrong and must be extended **before** continuing.
+2. **Eliminating dual code paths** — once rewritten, `widget-types.ts`, the old `WidgetRenderer` switch statement, and per-type `widget-config-dialog.tsx` branches are deleted.
+
+The rewrite is chunked to surface SDK gaps early:
+
+- **Chunk A — Live-metric-only widgets** (smallest, prove the live hook surface): `stat-number`, `metric-card`, `gauge`, `server-cards`.
+- **Chunk B — Historical chart widgets** (prove `useHistory` and time-series shape): `line-chart`, `multi-line`, `top-n`, `disk-io`.
+- **Chunk C — Domain-data widgets** (prove first-class domain hooks and `actions`): `alert-list`, `service-status`, `traffic-bar`, `server-map`, `markdown`, `uptime-timeline`.
+
+After Chunk C lands, the old `WidgetRenderer` + `widget-types.ts` + per-type config dialog code is deleted in a single cleanup commit.
+
+Per project convention, `dashboard_widget.widget_type` is renamed to `module_id` in a schema-only migration; no data conversion (dev period).
+
+---
+
+## 6. Theme System
+
+The name "Theme" is reclaimed for the new concept: **a package of CSS variable overrides + optional bundled widget modules.** It is an overlay on the host SPA, not a replacement of it.
+
+### 6.1 What gets deleted
+
+The existing "SPA Theme" (full-SPA-replacement) feature is removed in its entirety:
 
 | Path | Action |
 |---|---|
-| `apps/web/src/themes/` (entire directory: 8 preset `.css` files, `preset-vars.ts`, `index.ts`) | Delete |
-| `apps/web/src/api/themes.ts` | Delete |
-| `apps/web/src/components/theme/` (theme-card, theme-editor, theme-preview, oklch-picker, delete-theme-dialog) | Delete |
-| `apps/web/src/routes/_authed/settings/appearance/themes.*` (all custom-theme subroutes) | Delete |
-| `apps/web/src/lib/theme-ref.ts` (the `preset:` / `custom:` prefix parser) | Delete |
-| `crates/server/src/entity/custom_theme.rs` | Delete |
-| Custom theme CRUD in `crates/server/src/router/api/theme.rs` | Delete (leave file if it still hosts unrelated handlers; otherwise remove) |
-| sea-orm migration to `DROP TABLE custom_theme` | New migration; `down()` is a no-op per project convention |
+| `crates/server/src/service/spa_theme/` (whole module: `mod.rs`, `service.rs`, `manifest.rs`, `loaded.rs`, `extractor.rs`, `error.rs`) | Delete |
+| `crates/server/src/entity/spa_theme.rs` | Delete |
+| `crates/server/src/router/api/spa_theme.rs` | Delete |
+| `crates/server/src/migration/m20260526_000035_create_spa_themes.rs` | Keep file (history), add new migration that drops `spa_themes` table |
+| `crates/server/src/state.rs` — `active_spa_theme: ArcSwap<...>` field | Remove |
+| `crates/server/src/router/static_files.rs` — all references to `active_spa_theme` and `LoadedTheme` (catch-all theme dispatch, lines around 14/99/200/203) | Remove; catch-all serves only the rust-embed default SPA |
+| `crates/server/src/openapi.rs` — SPA theme route registrations | Remove |
+| `apps/web/src/api/spa-themes.ts` | Delete |
+| `apps/web/src/components/spa-theme/` (whole directory, incl. activate/preview/card/upload/details components and their tests) | Delete |
+| `apps/web/src/routes/_authed/settings/appearance.tsx` and `.test.tsx` — SPA theme sections | Rewrite to new Theme management |
+| `apps/web/src/lib/i18n.ts` — SPA theme strings | Replace with new Theme strings |
+| `apps/web/src/themes/` (8 preset CSS files + `preset-vars.ts` + `index.ts`) | Delete |
+| `apps/web/src/lib/theme-ref.ts` (`preset:` / `custom:` prefix parser) | Delete |
+| `crates/server/src/entity/custom_theme.rs` + custom-theme CRUD in `crates/server/src/router/api/theme.rs` + `apps/web/src/components/theme/*` (theme-card, theme-editor, theme-preview, oklch-picker, delete-theme-dialog) + `apps/web/src/routes/_authed/settings/appearance/themes.*` | Delete |
+| sea-orm migration | One new migration: `DROP TABLE spa_themes; DROP TABLE custom_theme;` (`down` no-op per project convention) |
+
+Spec `2026-05-26-custom-spa-themes-design.md` is marked **Superseded** in its header by this document.
+
+### 6.2 New `theme` table
 
-### 4.2 What stays
+```rust
+pub struct Model {
+    pub id: String,                       // 'com.example.dark-night'
+    pub version: String,
+    pub name: String,
+    pub description: Option<String>,
+    pub author: Option<String>,
+    pub manifest_json: String,
+    pub css_vars_light_json: String,      // { "--background": "oklch(...)", ... }
+    pub css_vars_dark_json: String,
+    pub preview_blob: Option<Vec<u8>>,
+    pub package_sha256: String,
+    pub package_blob: Vec<u8>,            // full zip; widgets are also unpacked into widget_module
+    pub installed_by: Option<i64>,
+    pub installed_at: DateTimeWithTimeZone,
+}
+```
 
-- `apps/web/src/components/spa-theme/` (SPA Theme admin UI) — primary path going forward
-- `apps/web/src/api/spa-themes.ts`
-- `crates/server/src/entity/spa_theme.rs`
-- `ThemeProvider` — heavily simplified
+A separate `active_theme` settings row (single row) records which theme is currently active.
 
-### 4.3 SPA Theme manifest, extended
+### 6.3 Theme manifest
 
 ```json
 {
@@ -317,27 +574,17 @@ No official marketplace. Documentation maintains a hand-curated "Community Widge
   "description": "Dark monochrome with custom gauge widgets.",
 
   "cssVars": {
-    "light": {
-      "--background": "oklch(1 0 0)",
-      "--foreground": "oklch(0.145 0 0)",
-      "--primary":    "oklch(0.205 0 0)"
-    },
-    "dark": {
-      "--background": "oklch(0.145 0 0)",
-      "--foreground": "oklch(0.985 0 0)",
-      "--primary":    "oklch(0.985 0 0)"
-    }
+    "light": { "--background": "oklch(1 0 0)", "--foreground": "oklch(0.145 0 0)", "...": "..." },
+    "dark":  { "--background": "oklch(0.145 0 0)", "...": "..." }
   },
 
-  "widgets": [
-    "widgets/special-gauge.widget.js"
-  ],
+  "widgets": [ "widgets/special-gauge.widget.js" ],   // optional
 
   "preview": "preview.png"
 }
 ```
 
-A theme may declare **only** `cssVars` (pure recolor), **only** `widgets` (a widget pack), or both. This unifies the two contributor mental models — "I want a different look" and "I want new widgets" — into a single artifact and a single upload UX.
+A theme may declare **only** `cssVars` (pure recolor), **only** `widgets` (a widget pack), or both. Single concept, single upload UX.
 
 Zip structure:
 
@@ -349,128 +596,127 @@ my-theme.zip
     └── special-gauge.widget.js
 ```
 
-### 4.4 Simplified `ThemeProvider`
+On theme install:
+1. Validate manifest (required fields, valid CSS var keys, valid widget paths).
+2. For each `widgets[]` entry: extract its JSDoc block, register a `widget_module` row with `source_type = BundledByTheme` and `bundled_by_theme_id = theme.id`.
+3. Store the theme row.
+
+On theme uninstall:
+1. Cascade-delete `widget_module` rows where `bundled_by_theme_id = theme.id`.
+2. Delete the theme row.
+3. Dashboards referencing now-deleted widget instances render a "Widget removed" placeholder until edited.
+
+### 6.4 Simplified `ThemeProvider`
 
 ```ts
 type ThemeContext = {
   mode: 'light' | 'dark' | 'system'      // localStorage 'theme-mode'
   setMode: (m) => void
-  activeSpaThemeId: string | null         // server-side via /api/settings/active-spa-theme
+  activeThemeId: string | null            // server-side via /api/settings/active-theme
 }
 ```
 
 Activation flow:
 
-1. SPA boots → `GET /api/settings/active-spa-theme` → load manifest.
-2. Inject `manifest.cssVars.light` into `<style>` keyed under `:root`.
-3. Inject `manifest.cssVars.dark` keyed under `.dark`.
-4. If no SPA theme is active, fall back to the SPA's built-in default CSS variables (in `apps/web/src/index.css`, unchanged).
+1. SPA boots → `GET /api/settings/active-theme` → load manifest.
+2. Inject `cssVars.light` into a `<style>` keyed under `:root`.
+3. Inject `cssVars.dark` keyed under `.dark`.
+4. If no theme is active, fall back to host SPA's built-in default CSS variables (in `apps/web/src/index.css`, unchanged).
 5. Light/dark switching toggles `html.dark`; variables are already in place.
 
-Complexity removed:
-
-- `theme-ref.ts` `preset:foo` / `custom:bar` dual-prefix resolver — gone, single uuid space.
-- Dynamic loading of `themes/{id}.css` files — gone, vars come from manifest.
-- OKLCH editor and `custom_theme` CRUD — gone.
-- Two-layer activation state (mode × colorTheme) — collapsed to one (active SPA theme already carries both light and dark variable sets).
-
----
-
-## 5. Built-in Widget Rewrite
-
-All 14 built-in widgets are rewritten to the new SDK shape:
-
-`stat-number`, `metric-card`, `server-cards`, `gauge`, `line-chart`, `multi-line`, `top-n`, `alert-list`, `service-status`, `traffic-bar`, `disk-io`, `server-map`, `markdown`, `uptime-timeline`.
-
-Each becomes a `.widget.tsx` file in `apps/web/src/builtin-widgets/`, exporting `default defineWidget({...})`. At server startup, `rust-embed` includes them, and the boot routine upserts a `widget_module` row per file with `source_type = Builtin`.
-
-The rewrite serves two purposes:
-
-1. **Dogfooding the SDK** — if any of the 14 existing widgets cannot be expressed cleanly via `defineWidget` + the hook surface, the SDK API is wrong and must be extended.
-2. **Eliminating the dual code path** — once rewritten, the old `widget-types.ts` registry, `widget-renderer.tsx` type switching, and `widget-config-dialog.tsx` per-type forms are deleted.
-
-Per project convention (no data migrations during dev), the `dashboard_widget.widget_type` column is renamed to `module_id` in a schema-only migration. No conversion of existing rows is performed; developers re-create their local dashboards after the rename.
+Removed complexity:
+- `theme-ref.ts` dual-prefix resolver — gone.
+- Dynamic loading of preset `.css` files — gone.
+- OKLCH editor + custom_theme CRUD — gone.
+- Full-SPA-replacement catch-all and `ArcSwap<Option<LoadedTheme>>` in state — gone.
+- Two-layer activation state — collapsed to one.
 
 ---
 
-## 6. Documentation Deliverables (`apps/docs`)
+## 7. Documentation Deliverables
 
-Bilingual (zh / en), one MDX file per language under `apps/docs/content/docs/{cn,en}/`:
+Bilingual (zh / en) MDX under `apps/docs/content/docs/{cn,en}/`:
 
 | Doc | Contents |
 |---|---|
-| `widgets/overview.mdx` | Widget system overview: module concept, source types, builtin vs custom, SDK conceptual diagram |
-| `widgets/single-file-guide.mdx` | **Approach B full tutorial** — write a `.widget.js` from scratch: `npm init` → install SDK → `defineWidget` → local dev/preview → install into ServerBee via URL. Linked runnable example repo |
-| `widgets/collection-guide.mdx` | **Approach C full tutorial** — zip collection structure, `collection.json` schema, sharing utils across widgets, local packing script, upload & install flow |
-| `widgets/sdk-reference.mdx` | Full SDK API reference: `defineWidget` signature, every hook signature + return type + example, every `z.*` type + extensions |
-| `widgets/configuration-schema.mdx` | `configSchema` deep dive: using `z.serverId()` / `z.metricPath()` / `z.color()` / `z.duration()` to get auto-generated forms |
+| `widgets/overview.mdx` | Widget system overview, source types, builtin vs custom, SDK conceptual diagram |
+| `widgets/single-file-guide.mdx` | **Approach B full tutorial** — write a `.widget.js` from scratch, JSDoc manifest, `defineWidget`, local dev/preview, URL install. Linked runnable example repo |
+| `widgets/collection-guide.mdx` | **Approach C full tutorial** — zip collection structure, `collection.json`, sharing utils across widgets, local packing script, upload & install |
+| `widgets/sdk-reference.mdx` | Full SDK API reference — `defineWidget`, every hook (live/domain/escape-hatch/host), every `z.*` type, `actions[]` |
+| `widgets/configuration-schema.mdx` | `configSchema` deep dive with `z.serverId()` / `z.metricPath()` / `z.color()` / `z.duration()` |
+| `widgets/data-and-recipes.mdx` | Cookbook: common metric paths, building a chart from `useHistory`, joining live + historical, paginating via `useApiQuery` |
 | `widgets/sizing.mdx` | Sizing strategy guide (`fixed` / `free` / `aspect-square` / `content-height`) with use-case examples |
 | `widgets/capabilities.mdx` | `requiredCaps` usage and the "capability missing on this server" rendering contract |
-| `widgets/publishing.mdx` | Sharing a widget: hosting raw JS (GitHub raw / Gist / self-hosted), versioning, getting listed on the community page |
-| `themes/spa-theme-guide.mdx` | Rewritten SPA Theme docs: complete manifest field reference, combined `cssVars` + `widgets` usage, relationship with widget collections |
+| `widgets/security-and-trust.mdx` | **Trust model**: admin-installed = trusted; widgets run as the logged-in user; threats and what is *not* sandboxed; review checklist before installing community widgets |
+| `widgets/troubleshooting.mdx` | "Widget failed to load" causes, JSDoc manifest errors, version-mismatch errors, React-singleton symptoms (duplicate React, broken hooks), how to read the admin error panel |
+| `widgets/publishing.mdx` | Hosting raw JS (GitHub raw / Gist / self-hosted), versioning, **community widgets section** (curated example list) |
+| `themes/theme-guide.mdx` | New Theme guide — manifest fields, combined `cssVars` + `widgets`, install/activate/remove flow |
 
-Side-bar navigation is restructured to introduce a top-level **Widgets** section. Existing pages referencing the deleted preset/custom-theme features are rewritten or removed.
+11 widget pages + 1 theme page × 2 languages = **24 MDX files**. Sidebar gets a new top-level **Widgets** section.
 
-**Example repo:** a separate `serverbee-widget-examples` GitHub repository hosts three reference widgets: `hello-world.widget.js`, `metric-gauge.widget.js`, and a small `example-pack.zip` collection. The documentation links to it.
+**Example repo:** separate `serverbee-widget-examples` GitHub repo with three starting examples — `hello-world.widget.js`, `metric-gauge.widget.js`, a small `example-pack.zip` — plus a pre-configured Vite template producing externalised React + SDK bundles. Docs link to it.
 
 ---
 
-## 7. Testing Strategy
+## 8. Testing Strategy
 
 | Layer | Coverage |
 |---|---|
-| SDK unit tests (vitest, `apps/web`) | `defineWidget` validation, `renderConfigForm` snapshot tests, `z` schema parsing, SDK version compatibility decisions |
-| Widget Registry unit tests | `register` / `get` / `list` / `unregister`, id collision, version conflict, enable/disable |
-| Loader unit tests | Blob URL generation, import failure isolation, import-map shim resolving to host SDK |
-| Backend unit tests (Rust) | `widget_module` CRUD, URL fetch path validation (allowlist + size cap), zip extraction safety (zip-slip), ESM static parse extracting `defineWidget({...})` metadata |
-| Backend integration tests | Full lifecycle: upload zip → list → activate → render via SPA → uninstall |
-| Built-in widget regression | One minimal render test per rewritten widget (mock SDK hooks) to guard against regressions during the rewrite |
-| E2E manual checklist | `tests/dashboard-widgets-v2.md`: URL install, zip upload, configure widget, all 14 built-ins render, theme switch does not break loaded widgets |
+| SDK unit tests (vitest, `apps/web`) | `defineWidget` validation, `z` schema parsing, `renderConfigForm` snapshots, version compatibility decisions, action runner |
+| Widget Registry unit tests | `register` / `get` / `list` / `unregister`, id collision, version conflict, load-failure recording |
+| Loader unit tests | Native `import(url)` happy path, isolation of one module's failure, import-map shim resolving to host React/SDK singletons |
+| Backend unit tests (Rust) | `widget_module` CRUD, URL fetch (allowlist + size cap + reject private/loopback), zip-slip guard, JSDoc-block regex + JSON parse + manifest validation, theme install with bundled widgets, theme uninstall cascade |
+| Backend integration tests | Full lifecycle per source type: URL install / single-file upload / zip upload / theme upload → list → render via SPA → uninstall. Asset-serve route 404s on path traversal |
+| Built-in widget regression | One render snapshot per rewritten widget, written **before** rewrite begins. Reviewer diffs snapshots after each chunk |
+| E2E manual checklist | `tests/dashboard-widgets-v2.md`: URL install, zip upload, theme upload, configure widget, all 14 built-ins render, theme switch does not break loaded widgets, action button triggers mutation |
 
-**Not in scope:** iframe sandbox tests (trusted-admin model, no sandbox); marketplace tests (no marketplace).
+**Not in scope:** sandbox tests (trusted-admin model); marketplace tests (no marketplace); per-widget permission tests (no allowlist).
 
 ---
 
-## 8. Implementation Phasing
+## 9. Implementation Phasing
 
-Detailed in separate plan documents under `docs/superpowers/plans/`. Preview:
+Plans live under `docs/superpowers/plans/`. Preview:
 
-1. **Plan 1 — SDK + Registry foundation**
-   - `@serverbee/widget-sdk` package skeleton, type definitions, `defineWidget`, `z` mini-validator
-   - Frontend Registry + Loader + import-map shim
-   - Backend `widget_module` entity + migration + boot-time builtin registration
-   - Unit-test coverage of the new surfaces
+1. **Plan 1 — SDK + Registry + asset serving**
+   - `@serverbee/widget-sdk` package skeleton, types, `defineWidget`, `z` mini-validator, all hooks (live + domain + escape hatch + host), `actions` runner
+   - Frontend Registry + Loader + import-map shim for React/SDK
+   - Backend `widget_module` entity + migration + `/api/widget-modules` (list + asset serve)
+   - JSDoc extractor + manifest validator (Rust)
+   - Unit-test coverage
 
-2. **Plan 2 — Rewrite the 14 built-in widgets**
-   - One `.widget.tsx` per widget under `apps/web/src/builtin-widgets/`
-   - Rename `dashboard_widget.widget_type` → `module_id` (schema only, no data migration)
-   - Rewrite `WidgetRenderer` against the Registry; delete `widget-types.ts`, the old `widget-config-dialog.tsx` per-type forms
-   - One render snapshot per widget
+2. **Plan 2 — Built-in widget build pipeline + rewrite**
+   - **2A** Vite multi-entry config + builtin manifest plugin + Rust boot registration + render-snapshot harness
+   - **2B** Rewrite Chunk A (live-only): `stat-number`, `metric-card`, `gauge`, `server-cards`
+   - **2C** Rewrite Chunks B + C (historical + domain): the other 10 widgets, then delete old `widget-types.ts`, old `WidgetRenderer`, old per-type config dialogs in a cleanup commit
+   - Rename `dashboard_widget.widget_type` → `module_id` (schema-only migration)
 
-3. **Plan 3 — Custom widget install + SPA Theme manifest extension + delete legacy theme code**
-   - URL install + .js upload + .zip collection install UX
-   - Backend: URL fetch with allowlist, zip parsing with zip-slip guard, static ESM parse for manifest extraction
-   - Extend SPA Theme manifest with `cssVars` + `widgets`; update activation pipeline
-   - Simplify `ThemeProvider`
-   - Delete `apps/web/src/themes/`, `custom_theme` entity, theme editor UI, related routes/APIs
+3. **Plan 3 — Install UX, Theme system, legacy deletion**
+   - **3A** Widget install UX: URL install + .js upload + .zip collection install (frontend + backend)
+   - **3B** Theme system: new `theme` entity + install/uninstall (cascade) + activate API + simplified ThemeProvider + new appearance settings page
+   - **3C** Delete legacy: SPA full-SPA-replacement code (28 files listed in §6.1) + `apps/web/src/themes/` + `custom_theme` entity & UI + drop `spa_themes` and `custom_theme` tables
 
-4. **Plan 4 — Documentation + example repo**
-   - The 9 MDX pages above, in both `cn` and `en`
-   - First version of `serverbee-widget-examples` repo with 3 examples
-   - Docs site sidebar restructure
+4. **Plan 4 — Docs + example repo** (drafts may proceed in parallel with Plan 3; finalised only after SDK API freezes at end of Plan 1)
+   - 12 MDX pages × 2 languages
+   - `serverbee-widget-examples` repo seeded with 3 examples and Vite template
+   - Docs sidebar restructure
 
-Order: Plan 1 → Plan 2 → Plan 3. Plan 4 can proceed in parallel with Plan 3.
+Order: Plan 1 → 2A → 2B → 2C → 3A → 3B → 3C. Plan 4 drafting parallel with Plan 3, final pass after.
 
 ---
 
-## 9. Risks & Mitigations
+## 10. Risks & Mitigations
 
 | Risk | Mitigation |
 |---|---|
-| Older browsers do not support import-maps | Require Chrome ≥ 89 / Safari ≥ 16.4 / Firefox ≥ 108. Document in install requirements. Current ServerBee user base already runs modern browsers |
-| A broken custom widget could break the dashboard | `WidgetRenderer` wraps each instance in an error boundary; loader catches `import()` failures per module and surfaces a placeholder card so other widgets keep rendering |
-| SDK API churn breaks already-installed widgets | Strict SemVer on `sdkVersion`; loader rejects major-mismatch with a clear admin message; deprecations live for at least one minor version |
-| Rewriting the 14 widgets introduces visual regressions | A render snapshot per widget is written **before** the rewrite begins; reviewer diffs snapshots after rewrite |
-| Static ESM parse cannot extract `defineWidget({...})` from minified code | Documented requirement: published widgets ship as unminified ESM with the `defineWidget` call at top-level (the bundling examples in `single-file-guide.mdx` emit this format) |
-| Remote URL install could be abused for SSRF | Allowlist `http(s)` only; reject private/loopback ranges; cap body size; record `installed_by` |
-| Zip-slip on collection upload | Use a vetted zip crate that validates entry names; reject any entry whose canonicalised path escapes the extraction root |
+| Older browsers do not support import-maps | Require Chrome ≥ 89 / Safari ≥ 16.4 / Firefox ≥ 108. Document in install requirements |
+| Broken custom widget breaks dashboard | `WidgetRenderer` per-instance error boundary; loader catches `import()` failures per module and records to Registry as `loadFailure`; admin UI shows a "broken" list |
+| Duplicate React copy (singleton breakage) | Import-map externalises `react`, `react-dom`, `react/jsx-runtime`; SDK `peerDependencies` declares them; bundler templates in docs ship pre-configured with externals; example repo CI verifies bundles have no React |
+| JSDoc extraction brittleness | Single regex + `serde_json` is deterministic. Documented requirement: `@serverbee-widget` block must be at top of file, in a JSDoc comment, with valid JSON. `docs/single-file-guide.mdx` provides copy-pasteable templates |
+| SDK API churn breaks installed widgets | Strict SemVer on SDK; widget manifest declares `sdkVersion` range; loader rejects out-of-range with clear admin message; deprecations live ≥ 1 minor cycle |
+| Rewriting 14 widgets introduces visual regressions | Render snapshots written before each chunk; reviewer diffs snapshots after the chunk |
+| Bundle minification strips JSDoc | Documented requirement: published widget bundles must not minify-away top-of-file JSDoc comments. Vite template in example repo sets `terserOptions.format.comments = /@serverbee-widget/` |
+| URL install SSRF | Allowlist `http(s)` only; reject private/loopback/link-local ranges; cap body size; record `installed_by`; admin-only |
+| Zip-slip on collection or theme upload | Use a zip crate that validates entry names; reject any entry whose canonicalised path escapes extraction root |
+| Trust model misunderstanding by admins | `security-and-trust.mdx` doc; install confirmation dialog shows "This widget will run with your full account permissions" before any URL install |
+| Plan 2 SDK gaps surface mid-chunk | Each chunk is its own commit; if Chunk B reveals a missing hook, pause, extend SDK in Plan 1's package, then resume. Chunk ordering (live → historical → domain) front-loads the riskiest discovery |

From 5c4aca157ca465e3191a97e23c62c38a8533db07 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:07:14 +0800
Subject: [PATCH 03/64] =?UTF-8?q?docs(plan):=20plan=201=20=E2=80=94=20widg?=
 =?UTF-8?q?et=20SDK=20+=20Registry=20+=20asset=20serving?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...6-05-28-custom-widget-system-plan-1-sdk.md | 2993 +++++++++++++++++
 1 file changed, 2993 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-28-custom-widget-system-plan-1-sdk.md

diff --git a/docs/superpowers/plans/2026-05-28-custom-widget-system-plan-1-sdk.md b/docs/superpowers/plans/2026-05-28-custom-widget-system-plan-1-sdk.md
new file mode 100644
index 00000000..749dec7f
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-28-custom-widget-system-plan-1-sdk.md
@@ -0,0 +1,2993 @@
+# Custom Widget System — Plan 1: SDK + Registry + Asset Serving
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Land the foundation for the custom widget system: a stable `@serverbee/widget-sdk` package, a frontend Widget Registry + Loader, runtime shims that share the host's React/SDK singletons, and a backend `widget_module` table + endpoints that can list and serve any module's bundle and assets. No install UX, no builtin migration — those come in Plans 2/3.
+
+**Architecture:** SDK is a workspace package consumed via TypeScript source (`packages/widget-sdk/src/index.ts`). Frontend Registry is a Zustand-style singleton; Loader uses native `import(url)` against `/api/widget-modules/{id}/{*path}`. Backend stores module packages as BLOB in SQLite, serves them with ETag-based caching, and statically extracts the `@serverbee-widget` JSDoc manifest at install time. Import-map shims re-export host singletons so loaded modules cannot ship duplicate React/SDK copies.
+
+**Tech Stack:** Rust (Axum 0.8, sea-orm 1, utoipa 5, serde_json, regex, rust-embed, zip-rs) · TypeScript 5.9 (React 19, Vite 7, TanStack Query 5, Zustand 5, vitest 4) · bun 1.3 workspaces
+
+**Spec:** `docs/superpowers/specs/2026-05-28-custom-widget-system-design.md`
+
+---
+
+## File Structure
+
+### New files
+
+```
+packages/widget-sdk/
+├── package.json
+├── tsconfig.json
+├── README.md
+├── src/
+│   ├── index.ts                        # re-exports public surface
+│   ├── define-widget.ts                # defineWidget() + WidgetModule types
+│   ├── manifest.ts                     # WidgetManifest, SizingStrategy types
+│   ├── runtime-context.ts              # host context injection (createWidgetRuntime)
+│   ├── z/
+│   │   ├── index.ts                    # z.* exports
+│   │   ├── primitives.ts               # string/number/boolean/enum/array/object
+│   │   ├── extensions.ts               # serverId/metricPath/color/duration
+│   │   └── validate.ts                 # parse/safeParse
+│   ├── hooks/
+│   │   ├── index.ts
+│   │   ├── live.ts                     # useServers, useServer, useMetric, useCapability
+│   │   ├── domain.ts                   # useHistory, useAlerts, useServiceMonitors, useTraffic, useUptime, useGeoIp
+│   │   ├── escape-hatch.ts             # useApiQuery, useApiMutation
+│   │   └── host.ts                     # useTheme, useConfigUpdate
+│   ├── actions/
+│   │   ├── index.ts                    # ActionDefinition type, ActionsHelper, render()
+│   │   └── action-button.tsx           # default button + confirm dialog
+│   ├── form/
+│   │   ├── index.ts                    # renderConfigForm()
+│   │   └── field-renderers.tsx        # one renderer per z.* type
+│   └── version.ts                      # SDK_VERSION constant (build-injected later)
+└── tests/
+    ├── define-widget.test.ts
+    ├── z.test.ts
+    └── manifest.test.ts
+
+apps/web/src/widgets-runtime/
+├── registry.ts                         # WidgetRegistry singleton (Zustand store)
+├── registry.test.ts
+├── loader.ts                           # bootstrapLoader() — fetches list and imports each
+├── loader.test.ts
+├── runtime-bridge.ts                   # mounts SDK to globalThis.__SERVERBEE_SDK__
+└── shim-template.ts                    # template strings for the 4 shim files
+
+apps/web/public/runtime/                # served by Vite static
+├── widget-sdk.js                       # re-exports globalThis.__SERVERBEE_SDK__
+├── react.js                            # re-exports globalThis.__SERVERBEE_REACT__
+├── react-dom.js                        # re-exports globalThis.__SERVERBEE_REACT_DOM__
+└── react-jsx-runtime.js                # re-exports globalThis.__SERVERBEE_JSX_RUNTIME__
+
+crates/server/src/entity/widget_module.rs           # sea-orm entity
+crates/server/src/migration/m20260528_000050_create_widget_module.rs
+crates/server/src/service/widget_module/
+├── mod.rs                              # re-exports
+├── extractor.rs                        # JSDoc → WidgetManifest
+├── service.rs                          # WidgetModuleService: list/get/serve_asset
+├── package.rs                          # package layout: single-file vs zip
+└── error.rs                            # WidgetModuleError → AppError
+crates/server/src/router/api/widget_module.rs       # /api/widget-modules routes
+
+crates/server/tests/widget_module_integration.rs
+```
+
+### Modified files
+
+```
+package.json                            # (workspace catalog: no change needed; bun picks up packages/*)
+apps/web/package.json                   # add "@serverbee/widget-sdk": "workspace:*"
+apps/web/tsconfig.json                  # add path alias for @serverbee/widget-sdk in dev
+apps/web/vite.config.ts                 # add resolve.alias for @serverbee/widget-sdk
+apps/web/index.html                     # inject <script type="importmap">
+apps/web/src/main.tsx                   # call mountSdkBridge() + bootstrapLoader() before render
+crates/server/src/entity/mod.rs         # pub mod widget_module;
+crates/server/src/migration/mod.rs      # register new migration
+crates/server/src/service/mod.rs        # pub mod widget_module;
+crates/server/src/router/api/mod.rs     # mount widget_module router
+crates/server/src/openapi.rs            # register widget_module schemas + routes
+```
+
+---
+
+## Conventions & Reusables
+
+- API responses go through `crate::error::ApiResponse<T>` and `crate::error::ok(...)`.
+- Admin-only mutating routes register under `write_router()` (already wraps `require_admin`).
+- Migrations: implement `up()` only; `down()` returns `Ok(())` (project convention, CLAUDE.md).
+- Frontend tests use Vitest + jsdom; setup in `apps/web/src/test/setup.ts`.
+- Rust tests use the helper at `crates/server/tests/integration.rs::start_test_server()` (do not duplicate it — re-import it).
+
+---
+
+## Task 1: Create `@serverbee/widget-sdk` package skeleton
+
+**Files:**
+- Create: `packages/widget-sdk/package.json`
+- Create: `packages/widget-sdk/tsconfig.json`
+- Create: `packages/widget-sdk/src/index.ts`
+- Create: `packages/widget-sdk/README.md`
+
+- [ ] **Step 1: Write package.json**
+
+```json
+{
+  "name": "@serverbee/widget-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": { "default": "./src/index.ts" },
+    "./z": { "default": "./src/z/index.ts" },
+    "./hooks": { "default": "./src/hooks/index.ts" },
+    "./actions": { "default": "./src/actions/index.ts" }
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.90.21",
+    "@types/react": "^19.2.5",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.0",
+    "jsdom": "^28.1.0",
+    "@testing-library/react": "^16.3.2"
+  }
+}
+```
+
+- [ ] **Step 2: Write tsconfig.json**
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"]
+  },
+  "include": ["src/**/*", "tests/**/*"]
+}
+```
+
+- [ ] **Step 3: Write minimal index.ts and README**
+
+`packages/widget-sdk/src/index.ts`:
+
+```ts
+export const SDK_VERSION = '0.1.0'
+```
+
+`packages/widget-sdk/README.md`:
+
+```markdown
+# @serverbee/widget-sdk
+
+Stable API surface for ServerBee custom widgets. Authors `import { defineWidget, z, useMetric } from '@serverbee/widget-sdk'`. See the developer guide at apps/docs/content/docs/{en,cn}/widgets/single-file-guide.mdx.
+```
+
+- [ ] **Step 4: Wire workspace, verify install**
+
+In `apps/web/package.json`, add to `dependencies`:
+
+```json
+"@serverbee/widget-sdk": "workspace:*"
+```
+
+Run from repo root: `bun install`
+Expected: success, `apps/web/node_modules/@serverbee/widget-sdk` exists as a symlink to `packages/widget-sdk`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/widget-sdk apps/web/package.json bun.lock
+git -c commit.gpgsign=false commit -m "feat(widget-sdk): scaffold workspace package"
+```
+
+---
+
+## Task 2: Add Vite + tsconfig alias so apps/web imports resolve to source
+
+**Files:**
+- Modify: `apps/web/vite.config.ts`
+- Modify: `apps/web/tsconfig.json`
+
+- [ ] **Step 1: Add alias to vite.config.ts**
+
+In `apps/web/vite.config.ts`, inside `resolve.alias`, add:
+
+```ts
+'@serverbee/widget-sdk': path.resolve(__dirname, '../../packages/widget-sdk/src/index.ts'),
+'@serverbee/widget-sdk/z': path.resolve(__dirname, '../../packages/widget-sdk/src/z/index.ts'),
+'@serverbee/widget-sdk/hooks': path.resolve(__dirname, '../../packages/widget-sdk/src/hooks/index.ts'),
+'@serverbee/widget-sdk/actions': path.resolve(__dirname, '../../packages/widget-sdk/src/actions/index.ts'),
+```
+
+- [ ] **Step 2: Add path mapping to tsconfig.json**
+
+In `apps/web/tsconfig.json`, under `compilerOptions.paths`, add:
+
+```json
+"@serverbee/widget-sdk":         ["../../packages/widget-sdk/src/index.ts"],
+"@serverbee/widget-sdk/z":       ["../../packages/widget-sdk/src/z/index.ts"],
+"@serverbee/widget-sdk/hooks":   ["../../packages/widget-sdk/src/hooks/index.ts"],
+"@serverbee/widget-sdk/actions": ["../../packages/widget-sdk/src/actions/index.ts"]
+```
+
+- [ ] **Step 3: Verify typecheck and build still pass**
+
+Run: `cd apps/web && bun run typecheck`
+Expected: no errors.
+
+Run: `cd apps/web && bun run build`
+Expected: builds successfully (no widget code yet, so nothing imports SDK).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add apps/web/vite.config.ts apps/web/tsconfig.json
+git -c commit.gpgsign=false commit -m "build(web): alias @serverbee/widget-sdk to source"
+```
+
+---
+
+## Task 3: Define manifest & sizing types
+
+**Files:**
+- Create: `packages/widget-sdk/src/manifest.ts`
+- Create: `packages/widget-sdk/tests/manifest.test.ts`
+- Modify: `packages/widget-sdk/src/index.ts`
+
+- [ ] **Step 1: Write failing test for manifest types**
+
+`packages/widget-sdk/tests/manifest.test.ts`:
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { validateManifest } from '../src/manifest'
+
+describe('validateManifest', () => {
+  const base = {
+    id: 'com.example.foo',
+    version: '1.0.0',
+    name: 'Foo',
+    category: 'Real-time' as const,
+    sizing: { defaultW: 3, defaultH: 3, minW: 2, minH: 2, strategy: 'aspect-square' as const },
+    sdkVersion: '^0.1.0',
+  }
+
+  it('accepts a minimal valid manifest', () => {
+    expect(validateManifest(base)).toEqual(base)
+  })
+
+  it('rejects missing id', () => {
+    expect(() => validateManifest({ ...base, id: '' })).toThrow(/id/)
+  })
+
+  it('rejects unknown sizing strategy', () => {
+    expect(() =>
+      validateManifest({ ...base, sizing: { ...base.sizing, strategy: 'bogus' as any } })
+    ).toThrow(/strategy/)
+  })
+
+  it('rejects invalid semver', () => {
+    expect(() => validateManifest({ ...base, version: 'not-semver' })).toThrow(/version/)
+  })
+})
+```
+
+- [ ] **Step 2: Run test, verify failure**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/manifest.test.ts`
+Expected: FAIL (module not found).
+
+- [ ] **Step 3: Implement manifest.ts**
+
+`packages/widget-sdk/src/manifest.ts`:
+
+```ts
+export type WidgetCategory = 'Real-time' | 'Charts' | 'Status'
+
+export type SizingStrategy = 'fixed' | 'free' | 'aspect-square' | 'content-height'
+
+export interface WidgetSizing {
+  defaultW: number
+  defaultH: number
+  minW: number
+  minH: number
+  maxW?: number
+  maxH?: number
+  strategy: SizingStrategy
+}
+
+export interface WidgetManifest {
+  id: string
+  version: string
+  name: string
+  description?: string
+  author?: string
+  category: WidgetCategory
+  sizing: WidgetSizing
+  requiredCaps?: string[]
+  sdkVersion: string
+}
+
+const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.]+)?$/
+const SEMVER_RANGE_RE = /^[\^~]?\d+\.\d+\.\d+/
+const VALID_CATEGORIES = new Set<WidgetCategory>(['Real-time', 'Charts', 'Status'])
+const VALID_STRATEGIES = new Set<SizingStrategy>([
+  'fixed', 'free', 'aspect-square', 'content-height',
+])
+
+export function validateManifest(input: unknown): WidgetManifest {
+  if (!input || typeof input !== 'object') throw new Error('manifest must be an object')
+  const m = input as Record<string, any>
+
+  if (typeof m.id !== 'string' || m.id.length === 0) throw new Error('manifest.id required')
+  if (typeof m.version !== 'string' || !SEMVER_RE.test(m.version))
+    throw new Error('manifest.version must be valid semver')
+  if (typeof m.name !== 'string' || m.name.length === 0) throw new Error('manifest.name required')
+  if (!VALID_CATEGORIES.has(m.category))
+    throw new Error('manifest.category invalid')
+  if (!m.sizing || typeof m.sizing !== 'object') throw new Error('manifest.sizing required')
+
+  const sz = m.sizing as Record<string, any>
+  for (const k of ['defaultW', 'defaultH', 'minW', 'minH'] as const) {
+    if (typeof sz[k] !== 'number') throw new Error(`manifest.sizing.${k} must be number`)
+  }
+  if (!VALID_STRATEGIES.has(sz.strategy)) throw new Error('manifest.sizing.strategy invalid')
+
+  if (typeof m.sdkVersion !== 'string' || !SEMVER_RANGE_RE.test(m.sdkVersion))
+    throw new Error('manifest.sdkVersion must be valid semver range')
+
+  if (m.requiredCaps !== undefined && !Array.isArray(m.requiredCaps))
+    throw new Error('manifest.requiredCaps must be array')
+
+  return m as WidgetManifest
+}
+```
+
+- [ ] **Step 4: Run test, verify pass**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/manifest.test.ts`
+Expected: PASS (4 tests).
+
+- [ ] **Step 5: Re-export and commit**
+
+In `packages/widget-sdk/src/index.ts`:
+
+```ts
+export const SDK_VERSION = '0.1.0'
+export type { WidgetManifest, WidgetCategory, WidgetSizing, SizingStrategy } from './manifest'
+export { validateManifest } from './manifest'
+```
+
+```bash
+git add packages/widget-sdk
+git -c commit.gpgsign=false commit -m "feat(widget-sdk): WidgetManifest types + validator"
+```
+
+---
+
+## Task 4: `defineWidget` + `WidgetModule` types
+
+**Files:**
+- Create: `packages/widget-sdk/src/define-widget.ts`
+- Create: `packages/widget-sdk/tests/define-widget.test.ts`
+- Modify: `packages/widget-sdk/src/index.ts`
+
+- [ ] **Step 1: Write failing test**
+
+`packages/widget-sdk/tests/define-widget.test.ts`:
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { defineWidget } from '../src/define-widget'
+
+describe('defineWidget', () => {
+  it('wraps the user input into a WidgetModule shape', () => {
+    const mod = defineWidget({
+      configSchema: { _kind: 'object', shape: {} } as any,
+      component: () => null,
+    })
+    expect(mod.__brand).toBe('WidgetModule')
+    expect(typeof mod.component).toBe('function')
+    expect(mod.actions).toEqual([])
+  })
+
+  it('preserves user-supplied actions array', () => {
+    const mod = defineWidget({
+      configSchema: { _kind: 'object', shape: {} } as any,
+      component: () => null,
+      actions: [{ id: 'a', label: 'A', run: async () => {} }],
+    })
+    expect(mod.actions).toHaveLength(1)
+    expect(mod.actions[0].id).toBe('a')
+  })
+
+  it('throws when component is missing', () => {
+    expect(() => defineWidget({ configSchema: {} as any } as any)).toThrow(/component/)
+  })
+})
+```
+
+- [ ] **Step 2: Run test, verify failure**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/define-widget.test.ts`
+Expected: FAIL (module not found).
+
+- [ ] **Step 3: Implement define-widget.ts**
+
+```ts
+import type { ComponentType, ReactNode } from 'react'
+import type { ZodTypeAny, Infer } from './z'
+
+export interface ActionContext {
+  apiMutation: <Req = unknown, Res = unknown>(method: string, path: string, body?: Req) => Promise<Res>
+}
+
+export interface ActionDefinition {
+  id: string
+  label: string
+  icon?: string
+  confirm?: { title: string; body?: string }
+  run: (ctx: ActionContext) => Promise<void>
+}
+
+export interface ActionsHelper {
+  render: (id: string) => ReactNode
+}
+
+export interface WidgetComponentProps<TConfig> {
+  config: TConfig
+  size: { w: number; h: number }
+  isEditing: boolean
+  actions: ActionsHelper
+}
+
+export interface DefineWidgetInput<TSchema extends ZodTypeAny> {
+  configSchema: TSchema
+  component: ComponentType<WidgetComponentProps<Infer<TSchema>>>
+  actions?: ActionDefinition[]
+}
+
+export interface WidgetModule<TConfig = unknown> {
+  __brand: 'WidgetModule'
+  configSchema: ZodTypeAny
+  component: ComponentType<WidgetComponentProps<TConfig>>
+  actions: ActionDefinition[]
+}
+
+export function defineWidget<TSchema extends ZodTypeAny>(
+  input: DefineWidgetInput<TSchema>,
+): WidgetModule<Infer<TSchema>> {
+  if (!input || typeof input.component !== 'function') {
+    throw new Error('defineWidget: component is required')
+  }
+  return {
+    __brand: 'WidgetModule',
+    configSchema: input.configSchema,
+    component: input.component as any,
+    actions: input.actions ?? [],
+  }
+}
+```
+
+This file imports `ZodTypeAny` and `Infer` from `./z` — those will be created in Task 5. Add temporary stubs to compile:
+
+`packages/widget-sdk/src/z/index.ts` (stub, replaced in Task 5):
+
+```ts
+export type ZodTypeAny = { _kind: string }
+export type Infer<T extends ZodTypeAny> = any
+```
+
+- [ ] **Step 4: Run test, verify pass**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/define-widget.test.ts`
+Expected: PASS (3 tests).
+
+- [ ] **Step 5: Re-export and commit**
+
+In `packages/widget-sdk/src/index.ts`, add:
+
+```ts
+export { defineWidget } from './define-widget'
+export type {
+  WidgetModule, WidgetComponentProps,
+  ActionDefinition, ActionContext, ActionsHelper,
+} from './define-widget'
+```
+
+```bash
+git add packages/widget-sdk
+git -c commit.gpgsign=false commit -m "feat(widget-sdk): defineWidget + WidgetModule types"
+```
+
+---
+
+## Task 5: `z` mini-validator — primitives
+
+**Files:**
+- Create: `packages/widget-sdk/src/z/primitives.ts`
+- Create: `packages/widget-sdk/src/z/validate.ts`
+- Modify: `packages/widget-sdk/src/z/index.ts`
+- Create: `packages/widget-sdk/tests/z.test.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+`packages/widget-sdk/tests/z.test.ts`:
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { z } from '../src/z'
+
+describe('z primitives', () => {
+  it('z.string() parses strings', () => {
+    expect(z.string().parse('hi')).toBe('hi')
+    expect(() => z.string().parse(1)).toThrow(/string/)
+  })
+
+  it('z.number() with min/max', () => {
+    const s = z.number().min(0).max(10)
+    expect(s.parse(5)).toBe(5)
+    expect(() => s.parse(-1)).toThrow(/min/)
+    expect(() => s.parse(11)).toThrow(/max/)
+  })
+
+  it('z.boolean()', () => {
+    expect(z.boolean().parse(true)).toBe(true)
+    expect(() => z.boolean().parse('true')).toThrow()
+  })
+
+  it('z.enum()', () => {
+    const s = z.enum(['a', 'b', 'c'] as const)
+    expect(s.parse('a')).toBe('a')
+    expect(() => s.parse('d')).toThrow(/enum/)
+  })
+
+  it('z.array(inner)', () => {
+    const s = z.array(z.number())
+    expect(s.parse([1, 2])).toEqual([1, 2])
+    expect(() => s.parse([1, 'x'])).toThrow()
+  })
+
+  it('z.object({ a, b }) applies defaults and rejects missing', () => {
+    const s = z.object({
+      a: z.string().default('hello'),
+      b: z.number(),
+    })
+    expect(s.parse({ b: 1 })).toEqual({ a: 'hello', b: 1 })
+    expect(() => s.parse({ a: 'x' })).toThrow(/b/)
+  })
+
+  it('.optional() allows undefined', () => {
+    const s = z.string().optional()
+    expect(s.parse(undefined)).toBeUndefined()
+  })
+
+  it('.describe() attaches label without affecting parse', () => {
+    const s = z.string().describe('Server name')
+    expect((s as any)._label).toBe('Server name')
+    expect(s.parse('x')).toBe('x')
+  })
+})
+```
+
+- [ ] **Step 2: Run, verify failure**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/z.test.ts`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement primitives + validate**
+
+`packages/widget-sdk/src/z/validate.ts`:
+
+```ts
+export class ZError extends Error {
+  constructor(public path: string[], message: string) {
+    super(`${path.length ? path.join('.') + ': ' : ''}${message}`)
+  }
+}
+```
+
+`packages/widget-sdk/src/z/primitives.ts`:
+
+```ts
+import { ZError } from './validate'
+
+export type Infer<T> = T extends ZodSchema<infer U> ? U : never
+export type ZodTypeAny = ZodSchema<any>
+
+export abstract class ZodSchema<T> {
+  abstract _kind: string
+  _label?: string
+  _default?: T
+  _optional = false
+
+  abstract _parse(input: unknown, path: string[]): T
+
+  parse(input: unknown): T {
+    if (input === undefined) {
+      if (this._default !== undefined) return this._default
+      if (this._optional) return undefined as T
+    }
+    return this._parse(input, [])
+  }
+
+  describe(label: string): this {
+    this._label = label
+    return this
+  }
+
+  default(value: T): this {
+    this._default = value
+    return this
+  }
+
+  optional(): this {
+    this._optional = true
+    return this
+  }
+}
+
+class ZString extends ZodSchema<string> {
+  _kind = 'string'
+  _parse(input: unknown, path: string[]): string {
+    if (typeof input !== 'string') throw new ZError(path, 'expected string')
+    return input
+  }
+}
+
+class ZNumber extends ZodSchema<number> {
+  _kind = 'number'
+  private _min?: number
+  private _max?: number
+
+  min(v: number): this { this._min = v; return this }
+  max(v: number): this { this._max = v; return this }
+
+  _parse(input: unknown, path: string[]): number {
+    if (typeof input !== 'number' || Number.isNaN(input))
+      throw new ZError(path, 'expected number')
+    if (this._min !== undefined && input < this._min)
+      throw new ZError(path, `min ${this._min}`)
+    if (this._max !== undefined && input > this._max)
+      throw new ZError(path, `max ${this._max}`)
+    return input
+  }
+}
+
+class ZBoolean extends ZodSchema<boolean> {
+  _kind = 'boolean'
+  _parse(input: unknown, path: string[]): boolean {
+    if (typeof input !== 'boolean') throw new ZError(path, 'expected boolean')
+    return input
+  }
+}
+
+class ZEnum<U extends readonly string[]> extends ZodSchema<U[number]> {
+  _kind = 'enum'
+  constructor(public values: U) { super() }
+  _parse(input: unknown, path: string[]): U[number] {
+    if (typeof input !== 'string' || !this.values.includes(input as any))
+      throw new ZError(path, `enum: expected one of ${this.values.join(', ')}`)
+    return input as U[number]
+  }
+}
+
+class ZArray<T> extends ZodSchema<T[]> {
+  _kind = 'array'
+  constructor(public inner: ZodSchema<T>) { super() }
+  _parse(input: unknown, path: string[]): T[] {
+    if (!Array.isArray(input)) throw new ZError(path, 'expected array')
+    return input.map((item, i) => this.inner._parse(item, [...path, String(i)]))
+  }
+}
+
+class ZObject<Shape extends Record<string, ZodTypeAny>> extends ZodSchema<{
+  [K in keyof Shape]: Infer<Shape[K]>
+}> {
+  _kind = 'object'
+  constructor(public shape: Shape) { super() }
+  _parse(input: unknown, path: string[]) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+      throw new ZError(path, 'expected object')
+    const obj = input as Record<string, unknown>
+    const out: Record<string, unknown> = {}
+    for (const key of Object.keys(this.shape)) {
+      const schema = this.shape[key]
+      const val = obj[key]
+      if (val === undefined) {
+        if (schema._default !== undefined) { out[key] = schema._default; continue }
+        if (schema._optional) { out[key] = undefined; continue }
+        throw new ZError([...path, key], 'required')
+      }
+      out[key] = schema._parse(val, [...path, key])
+    }
+    return out as any
+  }
+}
+
+export const z = {
+  string: () => new ZString(),
+  number: () => new ZNumber(),
+  boolean: () => new ZBoolean(),
+  enum: <U extends readonly string[]>(values: U) => new ZEnum(values),
+  array: <T>(inner: ZodSchema<T>) => new ZArray(inner),
+  object: <S extends Record<string, ZodTypeAny>>(shape: S) => new ZObject(shape),
+}
+```
+
+`packages/widget-sdk/src/z/index.ts` (replace stub):
+
+```ts
+export { z, ZodSchema, type ZodTypeAny, type Infer } from './primitives'
+export { ZError } from './validate'
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/z.test.ts`
+Expected: PASS (8 tests).
+
+- [ ] **Step 5: Re-export and commit**
+
+In `packages/widget-sdk/src/index.ts`, add:
+
+```ts
+export { z, ZodSchema, type ZodTypeAny, type Infer, ZError } from './z'
+```
+
+```bash
+git add packages/widget-sdk
+git -c commit.gpgsign=false commit -m "feat(widget-sdk): z mini-validator primitives"
+```
+
+---
+
+## Task 6: `z` extensions — serverId/metricPath/color/duration
+
+**Files:**
+- Create: `packages/widget-sdk/src/z/extensions.ts`
+- Modify: `packages/widget-sdk/src/z/index.ts`
+- Modify: `packages/widget-sdk/tests/z.test.ts`
+
+- [ ] **Step 1: Add failing tests**
+
+Append to `packages/widget-sdk/tests/z.test.ts`:
+
+```ts
+describe('z extensions', () => {
+  it('z.serverId() validates non-empty string + marks kind', () => {
+    const s = z.serverId()
+    expect((s as any)._kind).toBe('serverId')
+    expect(s.parse('srv-1')).toBe('srv-1')
+    expect(() => s.parse('')).toThrow()
+  })
+
+  it('z.metricPath() validates dot/bracket path', () => {
+    const s = z.metricPath()
+    expect(s.parse('cpu.usage')).toBe('cpu.usage')
+    expect(s.parse('disks[0].used')).toBe('disks[0].used')
+    expect(() => s.parse('--invalid--')).toThrow()
+  })
+
+  it('z.color() accepts hex/oklch/rgb strings', () => {
+    const s = z.color()
+    expect(s.parse('#fff')).toBe('#fff')
+    expect(s.parse('oklch(0.5 0 0)')).toBe('oklch(0.5 0 0)')
+  })
+
+  it('z.duration() parses 5m / 1h / 30s', () => {
+    const s = z.duration()
+    expect(s.parse('5m')).toBe('5m')
+    expect(s.parse('1h')).toBe('1h')
+    expect(() => s.parse('bogus')).toThrow()
+  })
+})
+```
+
+- [ ] **Step 2: Run, verify failure**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/z.test.ts`
+Expected: 4 new tests FAIL.
+
+- [ ] **Step 3: Implement extensions**
+
+`packages/widget-sdk/src/z/extensions.ts`:
+
+```ts
+import { ZodSchema } from './primitives'
+import { ZError } from './validate'
+
+class ZServerId extends ZodSchema<string> {
+  _kind = 'serverId'
+  _parse(input: unknown, path: string[]): string {
+    if (typeof input !== 'string' || input.length === 0)
+      throw new ZError(path, 'expected non-empty serverId')
+    return input
+  }
+}
+
+const METRIC_PATH_RE = /^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*|\[\d+\])*$/
+
+class ZMetricPath extends ZodSchema<string> {
+  _kind = 'metricPath'
+  _parse(input: unknown, path: string[]): string {
+    if (typeof input !== 'string' || !METRIC_PATH_RE.test(input))
+      throw new ZError(path, 'expected metric path like cpu.usage or disks[0].used')
+    return input
+  }
+}
+
+const COLOR_RE = /^(#[0-9a-fA-F]{3,8}|oklch\([^)]+\)|rgb[a]?\([^)]+\)|hsl[a]?\([^)]+\))$/
+
+class ZColor extends ZodSchema<string> {
+  _kind = 'color'
+  _parse(input: unknown, path: string[]): string {
+    if (typeof input !== 'string' || !COLOR_RE.test(input))
+      throw new ZError(path, 'expected CSS color')
+    return input
+  }
+}
+
+const DURATION_RE = /^\d+(s|m|h|d)$/
+
+class ZDuration extends ZodSchema<string> {
+  _kind = 'duration'
+  _parse(input: unknown, path: string[]): string {
+    if (typeof input !== 'string' || !DURATION_RE.test(input))
+      throw new ZError(path, 'expected duration like 5m / 1h')
+    return input
+  }
+}
+
+export const serverId = () => new ZServerId()
+export const metricPath = () => new ZMetricPath()
+export const color = () => new ZColor()
+export const duration = () => new ZDuration()
+```
+
+In `packages/widget-sdk/src/z/index.ts`, merge extensions into `z`:
+
+```ts
+import { z as zPrimitives, ZodSchema, type ZodTypeAny, type Infer } from './primitives'
+import { serverId, metricPath, color, duration } from './extensions'
+
+export const z = Object.assign(zPrimitives, { serverId, metricPath, color, duration })
+export { ZodSchema, type ZodTypeAny, type Infer }
+export { ZError } from './validate'
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/z.test.ts`
+Expected: PASS (12 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/widget-sdk
+git -c commit.gpgsign=false commit -m "feat(widget-sdk): z extensions (serverId/metricPath/color/duration)"
+```
+
+---
+
+## Task 7: Runtime context (host bridge)
+
+**Files:**
+- Create: `packages/widget-sdk/src/runtime-context.ts`
+- Modify: `packages/widget-sdk/src/index.ts`
+
+- [ ] **Step 1: Write test stub**
+
+`packages/widget-sdk/tests/runtime-context.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach } from 'vitest'
+import { createWidgetRuntime, getRuntime, resetRuntime } from '../src/runtime-context'
+
+describe('runtime-context', () => {
+  beforeEach(() => resetRuntime())
+
+  it('throws if hooks called before host installs runtime', () => {
+    expect(() => getRuntime()).toThrow(/runtime not installed/)
+  })
+
+  it('returns installed runtime', () => {
+    const runtime = createWidgetRuntime({
+      apiBaseUrl: '/api',
+      queryClient: {} as any,
+      serversStore: () => [],
+      themeStore: () => ({ mode: 'light', cssVar: () => '' }),
+      onConfigUpdate: () => {},
+    })
+    expect(getRuntime()).toBe(runtime)
+  })
+})
+```
+
+- [ ] **Step 2: Run, verify failure**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/runtime-context.test.ts`
+Expected: FAIL (module not found).
+
+- [ ] **Step 3: Implement runtime-context.ts**
+
+```ts
+import type { QueryClient } from '@tanstack/react-query'
+
+export interface ServerSummary {
+  id: string
+  name: string
+  online: boolean
+  lastSeen: number | null
+  capabilities: number
+}
+
+export interface WidgetRuntime {
+  apiBaseUrl: string
+  queryClient: QueryClient
+  serversStore: () => ServerSummary[]
+  serverByIdStore: (id: string) => unknown    // ServerMetrics
+  themeStore: () => { mode: 'light' | 'dark'; cssVar: (name: string) => string }
+  onConfigUpdate: (instanceId: string, patch: Record<string, unknown>) => void
+}
+
+let _runtime: WidgetRuntime | null = null
+
+export function createWidgetRuntime(rt: Omit<WidgetRuntime, 'serverByIdStore'> & {
+  serverByIdStore?: WidgetRuntime['serverByIdStore']
+}): WidgetRuntime {
+  _runtime = {
+    serverByIdStore: () => undefined,
+    ...rt,
+  }
+  return _runtime
+}
+
+export function getRuntime(): WidgetRuntime {
+  if (!_runtime) throw new Error('widget-sdk: runtime not installed (host bridge missing)')
+  return _runtime
+}
+
+export function resetRuntime(): void {
+  _runtime = null
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/runtime-context.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Re-export and commit**
+
+In `packages/widget-sdk/src/index.ts`, add:
+
+```ts
+export { createWidgetRuntime, getRuntime, resetRuntime } from './runtime-context'
+export type { WidgetRuntime, ServerSummary } from './runtime-context'
+```
+
+```bash
+git add packages/widget-sdk
+git -c commit.gpgsign=false commit -m "feat(widget-sdk): host-runtime bridge"
+```
+
+---
+
+## Task 8: Live hooks (`useServers`, `useServer`, `useMetric`, `useCapability`)
+
+**Files:**
+- Create: `packages/widget-sdk/src/hooks/live.ts`
+- Create: `packages/widget-sdk/src/hooks/index.ts`
+- Create: `packages/widget-sdk/tests/hooks-live.test.tsx`
+
+- [ ] **Step 1: Write failing test**
+
+`packages/widget-sdk/tests/hooks-live.test.tsx`:
+
+```tsx
+import { describe, it, expect, beforeEach } from 'vitest'
+import { renderHook } from '@testing-library/react'
+import { useServers, useMetric, useCapability } from '../src/hooks/live'
+import { createWidgetRuntime, resetRuntime } from '../src/runtime-context'
+
+describe('live hooks', () => {
+  beforeEach(() => {
+    resetRuntime()
+    createWidgetRuntime({
+      apiBaseUrl: '/api',
+      queryClient: {} as any,
+      serversStore: () => [
+        { id: 's1', name: 'one', online: true, lastSeen: null, capabilities: 1 | 8 },
+      ],
+      serverByIdStore: (id) =>
+        id === 's1' ? { id: 's1', cpu: { usage: 42 }, disks: [{ used: 100 }] } : undefined,
+      themeStore: () => ({ mode: 'light', cssVar: () => '' }),
+      onConfigUpdate: () => {},
+    })
+  })
+
+  it('useServers returns runtime list', () => {
+    const { result } = renderHook(() => useServers())
+    expect(result.current).toHaveLength(1)
+    expect(result.current[0].id).toBe('s1')
+  })
+
+  it('useMetric extracts dot path', () => {
+    const { result } = renderHook(() => useMetric('s1', 'cpu.usage'))
+    expect(result.current).toBe(42)
+  })
+
+  it('useMetric extracts bracket path', () => {
+    const { result } = renderHook(() => useMetric('s1', 'disks[0].used'))
+    expect(result.current).toBe(100)
+  })
+
+  it('useMetric returns undefined when serverId is null', () => {
+    const { result } = renderHook(() => useMetric(null, 'cpu.usage'))
+    expect(result.current).toBeUndefined()
+  })
+
+  it('useCapability checks bitmask', () => {
+    const { result: ping } = renderHook(() => useCapability('s1', 'CAP_PING_ICMP'))
+    expect(ping.current).toBe(true)
+    const { result: term } = renderHook(() => useCapability('s1', 'CAP_TERMINAL'))
+    expect(term.current).toBe(true)
+    const { result: docker } = renderHook(() => useCapability('s1', 'CAP_DOCKER'))
+    expect(docker.current).toBe(false)
+  })
+})
+```
+
+- [ ] **Step 2: Run, verify failure**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/hooks-live.test.tsx`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement live hooks**
+
+`packages/widget-sdk/src/hooks/live.ts`:
+
+```ts
+import { getRuntime, type ServerSummary } from '../runtime-context'
+
+const CAPS: Record<string, number> = {
+  CAP_TERMINAL: 1,
+  CAP_EXEC: 2,
+  CAP_UPGRADE: 4,
+  CAP_PING_ICMP: 8,
+  CAP_PING_TCP: 16,
+  CAP_PING_HTTP: 32,
+  CAP_FILE: 64,
+  CAP_DOCKER: 128,
+  CAP_SECURITY_EVENTS: 256,
+  CAP_FIREWALL_BLOCK: 512,
+  CAP_IP_QUALITY: 1024,
+}
+
+export function useServers(): ServerSummary[] {
+  return getRuntime().serversStore()
+}
+
+export function useServer(id: string | null): unknown {
+  if (id === null) return undefined
+  return getRuntime().serverByIdStore(id)
+}
+
+const PATH_TOKEN_RE = /[a-zA-Z_][a-zA-Z0-9_]*|\[\d+\]/g
+
+export function useMetric(id: string | null, path: string): number | string | undefined {
+  if (id === null) return undefined
+  const server = getRuntime().serverByIdStore(id) as Record<string, any> | undefined
+  if (!server) return undefined
+  const tokens = path.match(PATH_TOKEN_RE) ?? []
+  let cur: any = server
+  for (const tok of tokens) {
+    if (cur == null) return undefined
+    cur = tok.startsWith('[') ? cur[Number(tok.slice(1, -1))] : cur[tok]
+  }
+  return cur
+}
+
+export function useCapability(id: string | null, cap: string): boolean {
+  if (id === null) return false
+  const bit = CAPS[cap]
+  if (!bit) return false
+  const server = getRuntime().serversStore().find((s) => s.id === id)
+  return server ? (server.capabilities & bit) !== 0 : false
+}
+```
+
+`packages/widget-sdk/src/hooks/index.ts`:
+
+```ts
+export { useServers, useServer, useMetric, useCapability } from './live'
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/hooks-live.test.tsx`
+Expected: PASS (5 tests).
+
+- [ ] **Step 5: Re-export and commit**
+
+In `packages/widget-sdk/src/index.ts`:
+
+```ts
+export * from './hooks'
+```
+
+```bash
+git add packages/widget-sdk
+git -c commit.gpgsign=false commit -m "feat(widget-sdk): live hooks"
+```
+
+---
+
+## Task 9: Escape-hatch hooks (`useApiQuery`, `useApiMutation`)
+
+**Files:**
+- Create: `packages/widget-sdk/src/hooks/escape-hatch.ts`
+- Modify: `packages/widget-sdk/src/hooks/index.ts`
+- Create: `packages/widget-sdk/tests/hooks-api.test.tsx`
+
+- [ ] **Step 1: Write failing test**
+
+`packages/widget-sdk/tests/hooks-api.test.tsx`:
+
+```tsx
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { renderHook, waitFor } from '@testing-library/react'
+import { createElement } from 'react'
+import { useApiQuery, useApiMutation } from '../src/hooks/escape-hatch'
+import { createWidgetRuntime, resetRuntime } from '../src/runtime-context'
+
+describe('api hooks', () => {
+  let qc: QueryClient
+  beforeEach(() => {
+    resetRuntime()
+    qc = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+    createWidgetRuntime({
+      apiBaseUrl: '/api',
+      queryClient: qc,
+      serversStore: () => [],
+      themeStore: () => ({ mode: 'light', cssVar: () => '' }),
+      onConfigUpdate: () => {},
+    })
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ data: { hello: 'world' } }),
+    }) as any
+  })
+
+  const wrapper = ({ children }: any) =>
+    createElement(QueryClientProvider, { client: qc, children })
+
+  it('useApiQuery unwraps {data}', async () => {
+    const { result } = renderHook(() => useApiQuery<{ hello: string }>('/api/test'), { wrapper })
+    await waitFor(() => expect(result.current.data).toEqual({ hello: 'world' }))
+  })
+
+  it('useApiMutation calls fetch with method+body', async () => {
+    const { result } = renderHook(() => useApiMutation<{ ok: true }, { x: number }>('POST', '/api/do'), { wrapper })
+    await result.current.mutateAsync({ x: 1 })
+    expect(global.fetch).toHaveBeenCalledWith(
+      '/api/do',
+      expect.objectContaining({ method: 'POST', credentials: 'include' }),
+    )
+  })
+})
+```
+
+- [ ] **Step 2: Run, verify failure**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/hooks-api.test.tsx`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement**
+
+`packages/widget-sdk/src/hooks/escape-hatch.ts`:
+
+```ts
+import { useQuery, useMutation, type UseQueryResult, type UseMutationResult } from '@tanstack/react-query'
+
+async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
+  const res = await fetch(path, {
+    method,
+    credentials: 'include',
+    headers: body ? { 'content-type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  if (!res.ok) throw new Error(`${method} ${path}: ${res.status}`)
+  const json = await res.json()
+  return (json && typeof json === 'object' && 'data' in json) ? (json as { data: T }).data : (json as T)
+}
+
+export function useApiQuery<T>(
+  path: string,
+  opts?: { params?: Record<string, string | number | undefined>; enabled?: boolean },
+): UseQueryResult<T> {
+  const params = opts?.params
+  const url = params
+    ? `${path}?${new URLSearchParams(
+        Object.fromEntries(
+          Object.entries(params).filter(([, v]) => v !== undefined).map(([k, v]) => [k, String(v)]),
+        ),
+      ).toString()}`
+    : path
+  return useQuery<T>({
+    queryKey: ['widget-api', url],
+    queryFn: () => request<T>('GET', url),
+    enabled: opts?.enabled,
+  })
+}
+
+export function useApiMutation<TRes, TReq = void>(
+  method: string,
+  path: string,
+): UseMutationResult<TRes, Error, TReq> {
+  return useMutation<TRes, Error, TReq>({
+    mutationFn: (body) => request<TRes>(method, path, body),
+  })
+}
+```
+
+In `packages/widget-sdk/src/hooks/index.ts`:
+
+```ts
+export { useServers, useServer, useMetric, useCapability } from './live'
+export { useApiQuery, useApiMutation } from './escape-hatch'
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/hooks-api.test.tsx`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/widget-sdk
+git -c commit.gpgsign=false commit -m "feat(widget-sdk): useApiQuery/useApiMutation"
+```
+
+---
+
+## Task 10: Domain hooks (alerts/service-monitors/traffic/uptime/geoip/history)
+
+**Files:**
+- Create: `packages/widget-sdk/src/hooks/domain.ts`
+- Modify: `packages/widget-sdk/src/hooks/index.ts`
+
+- [ ] **Step 1: Implement domain hooks (thin wrappers — tests come at integration layer)**
+
+`packages/widget-sdk/src/hooks/domain.ts`:
+
+```ts
+import { useApiQuery, useApiMutation } from './escape-hatch'
+
+export interface AlertEvent { id: string; severity: string; message: string; created_at: string }
+export interface ServiceMonitor { id: string; name: string; status: string }
+
+export function useAlerts(opts?: { limit?: number }) {
+  return useApiQuery<AlertEvent[]>('/api/alert-events', { params: { limit: opts?.limit ?? 20 } })
+}
+
+export function useServiceMonitors() {
+  return useApiQuery<ServiceMonitor[]>('/api/service-monitors')
+}
+
+export interface TrafficPoint { ts: number; rx: number; tx: number }
+
+export function useTraffic(serverId: string | null, range?: string) {
+  return useApiQuery<TrafficPoint[]>(
+    serverId ? `/api/servers/${serverId}/traffic` : '/api/traffic/overview/daily',
+    { params: { range }, enabled: true },
+  )
+}
+
+export interface UptimeEntry { day: string; uptime_pct: number; incidents: number }
+
+export function useUptime(serverId: string | null, days = 30) {
+  return useApiQuery<UptimeEntry[]>(
+    serverId ? `/api/servers/${serverId}/uptime-daily` : '/api/uptime/overview',
+    { params: { days } },
+  )
+}
+
+export interface HistoryPoint { ts: number; value: number }
+
+export function useHistory(serverId: string | null, path: string, range: string) {
+  return useApiQuery<HistoryPoint[]>('/api/metrics/history', {
+    params: { server_id: serverId ?? undefined, path, range },
+    enabled: serverId !== null,
+  })
+}
+
+export function useGeoIp() {
+  const status = useApiQuery<{ installed: boolean; source?: string }>('/api/geoip/status')
+  const download = useApiMutation<{ success: boolean }>('POST', '/api/geoip/download')
+  return { status, download }
+}
+```
+
+In `packages/widget-sdk/src/hooks/index.ts`, append:
+
+```ts
+export {
+  useAlerts, useServiceMonitors, useTraffic, useUptime, useHistory, useGeoIp,
+  type AlertEvent, type ServiceMonitor, type TrafficPoint, type UptimeEntry, type HistoryPoint,
+} from './domain'
+```
+
+- [ ] **Step 2: Verify typecheck**
+
+Run: `cd packages/widget-sdk && bunx tsc --noEmit`
+Expected: no errors.
+
+- [ ] **Step 3: Run all SDK tests**
+
+Run: `cd packages/widget-sdk && bunx vitest run`
+Expected: all existing tests still PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add packages/widget-sdk
+git -c commit.gpgsign=false commit -m "feat(widget-sdk): domain hooks (alerts/services/traffic/uptime/history/geoip)"
+```
+
+---
+
+## Task 11: Host hooks (`useTheme`, `useConfigUpdate`)
+
+**Files:**
+- Create: `packages/widget-sdk/src/hooks/host.ts`
+- Modify: `packages/widget-sdk/src/hooks/index.ts`
+
+- [ ] **Step 1: Implement and re-export**
+
+`packages/widget-sdk/src/hooks/host.ts`:
+
+```ts
+import { getRuntime } from '../runtime-context'
+
+export function useTheme() {
+  return getRuntime().themeStore()
+}
+
+export function useConfigUpdate<TConfig = Record<string, unknown>>(instanceId: string) {
+  const runtime = getRuntime()
+  return (patch: Partial<TConfig>) =>
+    runtime.onConfigUpdate(instanceId, patch as Record<string, unknown>)
+}
+```
+
+In `packages/widget-sdk/src/hooks/index.ts`, append:
+
+```ts
+export { useTheme, useConfigUpdate } from './host'
+```
+
+- [ ] **Step 2: Verify typecheck**
+
+Run: `cd packages/widget-sdk && bunx tsc --noEmit`
+Expected: no errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add packages/widget-sdk
+git -c commit.gpgsign=false commit -m "feat(widget-sdk): host hooks (useTheme/useConfigUpdate)"
+```
+
+---
+
+## Task 12: Actions runner
+
+**Files:**
+- Create: `packages/widget-sdk/src/actions/index.ts`
+- Create: `packages/widget-sdk/src/actions/action-button.tsx`
+- Create: `packages/widget-sdk/tests/actions.test.tsx`
+
+- [ ] **Step 1: Write test**
+
+`packages/widget-sdk/tests/actions.test.tsx`:
+
+```tsx
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { createActionsHelper } from '../src/actions'
+import type { ActionDefinition } from '../src/define-widget'
+
+describe('actions helper', () => {
+  beforeEach(() => {
+    global.fetch = vi.fn().mockResolvedValue({ ok: true, json: async () => ({ data: { ok: true } }) }) as any
+  })
+
+  it('renders a button that triggers run() and shows loading state', async () => {
+    const run = vi.fn().mockResolvedValue(undefined)
+    const actions: ActionDefinition[] = [{ id: 'a1', label: 'Do it', run }]
+    const helper = createActionsHelper(actions)
+    render(<>{helper.render('a1')}</>)
+    fireEvent.click(screen.getByRole('button', { name: 'Do it' }))
+    await waitFor(() => expect(run).toHaveBeenCalledOnce())
+  })
+
+  it('returns null for unknown id', () => {
+    const helper = createActionsHelper([])
+    const { container } = render(<>{helper.render('missing')}</>)
+    expect(container.textContent).toBe('')
+  })
+})
+```
+
+- [ ] **Step 2: Run, verify failure**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/actions.test.tsx`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement**
+
+`packages/widget-sdk/src/actions/action-button.tsx`:
+
+```tsx
+import { useState } from 'react'
+import type { ActionDefinition } from '../define-widget'
+
+interface Props {
+  action: ActionDefinition
+  onRun: () => Promise<void>
+}
+
+export function ActionButton({ action, onRun }: Props) {
+  const [pending, setPending] = useState(false)
+  const [confirming, setConfirming] = useState(false)
+  const trigger = async () => {
+    if (action.confirm && !confirming) { setConfirming(true); return }
+    setConfirming(false)
+    setPending(true)
+    try { await onRun() } finally { setPending(false) }
+  }
+  return (
+    <button type="button" disabled={pending} onClick={trigger}>
+      {confirming ? `Confirm: ${action.label}` : action.label}
+      {pending ? '…' : ''}
+    </button>
+  )
+}
+```
+
+`packages/widget-sdk/src/actions/index.ts`:
+
+```tsx
+import type { ReactNode } from 'react'
+import type { ActionDefinition, ActionsHelper, ActionContext } from '../define-widget'
+import { ActionButton } from './action-button'
+
+async function apiMutation<Req = unknown, Res = unknown>(method: string, path: string, body?: Req): Promise<Res> {
+  const res = await fetch(path, {
+    method, credentials: 'include',
+    headers: body ? { 'content-type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  if (!res.ok) throw new Error(`${method} ${path}: ${res.status}`)
+  const json = await res.json()
+  return (json && typeof json === 'object' && 'data' in json) ? (json as any).data : json
+}
+
+export function createActionsHelper(actions: ActionDefinition[]): ActionsHelper {
+  const ctx: ActionContext = { apiMutation }
+  return {
+    render(id: string): ReactNode {
+      const action = actions.find((a) => a.id === id)
+      if (!action) return null
+      return <ActionButton key={id} action={action} onRun={() => action.run(ctx)} />
+    },
+  }
+}
+
+export type { ActionDefinition, ActionsHelper, ActionContext } from '../define-widget'
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/actions.test.tsx`
+Expected: PASS.
+
+- [ ] **Step 5: Re-export and commit**
+
+In `packages/widget-sdk/src/index.ts`:
+
+```ts
+export { createActionsHelper } from './actions'
+```
+
+```bash
+git add packages/widget-sdk
+git -c commit.gpgsign=false commit -m "feat(widget-sdk): actions runner + ActionButton"
+```
+
+---
+
+## Task 13: `renderConfigForm` (minimal, primitives + enum + serverId)
+
+**Files:**
+- Create: `packages/widget-sdk/src/form/index.tsx`
+- Create: `packages/widget-sdk/src/form/field-renderers.tsx`
+- Create: `packages/widget-sdk/tests/form.test.tsx`
+
+- [ ] **Step 1: Write test**
+
+`packages/widget-sdk/tests/form.test.tsx`:
+
+```tsx
+import { describe, it, expect, beforeEach } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { useState } from 'react'
+import { z } from '../src/z'
+import { renderConfigForm } from '../src/form'
+import { createWidgetRuntime, resetRuntime } from '../src/runtime-context'
+
+function Wrapper({ schema, initial }: any) {
+  const [value, setValue] = useState(initial)
+  return <>{renderConfigForm(schema, value, setValue)}</>
+}
+
+describe('renderConfigForm', () => {
+  beforeEach(() => {
+    resetRuntime()
+    createWidgetRuntime({
+      apiBaseUrl: '/api', queryClient: {} as any,
+      serversStore: () => [{ id: 's1', name: 'One', online: true, lastSeen: null, capabilities: 0 }],
+      themeStore: () => ({ mode: 'light', cssVar: () => '' }),
+      onConfigUpdate: () => {},
+    })
+  })
+
+  it('renders a text input for z.string()', () => {
+    const schema = z.object({ name: z.string().describe('Name') })
+    render(<Wrapper schema={schema} initial={{ name: 'hi' }} />)
+    const input = screen.getByLabelText('Name') as HTMLInputElement
+    expect(input.value).toBe('hi')
+    fireEvent.change(input, { target: { value: 'world' } })
+    expect(input.value).toBe('world')
+  })
+
+  it('renders a number input for z.number()', () => {
+    const schema = z.object({ count: z.number().describe('Count') })
+    render(<Wrapper schema={schema} initial={{ count: 5 }} />)
+    expect((screen.getByLabelText('Count') as HTMLInputElement).value).toBe('5')
+  })
+
+  it('renders a select for z.enum()', () => {
+    const schema = z.object({ mode: z.enum(['a', 'b'] as const).describe('Mode') })
+    render(<Wrapper schema={schema} initial={{ mode: 'a' }} />)
+    expect(screen.getByLabelText('Mode')).toBeTruthy()
+  })
+
+  it('renders a server picker for z.serverId()', () => {
+    const schema = z.object({ srv: z.serverId().describe('Server') })
+    render(<Wrapper schema={schema} initial={{ srv: 's1' }} />)
+    expect(screen.getByLabelText('Server')).toBeTruthy()
+  })
+})
+```
+
+- [ ] **Step 2: Run, verify failure**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/form.test.tsx`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement renderers + form**
+
+`packages/widget-sdk/src/form/field-renderers.tsx`:
+
+```tsx
+import type { ZodTypeAny } from '../z'
+import { getRuntime } from '../runtime-context'
+
+interface FieldProps {
+  schema: ZodTypeAny
+  value: unknown
+  onChange: (v: unknown) => void
+  id: string
+  label: string
+}
+
+export function renderField(props: FieldProps) {
+  const kind = (props.schema as any)._kind
+  switch (kind) {
+    case 'string': return <input id={props.id} type="text" value={(props.value as string) ?? ''} onChange={(e) => props.onChange(e.target.value)} />
+    case 'number': return <input id={props.id} type="number" value={(props.value as number) ?? ''} onChange={(e) => props.onChange(e.target.value === '' ? undefined : Number(e.target.value))} />
+    case 'boolean': return <input id={props.id} type="checkbox" checked={!!props.value} onChange={(e) => props.onChange(e.target.checked)} />
+    case 'enum': {
+      const opts = (props.schema as any).values as string[]
+      return (
+        <select id={props.id} value={(props.value as string) ?? ''} onChange={(e) => props.onChange(e.target.value)}>
+          {opts.map((o) => <option key={o} value={o}>{o}</option>)}
+        </select>
+      )
+    }
+    case 'serverId': {
+      const servers = getRuntime().serversStore()
+      return (
+        <select id={props.id} value={(props.value as string) ?? ''} onChange={(e) => props.onChange(e.target.value)}>
+          <option value="">— choose —</option>
+          {servers.map((s) => <option key={s.id} value={s.id}>{s.name}</option>)}
+        </select>
+      )
+    }
+    case 'metricPath':
+    case 'color':
+    case 'duration':
+    default:
+      return <input id={props.id} type="text" value={(props.value as string) ?? ''} onChange={(e) => props.onChange(e.target.value)} />
+  }
+}
+```
+
+`packages/widget-sdk/src/form/index.tsx`:
+
+```tsx
+import type { ReactNode } from 'react'
+import type { ZodTypeAny } from '../z'
+import { renderField } from './field-renderers'
+
+export function renderConfigForm(
+  schema: ZodTypeAny,
+  value: Record<string, unknown>,
+  onChange: (v: Record<string, unknown>) => void,
+): ReactNode {
+  if ((schema as any)._kind !== 'object') {
+    return <em>Top-level schema must be z.object()</em>
+  }
+  const shape = (schema as any).shape as Record<string, ZodTypeAny>
+  return (
+    <div>
+      {Object.entries(shape).map(([key, fieldSchema]) => {
+        const label = (fieldSchema as any)._label ?? key
+        const id = `cfg-${key}`
+        return (
+          <div key={key} style={{ marginBottom: 8 }}>
+            <label htmlFor={id} style={{ display: 'block' }}>{label}</label>
+            {renderField({
+              schema: fieldSchema,
+              value: value[key],
+              onChange: (v) => onChange({ ...value, [key]: v }),
+              id,
+              label,
+            })}
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `cd packages/widget-sdk && bunx vitest run tests/form.test.tsx`
+Expected: PASS.
+
+- [ ] **Step 5: Re-export and commit**
+
+In `packages/widget-sdk/src/index.ts`:
+
+```ts
+export { renderConfigForm } from './form'
+```
+
+```bash
+git add packages/widget-sdk
+git -c commit.gpgsign=false commit -m "feat(widget-sdk): renderConfigForm + field renderers"
+```
+
+---
+
+## Task 14: Frontend Widget Registry
+
+**Files:**
+- Create: `apps/web/src/widgets-runtime/registry.ts`
+- Create: `apps/web/src/widgets-runtime/registry.test.ts`
+
+- [ ] **Step 1: Write failing test**
+
+`apps/web/src/widgets-runtime/registry.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach } from 'vitest'
+import type { WidgetModule, WidgetManifest } from '@serverbee/widget-sdk'
+import { useWidgetRegistry, registryActions } from './registry'
+
+const fakeManifest: WidgetManifest = {
+  id: 'com.test.foo', version: '1.0.0', name: 'Foo', category: 'Real-time',
+  sizing: { defaultW: 2, defaultH: 2, minW: 1, minH: 1, strategy: 'free' },
+  sdkVersion: '^0.1.0',
+}
+const fakeModule: WidgetModule = {
+  __brand: 'WidgetModule',
+  configSchema: {} as any,
+  component: () => null,
+  actions: [],
+}
+
+describe('registry', () => {
+  beforeEach(() => useWidgetRegistry.setState({ modules: new Map(), failures: new Map() }))
+
+  it('registers and retrieves a module', () => {
+    registryActions.register('com.test.foo', fakeModule, fakeManifest)
+    const entry = registryActions.get('com.test.foo')
+    expect(entry?.manifest.name).toBe('Foo')
+    expect(entry?.module).toBe(fakeModule)
+  })
+
+  it('records load failures', () => {
+    registryActions.recordLoadFailure('com.test.bad', new Error('boom'))
+    expect(registryActions.list()).toEqual([])
+    expect(useWidgetRegistry.getState().failures.get('com.test.bad')?.message).toBe('boom')
+  })
+
+  it('unregister removes the module', () => {
+    registryActions.register('com.test.foo', fakeModule, fakeManifest)
+    registryActions.unregister('com.test.foo')
+    expect(registryActions.get('com.test.foo')).toBeUndefined()
+  })
+})
+```
+
+- [ ] **Step 2: Run, verify failure**
+
+Run: `cd apps/web && bunx vitest run src/widgets-runtime/registry.test.ts`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement**
+
+`apps/web/src/widgets-runtime/registry.ts`:
+
+```ts
+import { create } from 'zustand'
+import type { WidgetModule, WidgetManifest } from '@serverbee/widget-sdk'
+
+export interface RegistryEntry {
+  manifest: WidgetManifest
+  module: WidgetModule
+}
+
+interface RegistryState {
+  modules: Map<string, RegistryEntry>
+  failures: Map<string, Error>
+}
+
+export const useWidgetRegistry = create<RegistryState>(() => ({
+  modules: new Map(),
+  failures: new Map(),
+}))
+
+export const registryActions = {
+  register(id: string, module: WidgetModule, manifest: WidgetManifest) {
+    useWidgetRegistry.setState((state) => {
+      const modules = new Map(state.modules)
+      modules.set(id, { manifest, module })
+      const failures = new Map(state.failures)
+      failures.delete(id)
+      return { modules, failures }
+    })
+  },
+  unregister(id: string) {
+    useWidgetRegistry.setState((state) => {
+      const modules = new Map(state.modules)
+      modules.delete(id)
+      return { modules }
+    })
+  },
+  get(id: string): RegistryEntry | undefined {
+    return useWidgetRegistry.getState().modules.get(id)
+  },
+  list(): RegistryEntry[] {
+    return Array.from(useWidgetRegistry.getState().modules.values())
+  },
+  recordLoadFailure(id: string, err: Error) {
+    useWidgetRegistry.setState((state) => {
+      const failures = new Map(state.failures)
+      failures.set(id, err)
+      return { failures }
+    })
+  },
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `cd apps/web && bunx vitest run src/widgets-runtime/registry.test.ts`
+Expected: PASS (3 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/web/src/widgets-runtime
+git -c commit.gpgsign=false commit -m "feat(web): Widget Registry singleton"
+```
+
+---
+
+## Task 15: Frontend Loader
+
+**Files:**
+- Create: `apps/web/src/widgets-runtime/loader.ts`
+- Create: `apps/web/src/widgets-runtime/loader.test.ts`
+
+- [ ] **Step 1: Write failing test**
+
+`apps/web/src/widgets-runtime/loader.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { bootstrapLoader } from './loader'
+import { useWidgetRegistry } from './registry'
+
+describe('bootstrapLoader', () => {
+  beforeEach(() => {
+    useWidgetRegistry.setState({ modules: new Map(), failures: new Map() })
+  })
+
+  it('lists modules, imports each, registers them', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true, json: async () => ({ data: [
+        { id: 'com.test.foo', version: '1.0.0', entry_path: 'index.js', manifest: {
+          id: 'com.test.foo', version: '1.0.0', name: 'Foo', category: 'Real-time',
+          sizing: { defaultW: 2, defaultH: 2, minW: 1, minH: 1, strategy: 'free' },
+          sdkVersion: '^0.1.0',
+        } },
+      ] }),
+    }) as any
+    const fakeModule = { __brand: 'WidgetModule', configSchema: {}, component: () => null, actions: [] }
+    const importer = vi.fn().mockResolvedValue({ default: fakeModule })
+    await bootstrapLoader({ importer })
+    expect(useWidgetRegistry.getState().modules.size).toBe(1)
+    expect(useWidgetRegistry.getState().modules.get('com.test.foo')?.manifest.name).toBe('Foo')
+  })
+
+  it('isolates one module failure', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true, json: async () => ({ data: [
+        { id: 'a', version: '1.0.0', entry_path: 'a.js', manifest: { id: 'a', version: '1.0.0', name: 'A', category: 'Real-time', sizing: { defaultW: 2, defaultH: 2, minW: 1, minH: 1, strategy: 'free' }, sdkVersion: '^0.1.0' } },
+        { id: 'b', version: '1.0.0', entry_path: 'b.js', manifest: { id: 'b', version: '1.0.0', name: 'B', category: 'Real-time', sizing: { defaultW: 2, defaultH: 2, minW: 1, minH: 1, strategy: 'free' }, sdkVersion: '^0.1.0' } },
+      ] }),
+    }) as any
+    const importer = vi.fn().mockImplementation((url: string) =>
+      url.includes('a.js')
+        ? Promise.resolve({ default: { __brand: 'WidgetModule', configSchema: {}, component: () => null, actions: [] } })
+        : Promise.reject(new Error('boom')),
+    )
+    await bootstrapLoader({ importer })
+    expect(useWidgetRegistry.getState().modules.has('a')).toBe(true)
+    expect(useWidgetRegistry.getState().failures.has('b')).toBe(true)
+  })
+})
+```
+
+- [ ] **Step 2: Run, verify failure**
+
+Run: `cd apps/web && bunx vitest run src/widgets-runtime/loader.test.ts`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement**
+
+`apps/web/src/widgets-runtime/loader.ts`:
+
+```ts
+import type { WidgetManifest, WidgetModule } from '@serverbee/widget-sdk'
+import { registryActions } from './registry'
+
+interface ListEntry {
+  id: string
+  version: string
+  entry_path: string
+  manifest: WidgetManifest
+}
+
+export interface BootstrapOptions {
+  /** Override the import function (used in tests). */
+  importer?: (url: string) => Promise<{ default: WidgetModule }>
+  baseUrl?: string
+}
+
+export async function bootstrapLoader(opts: BootstrapOptions = {}): Promise<void> {
+  const base = opts.baseUrl ?? '/api/widget-modules'
+  const importer = opts.importer ?? ((url: string) => import(/* @vite-ignore */ url))
+
+  const res = await fetch(base, { credentials: 'include' })
+  if (!res.ok) throw new Error(`bootstrapLoader: list failed ${res.status}`)
+  const body = await res.json() as { data: ListEntry[] }
+  const modules = body.data
+
+  await Promise.allSettled(
+    modules.map(async (entry) => {
+      try {
+        const url = `${base}/${entry.id}/${entry.entry_path}`
+        const mod = await importer(url)
+        if (!mod.default || mod.default.__brand !== 'WidgetModule') {
+          throw new Error(`module ${entry.id} did not export a WidgetModule via default`)
+        }
+        registryActions.register(entry.id, mod.default, entry.manifest)
+      } catch (err) {
+        registryActions.recordLoadFailure(entry.id, err instanceof Error ? err : new Error(String(err)))
+      }
+    }),
+  )
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `cd apps/web && bunx vitest run src/widgets-runtime/loader.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/web/src/widgets-runtime
+git -c commit.gpgsign=false commit -m "feat(web): bootstrap loader (fetch list, import, isolate failures)"
+```
+
+---
+
+## Task 16: Runtime bridge — mount SDK + React to globalThis
+
+**Files:**
+- Create: `apps/web/src/widgets-runtime/runtime-bridge.ts`
+- Create: `apps/web/public/runtime/widget-sdk.js`
+- Create: `apps/web/public/runtime/react.js`
+- Create: `apps/web/public/runtime/react-dom.js`
+- Create: `apps/web/public/runtime/react-jsx-runtime.js`
+- Modify: `apps/web/index.html`
+- Modify: `apps/web/src/main.tsx`
+
+- [ ] **Step 1: Write shim files**
+
+`apps/web/public/runtime/widget-sdk.js`:
+
+```js
+const ns = globalThis.__SERVERBEE_SDK__
+if (!ns) throw new Error('widget-sdk shim: host did not mount __SERVERBEE_SDK__')
+export const defineWidget = ns.defineWidget
+export const z = ns.z
+export const createActionsHelper = ns.createActionsHelper
+export const renderConfigForm = ns.renderConfigForm
+export const useServers = ns.useServers
+export const useServer = ns.useServer
+export const useMetric = ns.useMetric
+export const useCapability = ns.useCapability
+export const useApiQuery = ns.useApiQuery
+export const useApiMutation = ns.useApiMutation
+export const useAlerts = ns.useAlerts
+export const useServiceMonitors = ns.useServiceMonitors
+export const useTraffic = ns.useTraffic
+export const useUptime = ns.useUptime
+export const useHistory = ns.useHistory
+export const useGeoIp = ns.useGeoIp
+export const useTheme = ns.useTheme
+export const useConfigUpdate = ns.useConfigUpdate
+export const SDK_VERSION = ns.SDK_VERSION
+```
+
+`apps/web/public/runtime/react.js`:
+
+```js
+const r = globalThis.__SERVERBEE_REACT__
+if (!r) throw new Error('react shim: host did not mount __SERVERBEE_REACT__')
+export default r
+export const useState = r.useState
+export const useEffect = r.useEffect
+export const useMemo = r.useMemo
+export const useCallback = r.useCallback
+export const useRef = r.useRef
+export const useContext = r.useContext
+export const useReducer = r.useReducer
+export const useLayoutEffect = r.useLayoutEffect
+export const createContext = r.createContext
+export const Fragment = r.Fragment
+export const memo = r.memo
+export const forwardRef = r.forwardRef
+export const Component = r.Component
+export const Children = r.Children
+export const cloneElement = r.cloneElement
+export const createElement = r.createElement
+export const isValidElement = r.isValidElement
+```
+
+`apps/web/public/runtime/react-dom.js`:
+
+```js
+const rd = globalThis.__SERVERBEE_REACT_DOM__
+if (!rd) throw new Error('react-dom shim: host did not mount __SERVERBEE_REACT_DOM__')
+export default rd
+export const createPortal = rd.createPortal
+export const flushSync = rd.flushSync
+```
+
+`apps/web/public/runtime/react-jsx-runtime.js`:
+
+```js
+const j = globalThis.__SERVERBEE_JSX_RUNTIME__
+if (!j) throw new Error('jsx-runtime shim: host did not mount __SERVERBEE_JSX_RUNTIME__')
+export const jsx = j.jsx
+export const jsxs = j.jsxs
+export const Fragment = j.Fragment
+```
+
+- [ ] **Step 2: Write runtime-bridge.ts**
+
+`apps/web/src/widgets-runtime/runtime-bridge.ts`:
+
+```ts
+import * as React from 'react'
+import * as ReactDOM from 'react-dom'
+import * as JsxRuntime from 'react/jsx-runtime'
+import * as Sdk from '@serverbee/widget-sdk'
+import type { QueryClient } from '@tanstack/react-query'
+import type { ServerSummary } from '@serverbee/widget-sdk'
+
+export interface BridgeInputs {
+  queryClient: QueryClient
+  serversStore: () => ServerSummary[]
+  serverByIdStore: (id: string) => unknown
+  themeStore: () => { mode: 'light' | 'dark'; cssVar: (n: string) => string }
+  onConfigUpdate: (instanceId: string, patch: Record<string, unknown>) => void
+}
+
+export function mountRuntimeBridge(inputs: BridgeInputs): void {
+  ;(globalThis as any).__SERVERBEE_REACT__ = React
+  ;(globalThis as any).__SERVERBEE_REACT_DOM__ = ReactDOM
+  ;(globalThis as any).__SERVERBEE_JSX_RUNTIME__ = JsxRuntime
+  ;(globalThis as any).__SERVERBEE_SDK__ = Sdk
+
+  Sdk.createWidgetRuntime({
+    apiBaseUrl: '/api',
+    queryClient: inputs.queryClient,
+    serversStore: inputs.serversStore,
+    serverByIdStore: inputs.serverByIdStore,
+    themeStore: inputs.themeStore,
+    onConfigUpdate: inputs.onConfigUpdate,
+  })
+}
+```
+
+- [ ] **Step 3: Inject importmap in index.html**
+
+In `apps/web/index.html`, **before** the existing `<script type="module" src="/src/main.tsx">`:
+
+```html
+<script type="importmap">
+  {
+    "imports": {
+      "@serverbee/widget-sdk":  "/runtime/widget-sdk.js",
+      "react":                  "/runtime/react.js",
+      "react-dom":              "/runtime/react-dom.js",
+      "react/jsx-runtime":      "/runtime/react-jsx-runtime.js"
+    }
+  }
+</script>
+```
+
+- [ ] **Step 4: Wire main.tsx**
+
+In `apps/web/src/main.tsx`, after `QueryClient` is created and before `ReactDOM.createRoot(...).render(...)`, add:
+
+```ts
+import { mountRuntimeBridge } from './widgets-runtime/runtime-bridge'
+import { bootstrapLoader } from './widgets-runtime/loader'
+
+mountRuntimeBridge({
+  queryClient,
+  serversStore: () => [],            // wired in a later plan (Plan 2A)
+  serverByIdStore: () => undefined,  // wired in Plan 2A
+  themeStore: () => ({ mode: document.documentElement.classList.contains('dark') ? 'dark' : 'light', cssVar: (n) => getComputedStyle(document.documentElement).getPropertyValue(n).trim() }),
+  onConfigUpdate: () => {},          // wired in Plan 2A
+})
+
+// Best-effort: don't block rendering on module list (endpoint may not exist yet during Plan 1).
+bootstrapLoader().catch((e) => console.warn('widget bootstrap failed', e))
+```
+
+Note: in Plan 1 there are no modules to load (the endpoint returns empty), so the loader is essentially a no-op. Real builtin loading happens after Plan 2A.
+
+- [ ] **Step 5: Build + commit**
+
+Run: `cd apps/web && bun run build`
+Expected: builds successfully.
+
+```bash
+git add apps/web/index.html apps/web/src/main.tsx apps/web/src/widgets-runtime/runtime-bridge.ts apps/web/public/runtime
+git -c commit.gpgsign=false commit -m "feat(web): runtime bridge + import-map shims for widget SDK"
+```
+
+---
+
+## Task 17: Backend — `widget_module` entity
+
+**Files:**
+- Create: `crates/server/src/entity/widget_module.rs`
+- Modify: `crates/server/src/entity/mod.rs`
+
+- [ ] **Step 1: Write entity**
+
+`crates/server/src/entity/widget_module.rs`:
+
+```rust
+use sea_orm::entity::prelude::*;
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Debug, PartialEq, Eq, EnumIter, DeriveActiveEnum, Serialize, Deserialize, utoipa::ToSchema)]
+#[sea_orm(rs_type = "String", db_type = "String(StringLen::N(32))")]
+pub enum SourceType {
+    #[sea_orm(string_value = "Builtin")]
+    Builtin,
+    #[sea_orm(string_value = "Url")]
+    Url,
+    #[sea_orm(string_value = "Upload")]
+    Upload,
+    #[sea_orm(string_value = "BundledByTheme")]
+    BundledByTheme,
+}
+
+#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Serialize, Deserialize, utoipa::ToSchema)]
+#[sea_orm(table_name = "widget_module")]
+pub struct Model {
+    #[sea_orm(primary_key, auto_increment = false)]
+    pub id: String,
+    pub version: String,
+    pub source_type: SourceType,
+    pub source_url: Option<String>,
+    pub bundled_by_theme_id: Option<String>,
+    pub manifest_json: String,
+    pub code_sha256: String,
+    pub entry_path: String,
+    #[serde(skip)]
+    pub package_blob: Option<Vec<u8>>,
+    pub installed_by: Option<i64>,
+    pub installed_at: DateTimeUtc,
+    pub enabled: bool,
+}
+
+#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
+pub enum Relation {}
+
+impl ActiveModelBehavior for ActiveModel {}
+```
+
+- [ ] **Step 2: Register entity**
+
+In `crates/server/src/entity/mod.rs`, add:
+
+```rust
+pub mod widget_module;
+```
+
+- [ ] **Step 3: Build, verify compile**
+
+Run: `cargo build -p serverbee-server`
+Expected: success.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add crates/server/src/entity
+git -c commit.gpgsign=false commit -m "feat(server): widget_module sea-orm entity"
+```
+
+---
+
+## Task 18: Backend — migration for `widget_module`
+
+**Files:**
+- Create: `crates/server/src/migration/m20260528_000050_create_widget_module.rs`
+- Modify: `crates/server/src/migration/mod.rs`
+
+- [ ] **Step 1: Write migration**
+
+`crates/server/src/migration/m20260528_000050_create_widget_module.rs`:
+
+```rust
+use sea_orm_migration::prelude::*;
+
+#[derive(DeriveMigrationName)]
+pub struct Migration;
+
+#[async_trait::async_trait]
+impl MigrationTrait for Migration {
+    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        let db = manager.get_connection();
+        db.execute_unprepared(r#"
+            CREATE TABLE IF NOT EXISTS widget_module (
+                id                    TEXT NOT NULL PRIMARY KEY,
+                version               TEXT NOT NULL,
+                source_type           TEXT NOT NULL,
+                source_url            TEXT,
+                bundled_by_theme_id   TEXT,
+                manifest_json         TEXT NOT NULL,
+                code_sha256           TEXT NOT NULL,
+                entry_path            TEXT NOT NULL,
+                package_blob          BLOB,
+                installed_by          INTEGER,
+                installed_at          TEXT NOT NULL,
+                enabled               INTEGER NOT NULL DEFAULT 1
+            )
+        "#).await?;
+        db.execute_unprepared(
+            "CREATE INDEX IF NOT EXISTS idx_widget_module_source_type ON widget_module(source_type)",
+        ).await?;
+        db.execute_unprepared(
+            "CREATE INDEX IF NOT EXISTS idx_widget_module_theme ON widget_module(bundled_by_theme_id) WHERE bundled_by_theme_id IS NOT NULL",
+        ).await?;
+        Ok(())
+    }
+
+    async fn down(&self, _manager: &SchemaManager) -> Result<(), DbErr> {
+        Ok(())
+    }
+}
+```
+
+- [ ] **Step 2: Register migration**
+
+In `crates/server/src/migration/mod.rs`, find the `migrations()` vec and append the new module + entry. Example:
+
+```rust
+mod m20260528_000050_create_widget_module;
+// inside Migrator::migrations():
+Box::new(m20260528_000050_create_widget_module::Migration),
+```
+
+- [ ] **Step 3: Build & run server-side migration test (if any)**
+
+Run: `cargo build -p serverbee-server`
+Expected: success.
+
+Run: `cargo test -p serverbee-server migration --no-run` (compile only; quick check)
+Expected: success.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add crates/server/src/migration
+git -c commit.gpgsign=false commit -m "feat(server): migration for widget_module table"
+```
+
+---
+
+## Task 19: Backend — `WidgetManifest` Rust struct + JSDoc extractor
+
+**Files:**
+- Create: `crates/server/src/service/widget_module/mod.rs`
+- Create: `crates/server/src/service/widget_module/extractor.rs`
+- Modify: `crates/server/src/service/mod.rs`
+
+- [ ] **Step 1: Scaffold `mod.rs`**
+
+`crates/server/src/service/widget_module/mod.rs`:
+
+```rust
+pub mod extractor;
+pub mod error;
+pub mod service;
+
+pub use error::WidgetModuleError;
+pub use service::WidgetModuleService;
+```
+
+`crates/server/src/service/widget_module/error.rs`:
+
+```rust
+use crate::error::AppError;
+
+#[derive(Debug, thiserror::Error)]
+pub enum WidgetModuleError {
+    #[error("manifest extraction failed: {0}")]
+    ManifestExtraction(String),
+    #[error("manifest validation failed: {0}")]
+    ManifestValidation(String),
+    #[error("module id conflict: {0}")]
+    IdConflict(String),
+    #[error("module not found: {0}")]
+    NotFound(String),
+    #[error("invalid asset path")]
+    InvalidAssetPath,
+    #[error("database: {0}")]
+    Db(#[from] sea_orm::DbErr),
+}
+
+impl From<WidgetModuleError> for AppError {
+    fn from(err: WidgetModuleError) -> Self {
+        match err {
+            WidgetModuleError::NotFound(_) => AppError::not_found(err.to_string()),
+            WidgetModuleError::IdConflict(_) => AppError::conflict(err.to_string()),
+            WidgetModuleError::InvalidAssetPath
+            | WidgetModuleError::ManifestExtraction(_)
+            | WidgetModuleError::ManifestValidation(_) => AppError::bad_request(err.to_string()),
+            WidgetModuleError::Db(e) => AppError::internal(format!("db error: {e}")),
+        }
+    }
+}
+```
+
+- [ ] **Step 2: Write extractor tests**
+
+`crates/server/src/service/widget_module/extractor.rs`:
+
+```rust
+use serde::{Deserialize, Serialize};
+use regex::Regex;
+use once_cell::sync::Lazy;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, utoipa::ToSchema)]
+pub struct WidgetSizing {
+    pub default_w: u32,
+    pub default_h: u32,
+    pub min_w: u32,
+    pub min_h: u32,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_w: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_h: Option<u32>,
+    pub strategy: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, utoipa::ToSchema)]
+pub struct WidgetManifest {
+    pub id: String,
+    pub version: String,
+    pub name: String,
+    #[serde(default)]
+    pub description: Option<String>,
+    #[serde(default)]
+    pub author: Option<String>,
+    pub category: String,
+    pub sizing: WidgetSizing,
+    #[serde(default)]
+    pub required_caps: Option<Vec<String>>,
+    pub sdk_version: String,
+}
+
+static JSDOC_RE: Lazy<Regex> = Lazy::new(|| {
+    Regex::new(r"(?s)/\*\*[\s\S]*?@serverbee-widget\s+(\{[\s\S]*?\})[\s\S]*?\*/").unwrap()
+});
+
+static LINE_DECOR_RE: Lazy<Regex> = Lazy::new(|| Regex::new(r"(?m)^\s*\*\s?").unwrap());
+static SEMVER_RE: Lazy<Regex> = Lazy::new(|| Regex::new(r"^\d+\.\d+\.\d+(-[\w.]+)?$").unwrap());
+static SEMVER_RANGE_RE: Lazy<Regex> = Lazy::new(|| Regex::new(r"^[\^~]?\d+\.\d+\.\d+").unwrap());
+
+pub fn extract_manifest(source: &str) -> Result<WidgetManifest, super::WidgetModuleError> {
+    use super::WidgetModuleError as E;
+    let captures = JSDOC_RE.captures(source)
+        .ok_or_else(|| E::ManifestExtraction("no @serverbee-widget JSDoc block found".into()))?;
+    let raw_json = captures.get(1).unwrap().as_str();
+    let cleaned = LINE_DECOR_RE.replace_all(raw_json, "").to_string();
+
+    let manifest: WidgetManifest = serde_json::from_str(&cleaned)
+        .map_err(|e| E::ManifestExtraction(format!("invalid JSON: {e}")))?;
+
+    if manifest.id.is_empty() { return Err(E::ManifestValidation("id required".into())); }
+    if !SEMVER_RE.is_match(&manifest.version) {
+        return Err(E::ManifestValidation("version must be semver".into()));
+    }
+    if manifest.name.is_empty() { return Err(E::ManifestValidation("name required".into())); }
+    if !matches!(manifest.category.as_str(), "Real-time" | "Charts" | "Status") {
+        return Err(E::ManifestValidation("category invalid".into()));
+    }
+    if !matches!(manifest.sizing.strategy.as_str(), "fixed" | "free" | "aspect-square" | "content-height") {
+        return Err(E::ManifestValidation("sizing.strategy invalid".into()));
+    }
+    if !SEMVER_RANGE_RE.is_match(&manifest.sdk_version) {
+        return Err(E::ManifestValidation("sdkVersion must be semver range".into()));
+    }
+    Ok(manifest)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const GOOD: &str = r#"/**
+ * @serverbee-widget {
+ *   "id": "com.example.cpu",
+ *   "version": "1.0.0",
+ *   "name": "CPU",
+ *   "category": "Real-time",
+ *   "sizing": { "defaultW": 3, "defaultH": 3, "minW": 2, "minH": 2, "strategy": "aspect-square" },
+ *   "sdkVersion": "^0.1.0"
+ * }
+ */
+export default {};
+"#;
+
+    #[test]
+    fn extracts_a_valid_manifest() {
+        let m = extract_manifest(GOOD).unwrap();
+        assert_eq!(m.id, "com.example.cpu");
+        assert_eq!(m.sizing.strategy, "aspect-square");
+    }
+
+    #[test]
+    fn rejects_missing_block() {
+        let res = extract_manifest("export default {};");
+        assert!(matches!(res.unwrap_err(), super::super::WidgetModuleError::ManifestExtraction(_)));
+    }
+
+    #[test]
+    fn rejects_invalid_category() {
+        let src = GOOD.replace(r#""category": "Real-time""#, r#""category": "Bogus""#);
+        let res = extract_manifest(&src);
+        assert!(res.is_err());
+    }
+
+    #[test]
+    fn rejects_invalid_semver() {
+        let src = GOOD.replace(r#""version": "1.0.0""#, r#""version": "not-semver""#);
+        assert!(extract_manifest(&src).is_err());
+    }
+}
+```
+
+- [ ] **Step 3: Register module**
+
+In `crates/server/src/service/mod.rs`:
+
+```rust
+pub mod widget_module;
+```
+
+In `crates/server/Cargo.toml`, ensure dependencies present (most should already exist):
+- `regex = "1"` (likely present)
+- `once_cell = "1"` (likely present)
+- `thiserror = "1"` (likely present)
+
+If any missing, add to `[dependencies]`.
+
+- [ ] **Step 4: Run extractor tests**
+
+Run: `cargo test -p serverbee-server service::widget_module::extractor --lib`
+Expected: 4 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/server/src/service crates/server/Cargo.toml
+git -c commit.gpgsign=false commit -m "feat(server): widget manifest JSDoc extractor + validator"
+```
+
+---
+
+## Task 20: Backend — `WidgetModuleService` (list / get / serve_asset)
+
+**Files:**
+- Create: `crates/server/src/service/widget_module/service.rs`
+- Create: `crates/server/src/service/widget_module/package.rs`
+
+- [ ] **Step 1: Write package layout helper**
+
+`crates/server/src/service/widget_module/package.rs`:
+
+```rust
+use std::collections::HashMap;
+use std::io::{Cursor, Read};
+use super::WidgetModuleError;
+
+/// In-memory representation of a module package, addressable by path.
+pub struct UnpackedPackage {
+    pub entries: HashMap<String, Vec<u8>>,
+}
+
+impl UnpackedPackage {
+    /// A single-file package: entry_path is treated as the only file name.
+    pub fn from_single_file(entry_path: &str, code: Vec<u8>) -> Self {
+        let mut entries = HashMap::new();
+        entries.insert(entry_path.to_string(), code);
+        Self { entries }
+    }
+
+    /// Unpack a zip blob (defends against zip-slip and oversize entries).
+    pub fn from_zip(blob: &[u8]) -> Result<Self, WidgetModuleError> {
+        const MAX_ENTRY_BYTES: u64 = 5 * 1024 * 1024;
+        let reader = Cursor::new(blob);
+        let mut zip = zip::ZipArchive::new(reader)
+            .map_err(|e| WidgetModuleError::ManifestExtraction(format!("invalid zip: {e}")))?;
+        let mut entries = HashMap::new();
+        for i in 0..zip.len() {
+            let mut entry = zip.by_index(i)
+                .map_err(|e| WidgetModuleError::ManifestExtraction(format!("zip entry: {e}")))?;
+            if entry.is_dir() { continue; }
+            let name = entry.enclosed_name()
+                .ok_or(WidgetModuleError::InvalidAssetPath)?
+                .to_string_lossy().to_string();
+            if entry.size() > MAX_ENTRY_BYTES {
+                return Err(WidgetModuleError::ManifestExtraction(format!("entry too large: {name}")));
+            }
+            let mut buf = Vec::with_capacity(entry.size() as usize);
+            entry.read_to_end(&mut buf)
+                .map_err(|e| WidgetModuleError::ManifestExtraction(format!("read: {e}")))?;
+            entries.insert(name, buf);
+        }
+        Ok(Self { entries })
+    }
+
+    pub fn get(&self, path: &str) -> Option<&[u8]> {
+        let normalised = path.trim_start_matches('/');
+        if normalised.contains("..") { return None; }
+        self.entries.get(normalised).map(|v| v.as_slice())
+    }
+}
+```
+
+If `zip` crate is not in `Cargo.toml`, add: `zip = { version = "2", default-features = false, features = ["deflate"] }`.
+
+- [ ] **Step 2: Write service**
+
+`crates/server/src/service/widget_module/service.rs`:
+
+```rust
+use sea_orm::{ColumnTrait, DatabaseConnection, EntityTrait, QueryFilter, QueryOrder};
+use serde::Serialize;
+
+use super::{WidgetModuleError, extractor::WidgetManifest, package::UnpackedPackage};
+use crate::entity::widget_module::{self, Entity as WidgetModuleEntity, SourceType};
+
+#[derive(Debug, Serialize, utoipa::ToSchema)]
+pub struct WidgetModuleListEntry {
+    pub id: String,
+    pub version: String,
+    pub source_type: SourceType,
+    pub entry_path: String,
+    pub code_sha256: String,
+    pub manifest: serde_json::Value,
+    pub enabled: bool,
+}
+
+pub struct WidgetModuleService;
+
+impl WidgetModuleService {
+    pub async fn list(db: &DatabaseConnection) -> Result<Vec<WidgetModuleListEntry>, WidgetModuleError> {
+        let rows = WidgetModuleEntity::find()
+            .filter(widget_module::Column::Enabled.eq(true))
+            .order_by_asc(widget_module::Column::Id)
+            .all(db)
+            .await?;
+        rows.into_iter().map(|r| {
+            let manifest: serde_json::Value = serde_json::from_str(&r.manifest_json)
+                .map_err(|e| WidgetModuleError::ManifestValidation(format!("stored manifest invalid: {e}")))?;
+            Ok(WidgetModuleListEntry {
+                id: r.id,
+                version: r.version,
+                source_type: r.source_type,
+                entry_path: r.entry_path,
+                code_sha256: r.code_sha256,
+                manifest,
+                enabled: r.enabled,
+            })
+        }).collect()
+    }
+
+    pub async fn get(db: &DatabaseConnection, id: &str) -> Result<widget_module::Model, WidgetModuleError> {
+        WidgetModuleEntity::find_by_id(id.to_string())
+            .one(db)
+            .await?
+            .ok_or_else(|| WidgetModuleError::NotFound(id.to_string()))
+    }
+
+    /// Loads a package from BLOB and returns the bytes of a single asset path.
+    /// `entry_path` is the module's main file; other paths may be relative imports or assets.
+    pub async fn serve_asset(
+        db: &DatabaseConnection, id: &str, requested: &str,
+    ) -> Result<(Vec<u8>, String), WidgetModuleError> {
+        let row = Self::get(db, id).await?;
+        let blob = row.package_blob.ok_or_else(|| WidgetModuleError::NotFound(format!("{id}: no blob (builtin?)")))?;
+
+        // Heuristic: single-file packages store the entire entry as their blob.
+        // Multi-file (zip) packages are decoded via zip crate.
+        let package = if blob.starts_with(b"PK\x03\x04") {
+            UnpackedPackage::from_zip(&blob)?
+        } else {
+            UnpackedPackage::from_single_file(&row.entry_path, blob)
+        };
+
+        let bytes = package.get(requested)
+            .ok_or(WidgetModuleError::InvalidAssetPath)?
+            .to_vec();
+        let mime = mime_for(requested);
+        Ok((bytes, mime))
+    }
+}
+
+fn mime_for(path: &str) -> String {
+    let lower = path.to_ascii_lowercase();
+    if lower.ends_with(".js") || lower.ends_with(".mjs") { "text/javascript; charset=utf-8" }
+    else if lower.ends_with(".json") { "application/json" }
+    else if lower.ends_with(".css") { "text/css" }
+    else if lower.ends_with(".svg") { "image/svg+xml" }
+    else if lower.ends_with(".png") { "image/png" }
+    else if lower.ends_with(".jpg") || lower.ends_with(".jpeg") { "image/jpeg" }
+    else if lower.ends_with(".webp") { "image/webp" }
+    else { "application/octet-stream" }
+    .to_string()
+}
+```
+
+- [ ] **Step 3: Build, verify compile**
+
+Run: `cargo build -p serverbee-server`
+Expected: success.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add crates/server/src/service/widget_module crates/server/Cargo.toml
+git -c commit.gpgsign=false commit -m "feat(server): WidgetModuleService (list/get/serve_asset) + package extractor"
+```
+
+---
+
+## Task 21: Backend — API routes `/api/widget-modules`
+
+**Files:**
+- Create: `crates/server/src/router/api/widget_module.rs`
+- Modify: `crates/server/src/router/api/mod.rs`
+- Modify: `crates/server/src/openapi.rs`
+
+- [ ] **Step 1: Write routes file**
+
+`crates/server/src/router/api/widget_module.rs`:
+
+```rust
+use std::sync::Arc;
+use axum::{
+    extract::{Path, State},
+    http::{header, HeaderMap, HeaderValue, StatusCode},
+    response::IntoResponse,
+    routing::get,
+    Json, Router,
+};
+
+use crate::{
+    error::{AppError, ApiResponse, ok},
+    service::widget_module::{WidgetModuleService, service::WidgetModuleListEntry},
+    state::AppState,
+};
+
+pub fn read_router() -> Router<Arc<AppState>> {
+    Router::new()
+        .route("/widget-modules", get(list_modules))
+        .route("/widget-modules/{id}/{*asset_path}", get(serve_asset))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/widget-modules",
+    tag = "widget-modules",
+    responses((status = 200, body = Vec<WidgetModuleListEntry>)),
+    security(("session_cookie" = []), ("api_key" = []))
+)]
+async fn list_modules(
+    State(state): State<Arc<AppState>>,
+) -> Result<Json<ApiResponse<Vec<WidgetModuleListEntry>>>, AppError> {
+    let modules = WidgetModuleService::list(&state.db).await?;
+    ok(modules)
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/widget-modules/{id}/{asset_path}",
+    tag = "widget-modules",
+    params(
+        ("id" = String, Path),
+        ("asset_path" = String, Path)
+    ),
+    responses((status = 200, description = "Asset bytes"), (status = 404)),
+    security(("session_cookie" = []), ("api_key" = []))
+)]
+async fn serve_asset(
+    State(state): State<Arc<AppState>>,
+    Path((id, asset_path)): Path<(String, String)>,
+) -> Result<impl IntoResponse, AppError> {
+    let (bytes, mime) = WidgetModuleService::serve_asset(&state.db, &id, &asset_path).await?;
+    let row = WidgetModuleService::get(&state.db, &id).await?;
+    let etag = format!("\"{}-{}\"", row.version, &row.code_sha256[..8]);
+
+    let mut headers = HeaderMap::new();
+    headers.insert(header::CONTENT_TYPE, HeaderValue::from_str(&mime).unwrap());
+    headers.insert(header::ETAG, HeaderValue::from_str(&etag).unwrap());
+    headers.insert(header::CACHE_CONTROL, HeaderValue::from_static("public, max-age=86400, immutable"));
+    Ok((StatusCode::OK, headers, bytes))
+}
+```
+
+- [ ] **Step 2: Mount router**
+
+In `crates/server/src/router/api/mod.rs`, in the function that composes read routes, merge the new router:
+
+```rust
+pub mod widget_module;
+// inside the read router builder:
+.merge(widget_module::read_router())
+```
+
+- [ ] **Step 3: Register OpenAPI**
+
+In `crates/server/src/openapi.rs`, add the new paths and schemas to the `OpenApi` derive list:
+
+```rust
+paths(
+    // ... existing paths,
+    crate::router::api::widget_module::list_modules,
+    crate::router::api::widget_module::serve_asset,
+),
+components(schemas(
+    // ... existing schemas,
+    crate::service::widget_module::service::WidgetModuleListEntry,
+    crate::entity::widget_module::SourceType,
+)),
+```
+
+- [ ] **Step 4: Build, verify compile**
+
+Run: `cargo build -p serverbee-server`
+Expected: success.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/server/src/router/api crates/server/src/openapi.rs
+git -c commit.gpgsign=false commit -m "feat(server): /api/widget-modules list + asset endpoints"
+```
+
+---
+
+## Task 22: Backend — integration test for list + asset roundtrip
+
+**Files:**
+- Create: `crates/server/tests/widget_module_integration.rs`
+
+- [ ] **Step 1: Write integration test**
+
+`crates/server/tests/widget_module_integration.rs`:
+
+```rust
+// Reuse the in-process test server from the main integration suite.
+// Project convention: each integration test file is its own cargo target,
+// but we re-use the helper module by path.
+
+#[path = "integration.rs"]
+mod integration;
+
+use sea_orm::ActiveValue::Set;
+use sea_orm::{ActiveModelTrait, DatabaseConnection};
+use chrono::Utc;
+use serverbee_server::entity::widget_module::{self, SourceType};
+use serverbee_server::service::widget_module::extractor::extract_manifest;
+
+#[tokio::test]
+async fn list_returns_seeded_module() {
+    let (base, _tmp, db) = integration::start_test_server().await.expect("server");
+    seed_module(&db, "com.test.foo").await;
+
+    let client = reqwest::Client::new();
+    let res = client.get(format!("{base}/api/widget-modules"))
+        .send().await.unwrap();
+    assert_eq!(res.status(), 200);
+    let body: serde_json::Value = res.json().await.unwrap();
+    let list = body["data"].as_array().unwrap();
+    assert!(list.iter().any(|m| m["id"] == "com.test.foo"));
+}
+
+#[tokio::test]
+async fn serve_asset_returns_entry_bytes() {
+    let (base, _tmp, db) = integration::start_test_server().await.expect("server");
+    seed_module(&db, "com.test.foo").await;
+
+    let res = reqwest::get(format!("{base}/api/widget-modules/com.test.foo/index.js"))
+        .await.unwrap();
+    assert_eq!(res.status(), 200);
+    assert!(res.headers().get("content-type").unwrap().to_str().unwrap().contains("javascript"));
+    assert!(res.headers().contains_key("etag"));
+    let body = res.text().await.unwrap();
+    assert!(body.contains("@serverbee-widget"));
+}
+
+#[tokio::test]
+async fn serve_asset_rejects_path_traversal() {
+    let (base, _tmp, db) = integration::start_test_server().await.expect("server");
+    seed_module(&db, "com.test.foo").await;
+
+    let res = reqwest::get(format!("{base}/api/widget-modules/com.test.foo/../secret"))
+        .await.unwrap();
+    assert!(res.status().is_client_error() || res.status() == reqwest::StatusCode::NOT_FOUND);
+}
+
+async fn seed_module(db: &DatabaseConnection, id: &str) {
+    let code = format!(r#"/**
+ * @serverbee-widget {{
+ *   "id": "{id}",
+ *   "version": "1.0.0",
+ *   "name": "Foo",
+ *   "category": "Real-time",
+ *   "sizing": {{ "defaultW": 3, "defaultH": 3, "minW": 2, "minH": 2, "strategy": "aspect-square" }},
+ *   "sdkVersion": "^0.1.0"
+ * }}
+ */
+export default {{}};"#);
+    let manifest = extract_manifest(&code).expect("manifest");
+    let sha = sha256_hex(code.as_bytes());
+
+    widget_module::ActiveModel {
+        id: Set(id.to_string()),
+        version: Set("1.0.0".into()),
+        source_type: Set(SourceType::Upload),
+        source_url: Set(None),
+        bundled_by_theme_id: Set(None),
+        manifest_json: Set(serde_json::to_string(&manifest).unwrap()),
+        code_sha256: Set(sha),
+        entry_path: Set("index.js".into()),
+        package_blob: Set(Some(code.into_bytes())),
+        installed_by: Set(None),
+        installed_at: Set(Utc::now()),
+        enabled: Set(true),
+    }
+    .insert(db).await.unwrap();
+}
+
+fn sha256_hex(bytes: &[u8]) -> String {
+    use sha2::{Digest, Sha256};
+    let mut hasher = Sha256::new();
+    hasher.update(bytes);
+    format!("{:x}", hasher.finalize())
+}
+```
+
+Update `integration.rs::start_test_server()` if needed so it returns `(String, TempDir, DatabaseConnection)` instead of `(String, TempDir)`. If the existing signature differs, instead of changing it, expose a helper there: `pub async fn start_test_server_with_db() -> ...`. Inspect the existing file before editing.
+
+In `crates/server/Cargo.toml` `[dev-dependencies]`, ensure `sha2`, `reqwest = { version = "...", features = ["json"] }` are present (likely already).
+
+- [ ] **Step 2: Run integration tests**
+
+Run: `cargo test -p serverbee-server --test widget_module_integration`
+Expected: 3 tests PASS.
+
+- [ ] **Step 3: Run full test suite**
+
+Run: `cargo test -p serverbee-server`
+Expected: existing tests unaffected.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add crates/server/tests/widget_module_integration.rs crates/server/Cargo.toml crates/server/tests/integration.rs
+git -c commit.gpgsign=false commit -m "test(server): integration tests for widget_module list + asset"
+```
+
+---
+
+## Task 23: Wire SDK exports + final typecheck/build sanity
+
+**Files:**
+- Modify: `packages/widget-sdk/src/index.ts`
+
+- [ ] **Step 1: Make sure index.ts exports the full public surface**
+
+`packages/widget-sdk/src/index.ts` (final form):
+
+```ts
+export const SDK_VERSION = '0.1.0'
+
+// Types & validators
+export { validateManifest } from './manifest'
+export type { WidgetManifest, WidgetCategory, WidgetSizing, SizingStrategy } from './manifest'
+
+// defineWidget
+export { defineWidget } from './define-widget'
+export type {
+  WidgetModule, WidgetComponentProps,
+  ActionDefinition, ActionContext, ActionsHelper,
+} from './define-widget'
+
+// Schema
+export { z, ZodSchema, type ZodTypeAny, type Infer, ZError } from './z'
+
+// Runtime context
+export { createWidgetRuntime, getRuntime, resetRuntime } from './runtime-context'
+export type { WidgetRuntime, ServerSummary } from './runtime-context'
+
+// Hooks
+export * from './hooks'
+
+// Actions
+export { createActionsHelper } from './actions'
+
+// Form
+export { renderConfigForm } from './form'
+```
+
+- [ ] **Step 2: Full SDK test suite + typecheck**
+
+Run: `cd packages/widget-sdk && bunx vitest run`
+Expected: all tests PASS.
+
+Run: `cd packages/widget-sdk && bunx tsc --noEmit`
+Expected: no errors.
+
+- [ ] **Step 3: Full apps/web test + build**
+
+Run: `cd apps/web && bun run test`
+Expected: all existing tests + new registry/loader tests PASS.
+
+Run: `cd apps/web && bun run typecheck && bun run build`
+Expected: success.
+
+- [ ] **Step 4: Full Rust workspace check**
+
+Run: `cargo clippy --workspace -- -D warnings`
+Expected: success (0 warnings).
+
+Run: `cargo test --workspace`
+Expected: all tests PASS.
+
+- [ ] **Step 5: Commit & celebrate Plan 1 completion**
+
+```bash
+git add packages/widget-sdk/src/index.ts
+git -c commit.gpgsign=false commit -m "feat(widget-sdk): finalise public exports surface"
+```
+
+---
+
+## Plan 1 — Completion Criteria
+
+After all 23 tasks, the following must hold:
+
+- `bun install` succeeds at repo root with `@serverbee/widget-sdk` symlinked into `apps/web/node_modules`.
+- `cd packages/widget-sdk && bunx vitest run` — all SDK tests pass.
+- `cd apps/web && bun run test && bun run typecheck && bun run build` — frontend builds.
+- `cargo clippy --workspace -- -D warnings` — clean.
+- `cargo test --workspace` — passes, including the new `widget_module_integration` suite.
+- `GET /api/widget-modules` returns `{ "data": [] }` on a fresh DB.
+- A seeded module can be served byte-perfect through `GET /api/widget-modules/{id}/index.js`, with `ETag` and `Cache-Control: immutable` headers.
+- The `<script type="importmap">` is in `index.html`; the four shim files exist under `apps/web/public/runtime/`.
+
+What is intentionally **not** delivered in Plan 1 (handled in later plans):
+
+- Built-in widget compilation pipeline (Plan 2A).
+- Wiring `serversStore` / `serverByIdStore` / `onConfigUpdate` to the real WS/dashboard state (Plan 2A).
+- URL/Upload install UX (Plan 3A).
+- Theme system (Plan 3B).
+- Deletion of legacy `spa_theme` / `custom_theme` (Plan 3C).
+- Documentation site updates (Plan 4).
+
+---
+
+## Self-Review Notes (for executor)
+
+- Tasks 5–6 require Task 4's stub file to compile; do not skip ahead.
+- Task 7's `runtime-context.ts` import in Task 8's `live.ts` is essential — verify with `tsc --noEmit` after Task 8.
+- Task 16's shim files must be in `public/`, not `src/`, so Vite copies them through.
+- Task 18's migration filename includes the timestamp `m20260528_000050` — keep it lexicographically after the most recent existing migration so the runtime ordering is correct. Verify by `ls crates/server/src/migration | tail -3` before adding.
+- Task 22's `start_test_server()` signature change is invasive — prefer adding a second helper to the existing test file rather than editing the signature.

From 94994cebcceb7a4de96e77f37fb8d0677bf057e0 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:08:08 +0800
Subject: [PATCH 04/64] feat(widget-sdk): scaffold workspace package

---
 apps/web/package.json             |  1 +
 bun.lock                          | 21 ++++++++++++++++++++
 packages/widget-sdk/README.md     |  3 +++
 packages/widget-sdk/package.json  | 33 +++++++++++++++++++++++++++++++
 packages/widget-sdk/src/index.ts  |  1 +
 packages/widget-sdk/tsconfig.json | 17 ++++++++++++++++
 6 files changed, 76 insertions(+)
 create mode 100644 packages/widget-sdk/README.md
 create mode 100644 packages/widget-sdk/package.json
 create mode 100644 packages/widget-sdk/src/index.ts
 create mode 100644 packages/widget-sdk/tsconfig.json

diff --git a/apps/web/package.json b/apps/web/package.json
index de7f205a..5d3a1a68 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -17,6 +17,7 @@
     "@base-ui/react": "^1.2.0",
     "@fontsource-variable/inter": "^5.2.8",
     "@monaco-editor/react": "^4.7.0",
+    "@serverbee/widget-sdk": "workspace:*",
     "@tailwindcss/vite": "^4.1.17",
     "@tanstack/react-query": "^5.90.21",
     "@tanstack/react-router": "^1.166.7",
diff --git a/bun.lock b/bun.lock
index 366c2fc6..fbd5ebc6 100644
--- a/bun.lock
+++ b/bun.lock
@@ -55,6 +55,7 @@
         "@base-ui/react": "^1.2.0",
         "@fontsource-variable/inter": "^5.2.8",
         "@monaco-editor/react": "^4.7.0",
+        "@serverbee/widget-sdk": "workspace:*",
         "@tailwindcss/vite": "^4.1.17",
         "@tanstack/react-query": "^5.90.21",
         "@tanstack/react-router": "^1.166.7",
@@ -197,6 +198,24 @@
         "typescript": "^5.9.3",
       },
     },
+    "packages/widget-sdk": {
+      "name": "@serverbee/widget-sdk",
+      "version": "0.1.0",
+      "devDependencies": {
+        "@tanstack/react-query": "^5.90.21",
+        "@testing-library/react": "^16.3.2",
+        "@types/react": "^19.2.5",
+        "jsdom": "^28.1.0",
+        "react": "^19.2.0",
+        "react-dom": "^19.2.0",
+        "typescript": "~5.9.3",
+        "vitest": "^4.1.0",
+      },
+      "peerDependencies": {
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0",
+      },
+    },
   },
   "catalog": {
     "@libsql/client": "0.15.15",
@@ -972,6 +991,8 @@
 
     "@serverbee/web": ["@serverbee/web@workspace:apps/web"],
 
+    "@serverbee/widget-sdk": ["@serverbee/widget-sdk@workspace:packages/widget-sdk"],
+
     "@shikijs/core": ["@shikijs/core@4.0.2", "", { "dependencies": { "@shikijs/primitive": "4.0.2", "@shikijs/types": "4.0.2", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.4", "hast-util-to-html": "^9.0.5" } }, "sha512-hxT0YF4ExEqB8G/qFdtJvpmHXBYJ2lWW7qTHDarVkIudPFE6iCIrqdgWxGn5s+ppkGXI0aEGlibI0PAyzP3zlw=="],
 
     "@shikijs/engine-javascript": ["@shikijs/engine-javascript@4.0.2", "", { "dependencies": { "@shikijs/types": "4.0.2", "@shikijs/vscode-textmate": "^10.0.2", "oniguruma-to-es": "^4.3.4" } }, "sha512-7PW0Nm49DcoUIQEXlJhNNBHyoGMjalRETTCcjMqEaMoJRLljy1Bi/EGV3/qLBgLKQejdspiiYuHGQW6dX94Nag=="],
diff --git a/packages/widget-sdk/README.md b/packages/widget-sdk/README.md
new file mode 100644
index 00000000..3e3c24e8
--- /dev/null
+++ b/packages/widget-sdk/README.md
@@ -0,0 +1,3 @@
+# @serverbee/widget-sdk
+
+Stable API surface for ServerBee custom widgets. Authors `import { defineWidget, z, useMetric } from '@serverbee/widget-sdk'`. See the developer guide at apps/docs/content/docs/{en,cn}/widgets/single-file-guide.mdx.
diff --git a/packages/widget-sdk/package.json b/packages/widget-sdk/package.json
new file mode 100644
index 00000000..b470b666
--- /dev/null
+++ b/packages/widget-sdk/package.json
@@ -0,0 +1,33 @@
+{
+  "name": "@serverbee/widget-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./src/index.ts"
+    },
+    "./z": {
+      "default": "./src/z/index.ts"
+    },
+    "./hooks": {
+      "default": "./src/hooks/index.ts"
+    },
+    "./actions": {
+      "default": "./src/actions/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.90.21",
+    "@types/react": "^19.2.5",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.0",
+    "jsdom": "^28.1.0",
+    "@testing-library/react": "^16.3.2"
+  }
+}
diff --git a/packages/widget-sdk/src/index.ts b/packages/widget-sdk/src/index.ts
new file mode 100644
index 00000000..f151ab81
--- /dev/null
+++ b/packages/widget-sdk/src/index.ts
@@ -0,0 +1 @@
+export const SDK_VERSION = '0.1.0'
diff --git a/packages/widget-sdk/tsconfig.json b/packages/widget-sdk/tsconfig.json
new file mode 100644
index 00000000..6af96d63
--- /dev/null
+++ b/packages/widget-sdk/tsconfig.json
@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"]
+  },
+  "include": ["src/**/*", "tests/**/*"]
+}

From 3fa5dcafe895392bd58ace3ef3217ca5fc09ed25 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:08:40 +0800
Subject: [PATCH 05/64] build(web): alias @serverbee/widget-sdk to source

---
 apps/web/tsconfig.json  | 10 +++++++++-
 apps/web/vite.config.ts | 24 ++++++++++++++++++++++--
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index fec8c8e5..71dfe642 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -7,7 +7,15 @@
   "compilerOptions": {
     "baseUrl": ".",
     "paths": {
-      "@/*": ["./src/*"]
+      "@/*": ["./src/*"],
+      "@serverbee/widget-sdk": ["../../packages/widget-sdk/src/index.ts"],
+      "@serverbee/widget-sdk/z": ["../../packages/widget-sdk/src/z/index.ts"],
+      "@serverbee/widget-sdk/hooks": [
+        "../../packages/widget-sdk/src/hooks/index.ts"
+      ],
+      "@serverbee/widget-sdk/actions": [
+        "../../packages/widget-sdk/src/actions/index.ts"
+      ]
     }
   }
 }
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index 6ed146b9..e3a4677c 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -70,7 +70,17 @@ export default defineConfig(({ mode }) => {
       ],
       resolve: {
         alias: {
-          '@': path.resolve(import.meta.dirname, './src')
+          '@': path.resolve(import.meta.dirname, './src'),
+          '@serverbee/widget-sdk': path.resolve(import.meta.dirname, '../../packages/widget-sdk/src/index.ts'),
+          '@serverbee/widget-sdk/z': path.resolve(import.meta.dirname, '../../packages/widget-sdk/src/z/index.ts'),
+          '@serverbee/widget-sdk/hooks': path.resolve(
+            import.meta.dirname,
+            '../../packages/widget-sdk/src/hooks/index.ts'
+          ),
+          '@serverbee/widget-sdk/actions': path.resolve(
+            import.meta.dirname,
+            '../../packages/widget-sdk/src/actions/index.ts'
+          )
         }
       },
       build: {
@@ -134,7 +144,17 @@ export default defineConfig(({ mode }) => {
     ],
     resolve: {
       alias: {
-        '@': path.resolve(import.meta.dirname, './src')
+        '@': path.resolve(import.meta.dirname, './src'),
+        '@serverbee/widget-sdk': path.resolve(import.meta.dirname, '../../packages/widget-sdk/src/index.ts'),
+        '@serverbee/widget-sdk/z': path.resolve(import.meta.dirname, '../../packages/widget-sdk/src/z/index.ts'),
+        '@serverbee/widget-sdk/hooks': path.resolve(
+          import.meta.dirname,
+          '../../packages/widget-sdk/src/hooks/index.ts'
+        ),
+        '@serverbee/widget-sdk/actions': path.resolve(
+          import.meta.dirname,
+          '../../packages/widget-sdk/src/actions/index.ts'
+        )
       }
     },
     build: {

From 0e2f618ea132c93813dd57ec94215b30d5884369 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:11:51 +0800
Subject: [PATCH 06/64] feat(widget-sdk): WidgetManifest types + validator

---
 packages/widget-sdk/src/index.ts           |  2 +
 packages/widget-sdk/src/manifest.ts        | 73 ++++++++++++++++++++++
 packages/widget-sdk/tests/manifest.test.ts | 31 +++++++++
 3 files changed, 106 insertions(+)
 create mode 100644 packages/widget-sdk/src/manifest.ts
 create mode 100644 packages/widget-sdk/tests/manifest.test.ts

diff --git a/packages/widget-sdk/src/index.ts b/packages/widget-sdk/src/index.ts
index f151ab81..555fc5b3 100644
--- a/packages/widget-sdk/src/index.ts
+++ b/packages/widget-sdk/src/index.ts
@@ -1 +1,3 @@
 export const SDK_VERSION = '0.1.0'
+export type { SizingStrategy, WidgetCategory, WidgetManifest, WidgetSizing } from './manifest'
+export { validateManifest } from './manifest'
diff --git a/packages/widget-sdk/src/manifest.ts b/packages/widget-sdk/src/manifest.ts
new file mode 100644
index 00000000..9cbb34e8
--- /dev/null
+++ b/packages/widget-sdk/src/manifest.ts
@@ -0,0 +1,73 @@
+export type WidgetCategory = 'Real-time' | 'Charts' | 'Status'
+
+export type SizingStrategy = 'fixed' | 'free' | 'aspect-square' | 'content-height'
+
+export interface WidgetSizing {
+  defaultH: number
+  defaultW: number
+  maxH?: number
+  maxW?: number
+  minH: number
+  minW: number
+  strategy: SizingStrategy
+}
+
+export interface WidgetManifest {
+  author?: string
+  category: WidgetCategory
+  description?: string
+  id: string
+  name: string
+  requiredCaps?: string[]
+  sdkVersion: string
+  sizing: WidgetSizing
+  version: string
+}
+
+const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.]+)?$/
+const SEMVER_RANGE_RE = /^[\^~]?\d+\.\d+\.\d+/
+const VALID_CATEGORIES = new Set<WidgetCategory>(['Real-time', 'Charts', 'Status'])
+const VALID_STRATEGIES = new Set<SizingStrategy>(['fixed', 'free', 'aspect-square', 'content-height'])
+
+export function validateManifest(input: unknown): WidgetManifest {
+  if (!input || typeof input !== 'object') {
+    throw new Error('manifest must be an object')
+  }
+  const m = input as Record<string, any>
+
+  if (typeof m.id !== 'string' || m.id.length === 0) {
+    throw new Error('manifest.id required')
+  }
+  if (typeof m.version !== 'string' || !SEMVER_RE.test(m.version)) {
+    throw new Error('manifest.version must be valid semver')
+  }
+  if (typeof m.name !== 'string' || m.name.length === 0) {
+    throw new Error('manifest.name required')
+  }
+  if (!VALID_CATEGORIES.has(m.category)) {
+    throw new Error('manifest.category invalid')
+  }
+  if (!m.sizing || typeof m.sizing !== 'object') {
+    throw new Error('manifest.sizing required')
+  }
+
+  const sz = m.sizing as Record<string, any>
+  for (const k of ['defaultW', 'defaultH', 'minW', 'minH'] as const) {
+    if (typeof sz[k] !== 'number') {
+      throw new Error(`manifest.sizing.${k} must be number`)
+    }
+  }
+  if (!VALID_STRATEGIES.has(sz.strategy)) {
+    throw new Error('manifest.sizing.strategy invalid')
+  }
+
+  if (typeof m.sdkVersion !== 'string' || !SEMVER_RANGE_RE.test(m.sdkVersion)) {
+    throw new Error('manifest.sdkVersion must be valid semver range')
+  }
+
+  if (m.requiredCaps !== undefined && !Array.isArray(m.requiredCaps)) {
+    throw new Error('manifest.requiredCaps must be array')
+  }
+
+  return m as WidgetManifest
+}
diff --git a/packages/widget-sdk/tests/manifest.test.ts b/packages/widget-sdk/tests/manifest.test.ts
new file mode 100644
index 00000000..07cc0be3
--- /dev/null
+++ b/packages/widget-sdk/tests/manifest.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { validateManifest } from '../src/manifest'
+
+describe('validateManifest', () => {
+  const base = {
+    id: 'com.example.foo',
+    version: '1.0.0',
+    name: 'Foo',
+    category: 'Real-time' as const,
+    sizing: { defaultW: 3, defaultH: 3, minW: 2, minH: 2, strategy: 'aspect-square' as const },
+    sdkVersion: '^0.1.0'
+  }
+
+  it('accepts a minimal valid manifest', () => {
+    expect(validateManifest(base)).toEqual(base)
+  })
+
+  it('rejects missing id', () => {
+    expect(() => validateManifest({ ...base, id: '' })).toThrow(/id/)
+  })
+
+  it('rejects unknown sizing strategy', () => {
+    expect(() => validateManifest({ ...base, sizing: { ...base.sizing, strategy: 'bogus' as any } })).toThrow(
+      /strategy/
+    )
+  })
+
+  it('rejects invalid semver', () => {
+    expect(() => validateManifest({ ...base, version: 'not-semver' })).toThrow(/version/)
+  })
+})

From ebe3153bf7954d5076378d0145386fe7e78239c2 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:23:44 +0800
Subject: [PATCH 07/64] feat(widget-sdk): defineWidget + WidgetModule types

---
 packages/widget-sdk/src/define-widget.ts      | 52 +++++++++++++++++++
 packages/widget-sdk/src/index.ts              |  8 +++
 packages/widget-sdk/src/z/index.ts            |  2 +
 .../widget-sdk/tests/define-widget.test.ts    | 28 ++++++++++
 4 files changed, 90 insertions(+)
 create mode 100644 packages/widget-sdk/src/define-widget.ts
 create mode 100644 packages/widget-sdk/src/z/index.ts
 create mode 100644 packages/widget-sdk/tests/define-widget.test.ts

diff --git a/packages/widget-sdk/src/define-widget.ts b/packages/widget-sdk/src/define-widget.ts
new file mode 100644
index 00000000..ed60d999
--- /dev/null
+++ b/packages/widget-sdk/src/define-widget.ts
@@ -0,0 +1,52 @@
+import type { ComponentType, ReactNode } from 'react'
+import type { Infer, ZodTypeAny } from './z'
+
+export interface ActionContext {
+  apiMutation: <Req = unknown, Res = unknown>(method: string, path: string, body?: Req) => Promise<Res>
+}
+
+export interface ActionDefinition {
+  confirm?: { title: string; body?: string }
+  icon?: string
+  id: string
+  label: string
+  run: (ctx: ActionContext) => Promise<void>
+}
+
+export interface ActionsHelper {
+  render: (id: string) => ReactNode
+}
+
+export interface WidgetComponentProps<TConfig> {
+  actions: ActionsHelper
+  config: TConfig
+  isEditing: boolean
+  size: { w: number; h: number }
+}
+
+export interface DefineWidgetInput<TSchema extends ZodTypeAny> {
+  actions?: ActionDefinition[]
+  component: ComponentType<WidgetComponentProps<Infer<TSchema>>>
+  configSchema: TSchema
+}
+
+export interface WidgetModule<TConfig = unknown> {
+  __brand: 'WidgetModule'
+  actions: ActionDefinition[]
+  component: ComponentType<WidgetComponentProps<TConfig>>
+  configSchema: ZodTypeAny
+}
+
+export function defineWidget<TSchema extends ZodTypeAny>(
+  input: DefineWidgetInput<TSchema>
+): WidgetModule<Infer<TSchema>> {
+  if (!input || typeof input.component !== 'function') {
+    throw new Error('defineWidget: component is required')
+  }
+  return {
+    __brand: 'WidgetModule',
+    configSchema: input.configSchema,
+    component: input.component as any,
+    actions: input.actions ?? []
+  }
+}
diff --git a/packages/widget-sdk/src/index.ts b/packages/widget-sdk/src/index.ts
index 555fc5b3..9bdf469b 100644
--- a/packages/widget-sdk/src/index.ts
+++ b/packages/widget-sdk/src/index.ts
@@ -1,3 +1,11 @@
 export const SDK_VERSION = '0.1.0'
+export type {
+  ActionContext,
+  ActionDefinition,
+  ActionsHelper,
+  WidgetComponentProps,
+  WidgetModule
+} from './define-widget'
+export { defineWidget } from './define-widget'
 export type { SizingStrategy, WidgetCategory, WidgetManifest, WidgetSizing } from './manifest'
 export { validateManifest } from './manifest'
diff --git a/packages/widget-sdk/src/z/index.ts b/packages/widget-sdk/src/z/index.ts
new file mode 100644
index 00000000..a71e10ea
--- /dev/null
+++ b/packages/widget-sdk/src/z/index.ts
@@ -0,0 +1,2 @@
+export type ZodTypeAny = { _kind: string }
+export type Infer<T extends ZodTypeAny> = any
diff --git a/packages/widget-sdk/tests/define-widget.test.ts b/packages/widget-sdk/tests/define-widget.test.ts
new file mode 100644
index 00000000..ebf58393
--- /dev/null
+++ b/packages/widget-sdk/tests/define-widget.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { defineWidget } from '../src/define-widget'
+
+describe('defineWidget', () => {
+  it('wraps the user input into a WidgetModule shape', () => {
+    const mod = defineWidget({
+      configSchema: { _kind: 'object', shape: {} } as any,
+      component: () => null
+    })
+    expect(mod.__brand).toBe('WidgetModule')
+    expect(typeof mod.component).toBe('function')
+    expect(mod.actions).toEqual([])
+  })
+
+  it('preserves user-supplied actions array', () => {
+    const mod = defineWidget({
+      configSchema: { _kind: 'object', shape: {} } as any,
+      component: () => null,
+      actions: [{ id: 'a', label: 'A', run: async () => {} }]
+    })
+    expect(mod.actions).toHaveLength(1)
+    expect(mod.actions[0].id).toBe('a')
+  })
+
+  it('throws when component is missing', () => {
+    expect(() => defineWidget({ configSchema: {} as any } as any)).toThrow(/component/)
+  })
+})

From fdd021b4a7d16d52097741c6bbcd993c36ebedfb Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:25:19 +0800
Subject: [PATCH 08/64] feat(widget-sdk): z mini-validator primitives

---
 packages/widget-sdk/src/index.ts        |   1 +
 packages/widget-sdk/src/z/extensions.ts |  53 ++++++++
 packages/widget-sdk/src/z/index.ts      |   8 +-
 packages/widget-sdk/src/z/primitives.ts | 160 ++++++++++++++++++++++++
 packages/widget-sdk/src/z/validate.ts   |   8 ++
 packages/widget-sdk/tests/z.test.ts     |  82 ++++++++++++
 6 files changed, 310 insertions(+), 2 deletions(-)
 create mode 100644 packages/widget-sdk/src/z/extensions.ts
 create mode 100644 packages/widget-sdk/src/z/primitives.ts
 create mode 100644 packages/widget-sdk/src/z/validate.ts
 create mode 100644 packages/widget-sdk/tests/z.test.ts

diff --git a/packages/widget-sdk/src/index.ts b/packages/widget-sdk/src/index.ts
index 9bdf469b..a0e77251 100644
--- a/packages/widget-sdk/src/index.ts
+++ b/packages/widget-sdk/src/index.ts
@@ -9,3 +9,4 @@ export type {
 export { defineWidget } from './define-widget'
 export type { SizingStrategy, WidgetCategory, WidgetManifest, WidgetSizing } from './manifest'
 export { validateManifest } from './manifest'
+export { type Infer, ZError, ZodSchema, type ZodTypeAny, z } from './z'
diff --git a/packages/widget-sdk/src/z/extensions.ts b/packages/widget-sdk/src/z/extensions.ts
new file mode 100644
index 00000000..607d9471
--- /dev/null
+++ b/packages/widget-sdk/src/z/extensions.ts
@@ -0,0 +1,53 @@
+import { ZodSchema } from './primitives'
+import { ZError } from './validate'
+
+class ZServerId extends ZodSchema<string> {
+  _kind = 'serverId'
+  _parse(input: unknown, path: string[]): string {
+    if (typeof input !== 'string' || input.length === 0) {
+      throw new ZError(path, 'expected non-empty serverId')
+    }
+    return input
+  }
+}
+
+const METRIC_PATH_RE = /^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*|\[\d+\])*$/
+
+class ZMetricPath extends ZodSchema<string> {
+  _kind = 'metricPath'
+  _parse(input: unknown, path: string[]): string {
+    if (typeof input !== 'string' || !METRIC_PATH_RE.test(input)) {
+      throw new ZError(path, 'expected metric path like cpu.usage or disks[0].used')
+    }
+    return input
+  }
+}
+
+const COLOR_RE = /^(#[0-9a-fA-F]{3,8}|oklch\([^)]+\)|rgb[a]?\([^)]+\)|hsl[a]?\([^)]+\))$/
+
+class ZColor extends ZodSchema<string> {
+  _kind = 'color'
+  _parse(input: unknown, path: string[]): string {
+    if (typeof input !== 'string' || !COLOR_RE.test(input)) {
+      throw new ZError(path, 'expected CSS color')
+    }
+    return input
+  }
+}
+
+const DURATION_RE = /^\d+(s|m|h|d)$/
+
+class ZDuration extends ZodSchema<string> {
+  _kind = 'duration'
+  _parse(input: unknown, path: string[]): string {
+    if (typeof input !== 'string' || !DURATION_RE.test(input)) {
+      throw new ZError(path, 'expected duration like 5m / 1h')
+    }
+    return input
+  }
+}
+
+export const serverId = () => new ZServerId()
+export const metricPath = () => new ZMetricPath()
+export const color = () => new ZColor()
+export const duration = () => new ZDuration()
diff --git a/packages/widget-sdk/src/z/index.ts b/packages/widget-sdk/src/z/index.ts
index a71e10ea..c6a59f67 100644
--- a/packages/widget-sdk/src/z/index.ts
+++ b/packages/widget-sdk/src/z/index.ts
@@ -1,2 +1,6 @@
-export type ZodTypeAny = { _kind: string }
-export type Infer<T extends ZodTypeAny> = any
+import { color, duration, metricPath, serverId } from './extensions'
+import { type Infer, ZodSchema, type ZodTypeAny, z as zPrimitives } from './primitives'
+
+export const z = Object.assign(zPrimitives, { serverId, metricPath, color, duration })
+export { ZodSchema, type ZodTypeAny, type Infer }
+export { ZError } from './validate'
diff --git a/packages/widget-sdk/src/z/primitives.ts b/packages/widget-sdk/src/z/primitives.ts
new file mode 100644
index 00000000..e19fb202
--- /dev/null
+++ b/packages/widget-sdk/src/z/primitives.ts
@@ -0,0 +1,160 @@
+import { ZError } from './validate'
+
+export type Infer<T> = T extends ZodSchema<infer U> ? U : never
+export type ZodTypeAny = ZodSchema<any>
+
+export abstract class ZodSchema<T> {
+  abstract _kind: string
+  _label?: string
+  _default?: T
+  _optional = false
+
+  abstract _parse(input: unknown, path: string[]): T
+
+  parse(input: unknown): T {
+    if (input === undefined) {
+      if (this._default !== undefined) {
+        return this._default
+      }
+      if (this._optional) {
+        return undefined as T
+      }
+    }
+    return this._parse(input, [])
+  }
+
+  describe(label: string): this {
+    this._label = label
+    return this
+  }
+
+  default(value: T): this {
+    this._default = value
+    return this
+  }
+
+  optional(): this {
+    this._optional = true
+    return this
+  }
+}
+
+class ZString extends ZodSchema<string> {
+  _kind = 'string'
+  _parse(input: unknown, path: string[]): string {
+    if (typeof input !== 'string') {
+      throw new ZError(path, 'expected string')
+    }
+    return input
+  }
+}
+
+class ZNumber extends ZodSchema<number> {
+  _kind = 'number'
+  private _min?: number
+  private _max?: number
+
+  min(v: number): this {
+    this._min = v
+    return this
+  }
+
+  max(v: number): this {
+    this._max = v
+    return this
+  }
+
+  _parse(input: unknown, path: string[]): number {
+    if (typeof input !== 'number' || Number.isNaN(input)) {
+      throw new ZError(path, 'expected number')
+    }
+    if (this._min !== undefined && input < this._min) {
+      throw new ZError(path, `min ${this._min}`)
+    }
+    if (this._max !== undefined && input > this._max) {
+      throw new ZError(path, `max ${this._max}`)
+    }
+    return input
+  }
+}
+
+class ZBoolean extends ZodSchema<boolean> {
+  _kind = 'boolean'
+  _parse(input: unknown, path: string[]): boolean {
+    if (typeof input !== 'boolean') {
+      throw new ZError(path, 'expected boolean')
+    }
+    return input
+  }
+}
+
+class ZEnum<U extends readonly string[]> extends ZodSchema<U[number]> {
+  _kind = 'enum'
+  constructor(public values: U) {
+    super()
+  }
+
+  _parse(input: unknown, path: string[]): U[number] {
+    if (typeof input !== 'string' || !this.values.includes(input as any)) {
+      throw new ZError(path, `enum: expected one of ${this.values.join(', ')}`)
+    }
+    return input as U[number]
+  }
+}
+
+class ZArray<T> extends ZodSchema<T[]> {
+  _kind = 'array'
+  constructor(public inner: ZodSchema<T>) {
+    super()
+  }
+
+  _parse(input: unknown, path: string[]): T[] {
+    if (!Array.isArray(input)) {
+      throw new ZError(path, 'expected array')
+    }
+    return input.map((item, i) => this.inner._parse(item, [...path, String(i)]))
+  }
+}
+
+class ZObject<Shape extends Record<string, ZodTypeAny>> extends ZodSchema<{
+  [K in keyof Shape]: Infer<Shape[K]>
+}> {
+  _kind = 'object'
+  constructor(public shape: Shape) {
+    super()
+  }
+
+  _parse(input: unknown, path: string[]) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+      throw new ZError(path, 'expected object')
+    }
+    const obj = input as Record<string, unknown>
+    const out: Record<string, unknown> = {}
+    for (const key of Object.keys(this.shape)) {
+      const schema = this.shape[key]
+      const val = obj[key]
+      if (val === undefined) {
+        if (schema._default !== undefined) {
+          out[key] = schema._default
+          continue
+        }
+        if (schema._optional) {
+          out[key] = undefined
+          continue
+        }
+        throw new ZError([...path, key], 'required')
+      }
+      out[key] = schema._parse(val, [...path, key])
+    }
+    return out as any
+  }
+}
+
+export const z = {
+  string: () => new ZString(),
+  number: () => new ZNumber(),
+  boolean: () => new ZBoolean(),
+  enum: <U extends readonly string[]>(values: U) => new ZEnum(values),
+  array: <T>(inner: ZodSchema<T>) => new ZArray(inner),
+  object: <S extends Record<string, ZodTypeAny>>(shape: S) => new ZObject(shape)
+}
diff --git a/packages/widget-sdk/src/z/validate.ts b/packages/widget-sdk/src/z/validate.ts
new file mode 100644
index 00000000..7b42393b
--- /dev/null
+++ b/packages/widget-sdk/src/z/validate.ts
@@ -0,0 +1,8 @@
+export class ZError extends Error {
+  constructor(
+    public path: string[],
+    message: string
+  ) {
+    super(`${path.length ? path.join('.') + ': ' : ''}${message}`)
+  }
+}
diff --git a/packages/widget-sdk/tests/z.test.ts b/packages/widget-sdk/tests/z.test.ts
new file mode 100644
index 00000000..95cc36ac
--- /dev/null
+++ b/packages/widget-sdk/tests/z.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest'
+import { z } from '../src/z'
+
+describe('z primitives', () => {
+  it('z.string() parses strings', () => {
+    expect(z.string().parse('hi')).toBe('hi')
+    expect(() => z.string().parse(1)).toThrow(/string/)
+  })
+
+  it('z.number() with min/max', () => {
+    const s = z.number().min(0).max(10)
+    expect(s.parse(5)).toBe(5)
+    expect(() => s.parse(-1)).toThrow(/min/)
+    expect(() => s.parse(11)).toThrow(/max/)
+  })
+
+  it('z.boolean()', () => {
+    expect(z.boolean().parse(true)).toBe(true)
+    expect(() => z.boolean().parse('true')).toThrow()
+  })
+
+  it('z.enum()', () => {
+    const s = z.enum(['a', 'b', 'c'] as const)
+    expect(s.parse('a')).toBe('a')
+    expect(() => s.parse('d')).toThrow(/enum/)
+  })
+
+  it('z.array(inner)', () => {
+    const s = z.array(z.number())
+    expect(s.parse([1, 2])).toEqual([1, 2])
+    expect(() => s.parse([1, 'x'])).toThrow()
+  })
+
+  it('z.object({ a, b }) applies defaults and rejects missing', () => {
+    const s = z.object({
+      a: z.string().default('hello'),
+      b: z.number()
+    })
+    expect(s.parse({ b: 1 })).toEqual({ a: 'hello', b: 1 })
+    expect(() => s.parse({ a: 'x' })).toThrow(/b/)
+  })
+
+  it('.optional() allows undefined', () => {
+    const s = z.string().optional()
+    expect(s.parse(undefined)).toBeUndefined()
+  })
+
+  it('.describe() attaches label without affecting parse', () => {
+    const s = z.string().describe('Server name')
+    expect((s as any)._label).toBe('Server name')
+    expect(s.parse('x')).toBe('x')
+  })
+})
+
+describe('z extensions', () => {
+  it('z.serverId() validates non-empty string + marks kind', () => {
+    const s = z.serverId()
+    expect((s as any)._kind).toBe('serverId')
+    expect(s.parse('srv-1')).toBe('srv-1')
+    expect(() => s.parse('')).toThrow()
+  })
+
+  it('z.metricPath() validates dot/bracket path', () => {
+    const s = z.metricPath()
+    expect(s.parse('cpu.usage')).toBe('cpu.usage')
+    expect(s.parse('disks[0].used')).toBe('disks[0].used')
+    expect(() => s.parse('--invalid--')).toThrow()
+  })
+
+  it('z.color() accepts hex/oklch/rgb strings', () => {
+    const s = z.color()
+    expect(s.parse('#fff')).toBe('#fff')
+    expect(s.parse('oklch(0.5 0 0)')).toBe('oklch(0.5 0 0)')
+  })
+
+  it('z.duration() parses 5m / 1h / 30s', () => {
+    const s = z.duration()
+    expect(s.parse('5m')).toBe('5m')
+    expect(s.parse('1h')).toBe('1h')
+    expect(() => s.parse('bogus')).toThrow()
+  })
+})

From 3529f4d3365d9a093db4f7cb0c4aca4e072a62c1 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:25:35 +0800
Subject: [PATCH 09/64] feat(widget-sdk): host-runtime bridge

---
 packages/widget-sdk/src/index.ts              |  2 +
 packages/widget-sdk/src/runtime-context.ts    | 43 +++++++++++++++++++
 .../widget-sdk/tests/runtime-context.test.ts  | 21 +++++++++
 3 files changed, 66 insertions(+)
 create mode 100644 packages/widget-sdk/src/runtime-context.ts
 create mode 100644 packages/widget-sdk/tests/runtime-context.test.ts

diff --git a/packages/widget-sdk/src/index.ts b/packages/widget-sdk/src/index.ts
index a0e77251..b54a50a1 100644
--- a/packages/widget-sdk/src/index.ts
+++ b/packages/widget-sdk/src/index.ts
@@ -9,4 +9,6 @@ export type {
 export { defineWidget } from './define-widget'
 export type { SizingStrategy, WidgetCategory, WidgetManifest, WidgetSizing } from './manifest'
 export { validateManifest } from './manifest'
+export type { ServerSummary, WidgetRuntime } from './runtime-context'
+export { createWidgetRuntime, getRuntime, resetRuntime } from './runtime-context'
 export { type Infer, ZError, ZodSchema, type ZodTypeAny, z } from './z'
diff --git a/packages/widget-sdk/src/runtime-context.ts b/packages/widget-sdk/src/runtime-context.ts
new file mode 100644
index 00000000..a91dc5c9
--- /dev/null
+++ b/packages/widget-sdk/src/runtime-context.ts
@@ -0,0 +1,43 @@
+import type { QueryClient } from '@tanstack/react-query'
+
+export interface ServerSummary {
+  capabilities: number
+  id: string
+  lastSeen: number | null
+  name: string
+  online: boolean
+}
+
+export interface WidgetRuntime {
+  apiBaseUrl: string
+  onConfigUpdate: (instanceId: string, patch: Record<string, unknown>) => void
+  queryClient: QueryClient
+  serverByIdStore: (id: string) => unknown
+  serversStore: () => ServerSummary[]
+  themeStore: () => { mode: 'light' | 'dark'; cssVar: (name: string) => string }
+}
+
+let _runtime: WidgetRuntime | null = null
+
+export function createWidgetRuntime(
+  rt: Omit<WidgetRuntime, 'serverByIdStore'> & {
+    serverByIdStore?: WidgetRuntime['serverByIdStore']
+  }
+): WidgetRuntime {
+  _runtime = {
+    serverByIdStore: () => undefined,
+    ...rt
+  }
+  return _runtime
+}
+
+export function getRuntime(): WidgetRuntime {
+  if (!_runtime) {
+    throw new Error('widget-sdk: runtime not installed (host bridge missing)')
+  }
+  return _runtime
+}
+
+export function resetRuntime(): void {
+  _runtime = null
+}
diff --git a/packages/widget-sdk/tests/runtime-context.test.ts b/packages/widget-sdk/tests/runtime-context.test.ts
new file mode 100644
index 00000000..d1dcbbbe
--- /dev/null
+++ b/packages/widget-sdk/tests/runtime-context.test.ts
@@ -0,0 +1,21 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import { createWidgetRuntime, getRuntime, resetRuntime } from '../src/runtime-context'
+
+describe('runtime-context', () => {
+  beforeEach(() => resetRuntime())
+
+  it('throws if hooks called before host installs runtime', () => {
+    expect(() => getRuntime()).toThrow(/runtime not installed/)
+  })
+
+  it('returns installed runtime', () => {
+    const runtime = createWidgetRuntime({
+      apiBaseUrl: '/api',
+      queryClient: {} as any,
+      serversStore: () => [],
+      themeStore: () => ({ mode: 'light', cssVar: () => '' }),
+      onConfigUpdate: () => {}
+    })
+    expect(getRuntime()).toBe(runtime)
+  })
+})

From c16ad438f573564ec4d10610f07e24f4bc34cf53 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:26:24 +0800
Subject: [PATCH 10/64] feat(widget-sdk): live hooks
 (useServers/useServer/useMetric/useCapability)

---
 packages/widget-sdk/src/hooks/index.ts        |  1 +
 packages/widget-sdk/src/hooks/live.ts         | 61 +++++++++++++++++++
 packages/widget-sdk/src/index.ts              |  1 +
 packages/widget-sdk/tests/hooks-live.test.tsx | 48 +++++++++++++++
 packages/widget-sdk/vitest.config.ts          |  7 +++
 5 files changed, 118 insertions(+)
 create mode 100644 packages/widget-sdk/src/hooks/index.ts
 create mode 100644 packages/widget-sdk/src/hooks/live.ts
 create mode 100644 packages/widget-sdk/tests/hooks-live.test.tsx
 create mode 100644 packages/widget-sdk/vitest.config.ts

diff --git a/packages/widget-sdk/src/hooks/index.ts b/packages/widget-sdk/src/hooks/index.ts
new file mode 100644
index 00000000..5a8b47be
--- /dev/null
+++ b/packages/widget-sdk/src/hooks/index.ts
@@ -0,0 +1 @@
+export { useCapability, useMetric, useServer, useServers } from './live'
diff --git a/packages/widget-sdk/src/hooks/live.ts b/packages/widget-sdk/src/hooks/live.ts
new file mode 100644
index 00000000..e13a61b0
--- /dev/null
+++ b/packages/widget-sdk/src/hooks/live.ts
@@ -0,0 +1,61 @@
+import { getRuntime, type ServerSummary } from '../runtime-context'
+
+const CAPS: Record<string, number> = {
+  CAP_TERMINAL: 1,
+  CAP_EXEC: 2,
+  CAP_UPGRADE: 4,
+  CAP_PING_ICMP: 8,
+  CAP_PING_TCP: 16,
+  CAP_PING_HTTP: 32,
+  CAP_FILE: 64,
+  CAP_DOCKER: 128,
+  CAP_SECURITY_EVENTS: 256,
+  CAP_FIREWALL_BLOCK: 512,
+  CAP_IP_QUALITY: 1024
+}
+
+export function useServers(): ServerSummary[] {
+  return getRuntime().serversStore()
+}
+
+export function useServer(id: string | null): unknown {
+  if (id === null) {
+    return undefined
+  }
+  return getRuntime().serverByIdStore(id)
+}
+
+const PATH_TOKEN_RE = /[a-zA-Z_][a-zA-Z0-9_]*|\[\d+\]/g
+
+export function useMetric(id: string | null, path: string): number | string | undefined {
+  if (id === null) {
+    return undefined
+  }
+  const server = getRuntime().serverByIdStore(id) as Record<string, any> | undefined
+  if (!server) {
+    return undefined
+  }
+  const tokens = path.match(PATH_TOKEN_RE) ?? []
+  let cur: any = server
+  for (const tok of tokens) {
+    if (cur == null) {
+      return undefined
+    }
+    cur = tok.startsWith('[') ? cur[Number(tok.slice(1, -1))] : cur[tok]
+  }
+  return cur
+}
+
+export function useCapability(id: string | null, cap: string): boolean {
+  if (id === null) {
+    return false
+  }
+  const bit = CAPS[cap]
+  if (!bit) {
+    return false
+  }
+  const server = getRuntime()
+    .serversStore()
+    .find((s) => s.id === id)
+  return server ? (server.capabilities & bit) !== 0 : false
+}
diff --git a/packages/widget-sdk/src/index.ts b/packages/widget-sdk/src/index.ts
index b54a50a1..ada677e2 100644
--- a/packages/widget-sdk/src/index.ts
+++ b/packages/widget-sdk/src/index.ts
@@ -7,6 +7,7 @@ export type {
   WidgetModule
 } from './define-widget'
 export { defineWidget } from './define-widget'
+export * from './hooks'
 export type { SizingStrategy, WidgetCategory, WidgetManifest, WidgetSizing } from './manifest'
 export { validateManifest } from './manifest'
 export type { ServerSummary, WidgetRuntime } from './runtime-context'
diff --git a/packages/widget-sdk/tests/hooks-live.test.tsx b/packages/widget-sdk/tests/hooks-live.test.tsx
new file mode 100644
index 00000000..db7c340b
--- /dev/null
+++ b/packages/widget-sdk/tests/hooks-live.test.tsx
@@ -0,0 +1,48 @@
+import { renderHook } from '@testing-library/react'
+import { beforeEach, describe, expect, it } from 'vitest'
+import { useCapability, useMetric, useServers } from '../src/hooks/live'
+import { createWidgetRuntime, resetRuntime } from '../src/runtime-context'
+
+describe('live hooks', () => {
+  beforeEach(() => {
+    resetRuntime()
+    createWidgetRuntime({
+      apiBaseUrl: '/api',
+      queryClient: {} as any,
+      serversStore: () => [{ id: 's1', name: 'one', online: true, lastSeen: null, capabilities: 1 | 8 }],
+      serverByIdStore: (id) => (id === 's1' ? { id: 's1', cpu: { usage: 42 }, disks: [{ used: 100 }] } : undefined),
+      themeStore: () => ({ mode: 'light', cssVar: () => '' }),
+      onConfigUpdate: () => {}
+    })
+  })
+
+  it('useServers returns runtime list', () => {
+    const { result } = renderHook(() => useServers())
+    expect(result.current).toHaveLength(1)
+    expect(result.current[0].id).toBe('s1')
+  })
+
+  it('useMetric extracts dot path', () => {
+    const { result } = renderHook(() => useMetric('s1', 'cpu.usage'))
+    expect(result.current).toBe(42)
+  })
+
+  it('useMetric extracts bracket path', () => {
+    const { result } = renderHook(() => useMetric('s1', 'disks[0].used'))
+    expect(result.current).toBe(100)
+  })
+
+  it('useMetric returns undefined when serverId is null', () => {
+    const { result } = renderHook(() => useMetric(null, 'cpu.usage'))
+    expect(result.current).toBeUndefined()
+  })
+
+  it('useCapability checks bitmask', () => {
+    const { result: ping } = renderHook(() => useCapability('s1', 'CAP_PING_ICMP'))
+    expect(ping.current).toBe(true)
+    const { result: term } = renderHook(() => useCapability('s1', 'CAP_TERMINAL'))
+    expect(term.current).toBe(true)
+    const { result: docker } = renderHook(() => useCapability('s1', 'CAP_DOCKER'))
+    expect(docker.current).toBe(false)
+  })
+})
diff --git a/packages/widget-sdk/vitest.config.ts b/packages/widget-sdk/vitest.config.ts
new file mode 100644
index 00000000..4b2865a2
--- /dev/null
+++ b/packages/widget-sdk/vitest.config.ts
@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'jsdom'
+  }
+})

From d19d062068846df3b4d836d93b8e6e768859fdfa Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:27:54 +0800
Subject: [PATCH 11/64] feat(widget-sdk): useApiQuery/useApiMutation

---
 packages/widget-sdk/src/hooks/escape-hatch.ts | 45 +++++++++++++++++++
 packages/widget-sdk/src/hooks/index.ts        |  1 +
 packages/widget-sdk/tests/hooks-api.test.tsx  | 42 +++++++++++++++++
 3 files changed, 88 insertions(+)
 create mode 100644 packages/widget-sdk/src/hooks/escape-hatch.ts
 create mode 100644 packages/widget-sdk/tests/hooks-api.test.tsx

diff --git a/packages/widget-sdk/src/hooks/escape-hatch.ts b/packages/widget-sdk/src/hooks/escape-hatch.ts
new file mode 100644
index 00000000..7ac9bdd9
--- /dev/null
+++ b/packages/widget-sdk/src/hooks/escape-hatch.ts
@@ -0,0 +1,45 @@
+import { type UseMutationResult, type UseQueryResult, useMutation, useQuery } from '@tanstack/react-query'
+
+async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
+  const res = await fetch(path, {
+    method,
+    credentials: 'include',
+    headers: body ? { 'content-type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined
+  })
+  if (!res.ok) {
+    throw new Error(`${method} ${path}: ${res.status}`)
+  }
+  const json = await res.json()
+  return json && typeof json === 'object' && 'data' in json ? (json as { data: T }).data : (json as T)
+}
+
+export function useApiQuery<T>(
+  path: string,
+  opts?: {
+    params?: Record<string, string | number | undefined>
+    enabled?: boolean
+  }
+): UseQueryResult<T> {
+  const params = opts?.params
+  const url = params
+    ? `${path}?${new URLSearchParams(
+        Object.fromEntries(
+          Object.entries(params)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, v]) => [k, String(v)])
+        )
+      ).toString()}`
+    : path
+  return useQuery<T>({
+    queryKey: ['widget-api', url],
+    queryFn: () => request<T>('GET', url),
+    enabled: opts?.enabled
+  })
+}
+
+export function useApiMutation<TRes, TReq = void>(method: string, path: string): UseMutationResult<TRes, Error, TReq> {
+  return useMutation<TRes, Error, TReq>({
+    mutationFn: (body) => request<TRes>(method, path, body)
+  })
+}
diff --git a/packages/widget-sdk/src/hooks/index.ts b/packages/widget-sdk/src/hooks/index.ts
index 5a8b47be..79cb87e1 100644
--- a/packages/widget-sdk/src/hooks/index.ts
+++ b/packages/widget-sdk/src/hooks/index.ts
@@ -1 +1,2 @@
+export { useApiMutation, useApiQuery } from './escape-hatch'
 export { useCapability, useMetric, useServer, useServers } from './live'
diff --git a/packages/widget-sdk/tests/hooks-api.test.tsx b/packages/widget-sdk/tests/hooks-api.test.tsx
new file mode 100644
index 00000000..f8e86f02
--- /dev/null
+++ b/packages/widget-sdk/tests/hooks-api.test.tsx
@@ -0,0 +1,42 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { renderHook, waitFor } from '@testing-library/react'
+import { createElement } from 'react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { useApiMutation, useApiQuery } from '../src/hooks/escape-hatch'
+import { createWidgetRuntime, resetRuntime } from '../src/runtime-context'
+
+describe('api hooks', () => {
+  let qc: QueryClient
+  beforeEach(() => {
+    resetRuntime()
+    qc = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+    createWidgetRuntime({
+      apiBaseUrl: '/api',
+      queryClient: qc,
+      serversStore: () => [],
+      themeStore: () => ({ mode: 'light', cssVar: () => '' }),
+      onConfigUpdate: () => {}
+    })
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ data: { hello: 'world' } })
+    }) as any
+  })
+
+  const wrapper = ({ children }: any) => createElement(QueryClientProvider, { client: qc, children })
+
+  it('useApiQuery unwraps {data}', async () => {
+    const { result } = renderHook(() => useApiQuery<{ hello: string }>('/api/test'), { wrapper })
+    await waitFor(() => expect(result.current.data).toEqual({ hello: 'world' }))
+  })
+
+  it('useApiMutation calls fetch with method+body', async () => {
+    const { result } = renderHook(() => useApiMutation<{ ok: true }, { x: number }>('POST', '/api/do'), { wrapper })
+    await result.current.mutateAsync({ x: 1 })
+    expect(global.fetch).toHaveBeenCalledWith(
+      '/api/do',
+      expect.objectContaining({ method: 'POST', credentials: 'include' })
+    )
+  })
+})

From 0673801b482007f8b51046ad652f10f173df5ad0 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:27:59 +0800
Subject: [PATCH 12/64] feat(widget-sdk): domain hooks
 (alerts/services/traffic/uptime/history/geoip)

---
 packages/widget-sdk/src/hooks/domain.ts | 67 +++++++++++++++++++++++++
 packages/widget-sdk/src/hooks/index.ts  | 13 +++++
 2 files changed, 80 insertions(+)
 create mode 100644 packages/widget-sdk/src/hooks/domain.ts

diff --git a/packages/widget-sdk/src/hooks/domain.ts b/packages/widget-sdk/src/hooks/domain.ts
new file mode 100644
index 00000000..77b8f0ed
--- /dev/null
+++ b/packages/widget-sdk/src/hooks/domain.ts
@@ -0,0 +1,67 @@
+import { useApiMutation, useApiQuery } from './escape-hatch'
+
+export interface AlertEvent {
+  created_at: string
+  id: string
+  message: string
+  severity: string
+}
+
+export interface ServiceMonitor {
+  id: string
+  name: string
+  status: string
+}
+
+export function useAlerts(opts?: { limit?: number }) {
+  return useApiQuery<AlertEvent[]>('/api/alert-events', {
+    params: { limit: opts?.limit ?? 20 }
+  })
+}
+
+export function useServiceMonitors() {
+  return useApiQuery<ServiceMonitor[]>('/api/service-monitors')
+}
+
+export interface TrafficPoint {
+  rx: number
+  ts: number
+  tx: number
+}
+
+export function useTraffic(serverId: string | null, range?: string) {
+  return useApiQuery<TrafficPoint[]>(serverId ? `/api/servers/${serverId}/traffic` : '/api/traffic/overview/daily', {
+    params: { range },
+    enabled: true
+  })
+}
+
+export interface UptimeEntry {
+  day: string
+  incidents: number
+  uptime_pct: number
+}
+
+export function useUptime(serverId: string | null, days = 30) {
+  return useApiQuery<UptimeEntry[]>(serverId ? `/api/servers/${serverId}/uptime-daily` : '/api/uptime/overview', {
+    params: { days }
+  })
+}
+
+export interface HistoryPoint {
+  ts: number
+  value: number
+}
+
+export function useHistory(serverId: string | null, path: string, range: string) {
+  return useApiQuery<HistoryPoint[]>('/api/metrics/history', {
+    params: { server_id: serverId ?? undefined, path, range },
+    enabled: serverId !== null
+  })
+}
+
+export function useGeoIp() {
+  const status = useApiQuery<{ installed: boolean; source?: string }>('/api/geoip/status')
+  const download = useApiMutation<{ success: boolean }>('POST', '/api/geoip/download')
+  return { status, download }
+}
diff --git a/packages/widget-sdk/src/hooks/index.ts b/packages/widget-sdk/src/hooks/index.ts
index 79cb87e1..e4910dda 100644
--- a/packages/widget-sdk/src/hooks/index.ts
+++ b/packages/widget-sdk/src/hooks/index.ts
@@ -1,2 +1,15 @@
+export {
+  type AlertEvent,
+  type HistoryPoint,
+  type ServiceMonitor,
+  type TrafficPoint,
+  type UptimeEntry,
+  useAlerts,
+  useGeoIp,
+  useHistory,
+  useServiceMonitors,
+  useTraffic,
+  useUptime
+} from './domain'
 export { useApiMutation, useApiQuery } from './escape-hatch'
 export { useCapability, useMetric, useServer, useServers } from './live'

From 6b56876d993245bb39801ad1b8411510094f7063 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:30:24 +0800
Subject: [PATCH 13/64] feat(widget-sdk): host hooks (useTheme/useConfigUpdate)

---
 packages/widget-sdk/src/hooks/host.ts  | 10 ++++++++++
 packages/widget-sdk/src/hooks/index.ts |  1 +
 2 files changed, 11 insertions(+)
 create mode 100644 packages/widget-sdk/src/hooks/host.ts

diff --git a/packages/widget-sdk/src/hooks/host.ts b/packages/widget-sdk/src/hooks/host.ts
new file mode 100644
index 00000000..fdff632b
--- /dev/null
+++ b/packages/widget-sdk/src/hooks/host.ts
@@ -0,0 +1,10 @@
+import { getRuntime } from '../runtime-context'
+
+export function useTheme() {
+  return getRuntime().themeStore()
+}
+
+export function useConfigUpdate<TConfig = Record<string, unknown>>(instanceId: string) {
+  const runtime = getRuntime()
+  return (patch: Partial<TConfig>) => runtime.onConfigUpdate(instanceId, patch as Record<string, unknown>)
+}
diff --git a/packages/widget-sdk/src/hooks/index.ts b/packages/widget-sdk/src/hooks/index.ts
index e4910dda..347200cf 100644
--- a/packages/widget-sdk/src/hooks/index.ts
+++ b/packages/widget-sdk/src/hooks/index.ts
@@ -12,4 +12,5 @@ export {
   useUptime
 } from './domain'
 export { useApiMutation, useApiQuery } from './escape-hatch'
+export { useConfigUpdate, useTheme } from './host'
 export { useCapability, useMetric, useServer, useServers } from './live'

From be8d0b5309b4bdec791d6ac2e5130a50f10bc698 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:38:06 +0800
Subject: [PATCH 14/64] feat(widget-sdk): actions runner + ActionButton

---
 .../widget-sdk/src/actions/action-button.tsx  | 31 ++++++++++++++++
 packages/widget-sdk/src/actions/index.ts      | 35 +++++++++++++++++++
 packages/widget-sdk/src/index.ts              |  1 +
 packages/widget-sdk/tests/actions.test.tsx    | 28 +++++++++++++++
 4 files changed, 95 insertions(+)
 create mode 100644 packages/widget-sdk/src/actions/action-button.tsx
 create mode 100644 packages/widget-sdk/src/actions/index.ts
 create mode 100644 packages/widget-sdk/tests/actions.test.tsx

diff --git a/packages/widget-sdk/src/actions/action-button.tsx b/packages/widget-sdk/src/actions/action-button.tsx
new file mode 100644
index 00000000..abe3d9be
--- /dev/null
+++ b/packages/widget-sdk/src/actions/action-button.tsx
@@ -0,0 +1,31 @@
+import { useState } from 'react'
+import type { ActionDefinition } from '../define-widget'
+
+interface Props {
+  action: ActionDefinition
+  onRun: () => Promise<void>
+}
+
+export function ActionButton({ action, onRun }: Props) {
+  const [pending, setPending] = useState(false)
+  const [confirming, setConfirming] = useState(false)
+  const trigger = async () => {
+    if (action.confirm && !confirming) {
+      setConfirming(true)
+      return
+    }
+    setConfirming(false)
+    setPending(true)
+    try {
+      await onRun()
+    } finally {
+      setPending(false)
+    }
+  }
+  return (
+    <button disabled={pending} onClick={trigger} type="button">
+      {confirming ? `Confirm: ${action.label}` : action.label}
+      {pending ? '…' : ''}
+    </button>
+  )
+}
diff --git a/packages/widget-sdk/src/actions/index.ts b/packages/widget-sdk/src/actions/index.ts
new file mode 100644
index 00000000..8e827129
--- /dev/null
+++ b/packages/widget-sdk/src/actions/index.ts
@@ -0,0 +1,35 @@
+import { createElement, type ReactNode } from 'react'
+import type { ActionContext, ActionDefinition, ActionsHelper } from '../define-widget'
+import { ActionButton } from './action-button'
+
+async function apiMutation<Req = unknown, Res = unknown>(method: string, path: string, body?: Req): Promise<Res> {
+  const res = await fetch(path, {
+    method,
+    credentials: 'include',
+    headers: body ? { 'content-type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined
+  })
+  if (!res.ok) {
+    throw new Error(`${method} ${path}: ${res.status}`)
+  }
+  const json: unknown = await res.json()
+  if (json && typeof json === 'object' && 'data' in json) {
+    return (json as { data: Res }).data
+  }
+  return json as Res
+}
+
+export function createActionsHelper(actions: ActionDefinition[]): ActionsHelper {
+  const ctx: ActionContext = { apiMutation }
+  return {
+    render(id: string): ReactNode {
+      const action = actions.find((a) => a.id === id)
+      if (!action) {
+        return null
+      }
+      return createElement(ActionButton, { key: id, action, onRun: () => action.run(ctx) })
+    }
+  }
+}
+
+export type { ActionContext, ActionDefinition, ActionsHelper } from '../define-widget'
diff --git a/packages/widget-sdk/src/index.ts b/packages/widget-sdk/src/index.ts
index ada677e2..fac171ef 100644
--- a/packages/widget-sdk/src/index.ts
+++ b/packages/widget-sdk/src/index.ts
@@ -1,4 +1,5 @@
 export const SDK_VERSION = '0.1.0'
+export { createActionsHelper } from './actions'
 export type {
   ActionContext,
   ActionDefinition,
diff --git a/packages/widget-sdk/tests/actions.test.tsx b/packages/widget-sdk/tests/actions.test.tsx
new file mode 100644
index 00000000..c6f707e7
--- /dev/null
+++ b/packages/widget-sdk/tests/actions.test.tsx
@@ -0,0 +1,28 @@
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createActionsHelper } from '../src/actions'
+import type { ActionDefinition } from '../src/define-widget'
+
+describe('actions helper', () => {
+  beforeEach(() => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ data: { ok: true } })
+    }) as any
+  })
+
+  it('renders a button that triggers run() and shows loading state', async () => {
+    const run = vi.fn().mockResolvedValue(undefined)
+    const actions: ActionDefinition[] = [{ id: 'a1', label: 'Do it', run }]
+    const helper = createActionsHelper(actions)
+    render(<>{helper.render('a1')}</>)
+    fireEvent.click(screen.getByRole('button', { name: 'Do it' }))
+    await waitFor(() => expect(run).toHaveBeenCalledOnce())
+  })
+
+  it('returns null for unknown id', () => {
+    const helper = createActionsHelper([])
+    const { container } = render(<>{helper.render('missing')}</>)
+    expect(container.textContent).toBe('')
+  })
+})

From 8f8eb4bd3a365630aadba6013b647ffc6b6fda00 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:42:27 +0800
Subject: [PATCH 15/64] feat(widget-sdk): renderConfigForm + field renderers

---
 .../widget-sdk/src/form/field-renderers.tsx   | 78 +++++++++++++++++++
 packages/widget-sdk/src/form/index.tsx        | 36 +++++++++
 packages/widget-sdk/src/index.ts              |  1 +
 packages/widget-sdk/tests/form.test.tsx       | 51 ++++++++++++
 4 files changed, 166 insertions(+)
 create mode 100644 packages/widget-sdk/src/form/field-renderers.tsx
 create mode 100644 packages/widget-sdk/src/form/index.tsx
 create mode 100644 packages/widget-sdk/tests/form.test.tsx

diff --git a/packages/widget-sdk/src/form/field-renderers.tsx b/packages/widget-sdk/src/form/field-renderers.tsx
new file mode 100644
index 00000000..3cd46305
--- /dev/null
+++ b/packages/widget-sdk/src/form/field-renderers.tsx
@@ -0,0 +1,78 @@
+import { getRuntime } from '../runtime-context'
+import type { ZodTypeAny } from '../z'
+
+interface FieldProps {
+  id: string
+  label: string
+  onChange: (v: unknown) => void
+  schema: ZodTypeAny
+  value: unknown
+}
+
+export function renderField(props: FieldProps) {
+  const kind = (props.schema as any)._kind
+  switch (kind) {
+    case 'string':
+      return (
+        <input
+          id={props.id}
+          onChange={(e) => props.onChange(e.target.value)}
+          type="text"
+          value={(props.value as string) ?? ''}
+        />
+      )
+    case 'number':
+      return (
+        <input
+          id={props.id}
+          onChange={(e) => props.onChange(e.target.value === '' ? undefined : Number(e.target.value))}
+          type="number"
+          value={(props.value as number) ?? ''}
+        />
+      )
+    case 'boolean':
+      return (
+        <input
+          checked={!!props.value}
+          id={props.id}
+          onChange={(e) => props.onChange(e.target.checked)}
+          type="checkbox"
+        />
+      )
+    case 'enum': {
+      const opts = (props.schema as any).values as string[]
+      return (
+        <select id={props.id} onChange={(e) => props.onChange(e.target.value)} value={(props.value as string) ?? ''}>
+          {opts.map((o) => (
+            <option key={o} value={o}>
+              {o}
+            </option>
+          ))}
+        </select>
+      )
+    }
+    case 'serverId': {
+      const servers = getRuntime().serversStore()
+      return (
+        <select id={props.id} onChange={(e) => props.onChange(e.target.value)} value={(props.value as string) ?? ''}>
+          <option value="">— choose —</option>
+          {servers.map((s) => (
+            <option key={s.id} value={s.id}>
+              {s.name}
+            </option>
+          ))}
+        </select>
+      )
+    }
+    default:
+      // metricPath / color / duration → text input
+      return (
+        <input
+          id={props.id}
+          onChange={(e) => props.onChange(e.target.value)}
+          type="text"
+          value={(props.value as string) ?? ''}
+        />
+      )
+  }
+}
diff --git a/packages/widget-sdk/src/form/index.tsx b/packages/widget-sdk/src/form/index.tsx
new file mode 100644
index 00000000..6de110d2
--- /dev/null
+++ b/packages/widget-sdk/src/form/index.tsx
@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react'
+import type { ZodTypeAny } from '../z'
+import { renderField } from './field-renderers'
+
+export function renderConfigForm(
+  schema: ZodTypeAny,
+  value: Record<string, unknown>,
+  onChange: (v: Record<string, unknown>) => void
+): ReactNode {
+  if ((schema as any)._kind !== 'object') {
+    return <em>Top-level schema must be z.object()</em>
+  }
+  const shape = (schema as any).shape as Record<string, ZodTypeAny>
+  return (
+    <div>
+      {Object.entries(shape).map(([key, fieldSchema]) => {
+        const label = (fieldSchema as any)._label ?? key
+        const id = `cfg-${key}`
+        return (
+          <div key={key} style={{ marginBottom: 8 }}>
+            <label htmlFor={id} style={{ display: 'block' }}>
+              {label}
+            </label>
+            {renderField({
+              schema: fieldSchema,
+              value: value[key],
+              onChange: (v) => onChange({ ...value, [key]: v }),
+              id,
+              label
+            })}
+          </div>
+        )
+      })}
+    </div>
+  )
+}
diff --git a/packages/widget-sdk/src/index.ts b/packages/widget-sdk/src/index.ts
index fac171ef..3d85b3f2 100644
--- a/packages/widget-sdk/src/index.ts
+++ b/packages/widget-sdk/src/index.ts
@@ -8,6 +8,7 @@ export type {
   WidgetModule
 } from './define-widget'
 export { defineWidget } from './define-widget'
+export { renderConfigForm } from './form'
 export * from './hooks'
 export type { SizingStrategy, WidgetCategory, WidgetManifest, WidgetSizing } from './manifest'
 export { validateManifest } from './manifest'
diff --git a/packages/widget-sdk/tests/form.test.tsx b/packages/widget-sdk/tests/form.test.tsx
new file mode 100644
index 00000000..21eda989
--- /dev/null
+++ b/packages/widget-sdk/tests/form.test.tsx
@@ -0,0 +1,51 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { useState } from 'react'
+import { beforeEach, describe, expect, it } from 'vitest'
+import { renderConfigForm } from '../src/form'
+import { createWidgetRuntime, resetRuntime } from '../src/runtime-context'
+import { z } from '../src/z'
+
+function Wrapper({ schema, initial }: any) {
+  const [value, setValue] = useState(initial)
+  return <>{renderConfigForm(schema, value, setValue)}</>
+}
+
+describe('renderConfigForm', () => {
+  beforeEach(() => {
+    resetRuntime()
+    createWidgetRuntime({
+      apiBaseUrl: '/api',
+      queryClient: {} as any,
+      serversStore: () => [{ id: 's1', name: 'One', online: true, lastSeen: null, capabilities: 0 }],
+      themeStore: () => ({ mode: 'light', cssVar: () => '' }),
+      onConfigUpdate: () => {}
+    })
+  })
+
+  it('renders a text input for z.string()', () => {
+    const schema = z.object({ name: z.string().describe('Name') })
+    render(<Wrapper initial={{ name: 'hi' }} schema={schema} />)
+    const input = screen.getByLabelText('Name') as HTMLInputElement
+    expect(input.value).toBe('hi')
+    fireEvent.change(input, { target: { value: 'world' } })
+    expect(input.value).toBe('world')
+  })
+
+  it('renders a number input for z.number()', () => {
+    const schema = z.object({ count: z.number().describe('Count') })
+    render(<Wrapper initial={{ count: 5 }} schema={schema} />)
+    expect((screen.getByLabelText('Count') as HTMLInputElement).value).toBe('5')
+  })
+
+  it('renders a select for z.enum()', () => {
+    const schema = z.object({ mode: z.enum(['a', 'b'] as const).describe('Mode') })
+    render(<Wrapper initial={{ mode: 'a' }} schema={schema} />)
+    expect(screen.getByLabelText('Mode')).toBeTruthy()
+  })
+
+  it('renders a server picker for z.serverId()', () => {
+    const schema = z.object({ srv: z.serverId().describe('Server') })
+    render(<Wrapper initial={{ srv: 's1' }} schema={schema} />)
+    expect(screen.getByLabelText('Server')).toBeTruthy()
+  })
+})

From b00c756b6d7f36fae557558621f6e0de9d541f4a Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:43:35 +0800
Subject: [PATCH 16/64] feat(web): Widget Registry singleton

---
 apps/web/src/widgets-runtime/registry.test.ts | 41 ++++++++++++++++
 apps/web/src/widgets-runtime/registry.ts      | 49 +++++++++++++++++++
 2 files changed, 90 insertions(+)
 create mode 100644 apps/web/src/widgets-runtime/registry.test.ts
 create mode 100644 apps/web/src/widgets-runtime/registry.ts

diff --git a/apps/web/src/widgets-runtime/registry.test.ts b/apps/web/src/widgets-runtime/registry.test.ts
new file mode 100644
index 00000000..1863ad0a
--- /dev/null
+++ b/apps/web/src/widgets-runtime/registry.test.ts
@@ -0,0 +1,41 @@
+import type { WidgetManifest, WidgetModule } from '@serverbee/widget-sdk'
+import { beforeEach, describe, expect, it } from 'vitest'
+import { registryActions, useWidgetRegistry } from './registry'
+
+const fakeManifest: WidgetManifest = {
+  id: 'com.test.foo',
+  version: '1.0.0',
+  name: 'Foo',
+  category: 'Real-time',
+  sizing: { defaultW: 2, defaultH: 2, minW: 1, minH: 1, strategy: 'free' },
+  sdkVersion: '^0.1.0'
+}
+const fakeModule: WidgetModule = {
+  __brand: 'WidgetModule',
+  configSchema: {} as any,
+  component: () => null,
+  actions: []
+}
+
+describe('registry', () => {
+  beforeEach(() => useWidgetRegistry.setState({ modules: new Map(), failures: new Map() }))
+
+  it('registers and retrieves a module', () => {
+    registryActions.register('com.test.foo', fakeModule, fakeManifest)
+    const entry = registryActions.get('com.test.foo')
+    expect(entry?.manifest.name).toBe('Foo')
+    expect(entry?.module).toBe(fakeModule)
+  })
+
+  it('records load failures', () => {
+    registryActions.recordLoadFailure('com.test.bad', new Error('boom'))
+    expect(registryActions.list()).toEqual([])
+    expect(useWidgetRegistry.getState().failures.get('com.test.bad')?.message).toBe('boom')
+  })
+
+  it('unregister removes the module', () => {
+    registryActions.register('com.test.foo', fakeModule, fakeManifest)
+    registryActions.unregister('com.test.foo')
+    expect(registryActions.get('com.test.foo')).toBeUndefined()
+  })
+})
diff --git a/apps/web/src/widgets-runtime/registry.ts b/apps/web/src/widgets-runtime/registry.ts
new file mode 100644
index 00000000..2c1861ae
--- /dev/null
+++ b/apps/web/src/widgets-runtime/registry.ts
@@ -0,0 +1,49 @@
+import type { WidgetManifest, WidgetModule } from '@serverbee/widget-sdk'
+import { create } from 'zustand'
+
+export interface RegistryEntry {
+  manifest: WidgetManifest
+  module: WidgetModule
+}
+
+interface RegistryState {
+  failures: Map<string, Error>
+  modules: Map<string, RegistryEntry>
+}
+
+export const useWidgetRegistry = create<RegistryState>(() => ({
+  modules: new Map(),
+  failures: new Map()
+}))
+
+export const registryActions = {
+  register(id: string, module: WidgetModule, manifest: WidgetManifest) {
+    useWidgetRegistry.setState((state) => {
+      const modules = new Map(state.modules)
+      modules.set(id, { manifest, module })
+      const failures = new Map(state.failures)
+      failures.delete(id)
+      return { modules, failures }
+    })
+  },
+  unregister(id: string) {
+    useWidgetRegistry.setState((state) => {
+      const modules = new Map(state.modules)
+      modules.delete(id)
+      return { modules }
+    })
+  },
+  get(id: string): RegistryEntry | undefined {
+    return useWidgetRegistry.getState().modules.get(id)
+  },
+  list(): RegistryEntry[] {
+    return Array.from(useWidgetRegistry.getState().modules.values())
+  },
+  recordLoadFailure(id: string, err: Error) {
+    useWidgetRegistry.setState((state) => {
+      const failures = new Map(state.failures)
+      failures.set(id, err)
+      return { failures }
+    })
+  }
+}

From 2b247d28c344e2e821f1ae5c07ec399985b8f644 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:54:17 +0800
Subject: [PATCH 17/64] feat(web): bootstrap loader (fetch list, import,
 isolate failures)

---
 apps/web/src/widgets-runtime/loader.test.ts | 93 +++++++++++++++++++++
 apps/web/src/widgets-runtime/loader.ts      | 42 ++++++++++
 2 files changed, 135 insertions(+)
 create mode 100644 apps/web/src/widgets-runtime/loader.test.ts
 create mode 100644 apps/web/src/widgets-runtime/loader.ts

diff --git a/apps/web/src/widgets-runtime/loader.test.ts b/apps/web/src/widgets-runtime/loader.test.ts
new file mode 100644
index 00000000..2a94e64b
--- /dev/null
+++ b/apps/web/src/widgets-runtime/loader.test.ts
@@ -0,0 +1,93 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { bootstrapLoader } from './loader'
+import { useWidgetRegistry } from './registry'
+
+describe('bootstrapLoader', () => {
+  beforeEach(() => {
+    useWidgetRegistry.setState({ modules: new Map(), failures: new Map() })
+  })
+
+  it('lists modules, imports each, registers them', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        data: [
+          {
+            id: 'com.test.foo',
+            version: '1.0.0',
+            entry_path: 'index.js',
+            manifest: {
+              id: 'com.test.foo',
+              version: '1.0.0',
+              name: 'Foo',
+              category: 'Real-time',
+              sizing: { defaultW: 2, defaultH: 2, minW: 1, minH: 1, strategy: 'free' },
+              sdkVersion: '^0.1.0'
+            }
+          }
+        ]
+      })
+    }) as any
+    const fakeModule = {
+      __brand: 'WidgetModule',
+      configSchema: {},
+      component: () => null,
+      actions: []
+    }
+    const importer = vi.fn().mockResolvedValue({ default: fakeModule })
+    await bootstrapLoader({ importer })
+    expect(useWidgetRegistry.getState().modules.size).toBe(1)
+    expect(useWidgetRegistry.getState().modules.get('com.test.foo')?.manifest.name).toBe('Foo')
+  })
+
+  it('isolates one module failure', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        data: [
+          {
+            id: 'a',
+            version: '1.0.0',
+            entry_path: 'a.js',
+            manifest: {
+              id: 'a',
+              version: '1.0.0',
+              name: 'A',
+              category: 'Real-time',
+              sizing: { defaultW: 2, defaultH: 2, minW: 1, minH: 1, strategy: 'free' },
+              sdkVersion: '^0.1.0'
+            }
+          },
+          {
+            id: 'b',
+            version: '1.0.0',
+            entry_path: 'b.js',
+            manifest: {
+              id: 'b',
+              version: '1.0.0',
+              name: 'B',
+              category: 'Real-time',
+              sizing: { defaultW: 2, defaultH: 2, minW: 1, minH: 1, strategy: 'free' },
+              sdkVersion: '^0.1.0'
+            }
+          }
+        ]
+      })
+    }) as any
+    const importer = vi.fn().mockImplementation((url: string) =>
+      url.includes('a.js')
+        ? Promise.resolve({
+            default: {
+              __brand: 'WidgetModule',
+              configSchema: {},
+              component: () => null,
+              actions: []
+            }
+          })
+        : Promise.reject(new Error('boom'))
+    )
+    await bootstrapLoader({ importer })
+    expect(useWidgetRegistry.getState().modules.has('a')).toBe(true)
+    expect(useWidgetRegistry.getState().failures.has('b')).toBe(true)
+  })
+})
diff --git a/apps/web/src/widgets-runtime/loader.ts b/apps/web/src/widgets-runtime/loader.ts
new file mode 100644
index 00000000..18296fd0
--- /dev/null
+++ b/apps/web/src/widgets-runtime/loader.ts
@@ -0,0 +1,42 @@
+import type { WidgetManifest, WidgetModule } from '@serverbee/widget-sdk'
+import { registryActions } from './registry'
+
+interface ListEntry {
+  entry_path: string
+  id: string
+  manifest: WidgetManifest
+  version: string
+}
+
+export interface BootstrapOptions {
+  baseUrl?: string
+  /** Override the import function (used in tests). */
+  importer?: (url: string) => Promise<{ default: WidgetModule }>
+}
+
+export async function bootstrapLoader(opts: BootstrapOptions = {}): Promise<void> {
+  const base = opts.baseUrl ?? '/api/widget-modules'
+  const importer = opts.importer ?? ((url: string) => import(/* @vite-ignore */ url))
+
+  const res = await fetch(base, { credentials: 'include' })
+  if (!res.ok) {
+    throw new Error(`bootstrapLoader: list failed ${res.status}`)
+  }
+  const body = (await res.json()) as { data: ListEntry[] }
+  const modules = body.data
+
+  await Promise.allSettled(
+    modules.map(async (entry) => {
+      try {
+        const url = `${base}/${entry.id}/${entry.entry_path}`
+        const mod = await importer(url)
+        if (!mod.default || mod.default.__brand !== 'WidgetModule') {
+          throw new Error(`module ${entry.id} did not export a WidgetModule via default`)
+        }
+        registryActions.register(entry.id, mod.default, entry.manifest)
+      } catch (err) {
+        registryActions.recordLoadFailure(entry.id, err instanceof Error ? err : new Error(String(err)))
+      }
+    })
+  )
+}

From 8e67f0994412647871ce52a1b7d0499419c70a6e Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:58:47 +0800
Subject: [PATCH 18/64] fix(widget-sdk): replace constructor parameter
 shorthand for erasableSyntaxOnly

---
 packages/widget-sdk/src/z/primitives.ts | 15 ++++++++++++---
 packages/widget-sdk/src/z/validate.ts   |  8 ++++----
 2 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/packages/widget-sdk/src/z/primitives.ts b/packages/widget-sdk/src/z/primitives.ts
index e19fb202..96e81eae 100644
--- a/packages/widget-sdk/src/z/primitives.ts
+++ b/packages/widget-sdk/src/z/primitives.ts
@@ -90,8 +90,11 @@ class ZBoolean extends ZodSchema<boolean> {
 
 class ZEnum<U extends readonly string[]> extends ZodSchema<U[number]> {
   _kind = 'enum'
-  constructor(public values: U) {
+  values: U
+
+  constructor(values: U) {
     super()
+    this.values = values
   }
 
   _parse(input: unknown, path: string[]): U[number] {
@@ -104,8 +107,11 @@ class ZEnum<U extends readonly string[]> extends ZodSchema<U[number]> {
 
 class ZArray<T> extends ZodSchema<T[]> {
   _kind = 'array'
-  constructor(public inner: ZodSchema<T>) {
+  inner: ZodSchema<T>
+
+  constructor(inner: ZodSchema<T>) {
     super()
+    this.inner = inner
   }
 
   _parse(input: unknown, path: string[]): T[] {
@@ -120,8 +126,11 @@ class ZObject<Shape extends Record<string, ZodTypeAny>> extends ZodSchema<{
   [K in keyof Shape]: Infer<Shape[K]>
 }> {
   _kind = 'object'
-  constructor(public shape: Shape) {
+  shape: Shape
+
+  constructor(shape: Shape) {
     super()
+    this.shape = shape
   }
 
   _parse(input: unknown, path: string[]) {
diff --git a/packages/widget-sdk/src/z/validate.ts b/packages/widget-sdk/src/z/validate.ts
index 7b42393b..cf7c8db7 100644
--- a/packages/widget-sdk/src/z/validate.ts
+++ b/packages/widget-sdk/src/z/validate.ts
@@ -1,8 +1,8 @@
 export class ZError extends Error {
-  constructor(
-    public path: string[],
-    message: string
-  ) {
+  path: string[]
+
+  constructor(path: string[], message: string) {
     super(`${path.length ? path.join('.') + ': ' : ''}${message}`)
+    this.path = path
   }
 }

From 3d39ae900c522ddd960c1d4a17347f08cdb53fb1 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 20:59:42 +0800
Subject: [PATCH 19/64] feat(web): runtime bridge + import-map shims for widget
 SDK

---
 apps/web/index.html                           | 10 +++++++
 apps/web/public/runtime/react-dom.js          |  7 +++++
 apps/web/public/runtime/react-jsx-runtime.js  |  7 +++++
 apps/web/public/runtime/react.js              | 22 ++++++++++++++
 apps/web/public/runtime/widget-sdk.js         | 23 ++++++++++++++
 apps/web/src/main.tsx                         | 16 ++++++++++
 .../web/src/widgets-runtime/runtime-bridge.ts | 30 +++++++++++++++++++
 7 files changed, 115 insertions(+)
 create mode 100644 apps/web/public/runtime/react-dom.js
 create mode 100644 apps/web/public/runtime/react-jsx-runtime.js
 create mode 100644 apps/web/public/runtime/react.js
 create mode 100644 apps/web/public/runtime/widget-sdk.js
 create mode 100644 apps/web/src/widgets-runtime/runtime-bridge.ts

diff --git a/apps/web/index.html b/apps/web/index.html
index 98d5657d..cf791b06 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -9,6 +9,16 @@
   </head>
   <body>
     <div id="root"></div>
+    <script type="importmap">
+    {
+      "imports": {
+        "@serverbee/widget-sdk": "/runtime/widget-sdk.js",
+        "react": "/runtime/react.js",
+        "react-dom": "/runtime/react-dom.js",
+        "react/jsx-runtime": "/runtime/react-jsx-runtime.js"
+      }
+    }
+    </script>
     <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>
diff --git a/apps/web/public/runtime/react-dom.js b/apps/web/public/runtime/react-dom.js
new file mode 100644
index 00000000..0c4d882f
--- /dev/null
+++ b/apps/web/public/runtime/react-dom.js
@@ -0,0 +1,7 @@
+const rd = globalThis.__SERVERBEE_REACT_DOM__
+if (!rd) {
+  throw new Error('react-dom shim: host did not mount __SERVERBEE_REACT_DOM__')
+}
+export default rd
+export const createPortal = rd.createPortal
+export const flushSync = rd.flushSync
diff --git a/apps/web/public/runtime/react-jsx-runtime.js b/apps/web/public/runtime/react-jsx-runtime.js
new file mode 100644
index 00000000..71cfdeff
--- /dev/null
+++ b/apps/web/public/runtime/react-jsx-runtime.js
@@ -0,0 +1,7 @@
+const j = globalThis.__SERVERBEE_JSX_RUNTIME__
+if (!j) {
+  throw new Error('jsx-runtime shim: host did not mount __SERVERBEE_JSX_RUNTIME__')
+}
+export const jsx = j.jsx
+export const jsxs = j.jsxs
+export const Fragment = j.Fragment
diff --git a/apps/web/public/runtime/react.js b/apps/web/public/runtime/react.js
new file mode 100644
index 00000000..5f682c39
--- /dev/null
+++ b/apps/web/public/runtime/react.js
@@ -0,0 +1,22 @@
+const r = globalThis.__SERVERBEE_REACT__
+if (!r) {
+  throw new Error('react shim: host did not mount __SERVERBEE_REACT__')
+}
+export default r
+export const useState = r.useState
+export const useEffect = r.useEffect
+export const useMemo = r.useMemo
+export const useCallback = r.useCallback
+export const useRef = r.useRef
+export const useContext = r.useContext
+export const useReducer = r.useReducer
+export const useLayoutEffect = r.useLayoutEffect
+export const createContext = r.createContext
+export const Fragment = r.Fragment
+export const memo = r.memo
+export const forwardRef = r.forwardRef
+export const Component = r.Component
+export const Children = r.Children
+export const cloneElement = r.cloneElement
+export const createElement = r.createElement
+export const isValidElement = r.isValidElement
diff --git a/apps/web/public/runtime/widget-sdk.js b/apps/web/public/runtime/widget-sdk.js
new file mode 100644
index 00000000..3c817551
--- /dev/null
+++ b/apps/web/public/runtime/widget-sdk.js
@@ -0,0 +1,23 @@
+const ns = globalThis.__SERVERBEE_SDK__
+if (!ns) {
+  throw new Error('widget-sdk shim: host did not mount __SERVERBEE_SDK__')
+}
+export const defineWidget = ns.defineWidget
+export const z = ns.z
+export const createActionsHelper = ns.createActionsHelper
+export const renderConfigForm = ns.renderConfigForm
+export const useServers = ns.useServers
+export const useServer = ns.useServer
+export const useMetric = ns.useMetric
+export const useCapability = ns.useCapability
+export const useApiQuery = ns.useApiQuery
+export const useApiMutation = ns.useApiMutation
+export const useAlerts = ns.useAlerts
+export const useServiceMonitors = ns.useServiceMonitors
+export const useTraffic = ns.useTraffic
+export const useUptime = ns.useUptime
+export const useHistory = ns.useHistory
+export const useGeoIp = ns.useGeoIp
+export const useTheme = ns.useTheme
+export const useConfigUpdate = ns.useConfigUpdate
+export const SDK_VERSION = ns.SDK_VERSION
diff --git a/apps/web/src/main.tsx b/apps/web/src/main.tsx
index 36431617..c688f823 100644
--- a/apps/web/src/main.tsx
+++ b/apps/web/src/main.tsx
@@ -6,6 +6,8 @@ import { createRoot } from 'react-dom/client'
 import './index.css'
 import '@/lib/i18n'
 import { router } from './router'
+import { bootstrapLoader } from './widgets-runtime/loader'
+import { mountRuntimeBridge } from './widgets-runtime/runtime-bridge'
 
 const queryClient = new QueryClient({
   defaultOptions: {
@@ -13,6 +15,20 @@ const queryClient = new QueryClient({
   }
 })
 
+mountRuntimeBridge({
+  queryClient,
+  serversStore: () => [],
+  serverByIdStore: () => undefined,
+  themeStore: () => ({
+    mode: document.documentElement.classList.contains('dark') ? 'dark' : 'light',
+    cssVar: (n) => getComputedStyle(document.documentElement).getPropertyValue(n).trim()
+  }),
+  onConfigUpdate: () => {}
+})
+
+// Best-effort: don't block rendering. Endpoint may return empty in Plan 1.
+bootstrapLoader().catch((e) => console.warn('widget bootstrap failed', e))
+
 const root = document.getElementById('root')
 if (root) {
   createRoot(root).render(
diff --git a/apps/web/src/widgets-runtime/runtime-bridge.ts b/apps/web/src/widgets-runtime/runtime-bridge.ts
new file mode 100644
index 00000000..38b4fe23
--- /dev/null
+++ b/apps/web/src/widgets-runtime/runtime-bridge.ts
@@ -0,0 +1,30 @@
+import type { ServerSummary } from '@serverbee/widget-sdk'
+import * as Sdk from '@serverbee/widget-sdk'
+import type { QueryClient } from '@tanstack/react-query'
+import * as React from 'react'
+import * as JsxRuntime from 'react/jsx-runtime'
+import * as ReactDOM from 'react-dom'
+
+export interface BridgeInputs {
+  onConfigUpdate: (instanceId: string, patch: Record<string, unknown>) => void
+  queryClient: QueryClient
+  serverByIdStore: (id: string) => unknown
+  serversStore: () => ServerSummary[]
+  themeStore: () => { mode: 'light' | 'dark'; cssVar: (n: string) => string }
+}
+
+export function mountRuntimeBridge(inputs: BridgeInputs): void {
+  ;(globalThis as any).__SERVERBEE_REACT__ = React
+  ;(globalThis as any).__SERVERBEE_REACT_DOM__ = ReactDOM
+  ;(globalThis as any).__SERVERBEE_JSX_RUNTIME__ = JsxRuntime
+  ;(globalThis as any).__SERVERBEE_SDK__ = Sdk
+
+  Sdk.createWidgetRuntime({
+    apiBaseUrl: '/api',
+    queryClient: inputs.queryClient,
+    serversStore: inputs.serversStore,
+    serverByIdStore: inputs.serverByIdStore,
+    themeStore: inputs.themeStore,
+    onConfigUpdate: inputs.onConfigUpdate
+  })
+}

From 8327546869701288be1d6a30594f4ed21a746a25 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:00:11 +0800
Subject: [PATCH 20/64] feat(server): widget_module sea-orm entity

---
 crates/server/src/entity/mod.rs           |  1 +
 crates/server/src/entity/widget_module.rs | 39 +++++++++++++++++++++++
 2 files changed, 40 insertions(+)
 create mode 100644 crates/server/src/entity/widget_module.rs

diff --git a/crates/server/src/entity/mod.rs b/crates/server/src/entity/mod.rs
index d38a2ab1..da54f928 100644
--- a/crates/server/src/entity/mod.rs
+++ b/crates/server/src/entity/mod.rs
@@ -49,3 +49,4 @@ pub mod unlock_result;
 pub mod unlock_service;
 pub mod uptime_daily;
 pub mod user;
+pub mod widget_module;
diff --git a/crates/server/src/entity/widget_module.rs b/crates/server/src/entity/widget_module.rs
new file mode 100644
index 00000000..586697f8
--- /dev/null
+++ b/crates/server/src/entity/widget_module.rs
@@ -0,0 +1,39 @@
+use sea_orm::entity::prelude::*;
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Debug, PartialEq, Eq, EnumIter, DeriveActiveEnum, Serialize, Deserialize)]
+#[sea_orm(rs_type = "String", db_type = "Text")]
+pub enum SourceType {
+    #[sea_orm(string_value = "Builtin")]
+    Builtin,
+    #[sea_orm(string_value = "Url")]
+    Url,
+    #[sea_orm(string_value = "Upload")]
+    Upload,
+    #[sea_orm(string_value = "BundledByTheme")]
+    BundledByTheme,
+}
+
+#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Serialize, Deserialize)]
+#[sea_orm(table_name = "widget_module")]
+pub struct Model {
+    #[sea_orm(primary_key, auto_increment = false)]
+    pub id: String,
+    pub version: String,
+    pub source_type: SourceType,
+    pub source_url: Option<String>,
+    pub bundled_by_theme_id: Option<String>,
+    pub manifest_json: String,
+    pub code_sha256: String,
+    pub entry_path: String,
+    #[serde(skip)]
+    pub package_blob: Option<Vec<u8>>,
+    pub installed_by: Option<i64>,
+    pub installed_at: DateTimeUtc,
+    pub enabled: bool,
+}
+
+#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
+pub enum Relation {}
+
+impl ActiveModelBehavior for ActiveModel {}

From 7ce5723468f6737896d7eb1e22579416397e73b6 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:00:57 +0800
Subject: [PATCH 21/64] feat(server): migration for widget_module table

---
 .../m20260528_000037_create_widget_module.rs  | 43 +++++++++++++++++++
 crates/server/src/migration/mod.rs            |  2 +
 2 files changed, 45 insertions(+)
 create mode 100644 crates/server/src/migration/m20260528_000037_create_widget_module.rs

diff --git a/crates/server/src/migration/m20260528_000037_create_widget_module.rs b/crates/server/src/migration/m20260528_000037_create_widget_module.rs
new file mode 100644
index 00000000..78e01363
--- /dev/null
+++ b/crates/server/src/migration/m20260528_000037_create_widget_module.rs
@@ -0,0 +1,43 @@
+use sea_orm_migration::prelude::*;
+
+#[derive(DeriveMigrationName)]
+pub struct Migration;
+
+#[async_trait::async_trait]
+impl MigrationTrait for Migration {
+    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        let db = manager.get_connection();
+        db.execute_unprepared(
+            r#"
+            CREATE TABLE IF NOT EXISTS widget_module (
+                id                    TEXT NOT NULL PRIMARY KEY,
+                version               TEXT NOT NULL,
+                source_type           TEXT NOT NULL,
+                source_url            TEXT,
+                bundled_by_theme_id   TEXT,
+                manifest_json         TEXT NOT NULL,
+                code_sha256           TEXT NOT NULL,
+                entry_path            TEXT NOT NULL,
+                package_blob          BLOB,
+                installed_by          INTEGER,
+                installed_at          TEXT NOT NULL,
+                enabled               INTEGER NOT NULL DEFAULT 1
+            )
+            "#,
+        )
+        .await?;
+        db.execute_unprepared(
+            "CREATE INDEX IF NOT EXISTS idx_widget_module_source_type ON widget_module(source_type)",
+        )
+        .await?;
+        db.execute_unprepared(
+            "CREATE INDEX IF NOT EXISTS idx_widget_module_theme ON widget_module(bundled_by_theme_id) WHERE bundled_by_theme_id IS NOT NULL",
+        )
+        .await?;
+        Ok(())
+    }
+
+    async fn down(&self, _manager: &SchemaManager) -> Result<(), DbErr> {
+        Ok(())
+    }
+}
diff --git a/crates/server/src/migration/mod.rs b/crates/server/src/migration/mod.rs
index 06ee5d66..af7374d1 100644
--- a/crates/server/src/migration/mod.rs
+++ b/crates/server/src/migration/mod.rs
@@ -36,6 +36,7 @@ mod m20260525_000033_ip_quality_snapshot_extra_fields;
 mod m20260525_000034_agent_registration_redesign;
 mod m20260526_000035_create_spa_themes;
 mod m20260526_000036_simplify_status_page;
+mod m20260528_000037_create_widget_module;
 
 pub struct Migrator;
 
@@ -78,6 +79,7 @@ impl MigratorTrait for Migrator {
             Box::new(m20260525_000034_agent_registration_redesign::Migration),
             Box::new(m20260526_000035_create_spa_themes::Migration),
             Box::new(m20260526_000036_simplify_status_page::Migration),
+            Box::new(m20260528_000037_create_widget_module::Migration),
         ]
     }
 }

From 55127e8cdb56dd228bf3f23925ec076464eff964 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:03:31 +0800
Subject: [PATCH 22/64] feat(server): widget manifest JSDoc extractor +
 validator

---
 crates/server/src/service/mod.rs              |   1 +
 .../server/src/service/widget_module/error.rs |  30 ++++
 .../src/service/widget_module/extractor.rs    | 138 ++++++++++++++++++
 .../server/src/service/widget_module/mod.rs   |   4 +
 4 files changed, 173 insertions(+)
 create mode 100644 crates/server/src/service/widget_module/error.rs
 create mode 100644 crates/server/src/service/widget_module/extractor.rs
 create mode 100644 crates/server/src/service/widget_module/mod.rs

diff --git a/crates/server/src/service/mod.rs b/crates/server/src/service/mod.rs
index 58d36190..cd26b778 100644
--- a/crates/server/src/service/mod.rs
+++ b/crates/server/src/service/mod.rs
@@ -44,3 +44,4 @@ pub mod upgrade_release;
 pub mod upgrade_tracker;
 pub mod uptime;
 pub mod user;
+pub mod widget_module;
diff --git a/crates/server/src/service/widget_module/error.rs b/crates/server/src/service/widget_module/error.rs
new file mode 100644
index 00000000..e74fbbb2
--- /dev/null
+++ b/crates/server/src/service/widget_module/error.rs
@@ -0,0 +1,30 @@
+use crate::error::AppError;
+
+#[derive(Debug, thiserror::Error)]
+pub enum WidgetModuleError {
+    #[error("manifest extraction failed: {0}")]
+    ManifestExtraction(String),
+    #[error("manifest validation failed: {0}")]
+    ManifestValidation(String),
+    #[error("module id conflict: {0}")]
+    IdConflict(String),
+    #[error("module not found: {0}")]
+    NotFound(String),
+    #[error("invalid asset path")]
+    InvalidAssetPath,
+    #[error("database: {0}")]
+    Db(#[from] sea_orm::DbErr),
+}
+
+impl From<WidgetModuleError> for AppError {
+    fn from(err: WidgetModuleError) -> Self {
+        match err {
+            WidgetModuleError::NotFound(msg) => AppError::NotFound(msg),
+            WidgetModuleError::IdConflict(msg) => AppError::Conflict(msg),
+            WidgetModuleError::InvalidAssetPath
+            | WidgetModuleError::ManifestExtraction(_)
+            | WidgetModuleError::ManifestValidation(_) => AppError::BadRequest(err.to_string()),
+            WidgetModuleError::Db(e) => AppError::Internal(format!("db error: {e}")),
+        }
+    }
+}
diff --git a/crates/server/src/service/widget_module/extractor.rs b/crates/server/src/service/widget_module/extractor.rs
new file mode 100644
index 00000000..f37554f5
--- /dev/null
+++ b/crates/server/src/service/widget_module/extractor.rs
@@ -0,0 +1,138 @@
+use once_cell::sync::Lazy;
+use regex::Regex;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct WidgetSizing {
+    #[serde(rename = "defaultW")]
+    pub default_w: u32,
+    #[serde(rename = "defaultH")]
+    pub default_h: u32,
+    #[serde(rename = "minW")]
+    pub min_w: u32,
+    #[serde(rename = "minH")]
+    pub min_h: u32,
+    #[serde(default, skip_serializing_if = "Option::is_none", rename = "maxW")]
+    pub max_w: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none", rename = "maxH")]
+    pub max_h: Option<u32>,
+    pub strategy: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct WidgetManifest {
+    pub id: String,
+    pub version: String,
+    pub name: String,
+    #[serde(default)]
+    pub description: Option<String>,
+    #[serde(default)]
+    pub author: Option<String>,
+    pub category: String,
+    pub sizing: WidgetSizing,
+    #[serde(default, rename = "requiredCaps")]
+    pub required_caps: Option<Vec<String>>,
+    #[serde(rename = "sdkVersion")]
+    pub sdk_version: String,
+}
+
+static JSDOC_RE: Lazy<Regex> = Lazy::new(|| {
+    // Match @serverbee-widget followed by JSON object until JSDoc end (*/]
+    // Capture from opening { to } before the comment end
+    Regex::new(r"(?s)/\*\*[\s\S]*?@serverbee-widget\s+(\{[\s\S]*?\})\s*\*/").unwrap()
+});
+static LINE_DECOR_RE: Lazy<Regex> = Lazy::new(|| Regex::new(r"(?m)^\s*\*\s?").unwrap());
+static SEMVER_RE: Lazy<Regex> = Lazy::new(|| Regex::new(r"^\d+\.\d+\.\d+(-[\w.]+)?$").unwrap());
+static SEMVER_RANGE_RE: Lazy<Regex> =
+    Lazy::new(|| Regex::new(r"^[\^~]?\d+\.\d+\.\d+").unwrap());
+
+pub fn extract_manifest(source: &str) -> Result<WidgetManifest, super::WidgetModuleError> {
+    use super::WidgetModuleError as E;
+    let captures = JSDOC_RE
+        .captures(source)
+        .ok_or_else(|| E::ManifestExtraction("no @serverbee-widget JSDoc block found".into()))?;
+    let raw_json = captures.get(1).unwrap().as_str();
+    let cleaned = raw_json
+        .lines()
+        .map(|line| LINE_DECOR_RE.replace(line, "").to_string())
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    let manifest: WidgetManifest = serde_json::from_str(&cleaned)
+        .map_err(|e| E::ManifestExtraction(format!("invalid JSON: {e}")))?;
+
+    if manifest.id.is_empty() {
+        return Err(E::ManifestValidation("id required".into()));
+    }
+    if !SEMVER_RE.is_match(&manifest.version) {
+        return Err(E::ManifestValidation("version must be semver".into()));
+    }
+    if manifest.name.is_empty() {
+        return Err(E::ManifestValidation("name required".into()));
+    }
+    if !matches!(
+        manifest.category.as_str(),
+        "Real-time" | "Charts" | "Status"
+    ) {
+        return Err(E::ManifestValidation("category invalid".into()));
+    }
+    if !matches!(
+        manifest.sizing.strategy.as_str(),
+        "fixed" | "free" | "aspect-square" | "content-height"
+    ) {
+        return Err(E::ManifestValidation("sizing.strategy invalid".into()));
+    }
+    if !SEMVER_RANGE_RE.is_match(&manifest.sdk_version) {
+        return Err(E::ManifestValidation(
+            "sdkVersion must be semver range".into(),
+        ));
+    }
+    Ok(manifest)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const GOOD: &str = r#"/**
+ * @serverbee-widget {
+ *   "id": "com.example.cpu",
+ *   "version": "1.0.0",
+ *   "name": "CPU",
+ *   "category": "Real-time",
+ *   "sizing": { "defaultW": 3, "defaultH": 3, "minW": 2, "minH": 2, "strategy": "aspect-square" },
+ *   "sdkVersion": "^0.1.0"
+ * }
+ */
+export default {};
+"#;
+
+    #[test]
+    fn extracts_a_valid_manifest() {
+        let m = extract_manifest(GOOD).unwrap();
+        assert_eq!(m.id, "com.example.cpu");
+        assert_eq!(m.sizing.strategy, "aspect-square");
+    }
+
+    #[test]
+    fn rejects_missing_block() {
+        let res = extract_manifest("export default {};");
+        assert!(matches!(
+            res.unwrap_err(),
+            super::super::WidgetModuleError::ManifestExtraction(_)
+        ));
+    }
+
+    #[test]
+    fn rejects_invalid_category() {
+        let src = GOOD.replace(r#""category": "Real-time""#, r#""category": "Bogus""#);
+        let res = extract_manifest(&src);
+        assert!(res.is_err());
+    }
+
+    #[test]
+    fn rejects_invalid_semver() {
+        let src = GOOD.replace(r#""version": "1.0.0""#, r#""version": "not-semver""#);
+        assert!(extract_manifest(&src).is_err());
+    }
+}
diff --git a/crates/server/src/service/widget_module/mod.rs b/crates/server/src/service/widget_module/mod.rs
new file mode 100644
index 00000000..2e5a1b25
--- /dev/null
+++ b/crates/server/src/service/widget_module/mod.rs
@@ -0,0 +1,4 @@
+pub mod error;
+pub mod extractor;
+
+pub use error::WidgetModuleError;

From bd29cc33d28df2d32804057981d3447e0e62ddea Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:06:52 +0800
Subject: [PATCH 23/64] feat(server): WidgetModuleService + package extractor

---
 .../server/src/service/widget_module/mod.rs   |   3 +
 .../src/service/widget_module/package.rs      |  59 ++++++++++
 .../src/service/widget_module/service.rs      | 108 ++++++++++++++++++
 3 files changed, 170 insertions(+)
 create mode 100644 crates/server/src/service/widget_module/package.rs
 create mode 100644 crates/server/src/service/widget_module/service.rs

diff --git a/crates/server/src/service/widget_module/mod.rs b/crates/server/src/service/widget_module/mod.rs
index 2e5a1b25..a6561085 100644
--- a/crates/server/src/service/widget_module/mod.rs
+++ b/crates/server/src/service/widget_module/mod.rs
@@ -1,4 +1,7 @@
 pub mod error;
 pub mod extractor;
+pub mod package;
+pub mod service;
 
 pub use error::WidgetModuleError;
+pub use service::WidgetModuleService;
diff --git a/crates/server/src/service/widget_module/package.rs b/crates/server/src/service/widget_module/package.rs
new file mode 100644
index 00000000..d5a38e5e
--- /dev/null
+++ b/crates/server/src/service/widget_module/package.rs
@@ -0,0 +1,59 @@
+use std::collections::HashMap;
+use std::io::{Cursor, Read};
+
+use super::WidgetModuleError;
+
+/// In-memory representation of a module package, addressable by path.
+pub struct UnpackedPackage {
+    pub entries: HashMap<String, Vec<u8>>,
+}
+
+impl UnpackedPackage {
+    /// A single-file package: entry_path is treated as the only file name.
+    pub fn from_single_file(entry_path: &str, code: Vec<u8>) -> Self {
+        let mut entries = HashMap::new();
+        entries.insert(entry_path.to_string(), code);
+        Self { entries }
+    }
+
+    /// Unpack a zip blob (defends against zip-slip and oversize entries).
+    pub fn from_zip(blob: &[u8]) -> Result<Self, WidgetModuleError> {
+        const MAX_ENTRY_BYTES: u64 = 5 * 1024 * 1024;
+        let reader = Cursor::new(blob);
+        let mut zip = zip::ZipArchive::new(reader)
+            .map_err(|e| WidgetModuleError::ManifestExtraction(format!("invalid zip: {e}")))?;
+        let mut entries = HashMap::new();
+        for i in 0..zip.len() {
+            let mut entry = zip
+                .by_index(i)
+                .map_err(|e| WidgetModuleError::ManifestExtraction(format!("zip entry: {e}")))?;
+            if entry.is_dir() {
+                continue;
+            }
+            let name = entry
+                .enclosed_name()
+                .ok_or(WidgetModuleError::InvalidAssetPath)?
+                .to_string_lossy()
+                .to_string();
+            if entry.size() > MAX_ENTRY_BYTES {
+                return Err(WidgetModuleError::ManifestExtraction(format!(
+                    "entry too large: {name}"
+                )));
+            }
+            let mut buf = Vec::with_capacity(entry.size() as usize);
+            entry
+                .read_to_end(&mut buf)
+                .map_err(|e| WidgetModuleError::ManifestExtraction(format!("read: {e}")))?;
+            entries.insert(name, buf);
+        }
+        Ok(Self { entries })
+    }
+
+    pub fn get(&self, path: &str) -> Option<&[u8]> {
+        let normalised = path.trim_start_matches('/');
+        if normalised.contains("..") {
+            return None;
+        }
+        self.entries.get(normalised).map(|v| v.as_slice())
+    }
+}
diff --git a/crates/server/src/service/widget_module/service.rs b/crates/server/src/service/widget_module/service.rs
new file mode 100644
index 00000000..039cfd8f
--- /dev/null
+++ b/crates/server/src/service/widget_module/service.rs
@@ -0,0 +1,108 @@
+use sea_orm::{ColumnTrait, DatabaseConnection, EntityTrait, QueryFilter, QueryOrder};
+use serde::Serialize;
+use utoipa::ToSchema;
+
+use super::{WidgetModuleError, package::UnpackedPackage};
+use crate::entity::widget_module::{self, Entity as WidgetModuleEntity};
+
+#[derive(Debug, Serialize, ToSchema)]
+pub struct WidgetModuleListEntry {
+    pub id: String,
+    pub version: String,
+    pub source_type: String,
+    pub entry_path: String,
+    pub code_sha256: String,
+    #[schema(value_type = Object)]
+    pub manifest: serde_json::Value,
+    pub enabled: bool,
+}
+
+pub struct WidgetModuleService;
+
+impl WidgetModuleService {
+    pub async fn list(
+        db: &DatabaseConnection,
+    ) -> Result<Vec<WidgetModuleListEntry>, WidgetModuleError> {
+        let rows = WidgetModuleEntity::find()
+            .filter(widget_module::Column::Enabled.eq(true))
+            .order_by_asc(widget_module::Column::Id)
+            .all(db)
+            .await?;
+        rows.into_iter()
+            .map(|r| {
+                let manifest: serde_json::Value =
+                    serde_json::from_str(&r.manifest_json).map_err(|e| {
+                        WidgetModuleError::ManifestValidation(format!(
+                            "stored manifest invalid: {e}"
+                        ))
+                    })?;
+                Ok(WidgetModuleListEntry {
+                    id: r.id,
+                    version: r.version,
+                    source_type: format!("{:?}", r.source_type),
+                    entry_path: r.entry_path,
+                    code_sha256: r.code_sha256,
+                    manifest,
+                    enabled: r.enabled,
+                })
+            })
+            .collect()
+    }
+
+    pub async fn get(
+        db: &DatabaseConnection,
+        id: &str,
+    ) -> Result<widget_module::Model, WidgetModuleError> {
+        WidgetModuleEntity::find_by_id(id.to_string())
+            .one(db)
+            .await?
+            .ok_or_else(|| WidgetModuleError::NotFound(id.to_string()))
+    }
+
+    /// Loads the package and returns bytes + mime for a requested asset path.
+    pub async fn serve_asset(
+        db: &DatabaseConnection,
+        id: &str,
+        requested: &str,
+    ) -> Result<(Vec<u8>, String), WidgetModuleError> {
+        let row = Self::get(db, id).await?;
+        let blob = row
+            .package_blob
+            .ok_or_else(|| WidgetModuleError::NotFound(format!("{id}: no blob")))?;
+
+        let package = if blob.starts_with(b"PK\x03\x04") {
+            UnpackedPackage::from_zip(&blob)?
+        } else {
+            UnpackedPackage::from_single_file(&row.entry_path, blob)
+        };
+
+        let bytes = package
+            .get(requested)
+            .ok_or(WidgetModuleError::InvalidAssetPath)?
+            .to_vec();
+        let mime = mime_for(requested);
+        Ok((bytes, mime))
+    }
+}
+
+fn mime_for(path: &str) -> String {
+    let lower = path.to_ascii_lowercase();
+    if lower.ends_with(".js") || lower.ends_with(".mjs") {
+        "text/javascript; charset=utf-8"
+    } else if lower.ends_with(".json") {
+        "application/json"
+    } else if lower.ends_with(".css") {
+        "text/css"
+    } else if lower.ends_with(".svg") {
+        "image/svg+xml"
+    } else if lower.ends_with(".png") {
+        "image/png"
+    } else if lower.ends_with(".jpg") || lower.ends_with(".jpeg") {
+        "image/jpeg"
+    } else if lower.ends_with(".webp") {
+        "image/webp"
+    } else {
+        "application/octet-stream"
+    }
+    .to_string()
+}

From e2304a9524d80a5b504dc48b5fffbe2adfbcf1dd Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:12:13 +0800
Subject: [PATCH 24/64] feat(server): /api/widget-modules list + asset
 endpoints

---
 crates/server/src/openapi.rs                  |  6 ++
 crates/server/src/router/api/mod.rs           |  2 +
 crates/server/src/router/api/widget_module.rs | 76 +++++++++++++++++++
 3 files changed, 84 insertions(+)
 create mode 100644 crates/server/src/router/api/widget_module.rs

diff --git a/crates/server/src/openapi.rs b/crates/server/src/openapi.rs
index e37da517..9f5e300f 100644
--- a/crates/server/src/openapi.rs
+++ b/crates/server/src/openapi.rs
@@ -164,6 +164,9 @@ impl Modify for SecurityAddon {
         crate::router::api::dashboard::create_dashboard,
         crate::router::api::dashboard::update_dashboard,
         crate::router::api::dashboard::delete_dashboard,
+        // widget-modules
+        crate::router::api::widget_module::list_modules,
+        crate::router::api::widget_module::serve_asset,
         // service-monitors
         crate::router::api::service_monitor::list_monitors,
         crate::router::api::service_monitor::get_monitor,
@@ -357,6 +360,8 @@ impl Modify for SecurityAddon {
             crate::service::dashboard::CreateDashboardInput,
             crate::service::dashboard::UpdateDashboardInput,
             crate::service::dashboard::WidgetInput,
+            // widget-modules
+            crate::service::widget_module::service::WidgetModuleListEntry,
             // service-monitors
             crate::service::service_monitor::CreateServiceMonitor,
             crate::service::service_monitor::UpdateServiceMonitor,
@@ -537,6 +542,7 @@ impl Modify for SecurityAddon {
         (name = "users", description = "User management (admin only)"),
         (name = "tasks", description = "Remote command execution"),
         (name = "dashboards", description = "Custom dashboard management"),
+        (name = "widget-modules", description = "Custom widget module registry & asset serving"),
         (name = "service-monitors", description = "Server-side service monitoring (SSL/DNS/HTTP/TCP/WHOIS)"),
         (name = "ping-tasks", description = "Ping probe tasks"),
         (name = "traceroute", description = "Traceroute diagnostics"),
diff --git a/crates/server/src/router/api/mod.rs b/crates/server/src/router/api/mod.rs
index 691aac96..83bee74e 100644
--- a/crates/server/src/router/api/mod.rs
+++ b/crates/server/src/router/api/mod.rs
@@ -35,6 +35,7 @@ pub mod traceroute;
 pub mod traffic;
 pub mod uptime;
 pub mod user;
+pub mod widget_module;
 
 use std::sync::Arc;
 
@@ -73,6 +74,7 @@ pub fn router(state: Arc<AppState>) -> Router<Arc<AppState>> {
                 .merge(status_page::read_router())
                 .merge(uptime::read_router())
                 .merge(dashboard::read_router())
+                .merge(widget_module::read_router())
                 .merge(theme::read_router())
                 .merge(alert::alert_events_router())
                 .merge(geoip::read_router())
diff --git a/crates/server/src/router/api/widget_module.rs b/crates/server/src/router/api/widget_module.rs
new file mode 100644
index 00000000..c341c2ed
--- /dev/null
+++ b/crates/server/src/router/api/widget_module.rs
@@ -0,0 +1,76 @@
+use std::sync::Arc;
+
+use axum::{
+    Json, Router,
+    extract::{Path, State},
+    http::{HeaderMap, HeaderValue, StatusCode, header},
+    response::IntoResponse,
+    routing::get,
+};
+
+use crate::{
+    error::{ApiResponse, AppError, ok},
+    service::widget_module::{WidgetModuleService, service::WidgetModuleListEntry},
+    state::AppState,
+};
+
+pub fn read_router() -> Router<Arc<AppState>> {
+    Router::new()
+        .route("/widget-modules", get(list_modules))
+        .route("/widget-modules/{id}/{*asset_path}", get(serve_asset))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/widget-modules",
+    tag = "widget-modules",
+    responses(
+        (status = 200, description = "List installed widget modules", body = Vec<WidgetModuleListEntry>),
+    ),
+    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
+)]
+pub async fn list_modules(
+    State(state): State<Arc<AppState>>,
+) -> Result<Json<ApiResponse<Vec<WidgetModuleListEntry>>>, AppError> {
+    let modules = WidgetModuleService::list(&state.db).await?;
+    ok(modules)
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/widget-modules/{id}/{asset_path}",
+    tag = "widget-modules",
+    params(
+        ("id" = String, Path, description = "Module ID"),
+        ("asset_path" = String, Path, description = "Asset path within the package"),
+    ),
+    responses(
+        (status = 200, description = "Asset bytes"),
+        (status = 404, description = "Module or asset not found"),
+    ),
+    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
+)]
+pub async fn serve_asset(
+    State(state): State<Arc<AppState>>,
+    Path((id, asset_path)): Path<(String, String)>,
+) -> Result<impl IntoResponse, AppError> {
+    let (bytes, mime) = WidgetModuleService::serve_asset(&state.db, &id, &asset_path).await?;
+    let row = WidgetModuleService::get(&state.db, &id).await?;
+    let etag_suffix_len = 8.min(row.code_sha256.len());
+    let etag = format!("\"{}-{}\"", row.version, &row.code_sha256[..etag_suffix_len]);
+
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        header::CONTENT_TYPE,
+        HeaderValue::from_str(&mime).map_err(|e| AppError::Internal(e.to_string()))?,
+    );
+    headers.insert(
+        header::ETAG,
+        HeaderValue::from_str(&etag).map_err(|e| AppError::Internal(e.to_string()))?,
+    );
+    headers.insert(
+        header::CACHE_CONTROL,
+        HeaderValue::from_static("public, max-age=86400, immutable"),
+    );
+    Ok((StatusCode::OK, headers, bytes))
+}

From 85b3d83e2ff419da062915d7e38b2bcc7ad3fcbb Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:15:06 +0800
Subject: [PATCH 25/64] test(server): integration tests for widget_module list
 + asset

---
 .../server/tests/widget_module_integration.rs | 292 ++++++++++++++++++
 1 file changed, 292 insertions(+)
 create mode 100644 crates/server/tests/widget_module_integration.rs

diff --git a/crates/server/tests/widget_module_integration.rs b/crates/server/tests/widget_module_integration.rs
new file mode 100644
index 00000000..3ee150d0
--- /dev/null
+++ b/crates/server/tests/widget_module_integration.rs
@@ -0,0 +1,292 @@
+use std::time::Duration;
+
+use chrono::Utc;
+use reqwest::Client;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::TcpStream;
+use sea_orm::ActiveValue::Set;
+use sea_orm::{ActiveModelTrait, ConnectOptions, ConnectionTrait, Database, DatabaseConnection};
+use sea_orm_migration::MigratorTrait;
+use serde_json::json;
+use serverbee_server::config::{AppConfig, AuthConfig, DatabaseConfig, ServerConfig};
+use serverbee_server::entity::widget_module::{self, SourceType};
+use serverbee_server::migration::Migrator;
+use serverbee_server::router::create_router;
+use serverbee_server::service::auth::AuthService;
+use serverbee_server::service::widget_module::extractor::extract_manifest;
+use serverbee_server::state::AppState;
+
+struct TestServerContext {
+    base_url: String,
+    db: DatabaseConnection,
+    _tmp: tempfile::TempDir,
+}
+
+/// Start an in-process test server and return a context exposing both the
+/// base URL and the underlying sea-orm connection so tests can seed rows
+/// directly.
+async fn start_test_server_with_db() -> TestServerContext {
+    let tmp = tempfile::tempdir().expect("Failed to create temp dir");
+    let data_dir = tmp.path().to_str().unwrap().to_string();
+
+    let config = AppConfig {
+        server: ServerConfig {
+            listen: "127.0.0.1:0".to_string(),
+            data_dir: data_dir.clone(),
+            trusted_proxies: Vec::new(),
+        },
+        database: DatabaseConfig {
+            path: "test.db".to_string(),
+            max_connections: 5,
+        },
+        auth: AuthConfig {
+            session_ttl: 86400,
+            secure_cookie: false,
+            max_servers: 0,
+        },
+        ..AppConfig::default()
+    };
+
+    let db_path = format!("{data_dir}/test.db");
+    let db_url = format!("sqlite://{db_path}?mode=rwc");
+    let mut opt = ConnectOptions::new(&db_url);
+    opt.max_connections(5);
+    opt.sqlx_logging(false);
+
+    let db = Database::connect(opt)
+        .await
+        .expect("Failed to connect to test database");
+
+    db.execute_unprepared("PRAGMA journal_mode=WAL")
+        .await
+        .expect("Failed to enable WAL");
+    db.execute_unprepared("PRAGMA foreign_keys=ON")
+        .await
+        .expect("Failed to enable foreign keys");
+
+    Migrator::up(&db, None)
+        .await
+        .expect("Failed to run migrations");
+
+    AuthService::create_user(&db, "admin", "testpass", "admin")
+        .await
+        .expect("Failed to seed admin");
+
+    let state_db = db.clone();
+    let state = AppState::new(state_db, config)
+        .await
+        .expect("Failed to create AppState");
+    let app = create_router(state);
+
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("Failed to bind listener");
+    let addr = listener.local_addr().unwrap();
+    let base_url = format!("http://{addr}");
+
+    tokio::spawn(async move {
+        axum::serve(
+            listener,
+            app.into_make_service_with_connect_info::<std::net::SocketAddr>(),
+        )
+        .await
+        .unwrap();
+    });
+
+    tokio::time::sleep(Duration::from_millis(50)).await;
+
+    TestServerContext {
+        base_url,
+        db,
+        _tmp: tmp,
+    }
+}
+
+fn http_client() -> Client {
+    Client::builder()
+        .cookie_store(true)
+        .timeout(Duration::from_secs(10))
+        .build()
+        .expect("Failed to build HTTP client")
+}
+
+async fn login_admin(client: &Client, base_url: &str) {
+    let resp = client
+        .post(format!("{base_url}/api/auth/login"))
+        .json(&json!({ "username": "admin", "password": "testpass" }))
+        .send()
+        .await
+        .expect("Login request failed");
+    assert_eq!(resp.status(), 200, "Login should succeed");
+}
+
+async fn seed_module(db: &DatabaseConnection, id: &str) {
+    let code = format!(
+        r#"/**
+ * @serverbee-widget {{
+ *   "id": "{id}",
+ *   "version": "1.0.0",
+ *   "name": "Foo",
+ *   "category": "Real-time",
+ *   "sizing": {{ "defaultW": 3, "defaultH": 3, "minW": 2, "minH": 2, "strategy": "aspect-square" }},
+ *   "sdkVersion": "^0.1.0"
+ * }}
+ */
+export default {{}};
+"#
+    );
+    let manifest = extract_manifest(&code).expect("manifest");
+    let sha = sha256_hex(code.as_bytes());
+
+    widget_module::ActiveModel {
+        id: Set(id.to_string()),
+        version: Set("1.0.0".into()),
+        source_type: Set(SourceType::Upload),
+        source_url: Set(None),
+        bundled_by_theme_id: Set(None),
+        manifest_json: Set(serde_json::to_string(&manifest).unwrap()),
+        code_sha256: Set(sha),
+        entry_path: Set("index.js".into()),
+        package_blob: Set(Some(code.into_bytes())),
+        installed_by: Set(None),
+        installed_at: Set(Utc::now()),
+        enabled: Set(true),
+    }
+    .insert(db)
+    .await
+    .expect("Failed to seed widget_module row");
+}
+
+fn sha256_hex(bytes: &[u8]) -> String {
+    use sha2::{Digest, Sha256};
+    let mut hasher = Sha256::new();
+    hasher.update(bytes);
+    format!("{:x}", hasher.finalize())
+}
+
+#[tokio::test]
+async fn list_returns_seeded_module() {
+    let ctx = start_test_server_with_db().await;
+    seed_module(&ctx.db, "com.test.foo").await;
+
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    let res = client
+        .get(format!("{}/api/widget-modules", ctx.base_url))
+        .send()
+        .await
+        .expect("GET /api/widget-modules failed");
+    assert_eq!(res.status(), 200, "list endpoint should return 200");
+
+    let body: serde_json::Value = res.json().await.expect("invalid JSON body");
+    let list = body["data"].as_array().expect("data should be an array");
+    assert!(
+        list.iter().any(|m| m["id"] == "com.test.foo"),
+        "seeded module not found in list: {body}"
+    );
+}
+
+#[tokio::test]
+async fn serve_asset_returns_entry_bytes() {
+    let ctx = start_test_server_with_db().await;
+    seed_module(&ctx.db, "com.test.foo").await;
+
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    let res = client
+        .get(format!(
+            "{}/api/widget-modules/com.test.foo/index.js",
+            ctx.base_url
+        ))
+        .send()
+        .await
+        .expect("GET asset failed");
+    assert_eq!(res.status(), 200);
+
+    let ct = res
+        .headers()
+        .get("content-type")
+        .expect("content-type header missing")
+        .to_str()
+        .expect("invalid content-type")
+        .to_string();
+    assert!(ct.contains("javascript"), "unexpected content-type: {ct}");
+    assert!(
+        res.headers().contains_key("etag"),
+        "etag header should be present"
+    );
+
+    let body = res.text().await.expect("body text");
+    assert!(
+        body.contains("@serverbee-widget"),
+        "asset body should contain the original JSDoc block"
+    );
+}
+
+#[tokio::test]
+async fn serve_asset_rejects_path_traversal() {
+    let ctx = start_test_server_with_db().await;
+    seed_module(&ctx.db, "com.test.foo").await;
+
+    // Authenticate first and capture the session cookie so the raw TCP
+    // request below isn't rejected by the auth middleware (which would
+    // produce a 401 and mask whatever the path-traversal handling actually
+    // does).
+    let client = http_client();
+    let login_resp = client
+        .post(format!("{}/api/auth/login", ctx.base_url))
+        .json(&json!({ "username": "admin", "password": "testpass" }))
+        .send()
+        .await
+        .expect("login request failed");
+    assert_eq!(login_resp.status(), 200);
+    let set_cookie = login_resp
+        .headers()
+        .get(reqwest::header::SET_COOKIE)
+        .expect("Set-Cookie missing")
+        .to_str()
+        .expect("invalid cookie")
+        .to_string();
+    let cookie_pair = set_cookie
+        .split(';')
+        .next()
+        .expect("cookie pair")
+        .trim()
+        .to_string();
+
+    // Reqwest / the `url` crate normalize `..` segments client-side, and even
+    // percent-encoded `%2E%2E` gets canonicalized because `.` is unreserved.
+    // Craft a raw HTTP/1.1 request over a plain TCP socket so the literal
+    // `../secret` reaches the server.
+    let host_port = ctx
+        .base_url
+        .strip_prefix("http://")
+        .expect("base_url prefix")
+        .to_string();
+    let path = "/api/widget-modules/com.test.foo/../secret";
+
+    let mut stream = TcpStream::connect(&host_port)
+        .await
+        .expect("failed to connect to test server");
+    let req = format!(
+        "GET {path} HTTP/1.1\r\nHost: {host_port}\r\nCookie: {cookie_pair}\r\nConnection: close\r\n\r\n"
+    );
+    stream
+        .write_all(req.as_bytes())
+        .await
+        .expect("write request");
+
+    let mut buf = Vec::new();
+    stream
+        .read_to_end(&mut buf)
+        .await
+        .expect("read response");
+    let response = String::from_utf8_lossy(&buf);
+    let status_line = response.lines().next().unwrap_or("");
+    assert!(
+        status_line.starts_with("HTTP/1.1 4"),
+        "path traversal should be rejected with 4xx, got status line: {status_line}"
+    );
+}

From 9b5b004d8e5f609b8aa8cb4efd8779276652b39e Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:15:52 +0800
Subject: [PATCH 26/64] =?UTF-8?q?docs(plan):=20plan=202=20=E2=80=94=20buil?=
 =?UTF-8?q?d=20pipeline=20+=20runtime=20bridge=20wire-up?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...28-custom-widget-system-plan-2-pipeline.md | 727 ++++++++++++++++++
 1 file changed, 727 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-28-custom-widget-system-plan-2-pipeline.md

diff --git a/docs/superpowers/plans/2026-05-28-custom-widget-system-plan-2-pipeline.md b/docs/superpowers/plans/2026-05-28-custom-widget-system-plan-2-pipeline.md
new file mode 100644
index 00000000..f566bec1
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-28-custom-widget-system-plan-2-pipeline.md
@@ -0,0 +1,727 @@
+# Custom Widget System — Plan 2: Build Pipeline + Real Runtime Wire-up
+
+> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:subagent-driven-development.
+
+**Scope:** Make the SDK + Registry + asset endpoints from Plan 1 actually do something visible. Add one example built-in widget, wire the Vite multi-entry pipeline that ships it, write the Rust boot routine that registers it, and replace the runtime bridge's stub stores with the real `useServersWs` + theme + dashboard editor wiring. Rewriting the existing 14 widgets is **deferred** to a follow-up — Plan 2 lands the substrate that future PRs can rewrite against.
+
+**Goal:** After Plan 2, a fresh server boot registers one `Builtin` widget module, the SPA loads it through `/api/widget-modules/...`, and the dashboard editor can drop it onto a dashboard and see live data flowing.
+
+**Architecture:** Vite multi-entry emits `apps/web/dist/builtin-widgets/<id>/index.js` + `manifest.json`. Rust embeds that directory and upserts a `widget_module` row per manifest entry on every boot (`source_type = Builtin`, `package_blob = NULL`, served from rust-embed). The asset endpoint special-cases Builtin sources. A new `WidgetRendererV2` reads `dashboard_widget.module_id`, finds the module in the Registry, and renders the SDK `component`. The existing legacy `WidgetRenderer` keeps working for old `widget_type` rows (parallel until Plan 2 followup deletes them).
+
+**Tech Stack:** Vite 7 plugin API · rust-embed · Axum static file serving · React 19 + zustand
+
+**Spec:** `docs/superpowers/specs/2026-05-28-custom-widget-system-design.md`
+**Prior plan:** `docs/superpowers/plans/2026-05-28-custom-widget-system-plan-1-sdk.md`
+
+---
+
+## Conventions
+
+- All built-in widgets live at `apps/web/src/builtin-widgets/*.widget.tsx`.
+- Generated manifest at `apps/web/dist/builtin-widgets/manifest.json` is consumed by Rust.
+- New parallel dashboard widget id column `module_id` is **added** in this plan (next to `widget_type`); legacy column stays until Plan 3 cleanup.
+
+---
+
+## Task 1: Add example built-in widget source
+
+**Files:**
+- Create: `apps/web/src/builtin-widgets/hello-world.widget.tsx`
+- Create: `apps/web/src/builtin-widgets/.gitkeep` (ensure directory tracked)
+
+- [ ] **Step 1: Write the widget file**
+
+`apps/web/src/builtin-widgets/hello-world.widget.tsx`:
+
+```tsx
+/**
+ * @serverbee-widget {
+ *   "id": "com.serverbee.hello-world",
+ *   "version": "1.0.0",
+ *   "name": "Hello World",
+ *   "description": "A minimal builtin widget that displays the SPA theme mode and the count of online servers.",
+ *   "author": "ServerBee",
+ *   "category": "Real-time",
+ *   "sizing": { "defaultW": 3, "defaultH": 2, "minW": 2, "minH": 2, "strategy": "free" },
+ *   "sdkVersion": "^0.1.0"
+ * }
+ */
+import { defineWidget, useServers, useTheme, z } from '@serverbee/widget-sdk'
+
+const ConfigSchema = z.object({
+  greeting: z.string().describe('Greeting text').default('Hello, ServerBee'),
+})
+
+export default defineWidget({
+  configSchema: ConfigSchema,
+  component: ({ config }) => {
+    const servers = useServers()
+    const theme = useTheme()
+    const online = servers.filter((s) => s.online).length
+    return (
+      <div style={{ padding: 12, fontFamily: 'system-ui' }}>
+        <div style={{ fontSize: 16, fontWeight: 600 }}>{config.greeting}</div>
+        <div style={{ marginTop: 8, color: 'var(--muted-foreground)' }}>
+          {online} / {servers.length} online · {theme.mode} mode
+        </div>
+      </div>
+    )
+  },
+})
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add apps/web/src/builtin-widgets
+git -c commit.gpgsign=false commit -m "feat(web): add hello-world example builtin widget"
+```
+
+---
+
+## Task 2: Vite plugin to emit builtin-widgets manifest
+
+**Files:**
+- Create: `apps/web/vite-plugins/builtin-widgets.ts`
+- Modify: `apps/web/vite.config.ts`
+
+- [ ] **Step 1: Write the plugin**
+
+`apps/web/vite-plugins/builtin-widgets.ts`:
+
+```ts
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { globSync } from 'tinyglobby'
+import type { Plugin } from 'vite'
+
+interface BuiltinManifestEntry {
+  id: string
+  version: string
+  entry_path: string
+  manifest: Record<string, unknown>
+}
+
+const JSDOC_RE = /\/\*\*[\s\S]*?@serverbee-widget\s+(\{[\s\S]*?\})\s*\*\//
+const LINE_DECOR = /^\s*\*\s?/gm
+
+function extractManifest(source: string): Record<string, unknown> {
+  const m = source.match(JSDOC_RE)
+  if (!m) throw new Error('no @serverbee-widget JSDoc block')
+  return JSON.parse(m[1].replace(LINE_DECOR, ''))
+}
+
+export function builtinWidgetsPlugin(): Plugin {
+  const SRC_DIR = 'src/builtin-widgets'
+  const entries = new Map<string, { srcPath: string; manifest: Record<string, unknown> }>()
+
+  return {
+    name: 'serverbee-builtin-widgets',
+    config(userConfig) {
+      const files = globSync(`${SRC_DIR}/*.widget.tsx`, { absolute: false })
+      for (const file of files) {
+        const id = path.basename(file, '.widget.tsx') // e.g. 'hello-world'
+        const source = readFileSync(file, 'utf8')
+        const manifest = extractManifest(source)
+        entries.set(id, { srcPath: file, manifest })
+      }
+      const inputs: Record<string, string> = { main: 'index.html' }
+      for (const [id, e] of entries) {
+        inputs[`builtin-widgets/${id}/index`] = path.resolve(e.srcPath)
+      }
+      const existing = userConfig.build?.rollupOptions?.input
+      const merged =
+        typeof existing === 'string' || Array.isArray(existing)
+          ? inputs
+          : { ...(existing as Record<string, string>), ...inputs }
+      return {
+        build: {
+          rollupOptions: {
+            input: merged,
+            external: ['react', 'react-dom', 'react/jsx-runtime', '@serverbee/widget-sdk'],
+            output: {
+              entryFileNames: (chunk: any) =>
+                chunk.name?.startsWith('builtin-widgets/')
+                  ? `${chunk.name}.js`
+                  : 'assets/[name]-[hash].js',
+            },
+          },
+        },
+      }
+    },
+    generateBundle() {
+      const list: BuiltinManifestEntry[] = []
+      for (const [id, e] of entries) {
+        const m = e.manifest as { id: string; version: string }
+        list.push({
+          id: m.id,
+          version: m.version,
+          entry_path: `${id}/index.js`,
+          manifest: e.manifest,
+        })
+      }
+      this.emitFile({
+        type: 'asset',
+        fileName: 'builtin-widgets/manifest.json',
+        source: JSON.stringify(list, null, 2),
+      })
+    },
+  }
+}
+```
+
+- [ ] **Step 2: Add `tinyglobby` to apps/web devDependencies if not already present**
+
+Check: `grep tinyglobby apps/web/package.json`. If missing: `cd apps/web && bun add -d tinyglobby`.
+
+- [ ] **Step 3: Wire plugin into vite.config.ts**
+
+In `apps/web/vite.config.ts`:
+- `import { builtinWidgetsPlugin } from './vite-plugins/builtin-widgets'`
+- Add `builtinWidgetsPlugin()` to the `plugins` array (after `react()`)
+
+- [ ] **Step 4: Verify build emits the artifacts**
+
+Run: `cd apps/web && bun run build`
+After build:
+- `ls apps/web/dist/builtin-widgets/` → should contain `manifest.json` and `hello-world/index.js`
+- `cat apps/web/dist/builtin-widgets/manifest.json` → contains the hello-world entry with the manifest from the JSDoc block
+- `head -3 apps/web/dist/builtin-widgets/hello-world/index.js` → should reference imports from `react` / `@serverbee/widget-sdk` (NOT bundle them)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/web/vite-plugins apps/web/vite.config.ts apps/web/package.json bun.lock
+git -c commit.gpgsign=false commit -m "build(web): vite plugin emits builtin widget bundles + manifest"
+```
+
+---
+
+## Task 3: Rust — register builtin widgets at server boot
+
+**Files:**
+- Create: `crates/server/src/service/widget_module/builtin.rs`
+- Modify: `crates/server/src/service/widget_module/mod.rs`
+- Modify: `crates/server/src/router/static_files.rs` (special-case Builtin in asset serve) — see Task 4
+- Modify: `crates/server/src/main.rs` (or wherever `migrate_database` / startup runs) — invoke `register_all` after migrations
+
+- [ ] **Step 1: Write registration routine**
+
+`crates/server/src/service/widget_module/builtin.rs`:
+
+```rust
+use chrono::Utc;
+use rust_embed::Embed;
+use sea_orm::{ActiveValue::Set, DatabaseConnection, EntityTrait};
+use serde::Deserialize;
+use sha2::{Digest, Sha256};
+
+use crate::entity::widget_module::{self, Entity as WidgetModuleEntity, SourceType};
+
+/// Reads `dist/builtin-widgets/manifest.json` from the embedded SPA assets.
+#[derive(Embed)]
+#[folder = "../../apps/web/dist/builtin-widgets"]
+#[include = "**/*.js"]
+#[include = "manifest.json"]
+struct BuiltinAssets;
+
+#[derive(Debug, Deserialize)]
+struct ManifestEntry {
+    id: String,
+    version: String,
+    entry_path: String,
+    manifest: serde_json::Value,
+}
+
+pub async fn register_all(db: &DatabaseConnection) -> anyhow::Result<()> {
+    let raw = BuiltinAssets::get("manifest.json")
+        .ok_or_else(|| anyhow::anyhow!("dist/builtin-widgets/manifest.json missing (run `bun run build` first)"))?;
+    let entries: Vec<ManifestEntry> = serde_json::from_slice(raw.data.as_ref())?;
+
+    for entry in &entries {
+        let code = BuiltinAssets::get(&entry.entry_path)
+            .ok_or_else(|| anyhow::anyhow!("builtin entry missing: {}", entry.entry_path))?;
+        let sha = {
+            let mut h = Sha256::new();
+            h.update(code.data.as_ref());
+            format!("{:x}", h.finalize())
+        };
+
+        let active = widget_module::ActiveModel {
+            id: Set(entry.id.clone()),
+            version: Set(entry.version.clone()),
+            source_type: Set(SourceType::Builtin),
+            source_url: Set(None),
+            bundled_by_theme_id: Set(None),
+            manifest_json: Set(serde_json::to_string(&entry.manifest)?),
+            code_sha256: Set(sha),
+            entry_path: Set(entry.entry_path.clone()),
+            package_blob: Set(None),
+            installed_by: Set(None),
+            installed_at: Set(Utc::now()),
+            enabled: Set(true),
+        };
+
+        // Upsert by primary key
+        use sea_orm::sea_query::OnConflict;
+        WidgetModuleEntity::insert(active)
+            .on_conflict(
+                OnConflict::column(widget_module::Column::Id)
+                    .update_columns([
+                        widget_module::Column::Version,
+                        widget_module::Column::ManifestJson,
+                        widget_module::Column::CodeSha256,
+                        widget_module::Column::EntryPath,
+                        widget_module::Column::InstalledAt,
+                        widget_module::Column::Enabled,
+                    ])
+                    .to_owned(),
+            )
+            .exec(db)
+            .await?;
+    }
+
+    // Disable any stale Builtin rows not present in the current manifest.
+    use sea_orm::{ColumnTrait, QueryFilter};
+    let active_ids: Vec<String> = entries.iter().map(|e| e.id.clone()).collect();
+    let mut delete = WidgetModuleEntity::delete_many()
+        .filter(widget_module::Column::SourceType.eq(SourceType::Builtin));
+    if !active_ids.is_empty() {
+        delete = delete.filter(widget_module::Column::Id.is_not_in(active_ids));
+    }
+    delete.exec(db).await?;
+
+    Ok(())
+}
+
+pub fn builtin_asset_bytes(entry_path: &str) -> Option<Vec<u8>> {
+    BuiltinAssets::get(entry_path).map(|f| f.data.into_owned())
+}
+```
+
+- [ ] **Step 2: Register module**
+
+In `crates/server/src/service/widget_module/mod.rs`, add:
+```rust
+pub mod builtin;
+```
+
+- [ ] **Step 3: Invoke at startup**
+
+Find where the server runs migrations (`Migrator::up(&db, None).await?` — likely in `main.rs` or a `start_server` helper). Immediately after migrations, add:
+
+```rust
+crate::service::widget_module::builtin::register_all(&db).await?;
+```
+
+If the surrounding context returns a non-anyhow error type, map: `.map_err(|e| anyhow::anyhow!(e))?` or convert via the local error wrapper.
+
+- [ ] **Step 4: Verify**
+
+Build: `cargo build -p serverbee-server`.
+
+If the build fails because `apps/web/dist/builtin-widgets/` does not exist yet (i.e. fresh checkout), the developer must run `cd apps/web && bun run build` first. Document this in `CLAUDE.md` build commands section. For now ensure the artifacts exist locally before continuing.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/server/src/service/widget_module crates/server/src/main.rs
+git -c commit.gpgsign=false commit -m "feat(server): register builtin widgets on boot from embedded manifest"
+```
+
+---
+
+## Task 4: Asset endpoint serves Builtin via rust-embed
+
+**Files:**
+- Modify: `crates/server/src/service/widget_module/service.rs`
+
+- [ ] **Step 1: Branch on source_type**
+
+Find `serve_asset` in service.rs. Modify to check `row.source_type`:
+- If `SourceType::Builtin` → read bytes from `crate::service::widget_module::builtin::builtin_asset_bytes(requested)` (which already includes the full path like `hello-world/index.js`)
+- Otherwise → existing BLOB unpacking logic
+
+Replace the existing `serve_asset` with:
+
+```rust
+pub async fn serve_asset(
+    db: &DatabaseConnection,
+    id: &str,
+    requested: &str,
+) -> Result<(Vec<u8>, String), WidgetModuleError> {
+    let row = Self::get(db, id).await?;
+
+    if matches!(row.source_type, crate::entity::widget_module::SourceType::Builtin) {
+        // Builtin: requested path is module-local (e.g. "index.js"). Builtin manifest
+        // stores entry_path as e.g. "hello-world/index.js" — the URL `<id>/index.js`
+        // means resolve `<requested>` relative to the module's folder.
+        let folder = row.entry_path.rsplit_once('/').map(|(d, _)| d).unwrap_or("");
+        let full = if folder.is_empty() {
+            requested.to_string()
+        } else {
+            format!("{folder}/{requested}")
+        };
+        if full.contains("..") {
+            return Err(WidgetModuleError::InvalidAssetPath);
+        }
+        let bytes = crate::service::widget_module::builtin::builtin_asset_bytes(&full)
+            .ok_or(WidgetModuleError::InvalidAssetPath)?;
+        return Ok((bytes, mime_for(&full)));
+    }
+
+    let blob = row
+        .package_blob
+        .ok_or_else(|| WidgetModuleError::NotFound(format!("{id}: no blob")))?;
+
+    let package = if blob.starts_with(b"PK\x03\x04") {
+        UnpackedPackage::from_zip(&blob)?
+    } else {
+        UnpackedPackage::from_single_file(&row.entry_path, blob)
+    };
+
+    let bytes = package
+        .get(requested)
+        .ok_or(WidgetModuleError::InvalidAssetPath)?
+        .to_vec();
+    let mime = mime_for(requested);
+    Ok((bytes, mime))
+}
+```
+
+- [ ] **Step 2: Verify integration tests still pass**
+
+Run: `cargo test -p serverbee-server --test widget_module_integration`
+Expected: 3 tests still pass.
+
+- [ ] **Step 3: Add a 4th test for Builtin path**
+
+Append to `crates/server/tests/widget_module_integration.rs`:
+
+```rust
+#[tokio::test]
+async fn list_includes_builtin_hello_world() {
+    let ctx = start_test_server_with_db().await.expect("server");
+    let client = reqwest::Client::new();
+    let res = client
+        .get(format!("{}/api/widget-modules", ctx.base_url))
+        .header("cookie", &ctx.admin_cookie)
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(res.status(), 200);
+    let body: serde_json::Value = res.json().await.unwrap();
+    let list = body["data"].as_array().expect("list");
+    assert!(
+        list.iter().any(|m| m["id"] == "com.serverbee.hello-world"),
+        "expected hello-world in list, got {body:#?}"
+    );
+}
+```
+
+If the test helper doesn't already run register_all at startup (it should, via the normal main flow), the test will fail. Ensure `register_all` is called inside the test harness too — by virtue of running the real `create_router` + setup that the integration test already uses.
+
+Run: `cargo test -p serverbee-server --test widget_module_integration` — 4 tests pass.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add crates/server
+git -c commit.gpgsign=false commit -m "feat(server): serve Builtin widget assets via rust-embed"
+```
+
+---
+
+## Task 5: dashboard_widget — add `module_id` column
+
+**Files:**
+- Create: `crates/server/src/migration/m20260528_000051_dashboard_widget_module_id.rs`
+- Modify: `crates/server/src/migration/mod.rs`
+- Modify: `crates/server/src/entity/dashboard_widget.rs`
+
+- [ ] **Step 1: Write migration**
+
+`crates/server/src/migration/m20260528_000051_dashboard_widget_module_id.rs`:
+
+```rust
+use sea_orm_migration::prelude::*;
+
+#[derive(DeriveMigrationName)]
+pub struct Migration;
+
+#[async_trait::async_trait]
+impl MigrationTrait for Migration {
+    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        let db = manager.get_connection();
+        db.execute_unprepared(
+            "ALTER TABLE dashboard_widget ADD COLUMN module_id TEXT",
+        )
+        .await?;
+        db.execute_unprepared(
+            "CREATE INDEX IF NOT EXISTS idx_dashboard_widget_module_id ON dashboard_widget(module_id)",
+        )
+        .await?;
+        Ok(())
+    }
+    async fn down(&self, _m: &SchemaManager) -> Result<(), DbErr> { Ok(()) }
+}
+```
+
+- [ ] **Step 2: Register migration + entity field**
+
+- `crates/server/src/migration/mod.rs`: `mod m20260528_000051_dashboard_widget_module_id;` + append to migrations vec.
+- `crates/server/src/entity/dashboard_widget.rs`: add `pub module_id: Option<String>,` field to the `Model` struct (next to `widget_type`).
+
+- [ ] **Step 3: Verify**
+
+`cargo build -p serverbee-server && cargo clippy -p serverbee-server -- -D warnings`
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add crates/server
+git -c commit.gpgsign=false commit -m "feat(server): dashboard_widget.module_id column (alongside widget_type)"
+```
+
+---
+
+## Task 6: Front-end — real `mountRuntimeBridge` wiring
+
+**Files:**
+- Modify: `apps/web/src/widgets-runtime/runtime-bridge.ts`
+- Modify: `apps/web/src/main.tsx`
+
+- [ ] **Step 1: Inspect existing servers store**
+
+Read `apps/web/src/hooks/use-servers-ws.ts` and find:
+- The exposed hook that returns the array of ServerMetrics
+- The exact shape of a ServerMetrics object (we need `id`, `name`, `online`, capabilities bitmask)
+
+The `mountRuntimeBridge` callbacks need to be CALLED at hook-time (because they call zustand subscriptions). Since `serversStore: () => ServerSummary[]` is a plain function (not a React hook), we can't put a `useSyncExternalStore` in there directly. Solution: expose zustand store via `useServersWsStore.getState().servers` (raw snapshot) and map to ServerSummary.
+
+If the servers store doesn't have a `useStore.getState()` access (i.e. it's not a zustand store), we may need to expose a side-channel ref that the React tree updates. Inspect first; report findings.
+
+Strategy (most likely works):
+```ts
+import { useServersWsStore } from '@/hooks/use-servers-ws'  // confirm actual export
+
+serversStore: () => {
+  const snap = useServersWsStore.getState()
+  return snap.servers.map((s) => ({
+    id: s.id,
+    name: s.name ?? s.id,
+    online: s.online,
+    lastSeen: s.last_seen ? Date.parse(s.last_seen) : null,
+    capabilities: s.capabilities ?? 0,
+  }))
+},
+serverByIdStore: (id) => useServersWsStore.getState().servers.find((s) => s.id === id),
+```
+
+If `use-servers-ws.ts` exports something different (a TanStack Query hook, or a Context), instead expose the snapshot via a module-level mutable ref that gets updated by a `useEffect` in the layout. Adapt as needed.
+
+- [ ] **Step 2: Wire theme**
+
+In runtime-bridge.ts, the `themeStore` callback already works (reads `html.dark` class). Keep as-is.
+
+- [ ] **Step 3: Wire onConfigUpdate**
+
+This requires the dashboard editor to expose an update method. For Plan 2 keep as a stub (Plan 2-followup will wire it):
+
+```ts
+onConfigUpdate: (instanceId, patch) => {
+  console.warn('onConfigUpdate not yet wired', instanceId, patch)
+},
+```
+
+- [ ] **Step 4: Verify**
+
+`cd apps/web && bun run typecheck && bun run test` — all pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/web/src
+git -c commit.gpgsign=false commit -m "feat(web): wire real servers store into widget runtime bridge"
+```
+
+---
+
+## Task 7: WidgetRendererV2 — render modules by `module_id`
+
+**Files:**
+- Create: `apps/web/src/components/dashboard/widget-renderer-v2.tsx`
+- Create: `apps/web/src/components/dashboard/widget-renderer-v2.test.tsx`
+
+- [ ] **Step 1: Write minimal test**
+
+`apps/web/src/components/dashboard/widget-renderer-v2.test.tsx`:
+
+```tsx
+import { describe, it, expect, beforeEach } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { useWidgetRegistry } from '@/widgets-runtime/registry'
+import type { WidgetModule, WidgetManifest } from '@serverbee/widget-sdk'
+import { WidgetRendererV2 } from './widget-renderer-v2'
+
+const manifest: WidgetManifest = {
+  id: 'com.test.t',
+  version: '1.0.0',
+  name: 'T',
+  category: 'Real-time',
+  sizing: { defaultW: 2, defaultH: 2, minW: 1, minH: 1, strategy: 'free' },
+  sdkVersion: '^0.1.0',
+}
+const widgetModule: WidgetModule = {
+  __brand: 'WidgetModule',
+  configSchema: {} as any,
+  component: ({ config }: any) => <div>greeting: {config?.text ?? 'none'}</div>,
+  actions: [],
+}
+
+describe('WidgetRendererV2', () => {
+  beforeEach(() => {
+    useWidgetRegistry.setState({ modules: new Map(), failures: new Map() })
+  })
+
+  it('renders the registered module component with parsed config', () => {
+    useWidgetRegistry.setState({
+      modules: new Map([['com.test.t', { manifest, module: widgetModule }]]),
+      failures: new Map(),
+    })
+    render(<WidgetRendererV2 moduleId="com.test.t" configJson='{"text":"hi"}' isEditing={false} size={{ w: 200, h: 100 }} />)
+    expect(screen.getByText('greeting: hi')).toBeInTheDocument()
+  })
+
+  it('renders a placeholder when module is not registered', () => {
+    render(<WidgetRendererV2 moduleId="com.test.missing" configJson="{}" isEditing={false} size={{ w: 200, h: 100 }} />)
+    expect(screen.getByText(/not loaded/i)).toBeInTheDocument()
+  })
+})
+```
+
+- [ ] **Step 2: Run — FAIL**
+
+`cd apps/web && bunx vitest run src/components/dashboard/widget-renderer-v2.test.tsx`
+
+- [ ] **Step 3: Implement**
+
+`apps/web/src/components/dashboard/widget-renderer-v2.tsx`:
+
+```tsx
+import { Component, type ErrorInfo, type ReactNode, useMemo } from 'react'
+import { createActionsHelper } from '@serverbee/widget-sdk'
+import { useWidgetRegistry } from '@/widgets-runtime/registry'
+
+interface Props {
+  moduleId: string
+  configJson: string
+  isEditing: boolean
+  size: { w: number; h: number }
+}
+
+class ErrorBoundary extends Component<{ children: ReactNode }, { hasError: boolean }> {
+  state = { hasError: false }
+  static getDerivedStateFromError() {
+    return { hasError: true }
+  }
+  componentDidCatch(err: Error, info: ErrorInfo) {
+    console.error('widget render error', err, info)
+  }
+  render() {
+    return this.state.hasError ? (
+      <div className="flex h-full items-center justify-center text-destructive text-sm">
+        Widget crashed
+      </div>
+    ) : (
+      this.props.children
+    )
+  }
+}
+
+export function WidgetRendererV2({ moduleId, configJson, isEditing, size }: Props) {
+  const entry = useWidgetRegistry((s) => s.modules.get(moduleId))
+
+  const config = useMemo(() => {
+    try {
+      const raw = JSON.parse(configJson || '{}')
+      return entry?.module.configSchema?.parse?.(raw) ?? raw
+    } catch (e) {
+      console.warn('widget config parse failed', e)
+      return {}
+    }
+  }, [configJson, entry])
+
+  const actions = useMemo(
+    () => createActionsHelper(entry?.module.actions ?? []),
+    [entry?.module.actions],
+  )
+
+  if (!entry) {
+    return (
+      <div className="flex h-full items-center justify-center rounded-lg border bg-card p-3 text-muted-foreground text-sm">
+        Widget module not loaded: {moduleId}
+      </div>
+    )
+  }
+
+  const Component = entry.module.component
+  return (
+    <ErrorBoundary>
+      <Component config={config} size={size} isEditing={isEditing} actions={actions} />
+    </ErrorBoundary>
+  )
+}
+```
+
+- [ ] **Step 4: Run — PASS (2 tests)**
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/web/src/components/dashboard/widget-renderer-v2.tsx apps/web/src/components/dashboard/widget-renderer-v2.test.tsx
+git -c commit.gpgsign=false commit -m "feat(web): WidgetRendererV2 renders modules from Registry"
+```
+
+---
+
+## Task 8: Final integration verification
+
+- [ ] **Step 1: Full sequence sanity check**
+
+```bash
+cd apps/web && bun run build           # emits builtin-widgets/manifest.json + hello-world/index.js
+cargo build -p serverbee-server         # embeds the dist directory
+cargo test -p serverbee-server --test widget_module_integration  # 4 tests pass (incl. hello-world)
+cd apps/web && bun run test             # frontend tests pass
+cargo clippy --workspace -- -D warnings  # clean
+```
+
+- [ ] **Step 2: Manual smoke test (visual)**
+
+If a local dev server can be started, do not start it here — the goal-driven workflow will do VPS-based verification later. Just verify the artifacts on disk.
+
+- [ ] **Step 3: No commit** (already covered by per-task commits)
+
+---
+
+## Plan 2 — Completion Criteria
+
+After Tasks 1–8:
+
+- `apps/web/dist/builtin-widgets/manifest.json` lists the `com.serverbee.hello-world` module with the JSDoc manifest.
+- `apps/web/dist/builtin-widgets/hello-world/index.js` exists, imports React + SDK as externals, exports a `WidgetModule` default.
+- Rust server boot registers it as `widget_module(source_type='Builtin')`.
+- `GET /api/widget-modules` returns the hello-world entry.
+- `GET /api/widget-modules/com.serverbee.hello-world/index.js` returns the JS bytes with `Content-Type: text/javascript` + ETag.
+- `mountRuntimeBridge` is wired to the real `useServersWs` store.
+- `WidgetRendererV2` can render a module fetched from the Registry.
+- `dashboard_widget.module_id` column exists (no rows reference it yet — wiring it into Dashboard Grid is left to Plan 2-followup or Plan 3).
+
+What's intentionally deferred (NOT in Plan 2):
+
+- Rewriting the 14 existing widgets to the new shape (parallel work, future PRs).
+- Adding `WidgetPicker` v2 / `widget-config-dialog` v2.
+- Hooking `WidgetRendererV2` into the actual `DashboardGrid` (current grid still uses legacy renderer).
+- `onConfigUpdate` wiring (stub for now).
+- Deleting legacy widget code (`widget-types.ts`, `WidgetRenderer`, per-type dialogs) — Plan 3 cleanup.

From 67c5c278af659c61c79878a7b5a28a217e560203 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:15:57 +0800
Subject: [PATCH 27/64] feat(web): add hello-world example builtin widget

---
 .../builtin-widgets/hello-world.widget.tsx    | 35 +++++++++++++++++++
 1 file changed, 35 insertions(+)
 create mode 100644 apps/web/src/builtin-widgets/hello-world.widget.tsx

diff --git a/apps/web/src/builtin-widgets/hello-world.widget.tsx b/apps/web/src/builtin-widgets/hello-world.widget.tsx
new file mode 100644
index 00000000..168d2e32
--- /dev/null
+++ b/apps/web/src/builtin-widgets/hello-world.widget.tsx
@@ -0,0 +1,35 @@
+/**
+ * @serverbee-widget {
+ *   "id": "com.serverbee.hello-world",
+ *   "version": "1.0.0",
+ *   "name": "Hello World",
+ *   "description": "A minimal builtin widget that displays the SPA theme mode and the count of online servers.",
+ *   "author": "ServerBee",
+ *   "category": "Real-time",
+ *   "sizing": { "defaultW": 3, "defaultH": 2, "minW": 2, "minH": 2, "strategy": "free" },
+ *   "sdkVersion": "^0.1.0"
+ * }
+ */
+import { defineWidget, useServers, useTheme, z } from '@serverbee/widget-sdk'
+
+const ConfigSchema = z.object({
+  greeting: z.string().describe('Greeting text').default('Hello, ServerBee')
+})
+
+export default defineWidget({
+  configSchema: ConfigSchema,
+  component: ({ config }) => {
+    const servers = useServers()
+    const theme = useTheme()
+    const online = servers.filter((s) => s.online).length
+    const { greeting } = config as { greeting: string }
+    return (
+      <div style={{ padding: 12, fontFamily: 'system-ui' }}>
+        <div style={{ fontSize: 16, fontWeight: 600 }}>{greeting}</div>
+        <div style={{ marginTop: 8, color: 'var(--muted-foreground)' }}>
+          {online} / {servers.length} online · {theme.mode} mode
+        </div>
+      </div>
+    )
+  }
+})

From 2b017ef8f582c6345ccb5bb7499cdd759a456aeb Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:31:54 +0800
Subject: [PATCH 28/64] build(web): vite plugin emits builtin widget bundles +
 manifest

---
 apps/web/package.json                    |   1 +
 apps/web/vite-plugins/builtin-widgets.ts | 142 +++++++++++++++++++++++
 apps/web/vite.config.ts                  |   2 +
 bun.lock                                 |  19 ++-
 4 files changed, 163 insertions(+), 1 deletion(-)
 create mode 100644 apps/web/vite-plugins/builtin-widgets.ts

diff --git a/apps/web/package.json b/apps/web/package.json
index 5d3a1a68..78427334 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -63,6 +63,7 @@
     "globals": "^16.5.0",
     "jsdom": "^28.1.0",
     "openapi-typescript": "^7.13.0",
+    "tinyglobby": "^0.2.16",
     "typescript": "~5.9.3",
     "vite": "^7.2.4",
     "vite-plugin-pwa": "^1.2.0",
diff --git a/apps/web/vite-plugins/builtin-widgets.ts b/apps/web/vite-plugins/builtin-widgets.ts
new file mode 100644
index 00000000..691f614b
--- /dev/null
+++ b/apps/web/vite-plugins/builtin-widgets.ts
@@ -0,0 +1,142 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { globSync } from 'tinyglobby'
+import type { Plugin, ResolvedConfig } from 'vite'
+import { build as viteBuild } from 'vite'
+
+interface BuiltinManifestEntry {
+  entry_path: string
+  id: string
+  manifest: Record<string, unknown>
+  version: string
+}
+
+interface WidgetEntry {
+  manifest: Record<string, unknown>
+  srcPath: string
+}
+
+const JSDOC_RE = /\/\*\*[\s\S]*?@serverbee-widget\s+(\{[\s\S]*?\})\s*\*\//
+const LINE_DECOR = /^\s*\*\s?/gm
+const SRC_DIR = 'src/builtin-widgets'
+const EXTERNAL_IDS = ['react', 'react-dom', 'react/jsx-runtime', '@serverbee/widget-sdk']
+
+function extractManifest(source: string): Record<string, unknown> {
+  const m = source.match(JSDOC_RE)
+  if (!m) {
+    throw new Error('no @serverbee-widget JSDoc block')
+  }
+  return JSON.parse(m[1].replace(LINE_DECOR, ''))
+}
+
+function collectEntries(rootDir: string): Map<string, WidgetEntry> {
+  const entries = new Map<string, WidgetEntry>()
+  const files = globSync(`${SRC_DIR}/*.widget.tsx`, { cwd: rootDir, absolute: false })
+  for (const rel of files) {
+    const id = path.basename(rel, '.widget.tsx')
+    const abs = path.resolve(rootDir, rel)
+    const source = readFileSync(abs, 'utf8')
+    const manifest = extractManifest(source)
+    entries.set(id, { srcPath: abs, manifest })
+  }
+  return entries
+}
+
+/**
+ * Vite plugin: compile every `apps/web/src/builtin-widgets/*.widget.tsx`
+ * to a standalone ESM bundle at `dist/builtin-widgets/<id>/index.js`,
+ * with `react`/`react-dom`/`react/jsx-runtime`/`@serverbee/widget-sdk`
+ * marked external (provided by the host SPA at runtime). Also emits
+ * `dist/builtin-widgets/manifest.json` listing every widget.
+ *
+ * Widgets are compiled in a separate (nested) Vite build invoked at
+ * `closeBundle` of the main build, so the externals do NOT leak into
+ * the main SPA chunk graph or its HTML.
+ */
+export function builtinWidgetsPlugin(): Plugin {
+  let resolvedConfig: ResolvedConfig | undefined
+  let didNestedBuild = false
+
+  return {
+    name: 'serverbee-builtin-widgets',
+    apply: 'build',
+    configResolved(config) {
+      resolvedConfig = config
+    },
+    async closeBundle() {
+      if (didNestedBuild || !resolvedConfig) {
+        return
+      }
+      // Avoid recursion when this hook fires for the nested build itself.
+      didNestedBuild = true
+
+      const rootDir = resolvedConfig.root
+      const outDir = path.resolve(rootDir, resolvedConfig.build.outDir, 'builtin-widgets')
+      const entries = collectEntries(rootDir)
+      if (entries.size === 0) {
+        return
+      }
+
+      const input: Record<string, string> = {}
+      for (const [id, e] of entries) {
+        input[`${id}/index`] = e.srcPath
+      }
+
+      await viteBuild({
+        configFile: false,
+        root: rootDir,
+        mode: resolvedConfig.mode,
+        // Do NOT copy apps/web/public/* into the widget output directory.
+        publicDir: false,
+        logLevel: 'warn',
+        // Reuse the same aliases (e.g. @serverbee/widget-sdk source mapping)
+        // so widgets compile against the same workspace SDK as the SPA.
+        resolve: {
+          alias: resolvedConfig.resolve.alias
+        },
+        plugins: [
+          {
+            name: 'serverbee-builtin-widgets-manifest',
+            generateBundle() {
+              const list: BuiltinManifestEntry[] = []
+              for (const [id, e] of entries) {
+                const m = e.manifest as { id: string; version: string }
+                list.push({
+                  id: m.id,
+                  version: m.version,
+                  entry_path: `${id}/index.js`,
+                  manifest: e.manifest
+                })
+              }
+              this.emitFile({
+                type: 'asset',
+                fileName: 'manifest.json',
+                source: JSON.stringify(list, null, 2)
+              })
+            }
+          }
+        ],
+        build: {
+          outDir,
+          emptyOutDir: true,
+          minify: resolvedConfig.build.minify,
+          sourcemap: resolvedConfig.build.sourcemap,
+          target: resolvedConfig.build.target,
+          // Library-style multi-entry rollup build so each widget produces
+          // its own ESM chunk with preserved default export.
+          lib: false as unknown as undefined,
+          rollupOptions: {
+            input,
+            external: EXTERNAL_IDS,
+            preserveEntrySignatures: 'strict',
+            output: {
+              format: 'es',
+              entryFileNames: '[name].js',
+              chunkFileNames: 'shared/[name]-[hash].js'
+            }
+          }
+        }
+      })
+    }
+  }
+}
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index e3a4677c..26463100 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -5,6 +5,7 @@ import react from '@vitejs/plugin-react'
 import { defineConfig, loadEnv } from 'vite'
 import { VitePWA } from 'vite-plugin-pwa'
 import { createDevProxy } from './vite/dev-proxy'
+import { builtinWidgetsPlugin } from './vite-plugins/builtin-widgets'
 
 const apiRuntimePattern = /^\/api\//
 const pwaRuntimePattern = /^\/pwa-/
@@ -115,6 +116,7 @@ export default defineConfig(({ mode }) => {
         routeFileIgnorePattern
       }),
       react(),
+      builtinWidgetsPlugin(),
       tailwindcss(),
       VitePWA({
         registerType: 'autoUpdate',
diff --git a/bun.lock b/bun.lock
index fbd5ebc6..0216451d 100644
--- a/bun.lock
+++ b/bun.lock
@@ -101,6 +101,7 @@
         "globals": "^16.5.0",
         "jsdom": "^28.1.0",
         "openapi-typescript": "^7.13.0",
+        "tinyglobby": "^0.2.16",
         "typescript": "~5.9.3",
         "vite": "^7.2.4",
         "vite-plugin-pwa": "^1.2.0",
@@ -2641,7 +2642,7 @@
 
     "tinyexec": ["tinyexec@1.0.4", "", {}, "sha512-u9r3uZC0bdpGOXtlxUIdwf9pkmvhqJdrVCH9fapQtgy/OeTTMZ1nqH7agtvEfmGui6e1XxjcdrlxvxJvc3sMqw=="],
 
-    "tinyglobby": ["tinyglobby@0.2.15", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.3" } }, "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ=="],
+    "tinyglobby": ["tinyglobby@0.2.16", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.4" } }, "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg=="],
 
     "tinyrainbow": ["tinyrainbow@3.1.0", "", {}, "sha512-Bf+ILmBgretUrdJxzXM0SgXLZ3XfiaUuOj/IKQHuTXip+05Xn+uyEYdVg0kYDipTBcLrCVyUzAPz7QmArb0mmw=="],
 
@@ -2971,6 +2972,8 @@
 
     "@tanstack/router-plugin/zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
 
+    "@tanstack/router-utils/tinyglobby": ["tinyglobby@0.2.15", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.3" } }, "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ=="],
+
     "@tanstack/start-plugin-core/@babel/code-frame": ["@babel/code-frame@7.27.1", "", { "dependencies": { "@babel/helper-validator-identifier": "^7.27.1", "js-tokens": "^4.0.0", "picocolors": "^1.1.1" } }, "sha512-cjQ7ZlQ0Mv3b47hABuTevyTuYN4i+loJKGeV9flcCgIK37cCXRh+L1bd3iBHlynerhQ7BhCkn2BPbQUL+rGqFg=="],
 
     "@tanstack/start-plugin-core/@rolldown/pluginutils": ["@rolldown/pluginutils@1.0.0-beta.40", "", {}, "sha512-s3GeJKSQOwBlzdUrj4ISjJj5SfSh+aqn0wjOar4Bx95iV1ETI7F6S/5hLcfAxZ9kXDcyrAkxPlqmd1ZITttf+w=="],
@@ -2981,6 +2984,8 @@
 
     "@tanstack/start-plugin-core/@tanstack/router-utils": ["@tanstack/router-utils@1.161.4", "", { "dependencies": { "@babel/core": "^7.28.5", "@babel/generator": "^7.28.5", "@babel/parser": "^7.28.5", "@babel/types": "^7.28.5", "ansis": "^4.1.0", "babel-dead-code-elimination": "^1.0.12", "diff": "^8.0.2", "pathe": "^2.0.3", "tinyglobby": "^0.2.15" } }, "sha512-r8TpjyIZoqrXXaf2DDyjd44gjGBoyE+/oEaaH68yLI9ySPO1gUWmQENZ1MZnmBnpUGN24NOZxdjDLc8npK0SAw=="],
 
+    "@tanstack/start-plugin-core/tinyglobby": ["tinyglobby@0.2.15", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.3" } }, "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ=="],
+
     "@tanstack/start-plugin-core/zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
 
     "@testing-library/dom/aria-query": ["aria-query@5.3.0", "", { "dependencies": { "dequal": "^2.0.3" } }, "sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A=="],
@@ -3023,8 +3028,12 @@
 
     "filelist/minimatch": ["minimatch@5.1.9", "", { "dependencies": { "brace-expansion": "^2.0.1" } }, "sha512-7o1wEA2RyMP7Iu7GNba9vc0RWWGACJOCZBJX2GJWip0ikV+wcOsgVuY9uE8CPiyQhkGFSlhuSkZPavN7u1c2Fw=="],
 
+    "fumadocs-core/tinyglobby": ["tinyglobby@0.2.15", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.3" } }, "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ=="],
+
     "fumadocs-mdx/esbuild": ["esbuild@0.27.4", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.27.4", "@esbuild/android-arm": "0.27.4", "@esbuild/android-arm64": "0.27.4", "@esbuild/android-x64": "0.27.4", "@esbuild/darwin-arm64": "0.27.4", "@esbuild/darwin-x64": "0.27.4", "@esbuild/freebsd-arm64": "0.27.4", "@esbuild/freebsd-x64": "0.27.4", "@esbuild/linux-arm": "0.27.4", "@esbuild/linux-arm64": "0.27.4", "@esbuild/linux-ia32": "0.27.4", "@esbuild/linux-loong64": "0.27.4", "@esbuild/linux-mips64el": "0.27.4", "@esbuild/linux-ppc64": "0.27.4", "@esbuild/linux-riscv64": "0.27.4", "@esbuild/linux-s390x": "0.27.4", "@esbuild/linux-x64": "0.27.4", "@esbuild/netbsd-arm64": "0.27.4", "@esbuild/netbsd-x64": "0.27.4", "@esbuild/openbsd-arm64": "0.27.4", "@esbuild/openbsd-x64": "0.27.4", "@esbuild/openharmony-arm64": "0.27.4", "@esbuild/sunos-x64": "0.27.4", "@esbuild/win32-arm64": "0.27.4", "@esbuild/win32-ia32": "0.27.4", "@esbuild/win32-x64": "0.27.4" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-Rq4vbHnYkK5fws5NF7MYTU68FPRE1ajX7heQ/8QXXWqNgqqJ/GkmmyxIzUnf2Sr/bakf8l54716CcMGHYhMrrQ=="],
 
+    "fumadocs-mdx/tinyglobby": ["tinyglobby@0.2.15", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.3" } }, "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ=="],
+
     "giget/citty": ["citty@0.1.6", "", { "dependencies": { "consola": "^3.2.3" } }, "sha512-tskPPKEs8D2KPafUypv2gxwJP8h/OaJmC82QQGGDQcHvXX43xF2VDACcJVmZ0EuSxkpO9Kc4MlrA3q0+FG58AQ=="],
 
     "h3/rou3": ["rou3@0.8.1", "", {}, "sha512-ePa+XGk00/3HuCqrEnK3LxJW7I0SdNg6EFzKUJG73hMAdDcOUC/i/aSz7LSDwLrGr33kal/rqOGydzwl6U7zBA=="],
@@ -3087,10 +3096,18 @@
 
     "terser/commander": ["commander@2.20.3", "", {}, "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ=="],
 
+    "tinyglobby/picomatch": ["picomatch@4.0.4", "", {}, "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A=="],
+
     "tsx/esbuild": ["esbuild@0.27.4", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.27.4", "@esbuild/android-arm": "0.27.4", "@esbuild/android-arm64": "0.27.4", "@esbuild/android-x64": "0.27.4", "@esbuild/darwin-arm64": "0.27.4", "@esbuild/darwin-x64": "0.27.4", "@esbuild/freebsd-arm64": "0.27.4", "@esbuild/freebsd-x64": "0.27.4", "@esbuild/linux-arm": "0.27.4", "@esbuild/linux-arm64": "0.27.4", "@esbuild/linux-ia32": "0.27.4", "@esbuild/linux-loong64": "0.27.4", "@esbuild/linux-mips64el": "0.27.4", "@esbuild/linux-ppc64": "0.27.4", "@esbuild/linux-riscv64": "0.27.4", "@esbuild/linux-s390x": "0.27.4", "@esbuild/linux-x64": "0.27.4", "@esbuild/netbsd-arm64": "0.27.4", "@esbuild/netbsd-x64": "0.27.4", "@esbuild/openbsd-arm64": "0.27.4", "@esbuild/openbsd-x64": "0.27.4", "@esbuild/openharmony-arm64": "0.27.4", "@esbuild/sunos-x64": "0.27.4", "@esbuild/win32-arm64": "0.27.4", "@esbuild/win32-ia32": "0.27.4", "@esbuild/win32-x64": "0.27.4" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-Rq4vbHnYkK5fws5NF7MYTU68FPRE1ajX7heQ/8QXXWqNgqqJ/GkmmyxIzUnf2Sr/bakf8l54716CcMGHYhMrrQ=="],
 
     "vite/esbuild": ["esbuild@0.27.4", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.27.4", "@esbuild/android-arm": "0.27.4", "@esbuild/android-arm64": "0.27.4", "@esbuild/android-x64": "0.27.4", "@esbuild/darwin-arm64": "0.27.4", "@esbuild/darwin-x64": "0.27.4", "@esbuild/freebsd-arm64": "0.27.4", "@esbuild/freebsd-x64": "0.27.4", "@esbuild/linux-arm": "0.27.4", "@esbuild/linux-arm64": "0.27.4", "@esbuild/linux-ia32": "0.27.4", "@esbuild/linux-loong64": "0.27.4", "@esbuild/linux-mips64el": "0.27.4", "@esbuild/linux-ppc64": "0.27.4", "@esbuild/linux-riscv64": "0.27.4", "@esbuild/linux-s390x": "0.27.4", "@esbuild/linux-x64": "0.27.4", "@esbuild/netbsd-arm64": "0.27.4", "@esbuild/netbsd-x64": "0.27.4", "@esbuild/openbsd-arm64": "0.27.4", "@esbuild/openbsd-x64": "0.27.4", "@esbuild/openharmony-arm64": "0.27.4", "@esbuild/sunos-x64": "0.27.4", "@esbuild/win32-arm64": "0.27.4", "@esbuild/win32-ia32": "0.27.4", "@esbuild/win32-x64": "0.27.4" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-Rq4vbHnYkK5fws5NF7MYTU68FPRE1ajX7heQ/8QXXWqNgqqJ/GkmmyxIzUnf2Sr/bakf8l54716CcMGHYhMrrQ=="],
 
+    "vite/tinyglobby": ["tinyglobby@0.2.15", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.3" } }, "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ=="],
+
+    "vite-plugin-pwa/tinyglobby": ["tinyglobby@0.2.15", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.3" } }, "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ=="],
+
+    "vitest/tinyglobby": ["tinyglobby@0.2.15", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.3" } }, "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ=="],
+
     "whatwg-encoding/iconv-lite": ["iconv-lite@0.6.3", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw=="],
 
     "workbox-build/fs-extra": ["fs-extra@9.1.0", "", { "dependencies": { "at-least-node": "^1.0.0", "graceful-fs": "^4.2.0", "jsonfile": "^6.0.1", "universalify": "^2.0.0" } }, "sha512-hcg3ZmepS30/7BSFqRvoo3DOMQu7IjqxO5nCDt+zM9XWjb33Wg7ziNT+Qvqbuc3+gWpzO02JubVyk2G4Zvo1OQ=="],

From ad49065874917a098f9ecded71b0e5d62c5202c9 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:32:54 +0800
Subject: [PATCH 29/64] feat(server): register builtin widgets on boot from
 embedded manifest

---
 crates/server/src/main.rs                     |  7 ++
 .../src/service/widget_module/builtin.rs      | 94 +++++++++++++++++++
 .../server/src/service/widget_module/mod.rs   |  1 +
 .../src/service/widget_module/service.rs      | 26 +++++
 4 files changed, 128 insertions(+)
 create mode 100644 crates/server/src/service/widget_module/builtin.rs

diff --git a/crates/server/src/main.rs b/crates/server/src/main.rs
index f5d5d62c..639d67b8 100644
--- a/crates/server/src/main.rs
+++ b/crates/server/src/main.rs
@@ -76,6 +76,13 @@ async fn main() -> anyhow::Result<()> {
     Migrator::up(&db, None).await?;
     tracing::info!("Database migrations complete");
 
+    serverbee_server::service::widget_module::builtin::register_all(&db)
+        .await
+        .map_err(|e| {
+            tracing::error!("failed to register builtin widgets: {e}");
+            e
+        })?;
+
     if config.dev.demo_data {
         dev_demo::seed_demo_data(&db)
             .await
diff --git a/crates/server/src/service/widget_module/builtin.rs b/crates/server/src/service/widget_module/builtin.rs
new file mode 100644
index 00000000..fd840198
--- /dev/null
+++ b/crates/server/src/service/widget_module/builtin.rs
@@ -0,0 +1,94 @@
+use chrono::Utc;
+use rust_embed::Embed;
+use sea_orm::sea_query::OnConflict;
+use sea_orm::{ActiveValue::Set, ColumnTrait, DatabaseConnection, EntityTrait, QueryFilter};
+use serde::Deserialize;
+use sha2::{Digest, Sha256};
+
+use crate::entity::widget_module::{self, Entity as WidgetModuleEntity, SourceType};
+
+/// Reads files from `apps/web/dist/builtin-widgets/` at compile time.
+#[derive(Embed)]
+#[folder = "../../apps/web/dist/builtin-widgets"]
+struct BuiltinAssets;
+
+#[derive(Debug, Deserialize)]
+struct ManifestEntry {
+    id: String,
+    version: String,
+    entry_path: String,
+    manifest: serde_json::Value,
+}
+
+pub async fn register_all(db: &DatabaseConnection) -> anyhow::Result<()> {
+    let Some(raw) = BuiltinAssets::get("manifest.json") else {
+        tracing::warn!(
+            "builtin widgets manifest.json missing — run `cd apps/web && bun run build` to generate it"
+        );
+        return Ok(());
+    };
+
+    let entries: Vec<ManifestEntry> = serde_json::from_slice(raw.data.as_ref())?;
+
+    for entry in &entries {
+        let Some(code) = BuiltinAssets::get(&entry.entry_path) else {
+            tracing::warn!(
+                "builtin widget {} references missing entry_path {}",
+                entry.id,
+                entry.entry_path
+            );
+            continue;
+        };
+        let sha = {
+            let mut h = Sha256::new();
+            h.update(code.data.as_ref());
+            format!("{:x}", h.finalize())
+        };
+
+        let active = widget_module::ActiveModel {
+            id: Set(entry.id.clone()),
+            version: Set(entry.version.clone()),
+            source_type: Set(SourceType::Builtin),
+            source_url: Set(None),
+            bundled_by_theme_id: Set(None),
+            manifest_json: Set(serde_json::to_string(&entry.manifest)?),
+            code_sha256: Set(sha),
+            entry_path: Set(entry.entry_path.clone()),
+            package_blob: Set(None),
+            installed_by: Set(None),
+            installed_at: Set(Utc::now()),
+            enabled: Set(true),
+        };
+
+        WidgetModuleEntity::insert(active)
+            .on_conflict(
+                OnConflict::column(widget_module::Column::Id)
+                    .update_columns([
+                        widget_module::Column::Version,
+                        widget_module::Column::ManifestJson,
+                        widget_module::Column::CodeSha256,
+                        widget_module::Column::EntryPath,
+                        widget_module::Column::InstalledAt,
+                        widget_module::Column::Enabled,
+                    ])
+                    .to_owned(),
+            )
+            .exec(db)
+            .await?;
+    }
+
+    // Delete any stale Builtin rows not present in the current manifest.
+    let active_ids: Vec<String> = entries.iter().map(|e| e.id.clone()).collect();
+    let mut delete = WidgetModuleEntity::delete_many()
+        .filter(widget_module::Column::SourceType.eq(SourceType::Builtin));
+    if !active_ids.is_empty() {
+        delete = delete.filter(widget_module::Column::Id.is_not_in(active_ids));
+    }
+    delete.exec(db).await?;
+
+    Ok(())
+}
+
+pub fn builtin_asset_bytes(entry_path: &str) -> Option<Vec<u8>> {
+    BuiltinAssets::get(entry_path).map(|f| f.data.into_owned())
+}
diff --git a/crates/server/src/service/widget_module/mod.rs b/crates/server/src/service/widget_module/mod.rs
index a6561085..3e86104f 100644
--- a/crates/server/src/service/widget_module/mod.rs
+++ b/crates/server/src/service/widget_module/mod.rs
@@ -1,3 +1,4 @@
+pub mod builtin;
 pub mod error;
 pub mod extractor;
 pub mod package;
diff --git a/crates/server/src/service/widget_module/service.rs b/crates/server/src/service/widget_module/service.rs
index 039cfd8f..0d8ee24d 100644
--- a/crates/server/src/service/widget_module/service.rs
+++ b/crates/server/src/service/widget_module/service.rs
@@ -66,6 +66,32 @@ impl WidgetModuleService {
         requested: &str,
     ) -> Result<(Vec<u8>, String), WidgetModuleError> {
         let row = Self::get(db, id).await?;
+
+        if matches!(
+            row.source_type,
+            crate::entity::widget_module::SourceType::Builtin
+        ) {
+            // Builtin: the URL `/api/widget-modules/<id>/<requested>` resolves to a path
+            // within the embedded directory. `row.entry_path` is the module's main file
+            // (e.g. "hello-world/index.js"); we resolve `requested` relative to its folder.
+            let folder = row
+                .entry_path
+                .rsplit_once('/')
+                .map(|(d, _)| d)
+                .unwrap_or("");
+            let full = if folder.is_empty() {
+                requested.to_string()
+            } else {
+                format!("{folder}/{requested}")
+            };
+            if full.contains("..") {
+                return Err(WidgetModuleError::InvalidAssetPath);
+            }
+            let bytes = crate::service::widget_module::builtin::builtin_asset_bytes(&full)
+                .ok_or(WidgetModuleError::InvalidAssetPath)?;
+            return Ok((bytes, mime_for(&full)));
+        }
+
         let blob = row
             .package_blob
             .ok_or_else(|| WidgetModuleError::NotFound(format!("{id}: no blob")))?;

From 66fefa2d9d49974dc7a1089d9f593da1884e9f83 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:33:55 +0800
Subject: [PATCH 30/64] feat(server): serve Builtin widget assets via
 rust-embed

---
 .../server/tests/widget_module_integration.rs | 59 +++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/crates/server/tests/widget_module_integration.rs b/crates/server/tests/widget_module_integration.rs
index 3ee150d0..945c6f16 100644
--- a/crates/server/tests/widget_module_integration.rs
+++ b/crates/server/tests/widget_module_integration.rs
@@ -290,3 +290,62 @@ async fn serve_asset_rejects_path_traversal() {
         "path traversal should be rejected with 4xx, got status line: {status_line}"
     );
 }
+
+#[tokio::test]
+async fn list_includes_builtin_hello_world() {
+    let ctx = start_test_server_with_db().await;
+    serverbee_server::service::widget_module::builtin::register_all(&ctx.db)
+        .await
+        .expect("register builtin widgets");
+
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    let res = client
+        .get(format!("{}/api/widget-modules", ctx.base_url))
+        .send()
+        .await
+        .expect("GET /api/widget-modules failed");
+    assert_eq!(res.status(), 200);
+    let body: serde_json::Value = res.json().await.expect("invalid JSON");
+    let list = body["data"].as_array().expect("data should be array");
+    assert!(
+        list.iter().any(|m| m["id"] == "com.serverbee.hello-world"),
+        "expected hello-world in list, got {body:#?}"
+    );
+}
+
+#[tokio::test]
+async fn serve_builtin_asset_returns_js_bytes() {
+    let ctx = start_test_server_with_db().await;
+    serverbee_server::service::widget_module::builtin::register_all(&ctx.db)
+        .await
+        .expect("register builtin widgets");
+
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    let res = client
+        .get(format!(
+            "{}/api/widget-modules/com.serverbee.hello-world/index.js",
+            ctx.base_url
+        ))
+        .send()
+        .await
+        .expect("GET builtin asset failed");
+    assert_eq!(res.status(), 200);
+    let ct = res
+        .headers()
+        .get("content-type")
+        .expect("content-type missing")
+        .to_str()
+        .expect("invalid content-type")
+        .to_string();
+    assert!(ct.contains("javascript"), "unexpected content-type: {ct}");
+    let body = res.text().await.expect("body text");
+    assert!(
+        body.contains("@serverbee/widget-sdk") || body.contains("defineWidget"),
+        "expected SDK import or defineWidget in builtin js, got: {}",
+        &body[..body.len().min(200)]
+    );
+}

From d791b77b063a2fe4ad5a792b962d33cce1469283 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:38:01 +0800
Subject: [PATCH 31/64] =?UTF-8?q?docs(plan):=20plan=203=20=E2=80=94=20inst?=
 =?UTF-8?q?all=20UX=20+=20legacy=20theme=20cleanup?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...idget-system-plan-3-install-and-cleanup.md | 638 ++++++++++++++++++
 1 file changed, 638 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-28-custom-widget-system-plan-3-install-and-cleanup.md

diff --git a/docs/superpowers/plans/2026-05-28-custom-widget-system-plan-3-install-and-cleanup.md b/docs/superpowers/plans/2026-05-28-custom-widget-system-plan-3-install-and-cleanup.md
new file mode 100644
index 00000000..9f1ac4a9
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-28-custom-widget-system-plan-3-install-and-cleanup.md
@@ -0,0 +1,638 @@
+# Custom Widget System — Plan 3: Install UX + Legacy Theme Cleanup
+
+> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:subagent-driven-development.
+
+**Scope:** Ship the install UX (URL install + single-file upload, zip collection deferred) so admins can actually add a widget. Delete the three legacy theme systems (spa_theme full-replacement, custom_theme OKLCH, preset themes) — these are obsolete now that Themes-as-cssVars-pack is the consolidation target. New Theme entity itself is deferred to a follow-up; this plan only removes the legacy code.
+
+**Goal:** After Plan 3, an admin can paste a URL or upload a `.js` file with a valid `@serverbee-widget` JSDoc, see it install, and have it appear in `GET /api/widget-modules`. Legacy theme code is gone from the codebase.
+
+**Architecture:** New backend route `POST /api/widget-modules` (admin-only, multipart form with `file` field OR `url` query parameter, runs JSDoc extractor, stores BLOB). Delete endpoint `DELETE /api/widget-modules/{id}` (Builtin rows protected). Frontend: a single new settings page lists modules with install button + delete button. Legacy theme deletion removes ~28 files including entity/service/router/UI for `spa_theme` and `custom_theme`.
+
+**Spec:** `docs/superpowers/specs/2026-05-28-custom-widget-system-design.md`
+
+---
+
+## Section A — Backend install routes
+
+## Task 1: `POST /api/widget-modules` — install from URL or upload
+
+**Files:**
+- Modify: `crates/server/src/router/api/widget_module.rs`
+- Modify: `crates/server/src/service/widget_module/service.rs` (add `install_from_source`)
+
+- [ ] **Step 1: Service method**
+
+In `service.rs` add:
+
+```rust
+use chrono::Utc;
+use sea_orm::ActiveValue::Set;
+use sea_orm::ActiveModelTrait;
+use sha2::{Digest, Sha256};
+
+use super::extractor::extract_manifest;
+use crate::entity::widget_module;
+
+pub struct InstallInput {
+    pub source: super::extractor_source::Source,
+    pub installed_by: Option<i64>,
+}
+
+pub enum InstalledFrom { Url(String), Upload(String) }
+
+impl WidgetModuleService {
+    pub async fn install_single_file(
+        db: &DatabaseConnection,
+        code: Vec<u8>,
+        from: InstalledFrom,
+        installed_by: Option<i64>,
+    ) -> Result<widget_module::Model, super::WidgetModuleError> {
+        let source = std::str::from_utf8(&code)
+            .map_err(|e| super::WidgetModuleError::ManifestValidation(format!("not utf-8: {e}")))?;
+        let manifest = extract_manifest(source)?;
+
+        let sha = {
+            let mut h = Sha256::new();
+            h.update(&code);
+            format!("{:x}", h.finalize())
+        };
+
+        let (source_type, source_url) = match from {
+            InstalledFrom::Url(u) => (super::super::super::entity::widget_module::SourceType::Url, Some(u)),
+            InstalledFrom::Upload(name) => (super::super::super::entity::widget_module::SourceType::Upload, Some(name)),
+        };
+
+        let id_clone = manifest.id.clone();
+        let version_clone = manifest.version.clone();
+
+        let active = widget_module::ActiveModel {
+            id: Set(manifest.id.clone()),
+            version: Set(manifest.version.clone()),
+            source_type: Set(source_type),
+            source_url: Set(source_url),
+            bundled_by_theme_id: Set(None),
+            manifest_json: Set(serde_json::to_string(&manifest).unwrap()),
+            code_sha256: Set(sha),
+            entry_path: Set("index.js".into()),
+            package_blob: Set(Some(code)),
+            installed_by: Set(installed_by),
+            installed_at: Set(Utc::now()),
+            enabled: Set(true),
+        };
+
+        use sea_orm::EntityTrait;
+        use sea_orm::sea_query::OnConflict;
+        widget_module::Entity::insert(active)
+            .on_conflict(
+                OnConflict::column(widget_module::Column::Id)
+                    .update_columns([
+                        widget_module::Column::Version,
+                        widget_module::Column::SourceType,
+                        widget_module::Column::SourceUrl,
+                        widget_module::Column::ManifestJson,
+                        widget_module::Column::CodeSha256,
+                        widget_module::Column::PackageBlob,
+                        widget_module::Column::InstalledBy,
+                        widget_module::Column::InstalledAt,
+                        widget_module::Column::Enabled,
+                    ])
+                    .to_owned(),
+            )
+            .exec(db)
+            .await
+            .map_err(super::WidgetModuleError::Db)?;
+
+        Self::get(db, &id_clone).await
+    }
+
+    pub async fn uninstall(
+        db: &DatabaseConnection,
+        id: &str,
+    ) -> Result<(), super::WidgetModuleError> {
+        use sea_orm::EntityTrait;
+        let row = Self::get(db, id).await?;
+        if matches!(row.source_type, crate::entity::widget_module::SourceType::Builtin) {
+            return Err(super::WidgetModuleError::ManifestValidation("cannot uninstall builtin".into()));
+        }
+        widget_module::Entity::delete_by_id(id.to_string()).exec(db).await?;
+        Ok(())
+    }
+}
+```
+
+The unused `InstallInput` / `extractor_source` references above are illustrative — drop them and inline the source kind. Adjust paths if needed; the signatures that matter are:
+- `install_single_file(db, code, from, installed_by) -> Result<widget_module::Model, WidgetModuleError>`
+- `uninstall(db, id) -> Result<(), WidgetModuleError>`
+
+- [ ] **Step 2: Routes**
+
+In `router/api/widget_module.rs`, add:
+
+```rust
+use axum::extract::{Multipart, Query};
+use axum::routing::{delete, post};
+use serde::Deserialize;
+
+use crate::middleware::auth::CurrentUser;
+
+pub fn write_router() -> Router<Arc<AppState>> {
+    Router::new()
+        .route("/widget-modules", post(install_module))
+        .route("/widget-modules/{id}", delete(uninstall_module))
+}
+
+#[derive(Debug, Deserialize)]
+struct InstallQuery {
+    url: Option<String>,
+}
+
+#[utoipa::path(
+    post, path = "/api/widget-modules", tag = "widget-modules",
+    responses((status = 200, description = "Installed module")),
+    security(("session_cookie" = []), ("api_key" = []))
+)]
+async fn install_module(
+    State(state): State<Arc<AppState>>,
+    user: axum::extract::Extension<CurrentUser>,
+    Query(q): Query<InstallQuery>,
+    mut multipart: Option<Multipart>,
+) -> Result<Json<ApiResponse<serde_json::Value>>, AppError> {
+    let user_id = user.0.user_id.parse::<i64>().ok();
+
+    // Resolve code bytes either from `url` query param (URL install) or multipart `file` field.
+    let (bytes, from) = if let Some(url) = q.url.clone() {
+        if !(url.starts_with("https://") || url.starts_with("http://")) {
+            return Err(AppError::BadRequest("url must be http(s)".into()));
+        }
+        // Reject private/loopback ranges
+        let parsed = url::Url::parse(&url).map_err(|e| AppError::BadRequest(format!("bad url: {e}")))?;
+        if let Some(host) = parsed.host_str() {
+            if host == "localhost" || host == "127.0.0.1" || host.starts_with("10.") || host.starts_with("192.168.") {
+                return Err(AppError::BadRequest("private/loopback urls rejected".into()));
+            }
+        }
+        let resp = reqwest::Client::new()
+            .get(&url)
+            .send().await
+            .map_err(|e| AppError::BadRequest(format!("fetch: {e}")))?;
+        if !resp.status().is_success() {
+            return Err(AppError::BadRequest(format!("fetch {}: {}", url, resp.status())));
+        }
+        let bytes = resp.bytes().await
+            .map_err(|e| AppError::Internal(format!("read body: {e}")))?
+            .to_vec();
+        if bytes.len() > 1_048_576 {
+            return Err(AppError::BadRequest("module too large (>1MB)".into()));
+        }
+        (bytes, crate::service::widget_module::service::InstalledFrom::Url(url))
+    } else if let Some(mp) = multipart.as_mut() {
+        let mut bytes_opt = None;
+        let mut name_opt = None;
+        while let Some(field) = mp.next_field().await.map_err(|e| AppError::BadRequest(format!("multipart: {e}")))? {
+            if field.name() == Some("file") {
+                name_opt = field.file_name().map(|s| s.to_string());
+                let data = field.bytes().await.map_err(|e| AppError::BadRequest(format!("multipart body: {e}")))?;
+                if data.len() > 1_048_576 {
+                    return Err(AppError::BadRequest("module too large (>1MB)".into()));
+                }
+                bytes_opt = Some(data.to_vec());
+                break;
+            }
+        }
+        let bytes = bytes_opt.ok_or_else(|| AppError::BadRequest("missing 'file' part".into()))?;
+        (bytes, crate::service::widget_module::service::InstalledFrom::Upload(name_opt.unwrap_or_else(|| "upload.js".into())))
+    } else {
+        return Err(AppError::BadRequest("provide ?url=... or multipart file".into()));
+    };
+
+    let row = crate::service::widget_module::WidgetModuleService::install_single_file(
+        &state.db, bytes, from, user_id,
+    ).await?;
+    Ok(axum::Json(crate::error::ApiResponse {
+        data: serde_json::json!({
+            "id": row.id, "version": row.version,
+        }),
+    }))
+}
+
+#[utoipa::path(
+    delete, path = "/api/widget-modules/{id}", tag = "widget-modules",
+    params(("id" = String, Path)),
+    responses((status = 204)), security(("session_cookie" = []), ("api_key" = []))
+)]
+async fn uninstall_module(
+    State(state): State<Arc<AppState>>,
+    Path(id): Path<String>,
+) -> Result<StatusCode, AppError> {
+    crate::service::widget_module::WidgetModuleService::uninstall(&state.db, &id).await?;
+    Ok(StatusCode::NO_CONTENT)
+}
+```
+
+The `write_router()` function is automatically mounted behind `require_admin` middleware in `router/api/mod.rs`. Verify by checking how other modules' `write_router` are composed there.
+
+- [ ] **Step 3: Mount router**
+
+In `crates/server/src/router/api/mod.rs`, in the write router builder, add `.merge(widget_module::write_router())`. Find the pattern by grep `write_router` in that file.
+
+- [ ] **Step 4: Register in OpenAPI**
+
+`openapi.rs` — add `install_module` and `uninstall_module` to `paths(...)`.
+
+- [ ] **Step 5: Build + clippy**
+
+`cargo build -p serverbee-server && cargo clippy -p serverbee-server -- -D warnings`
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/server/src
+git -c commit.gpgsign=false commit -m "feat(server): POST /api/widget-modules install + DELETE uninstall"
+```
+
+---
+
+## Task 2: Integration test for install + uninstall
+
+**Files:**
+- Modify: `crates/server/tests/widget_module_integration.rs` (append)
+
+- [ ] **Step 1: Add test**
+
+```rust
+#[tokio::test]
+async fn install_single_file_via_multipart() {
+    let ctx = start_test_server_with_db().await.expect("server");
+    let code = r#"/**
+ * @serverbee-widget {
+ *   "id": "com.test.uploaded",
+ *   "version": "1.0.0",
+ *   "name": "Uploaded",
+ *   "category": "Real-time",
+ *   "sizing": { "defaultW": 2, "defaultH": 2, "minW": 1, "minH": 1, "strategy": "free" },
+ *   "sdkVersion": "^0.1.0"
+ * }
+ */
+export default {};"#;
+
+    let form = reqwest::multipart::Form::new()
+        .part(
+            "file",
+            reqwest::multipart::Part::bytes(code.as_bytes().to_vec()).file_name("uploaded.js"),
+        );
+
+    let client = ctx.http_client();
+    let res = client
+        .post(format!("{}/api/widget-modules", ctx.base_url))
+        .header("cookie", &ctx.admin_cookie)
+        .multipart(form)
+        .send().await.unwrap();
+    assert_eq!(res.status(), 200);
+    let body: serde_json::Value = res.json().await.unwrap();
+    assert_eq!(body["data"]["id"], "com.test.uploaded");
+
+    // Verify listed
+    let res2 = client.get(format!("{}/api/widget-modules", ctx.base_url))
+        .header("cookie", &ctx.admin_cookie).send().await.unwrap();
+    let list: serde_json::Value = res2.json().await.unwrap();
+    assert!(list["data"].as_array().unwrap().iter().any(|m| m["id"] == "com.test.uploaded"));
+
+    // Uninstall
+    let res3 = client.delete(format!("{}/api/widget-modules/com.test.uploaded", ctx.base_url))
+        .header("cookie", &ctx.admin_cookie).send().await.unwrap();
+    assert_eq!(res3.status(), 204);
+}
+
+#[tokio::test]
+async fn cannot_uninstall_builtin() {
+    let ctx = start_test_server_with_db().await.expect("server");
+    let client = ctx.http_client();
+    let res = client
+        .delete(format!("{}/api/widget-modules/com.serverbee.hello-world", ctx.base_url))
+        .header("cookie", &ctx.admin_cookie)
+        .send().await.unwrap();
+    assert!(res.status().is_client_error());
+}
+```
+
+Adjust `ctx.http_client()` to whatever helper the existing test file exposes — match the established convention.
+
+- [ ] **Step 2: Run tests**
+
+`cargo test -p serverbee-server --test widget_module_integration` — 7 tests pass.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add crates/server/tests
+git -c commit.gpgsign=false commit -m "test(server): widget_module install + uninstall integration"
+```
+
+---
+
+## Section B — Frontend install UX
+
+## Task 3: API client + settings page
+
+**Files:**
+- Create: `apps/web/src/api/widget-modules.ts`
+- Create: `apps/web/src/routes/_authed/settings/widgets.tsx`
+- Modify: `apps/web/src/lib/i18n.ts` (add strings) — only if i18n file is small; otherwise just hardcode English for now
+
+- [ ] **Step 1: API client**
+
+`apps/web/src/api/widget-modules.ts`:
+
+```ts
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+
+export interface ModuleSummary {
+  id: string
+  version: string
+  source_type: string
+  entry_path: string
+  code_sha256: string
+  manifest: Record<string, any>
+  enabled: boolean
+}
+
+export function useWidgetModules() {
+  return useQuery<ModuleSummary[]>({
+    queryKey: ['widget-modules'],
+    queryFn: async () => {
+      const res = await fetch('/api/widget-modules', { credentials: 'include' })
+      if (!res.ok) throw new Error(`list failed: ${res.status}`)
+      const json = await res.json()
+      return json.data
+    },
+  })
+}
+
+export function useInstallFromUrl() {
+  const qc = useQueryClient()
+  return useMutation<{ id: string; version: string }, Error, string>({
+    mutationFn: async (url) => {
+      const res = await fetch(`/api/widget-modules?url=${encodeURIComponent(url)}`, {
+        method: 'POST', credentials: 'include',
+      })
+      if (!res.ok) throw new Error(await res.text())
+      const json = await res.json()
+      return json.data
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['widget-modules'] }),
+  })
+}
+
+export function useInstallFromFile() {
+  const qc = useQueryClient()
+  return useMutation<{ id: string; version: string }, Error, File>({
+    mutationFn: async (file) => {
+      const fd = new FormData()
+      fd.append('file', file)
+      const res = await fetch('/api/widget-modules', {
+        method: 'POST', credentials: 'include', body: fd,
+      })
+      if (!res.ok) throw new Error(await res.text())
+      const json = await res.json()
+      return json.data
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['widget-modules'] }),
+  })
+}
+
+export function useUninstall() {
+  const qc = useQueryClient()
+  return useMutation<void, Error, string>({
+    mutationFn: async (id) => {
+      const res = await fetch(`/api/widget-modules/${id}`, {
+        method: 'DELETE', credentials: 'include',
+      })
+      if (!res.ok) throw new Error(await res.text())
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['widget-modules'] }),
+  })
+}
+```
+
+- [ ] **Step 2: Settings page**
+
+`apps/web/src/routes/_authed/settings/widgets.tsx`:
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { useState } from 'react'
+import {
+  useWidgetModules,
+  useInstallFromUrl,
+  useInstallFromFile,
+  useUninstall,
+} from '@/api/widget-modules'
+
+export const Route = createFileRoute('/_authed/settings/widgets')({
+  component: WidgetsPage,
+})
+
+function WidgetsPage() {
+  const list = useWidgetModules()
+  const installUrl = useInstallFromUrl()
+  const installFile = useInstallFromFile()
+  const uninstall = useUninstall()
+
+  const [url, setUrl] = useState('')
+
+  return (
+    <div style={{ padding: 24, maxWidth: 800 }}>
+      <h1 style={{ fontSize: 20, fontWeight: 600, marginBottom: 16 }}>Widget Modules</h1>
+
+      <section style={{ marginBottom: 24 }}>
+        <h2 style={{ fontSize: 14, fontWeight: 600, marginBottom: 8 }}>Install from URL</h2>
+        <div style={{ display: 'flex', gap: 8 }}>
+          <input
+            type="url" placeholder="https://example.com/foo.widget.js"
+            value={url} onChange={(e) => setUrl(e.target.value)}
+            style={{ flex: 1, padding: 6, border: '1px solid var(--border)' }}
+          />
+          <button
+            type="button"
+            onClick={() => url && installUrl.mutate(url, { onSuccess: () => setUrl('') })}
+            disabled={!url || installUrl.isPending}
+          >
+            Install
+          </button>
+        </div>
+        {installUrl.error && <p style={{ color: 'var(--destructive)' }}>{installUrl.error.message}</p>}
+      </section>
+
+      <section style={{ marginBottom: 24 }}>
+        <h2 style={{ fontSize: 14, fontWeight: 600, marginBottom: 8 }}>Upload .js file</h2>
+        <input
+          type="file" accept=".js,.mjs"
+          onChange={(e) => {
+            const f = e.target.files?.[0]
+            if (f) installFile.mutate(f)
+          }}
+        />
+        {installFile.error && <p style={{ color: 'var(--destructive)' }}>{installFile.error.message}</p>}
+      </section>
+
+      <section>
+        <h2 style={{ fontSize: 14, fontWeight: 600, marginBottom: 8 }}>Installed modules</h2>
+        {list.isLoading && <p>Loading…</p>}
+        {list.data?.map((m) => (
+          <div key={m.id} style={{ display: 'flex', gap: 12, alignItems: 'center', padding: 8, borderBottom: '1px solid var(--border)' }}>
+            <div style={{ flex: 1 }}>
+              <div style={{ fontWeight: 500 }}>{(m.manifest.name as string) || m.id}</div>
+              <div style={{ fontSize: 12, color: 'var(--muted-foreground)' }}>
+                {m.id} · {m.version} · {m.source_type}
+              </div>
+            </div>
+            {m.source_type !== 'Builtin' && (
+              <button type="button" onClick={() => uninstall.mutate(m.id)} disabled={uninstall.isPending}>
+                Uninstall
+              </button>
+            )}
+          </div>
+        ))}
+      </section>
+    </div>
+  )
+}
+```
+
+- [ ] **Step 3: Verify**
+
+`cd apps/web && bun run typecheck && bun run build` — both succeed. TanStack Router will pick up the new file route automatically (route file regeneration runs on dev/build).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add apps/web/src
+git -c commit.gpgsign=false commit -m "feat(web): widget modules settings page (install URL/.js, list, uninstall)"
+```
+
+---
+
+## Section C — Delete legacy theme code
+
+## Task 4: Inventory and stage legacy deletion
+
+Before deleting anything, inventory the files. Run:
+```bash
+grep -rlE "spa_theme|SpaTheme|active_spa_theme|ActiveSpaTheme|custom_theme|CustomTheme" \
+  crates/server/src/ apps/web/src/ 2>/dev/null | sort -u > /tmp/legacy-theme-files.txt
+cat /tmp/legacy-theme-files.txt
+```
+
+Expect ~28 files. Each must be evaluated:
+- **Delete entirely** if the file's sole purpose is the legacy theme system.
+- **Modify and keep** if it has unrelated content (e.g. `appearance.tsx` route, `i18n.ts`, `state.rs`, `openapi.rs`, `router/api/mod.rs`).
+
+Report the list to the controller before proceeding. Do not delete blindly.
+
+---
+
+## Task 5: Delete legacy backend code
+
+**Files to delete entirely:**
+- `crates/server/src/service/spa_theme/` (whole directory: mod.rs, service.rs, manifest.rs, loaded.rs, extractor.rs, error.rs)
+- `crates/server/src/entity/spa_theme.rs`
+- `crates/server/src/entity/custom_theme.rs` (if exists)
+- `crates/server/src/router/api/spa_theme.rs`
+- `crates/server/src/router/api/theme.rs` IF it's solely custom-theme CRUD; else strip just those handlers
+
+**Files to modify:**
+- `crates/server/src/entity/mod.rs` — remove `pub mod spa_theme;` and `pub mod custom_theme;` (if listed)
+- `crates/server/src/service/mod.rs` — remove `pub mod spa_theme;`
+- `crates/server/src/router/api/mod.rs` — remove `pub mod spa_theme;` and any `.merge(spa_theme::...)` calls. Remove similar for custom_theme.
+- `crates/server/src/state.rs` — remove the `active_spa_theme: ActiveSpaThemeSlot` field and any related types; delete `ActiveSpaThemeSlot` struct if local
+- `crates/server/src/router/static_files.rs` — remove ALL `active_spa_theme` / `LoadedTheme` references; the catch-all should serve only rust-embed default SPA assets
+- `crates/server/src/openapi.rs` — remove paths/schemas referring to deleted modules
+
+**New migration** `crates/server/src/migration/m20260528_000060_drop_legacy_theme_tables.rs`:
+```rust
+use sea_orm_migration::prelude::*;
+
+#[derive(DeriveMigrationName)]
+pub struct Migration;
+
+#[async_trait::async_trait]
+impl MigrationTrait for Migration {
+    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        let db = manager.get_connection();
+        db.execute_unprepared("DROP TABLE IF EXISTS spa_themes").await?;
+        db.execute_unprepared("DROP TABLE IF EXISTS custom_theme").await?;
+        Ok(())
+    }
+    async fn down(&self, _: &SchemaManager) -> Result<(), DbErr> { Ok(()) }
+}
+```
+Register in `migration/mod.rs`.
+
+- [ ] **Step 1: Inventory + delete**
+
+Work iteratively: delete a file, run `cargo build -p serverbee-server`, fix imports, repeat. If something compiles cleanly without a delete, prefer keeping it minimal until clippy is clean.
+
+- [ ] **Step 2: Verify**
+
+`cargo build -p serverbee-server && cargo clippy --workspace -- -D warnings && cargo test --workspace`
+
+The previously passing `spa_theme_integration.rs` (and similar) integration test files reference deleted code — DELETE those test files too.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add crates/server
+git -c commit.gpgsign=false commit -m "refactor(server): delete legacy spa_theme + custom_theme code"
+```
+
+---
+
+## Task 6: Delete legacy frontend code
+
+**Files to delete entirely:**
+- `apps/web/src/themes/` (whole directory: preset CSS files + `preset-vars.ts` + `index.ts`)
+- `apps/web/src/api/themes.ts`
+- `apps/web/src/api/spa-themes.ts`
+- `apps/web/src/components/theme/` (whole directory if all files are legacy theme UI)
+- `apps/web/src/components/spa-theme/` (whole directory)
+- `apps/web/src/lib/theme-ref.ts`
+- `apps/web/src/routes/_authed/settings/appearance/themes.*` files (if any exist)
+
+**Files to modify:**
+- `apps/web/src/routes/_authed/settings/appearance.tsx` and `appearance.test.tsx` — strip the spa-theme / custom-theme sections; if the page becomes empty, replace with a simple stub linking to widgets page
+- `apps/web/src/components/theme-provider.tsx` — collapse to just light/dark mode toggle. Remove all `ThemeRef` parsing, dynamic CSS file loading, custom theme variable injection. Verify nothing in the app breaks (`bun run test`).
+- `apps/web/src/lib/i18n.ts` — remove spa-theme / custom-theme strings
+
+- [ ] **Step 1: Iterate**
+
+Run `cd apps/web && bun run typecheck` after each deletion to catch broken imports. Common pattern:
+- Delete `api/themes.ts` → consumer files in `components/theme/` will fail → delete those next → consumer routes will fail → delete or stub those next.
+
+- [ ] **Step 2: Verify**
+
+`cd apps/web && bun run typecheck && bun run test && bun run build` — all pass.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/web/src
+git -c commit.gpgsign=false commit -m "refactor(web): delete legacy theme code (preset/custom/spa)"
+```
+
+---
+
+## Plan 3 — Completion Criteria
+
+- `POST /api/widget-modules?url=...` installs from a URL.
+- `POST /api/widget-modules` with multipart `file` installs from upload.
+- `DELETE /api/widget-modules/{id}` uninstalls non-Builtin modules.
+- `/_authed/settings/widgets` page lists modules, installs, uninstalls.
+- All legacy theme code is removed (`spa_theme`, `custom_theme`, preset themes); compile is clean; tests pass.
+- A subsequent `cargo build` after removing the apps/web/dist directory should fail with a clear message about needing `bun run build` first (acceptable — this is expected for rust-embed).
+
+Deferred to follow-ups:
+
+- Zip collection upload (`Plan 3 follow-up`).
+- New Theme entity (cssVars + widgets pack) — not in this plan since SPA Theme replacement is deleted but the new Theme is a future concept.
+- 14-widget rewrite.
+- WidgetRendererV2 mounting in DashboardGrid.

From 0ecb2ff8fe13ec4e9620e5fd10ef8f4d86809664 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:43:44 +0800
Subject: [PATCH 32/64] feat(server): POST /api/widget-modules install + DELETE
 uninstall

---
 crates/server/src/openapi.rs                  |   2 +
 crates/server/src/router/api/mod.rs           |   1 +
 crates/server/src/router/api/widget_module.rs | 159 +++++++++++++++++-
 .../src/service/widget_module/service.rs      |  96 +++++++++++
 4 files changed, 255 insertions(+), 3 deletions(-)

diff --git a/crates/server/src/openapi.rs b/crates/server/src/openapi.rs
index 9f5e300f..3ed3381b 100644
--- a/crates/server/src/openapi.rs
+++ b/crates/server/src/openapi.rs
@@ -167,6 +167,8 @@ impl Modify for SecurityAddon {
         // widget-modules
         crate::router::api::widget_module::list_modules,
         crate::router::api::widget_module::serve_asset,
+        crate::router::api::widget_module::install_module,
+        crate::router::api::widget_module::uninstall_module,
         // service-monitors
         crate::router::api::service_monitor::list_monitors,
         crate::router::api::service_monitor::get_monitor,
diff --git a/crates/server/src/router/api/mod.rs b/crates/server/src/router/api/mod.rs
index 83bee74e..1e5393b5 100644
--- a/crates/server/src/router/api/mod.rs
+++ b/crates/server/src/router/api/mod.rs
@@ -102,6 +102,7 @@ pub fn router(state: Arc<AppState>) -> Router<Arc<AppState>> {
                         .merge(service_monitor::write_router())
                         .merge(traceroute::write_router())
                         .merge(dashboard::write_router())
+                        .merge(widget_module::write_router())
                         .merge(theme::write_router())
                         .merge(setting::router())
                         .merge(agent::admin_router())
diff --git a/crates/server/src/router/api/widget_module.rs b/crates/server/src/router/api/widget_module.rs
index c341c2ed..44e829ea 100644
--- a/crates/server/src/router/api/widget_module.rs
+++ b/crates/server/src/router/api/widget_module.rs
@@ -2,15 +2,20 @@ use std::sync::Arc;
 
 use axum::{
     Json, Router,
-    extract::{Path, State},
+    extract::{Extension, Multipart, Path, Query, State},
     http::{HeaderMap, HeaderValue, StatusCode, header},
     response::IntoResponse,
-    routing::get,
+    routing::{delete, get, post},
 };
+use serde::Deserialize;
 
 use crate::{
     error::{ApiResponse, AppError, ok},
-    service::widget_module::{WidgetModuleService, service::WidgetModuleListEntry},
+    middleware::auth::CurrentUser,
+    service::widget_module::{
+        WidgetModuleService,
+        service::{InstalledFrom, WidgetModuleListEntry},
+    },
     state::AppState,
 };
 
@@ -20,6 +25,12 @@ pub fn read_router() -> Router<Arc<AppState>> {
         .route("/widget-modules/{id}/{*asset_path}", get(serve_asset))
 }
 
+pub fn write_router() -> Router<Arc<AppState>> {
+    Router::new()
+        .route("/widget-modules", post(install_module))
+        .route("/widget-modules/{id}", delete(uninstall_module))
+}
+
 #[utoipa::path(
     get,
     path = "/api/widget-modules",
@@ -74,3 +85,145 @@ pub async fn serve_asset(
     );
     Ok((StatusCode::OK, headers, bytes))
 }
+
+#[derive(Debug, Deserialize)]
+pub struct InstallQuery {
+    pub url: Option<String>,
+}
+
+/// Max accepted module size (1 MiB) — applies to both URL fetch and multipart upload.
+const MAX_MODULE_BYTES: usize = 1_048_576;
+
+fn is_private_host(host: &str) -> bool {
+    if host == "localhost" || host == "127.0.0.1" || host == "::1" {
+        return true;
+    }
+    if host.starts_with("10.") || host.starts_with("192.168.") {
+        return true;
+    }
+    // 172.16.0.0 – 172.31.255.255
+    if let Some(rest) = host.strip_prefix("172.")
+        && let Some((second, _)) = rest.split_once('.')
+        && let Ok(n) = second.parse::<u8>()
+        && (16..=31).contains(&n)
+    {
+        return true;
+    }
+    false
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/widget-modules",
+    tag = "widget-modules",
+    params(
+        ("url" = Option<String>, Query, description = "HTTPS URL to fetch the single-file widget JS from"),
+    ),
+    request_body(
+        content_type = "multipart/form-data",
+        description = "Alternatively, upload the widget JS in a `file` field",
+    ),
+    responses(
+        (status = 200, description = "Installed (or upgraded) widget module"),
+        (status = 400, description = "Bad URL, unsupported source, or invalid manifest"),
+    ),
+    security(("session_cookie" = []), ("api_key" = []))
+)]
+pub async fn install_module(
+    State(state): State<Arc<AppState>>,
+    Extension(user): Extension<CurrentUser>,
+    Query(q): Query<InstallQuery>,
+    multipart: Option<Multipart>,
+) -> Result<Json<ApiResponse<serde_json::Value>>, AppError> {
+    let user_id = user.user_id.parse::<i64>().ok();
+
+    let (bytes, from) = if let Some(url) = q.url {
+        if !(url.starts_with("https://") || url.starts_with("http://")) {
+            return Err(AppError::BadRequest("url must be http(s)".into()));
+        }
+        let parsed = url::Url::parse(&url)
+            .map_err(|e| AppError::BadRequest(format!("bad url: {e}")))?;
+        if let Some(host) = parsed.host_str()
+            && is_private_host(host)
+        {
+            return Err(AppError::BadRequest(
+                "private/loopback urls rejected".into(),
+            ));
+        }
+        let resp = reqwest::Client::new()
+            .get(&url)
+            .send()
+            .await
+            .map_err(|e| AppError::BadRequest(format!("fetch: {e}")))?;
+        if !resp.status().is_success() {
+            return Err(AppError::BadRequest(format!(
+                "fetch {}: {}",
+                url,
+                resp.status()
+            )));
+        }
+        let bytes = resp
+            .bytes()
+            .await
+            .map_err(|e| AppError::Internal(format!("read body: {e}")))?
+            .to_vec();
+        if bytes.len() > MAX_MODULE_BYTES {
+            return Err(AppError::BadRequest("module too large (>1MB)".into()));
+        }
+        (bytes, InstalledFrom::Url(url))
+    } else if let Some(mut mp) = multipart {
+        let mut bytes_opt: Option<Vec<u8>> = None;
+        let mut name_opt: Option<String> = None;
+        while let Some(field) = mp
+            .next_field()
+            .await
+            .map_err(|e| AppError::BadRequest(format!("multipart: {e}")))?
+        {
+            if field.name() == Some("file") {
+                name_opt = field.file_name().map(|s| s.to_string());
+                let data = field
+                    .bytes()
+                    .await
+                    .map_err(|e| AppError::BadRequest(format!("multipart body: {e}")))?;
+                if data.len() > MAX_MODULE_BYTES {
+                    return Err(AppError::BadRequest("module too large (>1MB)".into()));
+                }
+                bytes_opt = Some(data.to_vec());
+                break;
+            }
+        }
+        let bytes =
+            bytes_opt.ok_or_else(|| AppError::BadRequest("missing 'file' part".into()))?;
+        (
+            bytes,
+            InstalledFrom::Upload(name_opt.unwrap_or_else(|| "upload.js".into())),
+        )
+    } else {
+        return Err(AppError::BadRequest(
+            "provide ?url=... or multipart file".into(),
+        ));
+    };
+
+    let row = WidgetModuleService::install_single_file(&state.db, bytes, from, user_id).await?;
+    ok(serde_json::json!({ "id": row.id, "version": row.version }))
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/widget-modules/{id}",
+    tag = "widget-modules",
+    params(("id" = String, Path, description = "Module ID")),
+    responses(
+        (status = 204, description = "Module uninstalled"),
+        (status = 400, description = "Cannot uninstall builtin module"),
+        (status = 404, description = "Module not found"),
+    ),
+    security(("session_cookie" = []), ("api_key" = []))
+)]
+pub async fn uninstall_module(
+    State(state): State<Arc<AppState>>,
+    Path(id): Path<String>,
+) -> Result<StatusCode, AppError> {
+    WidgetModuleService::uninstall(&state.db, &id).await?;
+    Ok(StatusCode::NO_CONTENT)
+}
diff --git a/crates/server/src/service/widget_module/service.rs b/crates/server/src/service/widget_module/service.rs
index 0d8ee24d..cf7d9c42 100644
--- a/crates/server/src/service/widget_module/service.rs
+++ b/crates/server/src/service/widget_module/service.rs
@@ -5,6 +5,12 @@ use utoipa::ToSchema;
 use super::{WidgetModuleError, package::UnpackedPackage};
 use crate::entity::widget_module::{self, Entity as WidgetModuleEntity};
 
+#[derive(Debug, Clone)]
+pub enum InstalledFrom {
+    Url(String),
+    Upload(String),
+}
+
 #[derive(Debug, Serialize, ToSchema)]
 pub struct WidgetModuleListEntry {
     pub id: String,
@@ -109,6 +115,96 @@ impl WidgetModuleService {
         let mime = mime_for(requested);
         Ok((bytes, mime))
     }
+
+    /// Install (or upgrade) a single-file JS widget module by extracting the
+    /// JSDoc manifest, computing a sha256 fingerprint, and upserting the row.
+    pub async fn install_single_file(
+        db: &DatabaseConnection,
+        code: Vec<u8>,
+        from: InstalledFrom,
+        installed_by: Option<i64>,
+    ) -> Result<crate::entity::widget_module::Model, WidgetModuleError> {
+        use chrono::Utc;
+        use sea_orm::sea_query::OnConflict;
+        use sea_orm::{ActiveValue::Set, EntityTrait};
+        use sha2::{Digest, Sha256};
+
+        use crate::entity::widget_module::{self, SourceType};
+
+        let source = std::str::from_utf8(&code).map_err(|e| {
+            WidgetModuleError::ManifestValidation(format!("not utf-8: {e}"))
+        })?;
+        let manifest = super::extractor::extract_manifest(source)?;
+
+        let sha = {
+            let mut h = Sha256::new();
+            h.update(&code);
+            format!("{:x}", h.finalize())
+        };
+
+        let (source_type, source_url) = match from {
+            InstalledFrom::Url(u) => (SourceType::Url, Some(u)),
+            InstalledFrom::Upload(name) => (SourceType::Upload, Some(name)),
+        };
+
+        let manifest_json = serde_json::to_string(&manifest).map_err(|e| {
+            WidgetModuleError::ManifestValidation(format!("serialize manifest: {e}"))
+        })?;
+        let id_clone = manifest.id.clone();
+
+        let active = widget_module::ActiveModel {
+            id: Set(manifest.id.clone()),
+            version: Set(manifest.version.clone()),
+            source_type: Set(source_type),
+            source_url: Set(source_url),
+            bundled_by_theme_id: Set(None),
+            manifest_json: Set(manifest_json),
+            code_sha256: Set(sha),
+            entry_path: Set("index.js".into()),
+            package_blob: Set(Some(code)),
+            installed_by: Set(installed_by),
+            installed_at: Set(Utc::now()),
+            enabled: Set(true),
+        };
+
+        widget_module::Entity::insert(active)
+            .on_conflict(
+                OnConflict::column(widget_module::Column::Id)
+                    .update_columns([
+                        widget_module::Column::Version,
+                        widget_module::Column::SourceType,
+                        widget_module::Column::SourceUrl,
+                        widget_module::Column::ManifestJson,
+                        widget_module::Column::CodeSha256,
+                        widget_module::Column::PackageBlob,
+                        widget_module::Column::InstalledBy,
+                        widget_module::Column::InstalledAt,
+                        widget_module::Column::Enabled,
+                    ])
+                    .to_owned(),
+            )
+            .exec(db)
+            .await?;
+
+        Self::get(db, &id_clone).await
+    }
+
+    /// Delete a widget module row. Refuses to delete Builtin rows.
+    pub async fn uninstall(db: &DatabaseConnection, id: &str) -> Result<(), WidgetModuleError> {
+        let row = Self::get(db, id).await?;
+        if matches!(
+            row.source_type,
+            crate::entity::widget_module::SourceType::Builtin
+        ) {
+            return Err(WidgetModuleError::ManifestValidation(
+                "cannot uninstall builtin widget".into(),
+            ));
+        }
+        crate::entity::widget_module::Entity::delete_by_id(id.to_string())
+            .exec(db)
+            .await?;
+        Ok(())
+    }
 }
 
 fn mime_for(path: &str) -> String {

From 4fc2b8ccd9e9dfeafd6cc10470b6c73bf571d328 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:54:33 +0800
Subject: [PATCH 33/64] test(server): widget_module install + uninstall
 integration

---
 .../server/tests/widget_module_integration.rs | 129 ++++++++++++++++++
 1 file changed, 129 insertions(+)

diff --git a/crates/server/tests/widget_module_integration.rs b/crates/server/tests/widget_module_integration.rs
index 945c6f16..7b1eb83a 100644
--- a/crates/server/tests/widget_module_integration.rs
+++ b/crates/server/tests/widget_module_integration.rs
@@ -315,6 +315,135 @@ async fn list_includes_builtin_hello_world() {
     );
 }
 
+#[tokio::test]
+async fn install_single_file_via_multipart_and_uninstall() {
+    let ctx = start_test_server_with_db().await;
+
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    let code = r#"/**
+ * @serverbee-widget {
+ *   "id": "com.test.uploaded",
+ *   "version": "1.0.0",
+ *   "name": "Uploaded",
+ *   "category": "Real-time",
+ *   "sizing": { "defaultW": 2, "defaultH": 2, "minW": 1, "minH": 1, "strategy": "free" },
+ *   "sdkVersion": "^0.1.0"
+ * }
+ */
+export default {};"#;
+
+    let form = reqwest::multipart::Form::new().part(
+        "file",
+        reqwest::multipart::Part::bytes(code.as_bytes().to_vec()).file_name("uploaded.js"),
+    );
+
+    let res = client
+        .post(format!("{}/api/widget-modules", ctx.base_url))
+        .multipart(form)
+        .send()
+        .await
+        .expect("install request failed");
+    assert_eq!(res.status(), 200, "install should return 200");
+    let body: serde_json::Value = res.json().await.expect("invalid JSON");
+    assert_eq!(body["data"]["id"], "com.test.uploaded");
+    assert_eq!(body["data"]["version"], "1.0.0");
+
+    let res2 = client
+        .get(format!("{}/api/widget-modules", ctx.base_url))
+        .send()
+        .await
+        .expect("list request failed");
+    assert_eq!(res2.status(), 200);
+    let list: serde_json::Value = res2.json().await.expect("invalid JSON");
+    assert!(
+        list["data"]
+            .as_array()
+            .expect("data array")
+            .iter()
+            .any(|m| m["id"] == "com.test.uploaded"),
+        "uploaded module should appear in list: {list}"
+    );
+
+    let res3 = client
+        .delete(format!(
+            "{}/api/widget-modules/com.test.uploaded",
+            ctx.base_url
+        ))
+        .send()
+        .await
+        .expect("delete request failed");
+    assert_eq!(res3.status(), 204, "uninstall should return 204");
+
+    let res4 = client
+        .get(format!("{}/api/widget-modules", ctx.base_url))
+        .send()
+        .await
+        .expect("post-delete list failed");
+    let list2: serde_json::Value = res4.json().await.expect("invalid JSON");
+    assert!(
+        !list2["data"]
+            .as_array()
+            .expect("data array")
+            .iter()
+            .any(|m| m["id"] == "com.test.uploaded"),
+        "module should be gone after uninstall: {list2}"
+    );
+}
+
+#[tokio::test]
+async fn install_rejects_invalid_manifest() {
+    let ctx = start_test_server_with_db().await;
+
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    // No @serverbee-widget block at all.
+    let code = b"export default {};";
+    let form = reqwest::multipart::Form::new().part(
+        "file",
+        reqwest::multipart::Part::bytes(code.to_vec()).file_name("bad.js"),
+    );
+
+    let res = client
+        .post(format!("{}/api/widget-modules", ctx.base_url))
+        .multipart(form)
+        .send()
+        .await
+        .expect("install request failed");
+    assert_eq!(
+        res.status(),
+        400,
+        "install without manifest block should 400"
+    );
+}
+
+#[tokio::test]
+async fn cannot_uninstall_builtin() {
+    let ctx = start_test_server_with_db().await;
+    serverbee_server::service::widget_module::builtin::register_all(&ctx.db)
+        .await
+        .expect("register builtin widgets");
+
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    let res = client
+        .delete(format!(
+            "{}/api/widget-modules/com.serverbee.hello-world",
+            ctx.base_url
+        ))
+        .send()
+        .await
+        .expect("delete request failed");
+    assert!(
+        res.status().is_client_error(),
+        "uninstalling builtin should be a client error, got {}",
+        res.status()
+    );
+}
+
 #[tokio::test]
 async fn serve_builtin_asset_returns_js_bytes() {
     let ctx = start_test_server_with_db().await;

From 8c9d48afad89cdc61ba668e9e12493344b8aa027 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:55:12 +0800
Subject: [PATCH 34/64] feat(web): widget modules settings page (install
 URL/.js, list, uninstall)

Adds /settings/widgets admin page backed by the widget-modules API:
list installed modules, install from HTTPS URL or .js/.mjs upload, and
uninstall non-Builtin entries with a confirm dialog. Wires a Puzzle-icon
nav item and EN/ZH i18n strings.
---
 apps/web/src/api/widget-modules.ts            |  98 +++++++
 apps/web/src/components/app-sidebar.tsx       |   2 +
 apps/web/src/locales/en/common.json           |   1 +
 apps/web/src/locales/en/settings.json         |  17 +-
 apps/web/src/locales/zh/common.json           |   1 +
 apps/web/src/locales/zh/settings.json         |  17 +-
 apps/web/src/routeTree.gen.ts                 |  21 ++
 .../src/routes/_authed/settings/widgets.tsx   | 242 ++++++++++++++++++
 8 files changed, 397 insertions(+), 2 deletions(-)
 create mode 100644 apps/web/src/api/widget-modules.ts
 create mode 100644 apps/web/src/routes/_authed/settings/widgets.tsx

diff --git a/apps/web/src/api/widget-modules.ts b/apps/web/src/api/widget-modules.ts
new file mode 100644
index 00000000..7aa9cac1
--- /dev/null
+++ b/apps/web/src/api/widget-modules.ts
@@ -0,0 +1,98 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { api } from '@/lib/api-client'
+
+export interface ModuleSummary {
+  code_sha256: string
+  enabled: boolean
+  entry_path: string
+  id: string
+  manifest: Record<string, unknown>
+  source_type: string
+  version: string
+}
+
+export interface ModuleInstallResult {
+  id: string
+  version: string
+}
+
+const LIST_KEY = ['widget-modules'] as const
+
+export function useWidgetModules() {
+  return useQuery<ModuleSummary[]>({
+    queryKey: LIST_KEY,
+    queryFn: () => api.get<ModuleSummary[]>('/api/widget-modules')
+  })
+}
+
+async function readError(res: Response): Promise<string> {
+  const text = await res.text().catch(() => '')
+  if (text) {
+    try {
+      const parsed = JSON.parse(text)
+      if (parsed && typeof parsed === 'object' && 'error' in parsed) {
+        const err = (parsed as { error?: { message?: string } }).error
+        if (err?.message) {
+          return err.message
+        }
+      }
+    } catch {
+      // not JSON; fall through and use raw text
+    }
+    return text
+  }
+  return `request failed: ${res.status}`
+}
+
+export function useInstallFromUrl() {
+  const qc = useQueryClient()
+  return useMutation<ModuleInstallResult, Error, string>({
+    mutationFn: async (url) => {
+      const res = await fetch(`/api/widget-modules?url=${encodeURIComponent(url)}`, {
+        method: 'POST',
+        credentials: 'include'
+      })
+      if (!res.ok) {
+        throw new Error(await readError(res))
+      }
+      const json = await res.json()
+      return json.data as ModuleInstallResult
+    },
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: LIST_KEY }).catch(() => undefined)
+    }
+  })
+}
+
+export function useInstallFromFile() {
+  const qc = useQueryClient()
+  return useMutation<ModuleInstallResult, Error, File>({
+    mutationFn: async (file) => {
+      const fd = new FormData()
+      fd.append('file', file)
+      const res = await fetch('/api/widget-modules', {
+        method: 'POST',
+        credentials: 'include',
+        body: fd
+      })
+      if (!res.ok) {
+        throw new Error(await readError(res))
+      }
+      const json = await res.json()
+      return json.data as ModuleInstallResult
+    },
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: LIST_KEY }).catch(() => undefined)
+    }
+  })
+}
+
+export function useUninstallWidgetModule() {
+  const qc = useQueryClient()
+  return useMutation<void, Error, string>({
+    mutationFn: (id) => api.delete<void>(`/api/widget-modules/${id}`),
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: LIST_KEY }).catch(() => undefined)
+    }
+  })
+}
diff --git a/apps/web/src/components/app-sidebar.tsx b/apps/web/src/components/app-sidebar.tsx
index f168681e..32d4bf1f 100644
--- a/apps/web/src/components/app-sidebar.tsx
+++ b/apps/web/src/components/app-sidebar.tsx
@@ -15,6 +15,7 @@ import {
   LogOut,
   Monitor,
   Palette,
+  Puzzle,
   Radar,
   Settings,
   Shield,
@@ -74,6 +75,7 @@ const settingsItems = [
   { to: '/settings/api-keys', labelKey: 'nav_api_keys', icon: Key },
   { to: '/settings/security', labelKey: 'nav_security', icon: Shield },
   { to: '/settings/appearance', labelKey: 'nav_appearance', icon: Palette },
+  { to: '/settings/widgets', labelKey: 'nav_widgets', icon: Puzzle, adminOnly: true },
   { to: '/settings/audit-logs', labelKey: 'nav_audit_logs', icon: ClipboardList, adminOnly: true },
   { to: '/settings/rate-limits', labelKey: 'nav_rate_limits', icon: Gauge, adminOnly: true },
   { to: '/settings', labelKey: 'nav_settings', icon: Settings, adminOnly: true }
diff --git a/apps/web/src/locales/en/common.json b/apps/web/src/locales/en/common.json
index 57f47969..93796520 100644
--- a/apps/web/src/locales/en/common.json
+++ b/apps/web/src/locales/en/common.json
@@ -33,6 +33,7 @@
   "nav_api_keys": "API Keys",
   "nav_security": "Security",
   "nav_appearance": "Appearance",
+  "nav_widgets": "Widget Modules",
   "nav_audit_logs": "Audit Logs",
   "nav_rate_limits": "Rate Limits",
   "nav_geoip": "GeoIP",
diff --git a/apps/web/src/locales/en/settings.json b/apps/web/src/locales/en/settings.json
index c1059a60..12887585 100644
--- a/apps/web/src/locales/en/settings.json
+++ b/apps/web/src/locales/en/settings.json
@@ -556,5 +556,20 @@
   "rate_limit.summary_total": "{{count}} active",
   "rate_limit.limits": "Limit: {{login}} login / {{register}} register per {{minutes}} min",
   "rate_limit.toast_reset": "Cleared {{count}} entr(y/ies)",
-  "rate_limit.toast_reset_failed": "Failed to reset rate limit"
+  "rate_limit.toast_reset_failed": "Failed to reset rate limit",
+
+  "widgets.install_from_url": "Install from URL",
+  "widgets.install_from_url_desc": "Fetch a widget module from an HTTPS URL. The server validates and stores it locally.",
+  "widgets.url_label": "Module URL",
+  "widgets.install": "Install",
+  "widgets.upload_file": "Upload .js file",
+  "widgets.upload_file_desc": "Pick a single-file widget bundle (.js or .mjs) from your computer.",
+  "widgets.uploading": "Uploading…",
+  "widgets.installed_modules": "Installed modules",
+  "widgets.no_modules": "No widget modules installed yet.",
+  "widgets.uninstall": "Uninstall",
+  "widgets.builtin_locked": "Built-in (cannot uninstall)",
+  "widgets.confirm_uninstall": "Uninstall \"{{name}}\"? Any dashboard widgets using this module will stop rendering.",
+  "widgets.toast_installed": "Installed {{id}} v{{version}}",
+  "widgets.toast_uninstalled": "Uninstalled {{id}}"
 }
diff --git a/apps/web/src/locales/zh/common.json b/apps/web/src/locales/zh/common.json
index 41642e1e..d20784d3 100644
--- a/apps/web/src/locales/zh/common.json
+++ b/apps/web/src/locales/zh/common.json
@@ -33,6 +33,7 @@
   "nav_api_keys": "API 密钥",
   "nav_security": "安全",
   "nav_appearance": "外观",
+  "nav_widgets": "Widget 模块",
   "nav_audit_logs": "审计日志",
   "nav_rate_limits": "速率限制",
   "nav_geoip": "GeoIP",
diff --git a/apps/web/src/locales/zh/settings.json b/apps/web/src/locales/zh/settings.json
index e714c0a0..ede40fd7 100644
--- a/apps/web/src/locales/zh/settings.json
+++ b/apps/web/src/locales/zh/settings.json
@@ -537,5 +537,20 @@
   "rate_limit.summary_total": "{{count}} 条活跃",
   "rate_limit.limits": "阈值：每 {{minutes}} 分钟 登录 {{login}} 次 / 注册 {{register}} 次",
   "rate_limit.toast_reset": "已清除 {{count}} 条",
-  "rate_limit.toast_reset_failed": "清除速率限制失败"
+  "rate_limit.toast_reset_failed": "清除速率限制失败",
+
+  "widgets.install_from_url": "从 URL 安装",
+  "widgets.install_from_url_desc": "从 HTTPS URL 拉取 Widget 模块，服务端会校验并本地存储。",
+  "widgets.url_label": "模块 URL",
+  "widgets.install": "安装",
+  "widgets.upload_file": "上传 .js 文件",
+  "widgets.upload_file_desc": "从本地选择一个单文件 Widget 包（.js 或 .mjs）。",
+  "widgets.uploading": "上传中…",
+  "widgets.installed_modules": "已安装的模块",
+  "widgets.no_modules": "尚未安装任何 Widget 模块。",
+  "widgets.uninstall": "卸载",
+  "widgets.builtin_locked": "内置（不可卸载）",
+  "widgets.confirm_uninstall": "确定卸载 “{{name}}” 吗？任何仪表盘上使用该模块的小组件都将无法渲染。",
+  "widgets.toast_installed": "已安装 {{id}} v{{version}}",
+  "widgets.toast_uninstalled": "已卸载 {{id}}"
 }
diff --git a/apps/web/src/routeTree.gen.ts b/apps/web/src/routeTree.gen.ts
index 4a35d7b5..7d8f500b 100644
--- a/apps/web/src/routeTree.gen.ts
+++ b/apps/web/src/routeTree.gen.ts
@@ -27,6 +27,7 @@ import { Route as AuthedNetworkIndexRouteImport } from './routes/_authed/network
 import { Route as StatusServerServerIdRouteImport } from './routes/status.server.$serverId'
 import { Route as StatusNetworkServerIdRouteImport } from './routes/status.network.$serverId'
 import { Route as AuthedTerminalServerIdRouteImport } from './routes/_authed/terminal.$serverId'
+import { Route as AuthedSettingsWidgetsRouteImport } from './routes/_authed/settings/widgets'
 import { Route as AuthedSettingsUsersRouteImport } from './routes/_authed/settings/users'
 import { Route as AuthedSettingsTasksRouteImport } from './routes/_authed/settings/tasks'
 import { Route as AuthedSettingsStatusPagesRouteImport } from './routes/_authed/settings/status-pages'
@@ -142,6 +143,11 @@ const AuthedTerminalServerIdRoute = AuthedTerminalServerIdRouteImport.update({
   path: '/terminal/$serverId',
   getParentRoute: () => AuthedRoute,
 } as any)
+const AuthedSettingsWidgetsRoute = AuthedSettingsWidgetsRouteImport.update({
+  id: '/settings/widgets',
+  path: '/settings/widgets',
+  getParentRoute: () => AuthedRoute,
+} as any)
 const AuthedSettingsUsersRoute = AuthedSettingsUsersRouteImport.update({
   id: '/settings/users',
   path: '/settings/users',
@@ -310,6 +316,7 @@ export interface FileRoutesByFullPath {
   '/settings/status-pages': typeof AuthedSettingsStatusPagesRoute
   '/settings/tasks': typeof AuthedSettingsTasksRoute
   '/settings/users': typeof AuthedSettingsUsersRoute
+  '/settings/widgets': typeof AuthedSettingsWidgetsRoute
   '/terminal/$serverId': typeof AuthedTerminalServerIdRoute
   '/status/network/$serverId': typeof StatusNetworkServerIdRoute
   '/status/server/$serverId': typeof StatusServerServerIdRoute
@@ -352,6 +359,7 @@ export interface FileRoutesByTo {
   '/settings/status-pages': typeof AuthedSettingsStatusPagesRoute
   '/settings/tasks': typeof AuthedSettingsTasksRoute
   '/settings/users': typeof AuthedSettingsUsersRoute
+  '/settings/widgets': typeof AuthedSettingsWidgetsRoute
   '/terminal/$serverId': typeof AuthedTerminalServerIdRoute
   '/status/network/$serverId': typeof StatusNetworkServerIdRoute
   '/status/server/$serverId': typeof StatusServerServerIdRoute
@@ -398,6 +406,7 @@ export interface FileRoutesById {
   '/_authed/settings/status-pages': typeof AuthedSettingsStatusPagesRoute
   '/_authed/settings/tasks': typeof AuthedSettingsTasksRoute
   '/_authed/settings/users': typeof AuthedSettingsUsersRoute
+  '/_authed/settings/widgets': typeof AuthedSettingsWidgetsRoute
   '/_authed/terminal/$serverId': typeof AuthedTerminalServerIdRoute
   '/status/network/$serverId': typeof StatusNetworkServerIdRoute
   '/status/server/$serverId': typeof StatusServerServerIdRoute
@@ -444,6 +453,7 @@ export interface FileRouteTypes {
     | '/settings/status-pages'
     | '/settings/tasks'
     | '/settings/users'
+    | '/settings/widgets'
     | '/terminal/$serverId'
     | '/status/network/$serverId'
     | '/status/server/$serverId'
@@ -486,6 +496,7 @@ export interface FileRouteTypes {
     | '/settings/status-pages'
     | '/settings/tasks'
     | '/settings/users'
+    | '/settings/widgets'
     | '/terminal/$serverId'
     | '/status/network/$serverId'
     | '/status/server/$serverId'
@@ -531,6 +542,7 @@ export interface FileRouteTypes {
     | '/_authed/settings/status-pages'
     | '/_authed/settings/tasks'
     | '/_authed/settings/users'
+    | '/_authed/settings/widgets'
     | '/_authed/terminal/$serverId'
     | '/status/network/$serverId'
     | '/status/server/$serverId'
@@ -680,6 +692,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof AuthedTerminalServerIdRouteImport
       parentRoute: typeof AuthedRoute
     }
+    '/_authed/settings/widgets': {
+      id: '/_authed/settings/widgets'
+      path: '/settings/widgets'
+      fullPath: '/settings/widgets'
+      preLoaderRoute: typeof AuthedSettingsWidgetsRouteImport
+      parentRoute: typeof AuthedRoute
+    }
     '/_authed/settings/users': {
       id: '/_authed/settings/users'
       path: '/settings/users'
@@ -901,6 +920,7 @@ interface AuthedRouteChildren {
   AuthedSettingsStatusPagesRoute: typeof AuthedSettingsStatusPagesRoute
   AuthedSettingsTasksRoute: typeof AuthedSettingsTasksRoute
   AuthedSettingsUsersRoute: typeof AuthedSettingsUsersRoute
+  AuthedSettingsWidgetsRoute: typeof AuthedSettingsWidgetsRoute
   AuthedTerminalServerIdRoute: typeof AuthedTerminalServerIdRoute
   AuthedNetworkIndexRoute: typeof AuthedNetworkIndexRoute
   AuthedSecurityIndexRoute: typeof AuthedSecurityIndexRoute
@@ -935,6 +955,7 @@ const AuthedRouteChildren: AuthedRouteChildren = {
   AuthedSettingsStatusPagesRoute: AuthedSettingsStatusPagesRoute,
   AuthedSettingsTasksRoute: AuthedSettingsTasksRoute,
   AuthedSettingsUsersRoute: AuthedSettingsUsersRoute,
+  AuthedSettingsWidgetsRoute: AuthedSettingsWidgetsRoute,
   AuthedTerminalServerIdRoute: AuthedTerminalServerIdRoute,
   AuthedNetworkIndexRoute: AuthedNetworkIndexRoute,
   AuthedSecurityIndexRoute: AuthedSecurityIndexRoute,
diff --git a/apps/web/src/routes/_authed/settings/widgets.tsx b/apps/web/src/routes/_authed/settings/widgets.tsx
new file mode 100644
index 00000000..c3df133e
--- /dev/null
+++ b/apps/web/src/routes/_authed/settings/widgets.tsx
@@ -0,0 +1,242 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { Download, Loader2, Trash2, Upload } from 'lucide-react'
+import { type ChangeEvent, type FormEvent, useRef, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { toast } from 'sonner'
+import {
+  type ModuleSummary,
+  useInstallFromFile,
+  useInstallFromUrl,
+  useUninstallWidgetModule,
+  useWidgetModules
+} from '@/api/widget-modules'
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger
+} from '@/components/ui/alert-dialog'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Skeleton } from '@/components/ui/skeleton'
+
+export const Route = createFileRoute('/_authed/settings/widgets')({
+  component: WidgetsPage
+})
+
+function manifestDisplayName(m: ModuleSummary): string {
+  const manifest = m.manifest as { name?: unknown }
+  if (typeof manifest.name === 'string' && manifest.name.length > 0) {
+    return manifest.name
+  }
+  return m.id
+}
+
+function WidgetsPage() {
+  const { t } = useTranslation(['settings', 'common'])
+  const list = useWidgetModules()
+  const installUrl = useInstallFromUrl()
+  const installFile = useInstallFromFile()
+  const uninstall = useUninstallWidgetModule()
+
+  const [url, setUrl] = useState('')
+  const [deleteId, setDeleteId] = useState<string | null>(null)
+  const fileInputRef = useRef<HTMLInputElement>(null)
+
+  const handleInstallUrl = (e: FormEvent) => {
+    e.preventDefault()
+    const trimmed = url.trim()
+    if (trimmed.length === 0) {
+      return
+    }
+    installUrl.mutate(trimmed, {
+      onSuccess: (data) => {
+        setUrl('')
+        toast.success(t('widgets.toast_installed', { id: data.id, version: data.version }))
+      },
+      onError: (err) => {
+        toast.error(err.message)
+      }
+    })
+  }
+
+  const handleInstallFile = (e: ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0]
+    if (!file) {
+      return
+    }
+    installFile.mutate(file, {
+      onSuccess: (data) => {
+        toast.success(t('widgets.toast_installed', { id: data.id, version: data.version }))
+      },
+      onError: (err) => {
+        toast.error(err.message)
+      },
+      onSettled: () => {
+        if (fileInputRef.current) {
+          fileInputRef.current.value = ''
+        }
+      }
+    })
+  }
+
+  const handleUninstall = (id: string) => {
+    uninstall.mutate(id, {
+      onSuccess: () => {
+        toast.success(t('widgets.toast_uninstalled', { id }))
+      },
+      onError: (err) => {
+        toast.error(err.message)
+      }
+    })
+    setDeleteId(null)
+  }
+
+  return (
+    <div>
+      <div className="max-w-3xl space-y-6">
+        <div className="space-y-3">
+          <h2 className="font-semibold text-lg">{t('widgets.install_from_url')}</h2>
+          <p className="text-muted-foreground text-sm">{t('widgets.install_from_url_desc')}</p>
+          <form className="flex gap-2" onSubmit={handleInstallUrl}>
+            <Input
+              aria-label={t('widgets.url_label')}
+              autoComplete="off"
+              className="flex-1"
+              disabled={installUrl.isPending}
+              name="widget-url"
+              onChange={(e) => setUrl(e.target.value)}
+              placeholder="https://example.com/foo.widget.js"
+              type="url"
+              value={url}
+            />
+            <Button disabled={installUrl.isPending || url.trim().length === 0} type="submit">
+              {installUrl.isPending ? (
+                <Loader2 aria-hidden="true" className="size-4 animate-spin" />
+              ) : (
+                <Download aria-hidden="true" className="size-4" />
+              )}
+              {t('widgets.install')}
+            </Button>
+          </form>
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="font-semibold text-lg">{t('widgets.upload_file')}</h2>
+          <p className="text-muted-foreground text-sm">{t('widgets.upload_file_desc')}</p>
+          <div className="flex items-center gap-2">
+            <Input
+              accept=".js,.mjs"
+              aria-label={t('widgets.upload_file')}
+              className="flex-1"
+              disabled={installFile.isPending}
+              name="widget-file"
+              onChange={handleInstallFile}
+              ref={fileInputRef}
+              type="file"
+            />
+            {installFile.isPending && (
+              <span className="flex items-center gap-1 text-muted-foreground text-sm">
+                <Loader2 aria-hidden="true" className="size-4 animate-spin" />
+                {t('widgets.uploading')}
+              </span>
+            )}
+            {!installFile.isPending && <Upload aria-hidden="true" className="size-4 text-muted-foreground" />}
+          </div>
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="font-semibold text-lg">{t('widgets.installed_modules')}</h2>
+
+          {list.isLoading && (
+            <div className="space-y-2">
+              {Array.from({ length: 3 }, (_, i) => (
+                <Skeleton className="h-14" key={`skeleton-${i.toString()}`} />
+              ))}
+            </div>
+          )}
+
+          {list.error && (
+            <p className="text-destructive text-sm">
+              {list.error instanceof Error ? list.error.message : t('common:errors.operation_failed')}
+            </p>
+          )}
+
+          {!(list.isLoading || list.error) && (!list.data || list.data.length === 0) && (
+            <p className="text-center text-muted-foreground text-sm">{t('widgets.no_modules')}</p>
+          )}
+
+          {!list.isLoading && list.data && list.data.length > 0 && (
+            <div className="divide-y rounded-md border">
+              {list.data.map((m) => {
+                const isBuiltin = m.source_type === 'Builtin'
+                const displayName = manifestDisplayName(m)
+                return (
+                  <div
+                    className="flex flex-col gap-3 px-4 py-3 sm:flex-row sm:items-center sm:justify-between"
+                    key={m.id}
+                  >
+                    <div className="min-w-0">
+                      <p className="truncate font-medium text-sm">{displayName}</p>
+                      <div className="flex flex-wrap gap-x-3 gap-y-1 text-muted-foreground text-xs">
+                        <span className="font-mono">{m.id}</span>
+                        <span>v{m.version}</span>
+                        <span>{m.source_type}</span>
+                      </div>
+                    </div>
+                    {isBuiltin ? (
+                      <span className="text-muted-foreground text-xs sm:text-right">{t('widgets.builtin_locked')}</span>
+                    ) : (
+                      <AlertDialog
+                        onOpenChange={(open) => {
+                          if (!open) {
+                            setDeleteId(null)
+                          }
+                        }}
+                        open={deleteId === m.id}
+                      >
+                        <AlertDialogTrigger
+                          onClick={() => setDeleteId(m.id)}
+                          render={
+                            <Button
+                              aria-label={`${t('widgets.uninstall')} ${displayName}`}
+                              disabled={uninstall.isPending}
+                              size="sm"
+                              variant="destructive"
+                            />
+                          }
+                        >
+                          <Trash2 aria-hidden="true" className="size-3.5" />
+                          {t('widgets.uninstall')}
+                        </AlertDialogTrigger>
+                        <AlertDialogContent>
+                          <AlertDialogHeader>
+                            <AlertDialogTitle>{t('common:confirm_title')}</AlertDialogTitle>
+                            <AlertDialogDescription>
+                              {t('widgets.confirm_uninstall', { name: displayName })}
+                            </AlertDialogDescription>
+                          </AlertDialogHeader>
+                          <AlertDialogFooter>
+                            <AlertDialogCancel>{t('common:cancel')}</AlertDialogCancel>
+                            <AlertDialogAction onClick={() => handleUninstall(m.id)} variant="destructive">
+                              {t('widgets.uninstall')}
+                            </AlertDialogAction>
+                          </AlertDialogFooter>
+                        </AlertDialogContent>
+                      </AlertDialog>
+                    )}
+                  </div>
+                )
+              })}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}

From 4105b2bb175bc75b9f421f82d19095afa71bec2b Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 21:55:24 +0800
Subject: [PATCH 35/64] refactor(server): delete legacy spa_theme +
 custom_theme code

Drop the SPA package theme and custom CSS variable theme features
in favour of the new widget module system. Adds a forward-only
migration that drops the legacy spa_themes / custom_theme tables
and their referential-integrity triggers, and rips out the routes,
services, entities, integration tests, and AppState slot that
backed them. The catch-all SPA fallback now serves only the
embedded rust-embed bundle.
---
 crates/server/src/config.rs                   |  35 -
 crates/server/src/entity/custom_theme.rs      |  21 -
 crates/server/src/entity/mod.rs               |   2 -
 crates/server/src/entity/spa_theme.rs         |  31 -
 ...0260528_000060_drop_legacy_theme_tables.rs |  53 ++
 crates/server/src/migration/mod.rs            |   2 +
 crates/server/src/openapi.rs                  |  38 -
 crates/server/src/router/api/mod.rs           |   5 -
 crates/server/src/router/api/spa_theme.rs     | 502 -------------
 crates/server/src/router/api/theme.rs         | 593 ----------------
 crates/server/src/router/mod.rs               |  11 +-
 crates/server/src/router/static_files.rs      | 438 +-----------
 crates/server/src/router/system.rs            |  61 --
 crates/server/src/service/custom_theme.rs     | 669 ------------------
 crates/server/src/service/mod.rs              |   4 -
 crates/server/src/service/spa_theme/error.rs  | 178 -----
 .../server/src/service/spa_theme/extractor.rs | 330 ---------
 crates/server/src/service/spa_theme/loaded.rs |  42 --
 .../server/src/service/spa_theme/manifest.rs  | 271 -------
 crates/server/src/service/spa_theme/mod.rs    |  17 -
 .../server/src/service/spa_theme/service.rs   | 449 ------------
 crates/server/src/service/theme_ref.rs        | 301 --------
 crates/server/src/service/theme_validator.rs  | 356 ----------
 crates/server/src/state.rs                    |   5 -
 .../server/tests/custom_theme_integration.rs  | 445 ------------
 crates/server/tests/spa_theme_integration.rs  | 669 ------------------
 26 files changed, 66 insertions(+), 5462 deletions(-)
 delete mode 100644 crates/server/src/entity/custom_theme.rs
 delete mode 100644 crates/server/src/entity/spa_theme.rs
 create mode 100644 crates/server/src/migration/m20260528_000060_drop_legacy_theme_tables.rs
 delete mode 100644 crates/server/src/router/api/spa_theme.rs
 delete mode 100644 crates/server/src/router/api/theme.rs
 delete mode 100644 crates/server/src/router/system.rs
 delete mode 100644 crates/server/src/service/custom_theme.rs
 delete mode 100644 crates/server/src/service/spa_theme/error.rs
 delete mode 100644 crates/server/src/service/spa_theme/extractor.rs
 delete mode 100644 crates/server/src/service/spa_theme/loaded.rs
 delete mode 100644 crates/server/src/service/spa_theme/manifest.rs
 delete mode 100644 crates/server/src/service/spa_theme/mod.rs
 delete mode 100644 crates/server/src/service/spa_theme/service.rs
 delete mode 100644 crates/server/src/service/theme_ref.rs
 delete mode 100644 crates/server/src/service/theme_validator.rs
 delete mode 100644 crates/server/tests/custom_theme_integration.rs
 delete mode 100644 crates/server/tests/spa_theme_integration.rs

diff --git a/crates/server/src/config.rs b/crates/server/src/config.rs
index 8e71ed3f..147d1f6f 100644
--- a/crates/server/src/config.rs
+++ b/crates/server/src/config.rs
@@ -37,8 +37,6 @@ pub struct AppConfig {
     #[serde(default)]
     pub resend: ResendConfig,
     #[serde(default)]
-    pub feature: FeatureConfig,
-    #[serde(default)]
     pub dev: DevConfig,
     #[serde(default)]
     pub firewall: FirewallConfig,
@@ -65,7 +63,6 @@ impl Default for AppConfig {
             file: FileConfig::default(),
             mobile: MobileConfig::default(),
             resend: ResendConfig::default(),
-            feature: FeatureConfig::default(),
             dev: DevConfig::default(),
             firewall: FirewallConfig::default(),
             ip_quality: IpQualityConfig::default(),
@@ -503,20 +500,6 @@ fn default_very_high_latency_ms() -> f64 {
     800.0
 }
 
-#[derive(Debug, Clone, Deserialize)]
-pub struct FeatureConfig {
-    #[serde(default = "default_true")]
-    pub custom_themes: bool,
-}
-
-impl Default for FeatureConfig {
-    fn default() -> Self {
-        Self {
-            custom_themes: default_true(),
-        }
-    }
-}
-
 #[derive(Debug, Clone, Deserialize, Default)]
 pub struct DevConfig {
     #[serde(default)]
@@ -677,12 +660,6 @@ mod tests {
         assert_eq!(cfg.resend.api_key, "");
     }
 
-    #[test]
-    fn test_app_config_default_enables_custom_themes() {
-        let cfg = AppConfig::default();
-        assert!(cfg.feature.custom_themes);
-    }
-
     #[test]
     fn dev_demo_data_defaults_to_disabled_and_reads_env_var() {
         let cfg = AppConfig::default();
@@ -831,16 +808,4 @@ mod tests {
         assert!(!warnings.iter().any(|w| w.contains("matches risk_provider")));
     }
 
-    #[test]
-    fn test_feature_config_reads_custom_themes_env_var() {
-        figment::Jail::expect_with(|jail| {
-            jail.set_env("SERVERBEE_FEATURE__CUSTOM_THEMES", "false");
-            let cfg: AppConfig = figment::Figment::new()
-                .merge(figment::providers::Env::prefixed("SERVERBEE_").split("__"))
-                .extract()
-                .expect("custom themes feature flag should deserialize from env");
-            assert!(!cfg.feature.custom_themes);
-            Ok(())
-        });
-    }
 }
diff --git a/crates/server/src/entity/custom_theme.rs b/crates/server/src/entity/custom_theme.rs
deleted file mode 100644
index ab46158a..00000000
--- a/crates/server/src/entity/custom_theme.rs
+++ /dev/null
@@ -1,21 +0,0 @@
-use sea_orm::entity::prelude::*;
-
-#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
-#[sea_orm(table_name = "custom_theme")]
-pub struct Model {
-    #[sea_orm(primary_key)]
-    pub id: i32,
-    pub name: String,
-    pub description: Option<String>,
-    pub based_on: Option<String>,
-    pub vars_light: String,
-    pub vars_dark: String,
-    pub created_by: String,
-    pub created_at: DateTimeUtc,
-    pub updated_at: DateTimeUtc,
-}
-
-#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
-pub enum Relation {}
-
-impl ActiveModelBehavior for ActiveModel {}
diff --git a/crates/server/src/entity/mod.rs b/crates/server/src/entity/mod.rs
index da54f928..8ec9b0ff 100644
--- a/crates/server/src/entity/mod.rs
+++ b/crates/server/src/entity/mod.rs
@@ -5,7 +5,6 @@ pub mod api_key;
 pub mod audit_log;
 pub mod block_list;
 pub mod config;
-pub mod custom_theme;
 pub mod dashboard;
 pub mod dashboard_widget;
 pub mod device_token;
@@ -36,7 +35,6 @@ pub mod server_tag;
 pub mod service_monitor;
 pub mod service_monitor_record;
 pub mod session;
-pub mod spa_theme;
 pub mod status_page;
 pub mod task;
 pub mod task_result;
diff --git a/crates/server/src/entity/spa_theme.rs b/crates/server/src/entity/spa_theme.rs
deleted file mode 100644
index 3702eed7..00000000
--- a/crates/server/src/entity/spa_theme.rs
+++ /dev/null
@@ -1,31 +0,0 @@
-use sea_orm::entity::prelude::*;
-use serde::Serialize;
-
-#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Serialize)]
-#[sea_orm(table_name = "spa_themes")]
-pub struct Model {
-    #[sea_orm(primary_key)]
-    pub id: i64,
-    #[sea_orm(unique)]
-    pub uuid: String,
-    pub manifest_id: String,
-    pub name: String,
-    pub version: String,
-    pub author: Option<String>,
-    pub description: Option<String>,
-    pub manifest_json: String,
-    #[serde(skip)]
-    pub package_data: Vec<u8>,
-    #[serde(skip)]
-    pub preview_data: Option<Vec<u8>>,
-    pub preview_mime: Option<String>,
-    pub size_bytes: i64,
-    pub uploaded_by: String,
-    pub uploaded_at: DateTimeUtc,
-    pub is_superseded: i32,
-}
-
-#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
-pub enum Relation {}
-
-impl ActiveModelBehavior for ActiveModel {}
diff --git a/crates/server/src/migration/m20260528_000060_drop_legacy_theme_tables.rs b/crates/server/src/migration/m20260528_000060_drop_legacy_theme_tables.rs
new file mode 100644
index 00000000..3b213f89
--- /dev/null
+++ b/crates/server/src/migration/m20260528_000060_drop_legacy_theme_tables.rs
@@ -0,0 +1,53 @@
+//! Drop the legacy `spa_themes` and `custom_theme` tables.
+//!
+//! These tables backed the now-removed SPA package upload + custom CSS variable
+//! theme features. The new widget module system supersedes both. `down()` is a
+//! no-op per project policy (see CLAUDE.md): migrations are forward-only.
+use sea_orm_migration::prelude::*;
+
+#[derive(DeriveMigrationName)]
+pub struct Migration;
+
+#[async_trait::async_trait]
+impl MigrationTrait for Migration {
+    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        let db = manager.get_connection();
+        // Drop dependent triggers first (created in
+        // m20260430_000021_custom_theme_ref_integrity) before the tables they
+        // reference go away. `m20260526_000036_simplify_status_page` already
+        // drops the `status_page` triggers; the `configs` triggers and the
+        // `custom_theme` table itself are still around and must go now. The
+        // `configs` triggers also have to be dropped explicitly because their
+        // WHEN clauses reference `custom_theme`, and SQLite refuses to load a
+        // trigger whose body references a missing table the next time the
+        // owning table is touched. `IF EXISTS` keeps every step idempotent.
+        db.execute_unprepared(
+            "DROP TRIGGER IF EXISTS trg_custom_theme_config_insert_ref_exists",
+        )
+        .await?;
+        db.execute_unprepared(
+            "DROP TRIGGER IF EXISTS trg_custom_theme_config_update_ref_exists",
+        )
+        .await?;
+        db.execute_unprepared(
+            "DROP TRIGGER IF EXISTS trg_custom_theme_status_page_insert_ref_exists",
+        )
+        .await?;
+        db.execute_unprepared(
+            "DROP TRIGGER IF EXISTS trg_custom_theme_status_page_update_ref_exists",
+        )
+        .await?;
+        db.execute_unprepared("DROP TRIGGER IF EXISTS trg_custom_theme_delete_no_active_config_ref")
+            .await?;
+        db.execute_unprepared("DROP TRIGGER IF EXISTS trg_custom_theme_delete_no_status_page_ref")
+            .await?;
+        db.execute_unprepared("DROP TABLE IF EXISTS spa_themes").await?;
+        db.execute_unprepared("DROP TABLE IF EXISTS custom_theme")
+            .await?;
+        Ok(())
+    }
+
+    async fn down(&self, _manager: &SchemaManager) -> Result<(), DbErr> {
+        Ok(())
+    }
+}
diff --git a/crates/server/src/migration/mod.rs b/crates/server/src/migration/mod.rs
index af7374d1..9fa1c182 100644
--- a/crates/server/src/migration/mod.rs
+++ b/crates/server/src/migration/mod.rs
@@ -37,6 +37,7 @@ mod m20260525_000034_agent_registration_redesign;
 mod m20260526_000035_create_spa_themes;
 mod m20260526_000036_simplify_status_page;
 mod m20260528_000037_create_widget_module;
+mod m20260528_000060_drop_legacy_theme_tables;
 
 pub struct Migrator;
 
@@ -80,6 +81,7 @@ impl MigratorTrait for Migrator {
             Box::new(m20260526_000035_create_spa_themes::Migration),
             Box::new(m20260526_000036_simplify_status_page::Migration),
             Box::new(m20260528_000037_create_widget_module::Migration),
+            Box::new(m20260528_000060_drop_legacy_theme_tables::Migration),
         ]
     }
 }
diff --git a/crates/server/src/openapi.rs b/crates/server/src/openapi.rs
index 3ed3381b..d89743dd 100644
--- a/crates/server/src/openapi.rs
+++ b/crates/server/src/openapi.rs
@@ -106,18 +106,6 @@ impl Modify for SecurityAddon {
         crate::router::api::setting::update_settings,
         crate::router::api::setting::create_backup,
         crate::router::api::setting::restore_backup,
-        // themes
-        crate::router::api::theme::list_themes,
-        crate::router::api::theme::get_theme,
-        crate::router::api::theme::export_theme,
-        crate::router::api::theme::get_active_theme,
-        crate::router::api::theme::create_theme,
-        crate::router::api::theme::update_theme,
-        crate::router::api::theme::delete_theme,
-        crate::router::api::theme::get_references,
-        crate::router::api::theme::duplicate_theme,
-        crate::router::api::theme::import_theme,
-        crate::router::api::theme::put_active_theme,
         // notifications
         crate::router::api::notification::list_notifications,
         crate::router::api::notification::get_notification,
@@ -268,15 +256,6 @@ impl Modify for SecurityAddon {
         crate::router::api::ip_quality::get_server_summary,
         crate::router::api::ip_quality::list_events,
         crate::router::api::ip_quality::check_server,
-        // spa-themes
-        crate::router::api::spa_theme::list,
-        crate::router::api::spa_theme::get_one,
-        crate::router::api::spa_theme::get_preview,
-        crate::router::api::spa_theme::get_package,
-        crate::router::api::spa_theme::delete_one,
-        crate::router::api::spa_theme::upload,
-        crate::router::api::spa_theme::get_active,
-        crate::router::api::spa_theme::put_active,
     ),
     components(
         schemas(
@@ -329,16 +308,6 @@ impl Modify for SecurityAddon {
             crate::router::api::brand::UploadResponse,
             // settings
             crate::router::api::setting::SystemSettings,
-            // themes
-            crate::service::custom_theme::ThemeSummary,
-            crate::service::custom_theme::Theme,
-            crate::service::custom_theme::CreateThemeInput,
-            crate::service::custom_theme::UpdateThemeInput,
-            crate::service::custom_theme::ThemeResolved,
-            crate::service::custom_theme::ActiveThemeResponse,
-            crate::service::theme_ref::ThemeReferences,
-            crate::router::api::theme::ExportPayload,
-            crate::router::api::theme::PutActiveThemeInput,
             // notifications
             crate::service::notification::CreateNotification,
             crate::service::notification::UpdateNotification,
@@ -513,12 +482,6 @@ impl Modify for SecurityAddon {
             crate::service::ip_quality::ServerIpQualityData,
             crate::service::ip_quality::UnlockResultDto,
             crate::service::ip_quality::UnlockEventDto,
-            // spa-themes
-            crate::service::spa_theme::service::SpaThemeSummary,
-            crate::service::spa_theme::service::UploadResult,
-            crate::service::spa_theme::service::UpgradeOf,
-            crate::router::api::spa_theme::PutActiveBody,
-            crate::router::api::spa_theme::ActiveResp,
         ),
     ),
     tags(
@@ -531,7 +494,6 @@ impl Modify for SecurityAddon {
         (name = "server-groups", description = "Server group management"),
         (name = "brand", description = "Custom branding (logo, favicon, site title)"),
         (name = "settings", description = "System settings"),
-        (name = "themes", description = "Custom theme management"),
         (name = "notifications", description = "Notification channels"),
         (name = "notification-groups", description = "Notification groups"),
         (name = "alert-rules", description = "Alert rules"),
diff --git a/crates/server/src/router/api/mod.rs b/crates/server/src/router/api/mod.rs
index 1e5393b5..e88969e3 100644
--- a/crates/server/src/router/api/mod.rs
+++ b/crates/server/src/router/api/mod.rs
@@ -26,11 +26,9 @@ pub mod server_group;
 pub mod server_tag;
 pub mod service_monitor;
 pub mod setting;
-pub mod spa_theme;
 pub mod status;
 pub mod status_page;
 pub mod task;
-pub mod theme;
 pub mod traceroute;
 pub mod traffic;
 pub mod uptime;
@@ -75,7 +73,6 @@ pub fn router(state: Arc<AppState>) -> Router<Arc<AppState>> {
                 .merge(uptime::read_router())
                 .merge(dashboard::read_router())
                 .merge(widget_module::read_router())
-                .merge(theme::read_router())
                 .merge(alert::alert_events_router())
                 .merge(geoip::read_router())
                 .merge(asn::read_router())
@@ -103,7 +100,6 @@ pub fn router(state: Arc<AppState>) -> Router<Arc<AppState>> {
                         .merge(traceroute::write_router())
                         .merge(dashboard::write_router())
                         .merge(widget_module::write_router())
-                        .merge(theme::write_router())
                         .merge(setting::router())
                         .merge(agent::admin_router())
                         .merge(brand::write_router())
@@ -119,7 +115,6 @@ pub fn router(state: Arc<AppState>) -> Router<Arc<AppState>> {
                         .merge(rate_limit::router())
                         .merge(security::write_router())
                         .merge(firewall::write_router())
-                        .merge(spa_theme::router())
                         .merge(status_page::write_router())
                         .layer(middleware::from_fn(require_admin)),
                 )
diff --git a/crates/server/src/router/api/spa_theme.rs b/crates/server/src/router/api/spa_theme.rs
deleted file mode 100644
index d9df28aa..00000000
--- a/crates/server/src/router/api/spa_theme.rs
+++ /dev/null
@@ -1,502 +0,0 @@
-//! REST API for custom SPA theme management.
-//!
-//! All routes are admin-only; they inherit the `require_admin` middleware from
-//! the enclosing router block in `api/mod.rs`.
-
-use std::sync::Arc;
-
-use axum::extract::multipart::MultipartRejection;
-use axum::extract::{
-    ConnectInfo, DefaultBodyLimit, Extension, FromRequest, Multipart, Path, Request, State,
-};
-use axum::http::{HeaderMap, StatusCode};
-use axum::response::IntoResponse;
-use axum::routing::get;
-use axum::{Json, Router};
-
-use crate::error::{ApiResponse, AppError, ok};
-use crate::middleware::auth::CurrentUser;
-use crate::router::utils::extract_client_ip;
-use crate::service::audit::AuditService;
-use crate::service::spa_theme::error::SpaThemeError;
-use crate::service::spa_theme::service::{SpaThemeSummary, UploadResult};
-use crate::service::spa_theme::{SpaThemeService, UPLOAD_LIMIT_BYTES};
-use crate::state::AppState;
-
-// ---------------------------------------------------------------------------
-// Custom multipart extractor that translates 413 → our JSON contract
-// ---------------------------------------------------------------------------
-
-pub struct SpaThemeUpload(pub Multipart);
-
-impl<S> FromRequest<S> for SpaThemeUpload
-where
-    S: Send + Sync,
-{
-    type Rejection = AppError;
-
-    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
-        match Multipart::from_request(req, state).await {
-            Ok(m) => Ok(Self(m)),
-            Err(rej) => Err(map_rejection(rej)),
-        }
-    }
-}
-
-fn map_rejection(rej: MultipartRejection) -> AppError {
-    if rej.status() == StatusCode::PAYLOAD_TOO_LARGE {
-        return SpaThemeError::UploadTooLarge {
-            limit_bytes: UPLOAD_LIMIT_BYTES,
-        }
-        .into();
-    }
-    SpaThemeError::InvalidMultipart(rej.to_string()).into()
-}
-
-/// Map an error returned by `field.bytes()` / `mp.next_field()` in the upload
-/// handler. When the body limit is exceeded during lazy field reads (the common
-/// path for oversize uploads), `axum::extract::multipart::MultipartError` has
-/// status 413 — propagate that as `UploadTooLarge` so the client gets our JSON
-/// error contract instead of a generic 400.
-fn map_field_error(e: axum::extract::multipart::MultipartError) -> AppError {
-    if e.status() == StatusCode::PAYLOAD_TOO_LARGE {
-        return SpaThemeError::UploadTooLarge {
-            limit_bytes: UPLOAD_LIMIT_BYTES,
-        }
-        .into();
-    }
-    SpaThemeError::InvalidMultipart(e.to_string()).into()
-}
-
-// ---------------------------------------------------------------------------
-// Router + handlers
-// ---------------------------------------------------------------------------
-
-pub fn router() -> Router<Arc<AppState>> {
-    Router::new()
-        .route("/settings/spa-themes", get(list).post(upload))
-        .route(
-            "/settings/spa-themes/{uuid}",
-            get(get_one).delete(delete_one),
-        )
-        .route("/settings/spa-themes/{uuid}/preview", get(get_preview))
-        .route("/settings/spa-themes/{uuid}/package", get(get_package))
-        .route(
-            "/settings/active-spa-theme",
-            get(get_active).put(put_active),
-        )
-        .layer(DefaultBodyLimit::max(UPLOAD_LIMIT_BYTES as usize))
-}
-
-// ---------------------------------------------------------------------------
-// Handlers
-// ---------------------------------------------------------------------------
-
-#[utoipa::path(
-    get,
-    path = "/api/settings/spa-themes",
-    tag = "spa-themes",
-    responses(
-        (status = 200, description = "List of uploaded SPA themes", body = Vec<SpaThemeSummary>),
-        (status = 403, description = "Forbidden — admin only"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-pub async fn list(
-    State(state): State<Arc<AppState>>,
-) -> Result<Json<ApiResponse<Vec<SpaThemeSummary>>>, AppError> {
-    ok(SpaThemeService::list(&state.db).await?)
-}
-
-#[utoipa::path(
-    get,
-    path = "/api/settings/spa-themes/{uuid}",
-    tag = "spa-themes",
-    params(("uuid" = String, Path, description = "Theme UUID")),
-    responses(
-        (status = 200, description = "Theme metadata", body = SpaThemeSummary),
-        (status = 403, description = "Forbidden — admin only"),
-        (status = 404, description = "Not found"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-pub async fn get_one(
-    State(state): State<Arc<AppState>>,
-    Path(uuid): Path<String>,
-) -> Result<Json<ApiResponse<SpaThemeSummary>>, AppError> {
-    let row = SpaThemeService::get(&state.db, &uuid).await?;
-    let active = SpaThemeService::active_uuid(&state.db)
-        .await?
-        .unwrap_or_default();
-    ok(SpaThemeSummary {
-        is_active: active == row.uuid,
-        is_superseded: row.is_superseded != 0,
-        has_preview: row.preview_data.is_some(),
-        uuid: row.uuid,
-        manifest_id: row.manifest_id,
-        name: row.name,
-        version: row.version,
-        author: row.author,
-        description: row.description,
-        size_bytes: row.size_bytes,
-        uploaded_by: row.uploaded_by,
-        uploaded_at: row.uploaded_at.to_rfc3339(),
-    })
-}
-
-#[utoipa::path(
-    get,
-    path = "/api/settings/spa-themes/{uuid}/preview",
-    tag = "spa-themes",
-    params(("uuid" = String, Path, description = "Theme UUID")),
-    responses(
-        (status = 200, description = "Preview image bytes"),
-        (status = 403, description = "Forbidden — admin only"),
-        (status = 404, description = "No preview or theme not found"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-pub async fn get_preview(
-    State(state): State<Arc<AppState>>,
-    Path(uuid): Path<String>,
-) -> Result<axum::response::Response, AppError> {
-    let row = SpaThemeService::get(&state.db, &uuid).await?;
-    let Some(bytes) = row.preview_data else {
-        return Err(AppError::NotFound("no preview".into()));
-    };
-    let mime = row
-        .preview_mime
-        .unwrap_or_else(|| "application/octet-stream".into());
-    Ok(([(axum::http::header::CONTENT_TYPE, mime)], bytes).into_response())
-}
-
-#[utoipa::path(
-    get,
-    path = "/api/settings/spa-themes/{uuid}/package",
-    tag = "spa-themes",
-    params(("uuid" = String, Path, description = "Theme UUID")),
-    responses(
-        (status = 200, description = "Theme package (zip)"),
-        (status = 403, description = "Forbidden — admin only"),
-        (status = 404, description = "Not found"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-pub async fn get_package(
-    State(state): State<Arc<AppState>>,
-    Path(uuid): Path<String>,
-) -> Result<axum::response::Response, AppError> {
-    let row = SpaThemeService::get(&state.db, &uuid).await?;
-    let filename = format!("{}-{}.sbtheme", row.manifest_id, row.version);
-    Ok((
-        [
-            (
-                axum::http::header::CONTENT_TYPE,
-                "application/zip".to_string(),
-            ),
-            (
-                axum::http::header::CONTENT_DISPOSITION,
-                content_disposition_attachment(&filename),
-            ),
-        ],
-        row.package_data,
-    )
-        .into_response())
-}
-
-/// Build a `Content-Disposition: attachment` header value that is safe for
-/// arbitrary filenames.
-///
-/// Emits both the legacy `filename="..."` (ASCII-sanitized, for old clients)
-/// and the RFC 5987 `filename*=UTF-8''<percent-encoded>` (preferred by modern
-/// clients). Using both maximizes compatibility while keeping the value
-/// well-formed even when the input contains characters like `+` (semver build
-/// metadata), spaces, quotes, or non-ASCII.
-fn content_disposition_attachment(filename: &str) -> String {
-    // For the RFC 5987 `filename*` value we percent-encode anything outside a
-    // conservative subset of the spec's `attr-char` set. RFC 8187 `attr-char`
-    // technically allows `+`, but we intentionally encode it because some HTTP
-    // clients and intermediaries treat raw `+` in encoded extensions as a
-    // space, which corrupts semver build-metadata filenames like
-    // `theme-1.0.0+build1.sbtheme`.
-    fn is_safe(b: u8) -> bool {
-        b.is_ascii_alphanumeric()
-            || matches!(
-                b,
-                b'!' | b'#' | b'$' | b'&' | b'-' | b'.' | b'^' | b'_' | b'`' | b'|' | b'~'
-            )
-    }
-
-    let mut encoded = String::with_capacity(filename.len());
-    for &b in filename.as_bytes() {
-        if is_safe(b) {
-            encoded.push(b as char);
-        } else {
-            encoded.push_str(&format!("%{b:02X}"));
-        }
-    }
-
-    // ASCII fallback: keep safe bytes plus space; replace everything else with
-    // `_`. This guarantees the quoted `filename="..."` form is well-formed and
-    // cannot contain `"` (header injection) or `\` (line folding / smuggling).
-    let mut ascii_fallback = String::with_capacity(filename.len());
-    for &b in filename.as_bytes() {
-        if is_safe(b) || b == b' ' {
-            ascii_fallback.push(b as char);
-        } else {
-            ascii_fallback.push('_');
-        }
-    }
-
-    format!("attachment; filename=\"{ascii_fallback}\"; filename*=UTF-8''{encoded}")
-}
-
-#[utoipa::path(
-    delete,
-    path = "/api/settings/spa-themes/{uuid}",
-    tag = "spa-themes",
-    params(("uuid" = String, Path, description = "Theme UUID")),
-    responses(
-        (status = 204, description = "Deleted"),
-        (status = 403, description = "Forbidden — admin only"),
-        (status = 404, description = "Not found"),
-        (status = 409, description = "Theme is currently active"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-pub async fn delete_one(
-    State(state): State<Arc<AppState>>,
-    Extension(current_user): Extension<CurrentUser>,
-    ConnectInfo(addr): ConnectInfo<std::net::SocketAddr>,
-    headers: HeaderMap,
-    Path(uuid): Path<String>,
-) -> Result<StatusCode, AppError> {
-    // Fetch lightweight metadata for audit BEFORE deleting (so we can record manifest_id+version)
-    let row = SpaThemeService::get(&state.db, &uuid).await?;
-    let manifest_id = row.manifest_id.clone();
-    let version = row.version.clone();
-    drop(row); // release BLOB memory early
-    SpaThemeService::delete(&state.db, &uuid).await?;
-    let ip = extract_client_ip(
-        &ConnectInfo(addr),
-        &headers,
-        &state.config.server.trusted_proxies,
-    );
-    let _ = AuditService::log(
-        &state.db,
-        &current_user.user_id,
-        "spa_theme.delete",
-        Some(
-            &serde_json::json!({
-                "uuid": uuid,
-                "manifest_id": manifest_id,
-                "version": version,
-            })
-            .to_string(),
-        ),
-        &ip.to_string(),
-    )
-    .await;
-    Ok(StatusCode::NO_CONTENT)
-}
-
-#[utoipa::path(
-    post,
-    path = "/api/settings/spa-themes",
-    tag = "spa-themes",
-    request_body(content_type = "multipart/form-data", description = "Package file in `package` field"),
-    responses(
-        (status = 200, description = "Uploaded", body = UploadResult),
-        (status = 400, description = "Invalid package / manifest"),
-        (status = 403, description = "Forbidden — admin only"),
-        (status = 409, description = "Version already exists or downgrade"),
-        (status = 413, description = "Package too large"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-pub async fn upload(
-    State(state): State<Arc<AppState>>,
-    Extension(current_user): Extension<CurrentUser>,
-    ConnectInfo(addr): ConnectInfo<std::net::SocketAddr>,
-    headers: HeaderMap,
-    SpaThemeUpload(mut mp): SpaThemeUpload,
-) -> Result<Json<ApiResponse<UploadResult>>, AppError> {
-    let mut package_bytes: Option<Vec<u8>> = None;
-    while let Some(field) = mp.next_field().await.map_err(map_field_error)? {
-        if field.name() == Some("package") {
-            package_bytes = Some(field.bytes().await.map_err(map_field_error)?.to_vec());
-            break;
-        }
-    }
-    let bytes = package_bytes.ok_or_else(|| {
-        AppError::from(SpaThemeError::InvalidMultipart(
-            "missing 'package' field".into(),
-        ))
-    })?;
-    let (row, upgrade) = SpaThemeService::upload(&state.db, bytes, &current_user.user_id).await?;
-    let ip = extract_client_ip(
-        &ConnectInfo(addr),
-        &headers,
-        &state.config.server.trusted_proxies,
-    );
-    let _ = AuditService::log(
-        &state.db,
-        &current_user.user_id,
-        "spa_theme.upload",
-        Some(
-            &serde_json::json!({
-                "uuid": row.uuid,
-                "manifest_id": row.manifest_id,
-                "version": row.version,
-                "size_bytes": row.size_bytes,
-            })
-            .to_string(),
-        ),
-        &ip.to_string(),
-    )
-    .await;
-    ok(UploadResult {
-        uuid: row.uuid.clone(),
-        manifest: serde_json::from_str(&row.manifest_json).unwrap_or(serde_json::Value::Null),
-        size_bytes: row.size_bytes,
-        preview_url: if row.preview_data.is_some() {
-            Some(format!("/api/settings/spa-themes/{}/preview", row.uuid))
-        } else {
-            None
-        },
-        is_upgrade_of: upgrade,
-    })
-}
-
-// ---------------------------------------------------------------------------
-// Active-theme DTOs
-// ---------------------------------------------------------------------------
-
-#[derive(Debug, serde::Deserialize, utoipa::ToSchema)]
-pub struct PutActiveBody {
-    pub theme_id: Option<String>,
-}
-
-#[derive(Debug, serde::Serialize, utoipa::ToSchema)]
-pub struct ActiveResp {
-    pub theme_id: Option<String>,
-}
-
-// ---------------------------------------------------------------------------
-// Active-theme handlers
-// ---------------------------------------------------------------------------
-
-#[utoipa::path(
-    get,
-    path = "/api/settings/active-spa-theme",
-    tag = "spa-themes",
-    responses(
-        (status = 200, description = "Currently active theme UUID (null if default)", body = ActiveResp),
-        (status = 403, description = "Forbidden — admin only"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-pub async fn get_active(
-    State(state): State<Arc<AppState>>,
-) -> Result<Json<ApiResponse<ActiveResp>>, AppError> {
-    ok(ActiveResp {
-        theme_id: SpaThemeService::active_uuid(&state.db).await?,
-    })
-}
-
-#[utoipa::path(
-    put,
-    path = "/api/settings/active-spa-theme",
-    tag = "spa-themes",
-    request_body = PutActiveBody,
-    responses(
-        (status = 200, description = "Updated active theme", body = ActiveResp),
-        (status = 403, description = "Forbidden — admin only"),
-        (status = 404, description = "Theme UUID not found"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-pub async fn put_active(
-    State(state): State<Arc<AppState>>,
-    Extension(current_user): Extension<CurrentUser>,
-    ConnectInfo(addr): ConnectInfo<std::net::SocketAddr>,
-    headers: HeaderMap,
-    Json(body): Json<PutActiveBody>,
-) -> Result<Json<ApiResponse<ActiveResp>>, AppError> {
-    let previous = SpaThemeService::active_uuid(&state.db).await?;
-    let new =
-        SpaThemeService::set_active(&state.db, &state.active_spa_theme, body.theme_id.as_deref())
-            .await?;
-    let ip = extract_client_ip(
-        &ConnectInfo(addr),
-        &headers,
-        &state.config.server.trusted_proxies,
-    );
-    let audit = match (&previous, &new) {
-        (_, Some(u)) => Some(("spa_theme.activate", u.clone())),
-        (Some(p), None) => Some(("spa_theme.deactivate", p.clone())),
-        (None, None) => {
-            // No state change: there was no active theme and the request also
-            // asks for none. Skip the audit entry so the log reflects actual
-            // transitions only.
-            tracing::debug!(
-                user_id = %current_user.user_id,
-                "spa_theme.put_active no-op: no previous active theme and request requests none"
-            );
-            None
-        }
-    };
-    if let Some((action, audit_uuid)) = audit {
-        let _ = AuditService::log(
-            &state.db,
-            &current_user.user_id,
-            action,
-            Some(&serde_json::json!({"uuid": audit_uuid}).to_string()),
-            &ip.to_string(),
-        )
-        .await;
-    }
-    ok(ActiveResp { theme_id: new })
-}
-
-#[cfg(test)]
-mod tests {
-    use super::content_disposition_attachment;
-
-    #[test]
-    fn plain_ascii_filename() {
-        let v = content_disposition_attachment("acme-1.0.0.sbtheme");
-        assert_eq!(
-            v,
-            "attachment; filename=\"acme-1.0.0.sbtheme\"; filename*=UTF-8''acme-1.0.0.sbtheme"
-        );
-    }
-
-    #[test]
-    fn semver_build_metadata_plus_is_encoded() {
-        // The `+` in semver build metadata must be percent-encoded — some
-        // clients otherwise interpret raw `+` as a space.
-        let v = content_disposition_attachment("acme-1.0.0+build1.sbtheme");
-        assert!(v.contains("filename*=UTF-8''acme-1.0.0%2Bbuild1.sbtheme"));
-        // ASCII fallback replaces `+` with `_`.
-        assert!(v.contains("filename=\"acme-1.0.0_build1.sbtheme\""));
-    }
-
-    #[test]
-    fn quotes_and_backslashes_are_stripped_from_fallback() {
-        let v = content_disposition_attachment("a\"b\\c.sbtheme");
-        // Fallback must not contain `"` or `\` (header injection / smuggling).
-        let fallback_start = v.find("filename=\"").unwrap() + "filename=\"".len();
-        let fallback_end = v[fallback_start..].find('"').unwrap() + fallback_start;
-        let fallback = &v[fallback_start..fallback_end];
-        assert!(!fallback.contains('"'));
-        assert!(!fallback.contains('\\'));
-    }
-
-    #[test]
-    fn non_ascii_is_percent_encoded() {
-        // UTF-8 bytes for "é" are 0xC3 0xA9 → "%C3%A9".
-        let v = content_disposition_attachment("café.sbtheme");
-        assert!(v.contains("filename*=UTF-8''caf%C3%A9.sbtheme"));
-    }
-}
diff --git a/crates/server/src/router/api/theme.rs b/crates/server/src/router/api/theme.rs
deleted file mode 100644
index 25774914..00000000
--- a/crates/server/src/router/api/theme.rs
+++ /dev/null
@@ -1,593 +0,0 @@
-use std::sync::Arc;
-
-use axum::extract::{Path, State};
-use axum::routing::{delete, get, post, put};
-use axum::{Extension, Json, Router};
-use serde::{Deserialize, Serialize};
-
-use crate::error::{ApiResponse, AppError, ok};
-use crate::middleware::auth::CurrentUser;
-use crate::service::custom_theme::{
-    ActiveThemeResponse, CreateThemeInput, CustomThemeService, Theme, ThemeSummary,
-    UpdateThemeInput,
-};
-use crate::service::theme_ref::{self, ThemeReferences};
-use crate::service::theme_validator::VarMap;
-use crate::state::AppState;
-
-pub fn read_router() -> Router<Arc<AppState>> {
-    Router::new()
-        .route("/settings/themes", get(list_themes))
-        .route("/settings/themes/{id}", get(get_theme))
-        .route("/settings/themes/{id}/export", get(export_theme))
-        .route("/settings/active-theme", get(get_active_theme))
-}
-
-pub fn write_router() -> Router<Arc<AppState>> {
-    Router::new()
-        .route("/settings/themes", post(create_theme))
-        .route("/settings/themes/import", post(import_theme))
-        .route("/settings/themes/{id}", put(update_theme))
-        .route("/settings/themes/{id}", delete(delete_theme))
-        .route("/settings/themes/{id}/references", get(get_references))
-        .route("/settings/themes/{id}/duplicate", post(duplicate_theme))
-        .route("/settings/active-theme", put(put_active_theme))
-}
-
-#[utoipa::path(
-    get,
-    path = "/api/settings/themes",
-    tag = "themes",
-    responses(
-        (status = 200, description = "List custom themes", body = Vec<ThemeSummary>),
-        (status = 401, description = "Unauthenticated"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-async fn list_themes(
-    State(state): State<Arc<AppState>>,
-) -> Result<Json<ApiResponse<Vec<ThemeSummary>>>, AppError> {
-    ok(CustomThemeService::list(&state.db).await?)
-}
-
-#[utoipa::path(
-    get,
-    path = "/api/settings/themes/{id}",
-    tag = "themes",
-    params(("id" = i32, Path, description = "Theme ID")),
-    responses(
-        (status = 200, description = "Custom theme", body = Theme),
-        (status = 401, description = "Unauthenticated"),
-        (status = 404, description = "Theme not found"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-async fn get_theme(
-    State(state): State<Arc<AppState>>,
-    Path(id): Path<i32>,
-) -> Result<Json<ApiResponse<Theme>>, AppError> {
-    ok(CustomThemeService::get(&state.db, id).await?)
-}
-
-#[utoipa::path(
-    get,
-    path = "/api/settings/themes/{id}/export",
-    tag = "themes",
-    params(("id" = i32, Path, description = "Theme ID")),
-    responses(
-        (status = 200, description = "Exportable custom theme payload", body = ExportPayload),
-        (status = 401, description = "Unauthenticated"),
-        (status = 404, description = "Theme not found"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-async fn export_theme(
-    State(state): State<Arc<AppState>>,
-    Path(id): Path<i32>,
-) -> Result<Json<ApiResponse<ExportPayload>>, AppError> {
-    let theme = CustomThemeService::get(&state.db, id).await?;
-    ok(ExportPayload {
-        version: 1,
-        name: theme.name,
-        description: theme.description,
-        based_on: theme.based_on,
-        vars_light: theme.vars_light,
-        vars_dark: theme.vars_dark,
-    })
-}
-
-#[utoipa::path(
-    get,
-    path = "/api/settings/active-theme",
-    tag = "themes",
-    responses(
-        (status = 200, description = "Resolved active admin theme", body = ActiveThemeResponse),
-        (status = 401, description = "Unauthenticated"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-async fn get_active_theme(
-    State(state): State<Arc<AppState>>,
-) -> Result<Json<ApiResponse<ActiveThemeResponse>>, AppError> {
-    ok(CustomThemeService::active_theme(&state.db, state.config.feature.custom_themes).await?)
-}
-
-#[utoipa::path(
-    post,
-    path = "/api/settings/themes",
-    tag = "themes",
-    request_body = CreateThemeInput,
-    responses(
-        (status = 200, description = "Custom theme created", body = Theme),
-        (status = 401, description = "Unauthenticated"),
-        (status = 403, description = "Forbidden (non-admin)"),
-        (status = 422, description = "Validation error or custom themes disabled"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-async fn create_theme(
-    State(state): State<Arc<AppState>>,
-    Extension(current_user): Extension<CurrentUser>,
-    Json(input): Json<CreateThemeInput>,
-) -> Result<Json<ApiResponse<Theme>>, AppError> {
-    ensure_custom_themes_enabled(&state)?;
-    ok(CustomThemeService::create(&state.db, input, &current_user.user_id).await?)
-}
-
-#[utoipa::path(
-    put,
-    path = "/api/settings/themes/{id}",
-    tag = "themes",
-    params(("id" = i32, Path, description = "Theme ID")),
-    request_body = UpdateThemeInput,
-    responses(
-        (status = 200, description = "Custom theme updated", body = Theme),
-        (status = 401, description = "Unauthenticated"),
-        (status = 403, description = "Forbidden (non-admin)"),
-        (status = 404, description = "Theme not found"),
-        (status = 422, description = "Validation error or custom themes disabled"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-async fn update_theme(
-    State(state): State<Arc<AppState>>,
-    Path(id): Path<i32>,
-    Json(input): Json<UpdateThemeInput>,
-) -> Result<Json<ApiResponse<Theme>>, AppError> {
-    ensure_custom_themes_enabled(&state)?;
-    ok(CustomThemeService::update(&state.db, id, input).await?)
-}
-
-#[utoipa::path(
-    delete,
-    path = "/api/settings/themes/{id}",
-    tag = "themes",
-    params(("id" = i32, Path, description = "Theme ID")),
-    responses(
-        (status = 200, description = "Custom theme deleted"),
-        (status = 401, description = "Unauthenticated"),
-        (status = 403, description = "Forbidden (non-admin)"),
-        (status = 404, description = "Theme not found"),
-        (status = 409, description = "Theme is referenced"),
-        (status = 422, description = "Custom themes disabled"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-async fn delete_theme(
-    State(state): State<Arc<AppState>>,
-    Path(id): Path<i32>,
-) -> Result<Json<ApiResponse<&'static str>>, AppError> {
-    ensure_custom_themes_enabled(&state)?;
-    CustomThemeService::delete(&state.db, id).await?;
-    ok("ok")
-}
-
-#[utoipa::path(
-    get,
-    path = "/api/settings/themes/{id}/references",
-    tag = "themes",
-    params(("id" = i32, Path, description = "Theme ID")),
-    responses(
-        (status = 200, description = "Theme references", body = ThemeReferences),
-        (status = 401, description = "Unauthenticated"),
-        (status = 403, description = "Forbidden (non-admin)"),
-        (status = 404, description = "Theme not found"),
-        (status = 422, description = "Invalid theme ID"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-async fn get_references(
-    State(state): State<Arc<AppState>>,
-    Path(id): Path<i32>,
-) -> Result<Json<ApiResponse<ThemeReferences>>, AppError> {
-    if id > 0 {
-        CustomThemeService::get(&state.db, id).await?;
-    }
-
-    ok(theme_ref::list_references(&state.db, id).await?)
-}
-
-#[utoipa::path(
-    post,
-    path = "/api/settings/themes/{id}/duplicate",
-    tag = "themes",
-    params(("id" = i32, Path, description = "Theme ID")),
-    responses(
-        (status = 200, description = "Custom theme duplicated", body = Theme),
-        (status = 401, description = "Unauthenticated"),
-        (status = 403, description = "Forbidden (non-admin)"),
-        (status = 404, description = "Theme not found"),
-        (status = 422, description = "Validation error or custom themes disabled"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-async fn duplicate_theme(
-    State(state): State<Arc<AppState>>,
-    Extension(current_user): Extension<CurrentUser>,
-    Path(id): Path<i32>,
-) -> Result<Json<ApiResponse<Theme>>, AppError> {
-    ensure_custom_themes_enabled(&state)?;
-    ok(CustomThemeService::duplicate(&state.db, id, &current_user.user_id).await?)
-}
-
-#[utoipa::path(
-    post,
-    path = "/api/settings/themes/import",
-    tag = "themes",
-    request_body = ExportPayload,
-    responses(
-        (status = 200, description = "Custom theme imported", body = Theme),
-        (status = 401, description = "Unauthenticated"),
-        (status = 403, description = "Forbidden (non-admin)"),
-        (status = 422, description = "Validation error or custom themes disabled"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-async fn import_theme(
-    State(state): State<Arc<AppState>>,
-    Extension(current_user): Extension<CurrentUser>,
-    Json(input): Json<ExportPayload>,
-) -> Result<Json<ApiResponse<Theme>>, AppError> {
-    ensure_custom_themes_enabled(&state)?;
-    if input.version != 1 {
-        return Err(AppError::Validation(format!(
-            "unsupported theme export version: {}",
-            input.version
-        )));
-    }
-
-    ok(CustomThemeService::create(
-        &state.db,
-        CreateThemeInput {
-            name: input.name,
-            description: input.description,
-            based_on: input.based_on,
-            vars_light: input.vars_light,
-            vars_dark: input.vars_dark,
-        },
-        &current_user.user_id,
-    )
-    .await?)
-}
-
-#[utoipa::path(
-    put,
-    path = "/api/settings/active-theme",
-    tag = "themes",
-    request_body = PutActiveThemeInput,
-    responses(
-        (status = 200, description = "Resolved active admin theme", body = ActiveThemeResponse),
-        (status = 401, description = "Unauthenticated"),
-        (status = 403, description = "Forbidden (non-admin)"),
-        (status = 422, description = "Validation error or custom themes disabled"),
-    ),
-    security(("session_cookie" = []), ("api_key" = []), ("bearer_token" = []))
-)]
-async fn put_active_theme(
-    State(state): State<Arc<AppState>>,
-    Json(input): Json<PutActiveThemeInput>,
-) -> Result<Json<ApiResponse<ActiveThemeResponse>>, AppError> {
-    ok(CustomThemeService::set_active_theme(
-        &state.db,
-        &input.r#ref,
-        state.config.feature.custom_themes,
-    )
-    .await?)
-}
-
-#[derive(Debug, Deserialize, utoipa::ToSchema)]
-pub struct PutActiveThemeInput {
-    pub r#ref: String,
-}
-
-#[derive(Debug, Serialize, Deserialize, utoipa::ToSchema)]
-pub struct ExportPayload {
-    pub version: u32,
-    pub name: String,
-    pub description: Option<String>,
-    pub based_on: Option<String>,
-    pub vars_light: VarMap,
-    pub vars_dark: VarMap,
-}
-
-fn ensure_custom_themes_enabled(state: &AppState) -> Result<(), AppError> {
-    if state.config.feature.custom_themes {
-        Ok(())
-    } else {
-        Err(AppError::Validation(
-            "custom theme feature disabled".to_string(),
-        ))
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use axum::body::{Body, to_bytes};
-    use axum::http::{Request, StatusCode, header};
-    use serde_json::{Value, json};
-    use tower::ServiceExt;
-
-    use crate::config::AppConfig;
-    use crate::router::create_router;
-    use crate::service::auth::{AuthService, LoginParams};
-    use crate::service::theme_validator::REQUIRED_VARS;
-    use crate::state::AppState;
-    use crate::test_utils::setup_test_db;
-
-    fn valid_vars() -> Value {
-        REQUIRED_VARS
-            .iter()
-            .map(|key| ((*key).to_string(), json!("oklch(0.5 0.1 180)")))
-            .collect()
-    }
-
-    fn valid_theme_body(name: &str) -> Value {
-        json!({
-            "name": name,
-            "description": "Router test theme",
-            "based_on": "default",
-            "vars_light": valid_vars(),
-            "vars_dark": valid_vars(),
-        })
-    }
-
-    fn import_body(version: u32, name: &str) -> Value {
-        let mut body = valid_theme_body(name);
-        body.as_object_mut()
-            .expect("theme body must be an object")
-            .insert("version".to_string(), json!(version));
-        body
-    }
-
-    async fn build_app(db: sea_orm::DatabaseConnection, config: AppConfig) -> axum::Router {
-        let state = AppState::new(db, config)
-            .await
-            .expect("app state should initialize");
-        create_router(state)
-    }
-
-    async fn session_cookie(
-        db: &sea_orm::DatabaseConnection,
-        username: &str,
-        role: &str,
-    ) -> String {
-        AuthService::create_user(db, username, "password123", role)
-            .await
-            .expect("user should be created");
-        let (session, _) = AuthService::login(
-            db,
-            LoginParams {
-                username,
-                password: "password123",
-                totp_code: None,
-                ip: "127.0.0.1",
-                user_agent: "theme-router-test",
-                session_ttl: 3600,
-            },
-        )
-        .await
-        .expect("login should create a session");
-
-        format!("session_token={}", session.token)
-    }
-
-    async fn request_json(
-        app: axum::Router,
-        method: axum::http::Method,
-        uri: &str,
-        cookie: Option<&str>,
-        body: Option<Value>,
-    ) -> (StatusCode, Value) {
-        let mut builder = Request::builder().method(method).uri(uri);
-        if let Some(cookie) = cookie {
-            builder = builder.header(header::COOKIE, cookie);
-        }
-
-        let request_body = if let Some(value) = body {
-            builder = builder.header(header::CONTENT_TYPE, "application/json");
-            Body::from(serde_json::to_vec(&value).expect("body should serialize"))
-        } else {
-            Body::empty()
-        };
-        let response = app
-            .oneshot(builder.body(request_body).expect("request should build"))
-            .await
-            .expect("router should respond");
-        let status = response.status();
-        let bytes = to_bytes(response.into_body(), usize::MAX)
-            .await
-            .expect("response body should be readable");
-        let body = if bytes.is_empty() {
-            Value::Null
-        } else {
-            serde_json::from_slice(&bytes)
-                .unwrap_or_else(|_| Value::String(String::from_utf8_lossy(&bytes).into_owned()))
-        };
-
-        (status, body)
-    }
-
-    #[tokio::test]
-    async fn unauthenticated_list_themes_returns_401() {
-        let (db, _tmp) = setup_test_db().await;
-        let app = build_app(db, AppConfig::default()).await;
-
-        let (status, _) = request_json(
-            app,
-            axum::http::Method::GET,
-            "/api/settings/themes",
-            None,
-            None,
-        )
-        .await;
-
-        assert_eq!(status, StatusCode::UNAUTHORIZED);
-    }
-
-    #[tokio::test]
-    async fn member_can_read_themes_but_cannot_create_theme() {
-        let (db, _tmp) = setup_test_db().await;
-        let cookie = session_cookie(&db, "theme_member", "member").await;
-        let app = build_app(db, AppConfig::default()).await;
-
-        let (read_status, read_body) = request_json(
-            app.clone(),
-            axum::http::Method::GET,
-            "/api/settings/themes",
-            Some(&cookie),
-            None,
-        )
-        .await;
-        let (write_status, _) = request_json(
-            app,
-            axum::http::Method::POST,
-            "/api/settings/themes",
-            Some(&cookie),
-            Some(valid_theme_body("Member blocked")),
-        )
-        .await;
-
-        assert_eq!(read_status, StatusCode::OK);
-        assert_eq!(read_body["data"], json!([]));
-        assert_eq!(write_status, StatusCode::FORBIDDEN);
-    }
-
-    #[tokio::test]
-    async fn admin_can_create_theme_through_router() {
-        let (db, _tmp) = setup_test_db().await;
-        let cookie = session_cookie(&db, "theme_admin", "admin").await;
-        let app = build_app(db, AppConfig::default()).await;
-
-        let (status, body) = request_json(
-            app,
-            axum::http::Method::POST,
-            "/api/settings/themes",
-            Some(&cookie),
-            Some(valid_theme_body("Admin theme")),
-        )
-        .await;
-
-        assert_eq!(status, StatusCode::OK);
-        assert_eq!(body["data"]["name"], "Admin theme");
-        assert!(body["data"]["id"].as_i64().expect("theme id should be set") > 0);
-    }
-
-    #[tokio::test]
-    async fn disabled_custom_themes_reject_admin_mutations() {
-        let (db, _tmp) = setup_test_db().await;
-        let cookie = session_cookie(&db, "theme_disabled_admin", "admin").await;
-        let enabled_app = build_app(db.clone(), AppConfig::default()).await;
-        let (_, created) = request_json(
-            enabled_app,
-            axum::http::Method::POST,
-            "/api/settings/themes",
-            Some(&cookie),
-            Some(valid_theme_body("Existing theme")),
-        )
-        .await;
-        let id = created["data"]["id"]
-            .as_i64()
-            .expect("created theme should have id");
-
-        let mut disabled = AppConfig::default();
-        disabled.feature.custom_themes = false;
-        let app = build_app(db, disabled).await;
-
-        for (method, uri, body) in [
-            (
-                axum::http::Method::POST,
-                "/api/settings/themes".to_string(),
-                Some(valid_theme_body("Disabled create")),
-            ),
-            (
-                axum::http::Method::PUT,
-                format!("/api/settings/themes/{id}"),
-                Some(valid_theme_body("Disabled update")),
-            ),
-            (
-                axum::http::Method::DELETE,
-                format!("/api/settings/themes/{id}"),
-                None,
-            ),
-            (
-                axum::http::Method::POST,
-                format!("/api/settings/themes/{id}/duplicate"),
-                None,
-            ),
-            (
-                axum::http::Method::POST,
-                "/api/settings/themes/import".to_string(),
-                Some(import_body(1, "Disabled import")),
-            ),
-        ] {
-            let (status, response_body) =
-                request_json(app.clone(), method, &uri, Some(&cookie), body).await;
-            assert_eq!(status, StatusCode::UNPROCESSABLE_ENTITY, "{uri}");
-            assert_eq!(
-                response_body["error"]["message"],
-                "Validation error: custom theme feature disabled",
-                "{uri}"
-            );
-        }
-    }
-
-    #[tokio::test]
-    async fn import_static_route_is_not_captured_as_theme_id() {
-        let (db, _tmp) = setup_test_db().await;
-        let cookie = session_cookie(&db, "theme_import_admin", "admin").await;
-        let app = build_app(db, AppConfig::default()).await;
-
-        let (status, body) = request_json(
-            app,
-            axum::http::Method::POST,
-            "/api/settings/themes/import",
-            Some(&cookie),
-            Some(import_body(2, "Wrong version")),
-        )
-        .await;
-
-        assert_eq!(status, StatusCode::UNPROCESSABLE_ENTITY);
-        assert_eq!(
-            body["error"]["message"],
-            "Validation error: unsupported theme export version: 2"
-        );
-    }
-
-    #[tokio::test]
-    async fn references_for_missing_theme_returns_404() {
-        let (db, _tmp) = setup_test_db().await;
-        let cookie = session_cookie(&db, "theme_refs_admin", "admin").await;
-        let app = build_app(db, AppConfig::default()).await;
-
-        let (status, _) = request_json(
-            app,
-            axum::http::Method::GET,
-            "/api/settings/themes/404/references",
-            Some(&cookie),
-            None,
-        )
-        .await;
-
-        assert_eq!(status, StatusCode::NOT_FOUND);
-    }
-}
diff --git a/crates/server/src/router/mod.rs b/crates/server/src/router/mod.rs
index 61a54894..1820d55e 100644
--- a/crates/server/src/router/mod.rs
+++ b/crates/server/src/router/mod.rs
@@ -1,6 +1,5 @@
 pub mod api;
 mod static_files;
-mod system;
 pub mod utils;
 pub mod ws;
 
@@ -30,11 +29,8 @@ pub fn create_router(state: Arc<AppState>) -> Router {
         .nest("/api", ws::docker_logs::router())
         // Swagger UI
         .merge(SwaggerUi::new("/swagger-ui").url("/api-docs/openapi.json", ApiDoc::openapi()))
-        // System reserved routes must be mounted before the catch-all fallback so
-        // they are never shadowed by custom theme packages (spec § 6.4).
-        .nest("/__system", system::router())
-        // Embedded frontend: theme-aware serve with cookie precedence (spec § 6.5).
-        .fallback(static_files::theme_handler)
+        // Embedded frontend: serve the rust-embed SPA assets.
+        .fallback(static_files::spa_handler)
         // Security headers
         .layer(SetResponseHeaderLayer::overriding(
             axum::http::header::X_FRAME_OPTIONS,
@@ -44,9 +40,6 @@ pub fn create_router(state: Arc<AppState>) -> Router {
             axum::http::header::X_CONTENT_TYPE_OPTIONS,
             HeaderValue::from_static("nosniff"),
         ))
-        // Referrer-Policy uses `if_not_present` so the theme serve handler can
-        // override it to `same-origin` per spec § 5.5. All other responses fall
-        // back to `strict-origin-when-cross-origin` as the implicit default.
         .layer(SetResponseHeaderLayer::if_not_present(
             axum::http::header::REFERRER_POLICY,
             HeaderValue::from_static("strict-origin-when-cross-origin"),
diff --git a/crates/server/src/router/static_files.rs b/crates/server/src/router/static_files.rs
index 0b975b53..451af43e 100644
--- a/crates/server/src/router/static_files.rs
+++ b/crates/server/src/router/static_files.rs
@@ -1,214 +1,23 @@
-use std::sync::Arc;
-
-use axum::body::{Body, Bytes};
-use axum::extract::{Query, State};
-use axum::http::{HeaderMap, HeaderValue, StatusCode, Uri, header};
+//! Embedded SPA static file serving.
+//!
+//! The frontend is bundled into the server binary via `rust-embed` at compile
+//! time. This handler serves requested paths from the embedded bundle and falls
+//! back to `index.html` for unknown paths so TanStack Router can handle
+//! client-side routing.
+use axum::body::Body;
+use axum::http::{StatusCode, Uri, header};
 use axum::response::{IntoResponse, Response};
-use base64::Engine;
-use base64::engine::general_purpose::URL_SAFE_NO_PAD;
-use rand::RngCore;
-use rand::rngs::OsRng;
 use rust_embed::Embed;
-use serde::Deserialize;
-
-use crate::service::spa_theme::LoadedTheme;
-use crate::state::AppState;
 
 #[derive(Embed)]
 #[folder = "../../apps/web/dist"]
 struct Assets;
 
-/// Recovery cookie — pinned by `?theme=default`, drops the entire origin
-/// onto the bundled SPA for one hour. Shared with `router::system`.
-pub(super) const FORCE_DEFAULT_COOKIE: &str = "sb_force_default";
-/// Preview cookie — pinned by `?theme=preview:<uuid>` (admin-only), serves
-/// the previewed theme to the same browser for 15 minutes. Shared with
-/// `router::system`.
-pub(super) const PREVIEW_COOKIE: &str = "sb_preview_theme";
-/// Lifetime of the recovery cookie in seconds (1 hour). Shared with
-/// `router::system` for consistency between handler and clear endpoint.
-pub(super) const RECOVERY_MAX_AGE_SECS: u64 = 3600;
-/// Lifetime of the preview cookie in seconds — kept in sync with the
-/// `Max-Age` value we set on `sb_preview_theme`. Also drives the banner
-/// countdown timer's expiry epoch.
-pub(super) const PREVIEW_MAX_AGE_SECS: u64 = 900;
-
-#[derive(Debug, Deserialize)]
-pub struct ThemeQuery {
-    theme: Option<String>,
-}
-
-/// Decision the handler made about which source to serve.
-enum Source {
-    Default,
-    Active(LoadedTheme),
-    Preview { uuid: String, theme: Option<LoadedTheme> },
-}
-
-pub async fn theme_handler(
-    State(state): State<Arc<AppState>>,
-    Query(q): Query<ThemeQuery>,
-    headers: HeaderMap,
-    uri: Uri,
-) -> Response {
+pub async fn spa_handler(uri: Uri) -> Response {
     let path = uri.path().trim_start_matches('/');
-
-    // Parse cookies inline (no extra deps).
-    let cookie_str = headers
-        .get(header::COOKIE)
-        .and_then(|v| v.to_str().ok())
-        .unwrap_or("");
-    let cookies: Vec<(&str, &str)> = cookie_str
-        .split(';')
-        .filter_map(|c| {
-            let mut it = c.trim().splitn(2, '=');
-            Some((it.next()?, it.next().unwrap_or("")))
-        })
-        .collect();
-    let has_force_default = cookies.iter().any(|(k, _)| *k == FORCE_DEFAULT_COOKIE);
-    let preview_cookie = cookies
-        .iter()
-        .find(|(k, _)| *k == PREVIEW_COOKIE)
-        .map(|(_, v)| *v);
-
-    // Admin status is only consulted on preview paths (query or cookie). Skipping
-    // the auth lookup for normal SPA / asset requests avoids up to three DB
-    // round-trips per static request, a real win for asset-heavy pages.
-    let query_is_preview = q
-        .theme
-        .as_deref()
-        .map(|t| t.starts_with("preview:"))
-        .unwrap_or(false);
-    let needs_admin_check = query_is_preview || preview_cookie.is_some();
-    let is_admin = if needs_admin_check {
-        crate::middleware::auth::resolve_optional_user(&headers, &state)
-            .await
-            .as_ref()
-            .map(|u| u.role == "admin")
-            .unwrap_or(false)
-    } else {
-        false
-    };
-
-    // Cookie(s) to set, stored as individual header value strings.
-    let mut set_cookies: Vec<String> = Vec::new();
-
-    // Load the active theme once to avoid multiple arc_swap loads.
-    // Cloning is cheap: LoadedTheme contains Arc'd Bytes values.
-    let active: Option<LoadedTheme> = {
-        let guard = state.active_spa_theme.load();
-        (**guard).clone()
-    };
-
-    // Precedence per spec § 6.5
-    let source: Source = match q.theme.as_deref() {
-        // 1. ?theme=default → serve default SPA, set recovery cookie
-        Some("default") => {
-            set_cookies.push(format!(
-                "{FORCE_DEFAULT_COOKIE}=1; Path=/; Max-Age={RECOVERY_MAX_AGE_SECS}; SameSite=Strict"
-            ));
-            Source::Default
-        }
-
-        // 2. ?theme=preview:<uuid> AND admin → preview theme, set preview cookie
-        Some(t) if t.starts_with("preview:") && is_admin => {
-            let uuid = t.trim_start_matches("preview:").to_string();
-            set_cookies.push(format!(
-                "{PREVIEW_COOKIE}={uuid}; Path=/; Max-Age={PREVIEW_MAX_AGE_SECS}; SameSite=Strict"
-            ));
-            Source::Preview { uuid, theme: None }
-        }
-
-        // 3. ?theme=active → clear recovery+preview cookies, serve active (or default)
-        Some("active") => {
-            set_cookies.push(format!(
-                "{FORCE_DEFAULT_COOKIE}=; Path=/; Max-Age=0; SameSite=Strict"
-            ));
-            set_cookies.push(format!(
-                "{PREVIEW_COOKIE}=; Path=/; Max-Age=0; SameSite=Strict"
-            ));
-            if let Some(loaded) = active {
-                Source::Active(loaded)
-            } else {
-                Source::Default
-            }
-        }
-
-        // 4–7. No query param: cookie / active / default fallthrough
-        _ => {
-            if has_force_default {
-                // 4. Recovery cookie present → serve default
-                Source::Default
-            } else if let Some(uuid) = preview_cookie.filter(|_| is_admin) {
-                // 5. Preview cookie present AND admin → preview that theme
-                Source::Preview {
-                    uuid: uuid.to_string(),
-                    theme: None,
-                }
-            } else if let Some(loaded) = active {
-                // 6. Active theme set → serve it
-                Source::Active(loaded)
-            } else {
-                // 7. Nothing else → default SPA
-                Source::Default
-            }
-        }
-    };
-
-    // For Preview sources, load the theme on demand (may differ from active).
-    let source = match source {
-        Source::Preview { uuid, .. } => {
-            let loaded = load_preview_on_demand(&state, &uuid).await;
-            Source::Preview { uuid, theme: loaded }
-        }
-        other => other,
-    };
-
-    let resp = match &source {
-        Source::Default => serve_default(path),
-        Source::Active(theme) => serve_theme(path, theme, false),
-        Source::Preview { theme: Some(theme), .. } => serve_theme(path, theme, true),
-        // Preview requested but theme not found — fall back to default.
-        Source::Preview { theme: None, .. } => serve_default(path),
-    };
-
-    // Append Set-Cookie headers (each as a separate header value per RFC 6265 §3).
-    if set_cookies.is_empty() {
-        resp
-    } else {
-        let mut r = resp;
-        for cookie in set_cookies {
-            match HeaderValue::from_str(&cookie) {
-                Ok(v) => {
-                    r.headers_mut().append(header::SET_COOKIE, v);
-                }
-                Err(e) => {
-                    tracing::warn!(
-                        error = %e,
-                        cookie = %cookie,
-                        "failed to construct Set-Cookie header; dropping cookie"
-                    );
-                }
-            }
-        }
-        r
-    }
-}
-
-/// Load a theme from the DB on demand (used for preview of a non-active theme).
-async fn load_preview_on_demand(state: &Arc<AppState>, uuid: &str) -> Option<LoadedTheme> {
-    let row = crate::service::spa_theme::SpaThemeService::get(&state.db, uuid)
-        .await
-        .ok()?;
-    crate::service::spa_theme::SpaThemeService::load_row(&row).ok()
-}
-
-/// Serve a file from the embedded default SPA (rust-embed).
-fn serve_default(path: &str) -> Response {
     if let Some(file) = Assets::get(path) {
         return embedded_file_response(path, &file);
     }
-    // SPA history routing fallback
     match Assets::get("index.html") {
         Some(file) => embedded_file_response("index.html", &file),
         None => (StatusCode::NOT_FOUND, "Frontend not embedded").into_response(),
@@ -227,232 +36,3 @@ fn embedded_file_response(path: &str, file: &rust_embed::EmbeddedFile) -> Respon
         .body(Body::from(file.data.clone()))
         .unwrap_or_else(|_| StatusCode::INTERNAL_SERVER_ERROR.into_response())
 }
-
-/// Generate a fresh CSP nonce (16 random bytes, URL-safe base64-encoded).
-fn fresh_nonce() -> String {
-    let mut bytes = [0u8; 16];
-    OsRng.fill_bytes(&mut bytes);
-    URL_SAFE_NO_PAD.encode(bytes)
-}
-
-/// Build the CSP header value. When `nonce` is `Some`, adds `'nonce-...'` to
-/// `script-src` alongside `'unsafe-inline'` so the injected preview banner
-/// script is covered by an explicit allowance in addition to the blanket
-/// inline rule (spec § 6.6).
-fn csp_header(nonce: Option<&str>) -> String {
-    let script_src = match nonce {
-        Some(n) => format!("script-src 'self' 'unsafe-inline' 'unsafe-eval' 'nonce-{n}'"),
-        None => "script-src 'self' 'unsafe-inline' 'unsafe-eval'".to_string(),
-    };
-    format!(
-        "default-src 'self'; \
-         {script_src}; \
-         style-src 'self' 'unsafe-inline'; \
-         img-src 'self' data: blob:; \
-         font-src 'self' data:; \
-         connect-src 'self'; \
-         frame-ancestors 'none'; \
-         base-uri 'self'; \
-         form-action 'self'"
-    )
-}
-
-/// Serve a file from a custom theme, with CSP headers and optional preview banner.
-fn serve_theme(path: &str, theme: &LoadedTheme, inject_banner: bool) -> Response {
-    let p = if path.is_empty() { theme.entry.as_str() } else { path };
-    let (served_path, bytes) = if let Some(b) = theme.get(p) {
-        (p.to_string(), b)
-    } else if let Some(b) = theme.entry_html() {
-        // SPA history routing fallback
-        (theme.entry.clone(), b)
-    } else {
-        return (StatusCode::NOT_FOUND, "not found").into_response();
-    };
-
-    let mime = mime_guess::from_path(&served_path).first_or_octet_stream();
-    let is_html = mime.essence_str() == "text/html";
-
-    // Banner is only injected for HTML responses in preview mode. The nonce is
-    // produced fresh per response and threaded into both the CSP header and the
-    // injected `<script>` tag.
-    let (body_bytes, nonce) = if is_html && inject_banner {
-        let nonce = fresh_nonce();
-        let expires_at = std::time::SystemTime::now()
-            .duration_since(std::time::UNIX_EPOCH)
-            .map(|d| d.as_secs())
-            .unwrap_or(0)
-            + PREVIEW_MAX_AGE_SECS;
-        let injected = inject_preview_banner(&bytes, &nonce, expires_at);
-        (injected, Some(nonce))
-    } else {
-        (bytes, None)
-    };
-
-    let mut builder = Response::builder()
-        .header(header::CONTENT_TYPE, mime.as_ref())
-        .header(header::CONTENT_SECURITY_POLICY, csp_header(nonce.as_deref()))
-        // Spec § 5.5 — theme responses use `same-origin` (the global tower-http
-        // layer is configured with `if_not_present`, so this value wins).
-        .header(header::REFERRER_POLICY, "same-origin");
-    if served_path.starts_with("assets/") && !is_html {
-        builder = builder.header(header::CACHE_CONTROL, "public, max-age=31536000, immutable");
-    } else {
-        builder = builder.header(header::CACHE_CONTROL, "no-cache");
-    }
-    builder
-        .body(Body::from(body_bytes))
-        .unwrap_or_else(|_| StatusCode::INTERNAL_SERVER_ERROR.into_response())
-}
-
-/// Inject a preview-mode banner just before `</body>` in an HTML response.
-///
-/// The banner shows a countdown timer (`MM:SS`) driven by the `data-expires`
-/// attribute on the container div; the inline script ticks once per second
-/// and swaps to "Preview expired" on hit zero. Spec § 6.6.
-///
-/// The `<script>` tag carries the `nonce` attribute so the CSP `'nonce-...'`
-/// rule covers it explicitly, in addition to `'unsafe-inline'`.
-fn inject_preview_banner(html: &Bytes, nonce: &str, expires_at: u64) -> Bytes {
-    // Pre-built CSS / structure pieces. The runtime parts (expires epoch and
-    // nonce) are formatted in below.
-    const STYLE: &str = "position:fixed;top:0;left:0;right:0;z-index:2147483647;\
-        background:#fde68a;color:#111;padding:8px 12px;font:14px/1.4 sans-serif;\
-        text-align:center;box-shadow:0 1px 4px rgba(0,0,0,.2)";
-    const BTN_STYLE: &str = "margin-left:8px;padding:4px 10px;border:1px solid #333;\
-        background:#fff;cursor:pointer";
-    // Inline JS — keeps the banner under 1 KB total (spec § 6.6). Uses
-    // `var` / function expressions (no ES6) for broad compatibility.
-    const SCRIPT_BODY: &str = "(function(){\
-        var d=document.getElementById('__sb_preview');\
-        var t=document.getElementById('__sb_timer');\
-        var b=document.getElementById('__sb_exit');\
-        if(!d||!t||!b)return;\
-        var exp=parseInt(d.getAttribute('data-expires'),10)||0;\
-        function fmt(s){var m=Math.floor(s/60);var ss=s%60;\
-            return m+':'+(ss<10?'0'+ss:ss);}\
-        function tick(){\
-            var now=Math.floor(Date.now()/1000);\
-            var rem=exp-now;\
-            if(rem<=0){t.textContent='expired';b.disabled=true;clearInterval(iv);return;}\
-            t.textContent='expires in '+fmt(rem);\
-        }\
-        tick();var iv=setInterval(tick,1000);\
-        b.onclick=function(){\
-            fetch('/__system/clear-preview',{method:'POST',credentials:'include'})\
-                .then(function(){location.reload()});\
-        };\
-    })();";
-
-    let banner = format!(
-        "<div id=\"__sb_preview\" data-expires=\"{expires_at}\" style=\"{STYLE}\">\
-            Preview mode &middot; <span id=\"__sb_timer\">expires in --:--</span> &middot; \
-            <button id=\"__sb_exit\" style=\"{BTN_STYLE}\">Exit preview</button>\
-        </div>\
-        <script nonce=\"{nonce}\">{SCRIPT_BODY}</script>"
-    );
-
-    let s = std::str::from_utf8(html).unwrap_or("");
-    let lower = s.to_ascii_lowercase();
-    let injected = match lower.rfind("</body>") {
-        Some(i) => format!("{}{}{}", &s[..i], banner, &s[i..]),
-        None => format!("{s}{banner}"),
-    };
-    Bytes::from(injected)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn inject_banner_before_body_close() {
-        let html = Bytes::from("<html><body><h1>Hi</h1></body></html>");
-        let out = inject_preview_banner(&html, "abc123", 1_700_000_900);
-        let s = std::str::from_utf8(&out).unwrap();
-        assert!(s.contains("__sb_preview"));
-        assert!(s.contains("__sb_exit"));
-        // Banner comes before </body>
-        let banner_pos = s.find("__sb_preview").unwrap();
-        let body_close_pos = s.find("</body>").unwrap();
-        assert!(banner_pos < body_close_pos);
-    }
-
-    #[test]
-    fn inject_banner_no_body_tag_appends_at_end() {
-        let html = Bytes::from("<html><p>No body tag</p></html>");
-        let out = inject_preview_banner(&html, "xyz", 0);
-        let s = std::str::from_utf8(&out).unwrap();
-        assert!(s.contains("__sb_preview"));
-        // Appended after the original content
-        assert!(s.starts_with("<html><p>No body tag</p></html>"));
-    }
-
-    #[test]
-    fn inject_banner_uses_last_body_close() {
-        // Malformed HTML with two </body> tags — inject before the last one.
-        let html = Bytes::from("<body>A</body><body>B</body>");
-        let out = inject_preview_banner(&html, "n", 0);
-        let s = std::str::from_utf8(&out).unwrap();
-        // rfind picks the last </body>
-        assert!(s.ends_with("</body>"));
-        let last_body = s.rfind("</body>").unwrap();
-        let banner = s.rfind("__sb_preview").unwrap();
-        assert!(banner < last_body);
-    }
-
-    #[test]
-    fn inject_banner_includes_expiry_and_nonce() {
-        let html = Bytes::from("<body></body>");
-        let out = inject_preview_banner(&html, "NONCE-XYZ", 1_700_000_999);
-        let s = std::str::from_utf8(&out).unwrap();
-        assert!(s.contains(r#"data-expires="1700000999""#));
-        assert!(s.contains(r#"<script nonce="NONCE-XYZ">"#));
-        assert!(s.contains("__sb_timer"));
-        // Countdown logic markers
-        assert!(s.contains("setInterval"));
-        assert!(s.contains("Date.now"));
-    }
-
-    #[test]
-    fn inject_banner_on_invalid_utf8_returns_banner_only() {
-        // A theme that ships non-UTF-8 HTML is malformed, but the function
-        // must not panic. The current contract: drop the original bytes
-        // and serve a banner-only body. This test pins that behavior so
-        // any future change is intentional.
-        let bad = Bytes::from(vec![0xff, 0xfe, 0xfd, b'<', b'p', b'>']);
-        let out = inject_preview_banner(&bad, "n", 0);
-        let s = std::str::from_utf8(&out).expect("banner output must be valid UTF-8");
-        assert!(s.contains("__sb_preview"));
-        assert!(s.contains("__sb_exit"));
-        // Original (invalid) bytes are not preserved.
-        assert!(!s.starts_with("\u{fffd}"));
-    }
-
-    #[test]
-    fn csp_header_includes_nonce_when_provided() {
-        let csp = csp_header(Some("ABC123"));
-        assert!(csp.contains("'nonce-ABC123'"));
-        assert!(csp.contains("'unsafe-inline'"));
-        assert!(csp.contains("'unsafe-eval'"));
-    }
-
-    #[test]
-    fn csp_header_omits_nonce_when_none() {
-        let csp = csp_header(None);
-        assert!(!csp.contains("nonce-"));
-        assert!(csp.contains("script-src 'self' 'unsafe-inline' 'unsafe-eval'"));
-    }
-
-    #[test]
-    fn fresh_nonce_is_unique_and_url_safe() {
-        let a = fresh_nonce();
-        let b = fresh_nonce();
-        assert_ne!(a, b);
-        // URL-safe base64 alphabet only
-        for c in a.chars() {
-            assert!(c.is_ascii_alphanumeric() || c == '-' || c == '_');
-        }
-        // 16 bytes → ceil(16/3 * 4) = 22 chars (no padding)
-        assert_eq!(a.len(), 22);
-    }
-}
diff --git a/crates/server/src/router/system.rs b/crates/server/src/router/system.rs
deleted file mode 100644
index 194f7685..00000000
--- a/crates/server/src/router/system.rs
+++ /dev/null
@@ -1,61 +0,0 @@
-/// `/__system/*` reserved routes (spec § 6.4).
-///
-/// These endpoints are always served by the default SPA routing layer and are
-/// never shadowed by a custom theme package. They clear browser cookies used by
-/// the theme-precedence logic (spec § 6.5).
-use std::sync::Arc;
-
-use axum::http::{HeaderValue, StatusCode, header};
-use axum::response::{IntoResponse, Response};
-use axum::routing::post;
-
-use crate::router::static_files::{FORCE_DEFAULT_COOKIE, PREVIEW_COOKIE};
-use crate::state::AppState;
-
-pub fn router() -> axum::Router<Arc<AppState>> {
-    axum::Router::new()
-        .route("/clear-recovery", post(clear_recovery))
-        .route("/clear-preview", post(clear_preview))
-}
-
-/// Build a cookie-clear `Set-Cookie` header value for the given cookie name.
-///
-/// Cookie names in this module are fixed ASCII identifiers, so `from_str`
-/// cannot fail in practice. The defensive log + fallback keeps a hypothetical
-/// future regression observable instead of silently returning a header value
-/// the browser can't parse.
-fn clear_cookie_header(name: &'static str) -> HeaderValue {
-    let value = format!("{name}=; Path=/; Max-Age=0; SameSite=Strict");
-    HeaderValue::from_str(&value).unwrap_or_else(|e| {
-        tracing::warn!(
-            error = %e,
-            cookie = %name,
-            "failed to construct clear Set-Cookie header; sending empty value"
-        );
-        HeaderValue::from_static("")
-    })
-}
-
-/// Clear the `sb_force_default` recovery cookie.
-///
-/// Called by the "Exit recovery" button in the default SPA when an admin is
-/// done with the `?theme=default` recovery mode and wants to return to the
-/// active custom theme.
-async fn clear_recovery() -> Response {
-    let mut r = StatusCode::NO_CONTENT.into_response();
-    r.headers_mut()
-        .append(header::SET_COOKIE, clear_cookie_header(FORCE_DEFAULT_COOKIE));
-    r
-}
-
-/// Clear the `sb_preview_theme` preview cookie.
-///
-/// Called by the "Exit preview" button injected into the preview theme HTML.
-/// After clearing, the browser reloads and sees the default SPA (or active theme
-/// if no recovery cookie is present).
-async fn clear_preview() -> Response {
-    let mut r = StatusCode::NO_CONTENT.into_response();
-    r.headers_mut()
-        .append(header::SET_COOKIE, clear_cookie_header(PREVIEW_COOKIE));
-    r
-}
diff --git a/crates/server/src/service/custom_theme.rs b/crates/server/src/service/custom_theme.rs
deleted file mode 100644
index bdcb82ee..00000000
--- a/crates/server/src/service/custom_theme.rs
+++ /dev/null
@@ -1,669 +0,0 @@
-use chrono::{DateTime, Utc};
-use sea_orm::{
-    ActiveModelTrait, ConnectionTrait, DatabaseConnection, DbErr, EntityTrait, QueryOrder, Set,
-    TransactionTrait,
-};
-use serde::{Deserialize, Serialize};
-use tracing::warn;
-
-use crate::entity::{config, custom_theme};
-use crate::error::AppError;
-use crate::service::config::ConfigService;
-use crate::service::theme_ref::{self, ThemeRef};
-use crate::service::theme_validator::{self, VarMap};
-
-const ACTIVE_THEME_KEY: &str = "active_admin_theme";
-const DEFAULT_REF: &str = "preset:default";
-const MAX_THEME_NAME_LEN: usize = 120;
-
-#[derive(Debug, Serialize, utoipa::ToSchema)]
-pub struct ThemeSummary {
-    pub id: i32,
-    pub name: String,
-    pub based_on: Option<String>,
-    pub updated_at: DateTime<Utc>,
-}
-
-#[derive(Debug, Serialize, utoipa::ToSchema)]
-pub struct Theme {
-    pub id: i32,
-    pub name: String,
-    pub description: Option<String>,
-    pub based_on: Option<String>,
-    pub vars_light: VarMap,
-    pub vars_dark: VarMap,
-    pub created_at: DateTime<Utc>,
-    pub updated_at: DateTime<Utc>,
-}
-
-#[derive(Debug, Deserialize, utoipa::ToSchema)]
-pub struct CreateThemeInput {
-    pub name: String,
-    pub description: Option<String>,
-    pub based_on: Option<String>,
-    pub vars_light: VarMap,
-    pub vars_dark: VarMap,
-}
-
-#[derive(Debug, Deserialize, utoipa::ToSchema)]
-pub struct UpdateThemeInput {
-    pub name: String,
-    pub description: Option<String>,
-    pub based_on: Option<String>,
-    pub vars_light: VarMap,
-    pub vars_dark: VarMap,
-}
-
-#[derive(Debug, Serialize, utoipa::ToSchema)]
-#[serde(tag = "kind", rename_all = "snake_case")]
-pub enum ThemeResolved {
-    Preset {
-        id: String,
-    },
-    Custom {
-        id: i32,
-        name: String,
-        vars_light: VarMap,
-        vars_dark: VarMap,
-        updated_at: DateTime<Utc>,
-    },
-}
-
-#[derive(Debug, Serialize, utoipa::ToSchema)]
-pub struct ActiveThemeResponse {
-    pub r#ref: String,
-    pub theme: ThemeResolved,
-}
-
-pub struct CustomThemeService;
-
-impl CustomThemeService {
-    pub async fn list(db: &DatabaseConnection) -> Result<Vec<ThemeSummary>, AppError> {
-        let themes = custom_theme::Entity::find()
-            .order_by_desc(custom_theme::Column::UpdatedAt)
-            .all(db)
-            .await?;
-
-        Ok(themes
-            .into_iter()
-            .map(|m| ThemeSummary {
-                id: m.id,
-                name: m.name,
-                based_on: m.based_on,
-                updated_at: m.updated_at,
-            })
-            .collect())
-    }
-
-    pub async fn get(db: &DatabaseConnection, id: i32) -> Result<Theme, AppError> {
-        let model = custom_theme::Entity::find_by_id(id)
-            .one(db)
-            .await?
-            .ok_or_else(|| AppError::NotFound(format!("theme {id}")))?;
-
-        model_to_theme(&model)
-    }
-
-    pub async fn create(
-        db: &DatabaseConnection,
-        input: CreateThemeInput,
-        user_id: &str,
-    ) -> Result<Theme, AppError> {
-        let name = normalize_theme_name(input.name)?;
-        let based_on = normalize_based_on(input.based_on)?;
-        theme_validator::validate_var_map(&input.vars_light)?;
-        theme_validator::validate_var_map(&input.vars_dark)?;
-
-        let vars_light = encode_vars(&input.vars_light)?;
-        let vars_dark = encode_vars(&input.vars_dark)?;
-        let now = Utc::now();
-        let model = custom_theme::ActiveModel {
-            id: sea_orm::NotSet,
-            name: Set(name),
-            description: Set(input.description),
-            based_on: Set(based_on),
-            vars_light: Set(vars_light),
-            vars_dark: Set(vars_dark),
-            created_by: Set(user_id.to_string()),
-            created_at: Set(now),
-            updated_at: Set(now),
-        }
-        .insert(db)
-        .await?;
-
-        model_to_theme(&model)
-    }
-
-    pub async fn update(
-        db: &DatabaseConnection,
-        id: i32,
-        input: UpdateThemeInput,
-    ) -> Result<Theme, AppError> {
-        let name = normalize_theme_name(input.name)?;
-        let based_on = normalize_based_on(input.based_on)?;
-        theme_validator::validate_var_map(&input.vars_light)?;
-        theme_validator::validate_var_map(&input.vars_dark)?;
-
-        let model = custom_theme::Entity::find_by_id(id)
-            .one(db)
-            .await?
-            .ok_or_else(|| AppError::NotFound(format!("theme {id}")))?;
-
-        let mut active: custom_theme::ActiveModel = model.into();
-        active.name = Set(name);
-        active.description = Set(input.description);
-        active.based_on = Set(based_on);
-        active.vars_light = Set(encode_vars(&input.vars_light)?);
-        active.vars_dark = Set(encode_vars(&input.vars_dark)?);
-        active.updated_at = Set(Utc::now());
-
-        let updated = active.update(db).await?;
-        model_to_theme(&updated)
-    }
-
-    pub async fn duplicate(
-        db: &DatabaseConnection,
-        id: i32,
-        user_id: &str,
-    ) -> Result<Theme, AppError> {
-        let source = Self::get(db, id).await?;
-        Self::create(
-            db,
-            CreateThemeInput {
-                name: duplicate_theme_name(&source.name),
-                description: source.description,
-                based_on: source.based_on,
-                vars_light: source.vars_light,
-                vars_dark: source.vars_dark,
-            },
-            user_id,
-        )
-        .await
-    }
-
-    pub async fn delete(db: &DatabaseConnection, id: i32) -> Result<(), AppError> {
-        let txn = db.begin().await?;
-        let references = list_references_in_connection(&txn, id).await?;
-        if references.admin {
-            return Err(AppError::Conflict(
-                "Theme is in use as the active admin theme; unbind it first.".into(),
-            ));
-        }
-
-        let result = custom_theme::Entity::delete_by_id(id)
-            .exec(&txn)
-            .await
-            .map_err(map_theme_ref_integrity_error)?;
-        if result.rows_affected == 0 {
-            return Err(AppError::NotFound(format!("theme {id}")));
-        }
-
-        txn.commit().await?;
-        Ok(())
-    }
-
-    pub async fn active_theme(
-        db: &DatabaseConnection,
-        feature_enabled: bool,
-    ) -> Result<ActiveThemeResponse, AppError> {
-        let stored = ConfigService::get(db, ACTIVE_THEME_KEY).await?;
-        let parsed = stored
-            .as_deref()
-            .and_then(|value| ThemeRef::parse(value).ok())
-            .unwrap_or_else(default_theme_ref);
-        let theme_ref = if feature_enabled {
-            parsed
-        } else {
-            match parsed {
-                ThemeRef::Preset(_) => parsed,
-                ThemeRef::Custom(_) => default_theme_ref(),
-            }
-        };
-
-        match Self::resolve(db, theme_ref.clone()).await {
-            Ok(response) => Ok(response),
-            Err(AppError::NotFound(message)) if matches!(theme_ref, ThemeRef::Custom(_)) => {
-                warn!(
-                    "Stored active custom theme ref is dangling, falling back to default: {message}"
-                );
-                Self::resolve(db, default_theme_ref()).await
-            }
-            Err(err) => Err(err),
-        }
-    }
-
-    pub async fn set_active_theme(
-        db: &DatabaseConnection,
-        urn: &str,
-        feature_enabled: bool,
-    ) -> Result<ActiveThemeResponse, AppError> {
-        let parsed = ThemeRef::parse(urn)?;
-        if !feature_enabled && matches!(parsed, ThemeRef::Custom(_)) {
-            return Err(AppError::Validation(
-                "custom theme feature disabled".to_string(),
-            ));
-        }
-
-        theme_ref::validate_theme_ref(db, &parsed).await?;
-        let canonical = parsed.to_urn();
-        set_config_value(db, ACTIVE_THEME_KEY, &canonical).await?;
-
-        Self::resolve(db, parsed).await
-    }
-
-    pub async fn resolve(
-        db: &DatabaseConnection,
-        r: ThemeRef,
-    ) -> Result<ActiveThemeResponse, AppError> {
-        match r {
-            ThemeRef::Preset(id) => Ok(ActiveThemeResponse {
-                r#ref: format!("preset:{id}"),
-                theme: ThemeResolved::Preset { id },
-            }),
-            ThemeRef::Custom(id) => {
-                let theme = Self::get(db, id).await?;
-                Ok(ActiveThemeResponse {
-                    r#ref: format!("custom:{id}"),
-                    theme: ThemeResolved::Custom {
-                        id: theme.id,
-                        name: theme.name,
-                        vars_light: theme.vars_light,
-                        vars_dark: theme.vars_dark,
-                        updated_at: theme.updated_at,
-                    },
-                })
-            }
-        }
-    }
-}
-
-fn model_to_theme(m: &custom_theme::Model) -> Result<Theme, AppError> {
-    Ok(Theme {
-        id: m.id,
-        name: m.name.clone(),
-        description: m.description.clone(),
-        based_on: m.based_on.clone(),
-        vars_light: decode_vars(&m.vars_light)?,
-        vars_dark: decode_vars(&m.vars_dark)?,
-        created_at: m.created_at,
-        updated_at: m.updated_at,
-    })
-}
-
-fn encode_vars(vars: &VarMap) -> Result<String, AppError> {
-    serde_json::to_string(vars)
-        .map_err(|e| AppError::Internal(format!("theme JSON encode error: {e}")))
-}
-
-fn decode_vars(raw: &str) -> Result<VarMap, AppError> {
-    serde_json::from_str(raw)
-        .map_err(|e| AppError::Internal(format!("theme JSON decode error: {e}")))
-}
-
-async fn set_config_value<C>(db: &C, key: &str, value: &str) -> Result<(), AppError>
-where
-    C: ConnectionTrait,
-{
-    let existing = config::Entity::find_by_id(key)
-        .one(db)
-        .await
-        .map_err(map_theme_ref_integrity_error)?;
-
-    match existing {
-        Some(model) => {
-            let mut active: config::ActiveModel = model.into();
-            active.value = Set(value.to_string());
-            active
-                .update(db)
-                .await
-                .map_err(map_theme_ref_integrity_error)?;
-        }
-        None => {
-            let new_config = config::ActiveModel {
-                key: Set(key.to_string()),
-                value: Set(value.to_string()),
-            };
-            new_config
-                .insert(db)
-                .await
-                .map_err(map_theme_ref_integrity_error)?;
-        }
-    }
-
-    Ok(())
-}
-
-fn map_theme_ref_integrity_error(err: DbErr) -> AppError {
-    let message = err.to_string();
-    if message.contains("custom_theme_ref_in_use") {
-        AppError::Conflict("Theme is in use as the active admin theme; unbind it first.".into())
-    } else if message.contains("custom_theme_ref_missing") {
-        AppError::Validation("custom theme reference does not exist".into())
-    } else {
-        AppError::from(err)
-    }
-}
-
-fn normalize_theme_name(name: String) -> Result<String, AppError> {
-    let name = name.trim().to_string();
-    if name.is_empty() {
-        return Err(AppError::Validation("theme name cannot be empty".into()));
-    }
-    if name.chars().count() > MAX_THEME_NAME_LEN {
-        return Err(AppError::Validation(format!(
-            "theme name cannot exceed {MAX_THEME_NAME_LEN} characters"
-        )));
-    }
-
-    Ok(name)
-}
-
-fn normalize_based_on(based_on: Option<String>) -> Result<Option<String>, AppError> {
-    let Some(id) = based_on
-        .map(|id| id.trim().to_string())
-        .filter(|id| !id.is_empty())
-    else {
-        return Ok(None);
-    };
-
-    if theme_ref::is_preset_id(&id) {
-        Ok(Some(id))
-    } else {
-        Err(AppError::Validation(format!("unknown preset: {id}")))
-    }
-}
-
-fn duplicate_theme_name(name: &str) -> String {
-    const COPY_SUFFIX: &str = " (copy)";
-    let max_base_len = MAX_THEME_NAME_LEN.saturating_sub(COPY_SUFFIX.chars().count());
-    let base = name.chars().take(max_base_len).collect::<String>();
-    format!("{base}{COPY_SUFFIX}")
-}
-
-async fn list_references_in_connection<C>(
-    db: &C,
-    custom_id: i32,
-) -> Result<theme_ref::ThemeReferences, AppError>
-where
-    C: ConnectionTrait,
-{
-    if custom_id <= 0 {
-        return Err(AppError::Validation(format!(
-            "invalid custom id: {custom_id}"
-        )));
-    }
-
-    let urn = ThemeRef::Custom(custom_id).to_urn();
-    let active_admin_theme = config::Entity::find_by_id(ACTIVE_THEME_KEY)
-        .one(db)
-        .await?
-        .map(|m| m.value);
-
-    Ok(theme_ref::ThemeReferences {
-        admin: active_admin_theme.as_deref() == Some(urn.as_str()),
-    })
-}
-
-fn default_theme_ref() -> ThemeRef {
-    ThemeRef::Preset(DEFAULT_REF.trim_start_matches("preset:").to_string())
-}
-
-#[cfg(test)]
-mod tests {
-    use sea_orm::ConnectionTrait;
-
-    use crate::service::theme_validator::REQUIRED_VARS;
-    use crate::test_utils::setup_test_db;
-
-    use super::*;
-
-    fn valid_vars() -> VarMap {
-        REQUIRED_VARS
-            .iter()
-            .map(|key| ((*key).to_string(), "oklch(0.5 0.1 180)".to_string()))
-            .collect()
-    }
-
-    fn create_input(name: &str) -> CreateThemeInput {
-        CreateThemeInput {
-            name: name.to_string(),
-            description: None,
-            based_on: Some("default".to_string()),
-            vars_light: valid_vars(),
-            vars_dark: valid_vars(),
-        }
-    }
-
-    fn validation_message(result: Result<Theme, AppError>) -> String {
-        match result {
-            Err(AppError::Validation(message)) => message,
-            other => panic!("expected validation error, got {other:?}"),
-        }
-    }
-
-    fn update_input(name: &str) -> UpdateThemeInput {
-        UpdateThemeInput {
-            name: name.to_string(),
-            description: None,
-            based_on: Some("default".to_string()),
-            vars_light: valid_vars(),
-            vars_dark: valid_vars(),
-        }
-    }
-
-    // R4: legacy `insert_status_page_with_theme_ref` and
-    // `update_status_page_theme_ref` helpers were removed along with the
-    // dropped `status_page.theme_ref` column. Tests that exercised the
-    // status-page-side trigger are gone for the same reason.
-
-    fn assert_db_err_contains(result: Result<impl std::fmt::Debug, DbErr>, needle: &str) {
-        let err = result.expect_err("operation should fail");
-        assert!(
-            err.to_string().contains(needle),
-            "expected DB error to contain {needle}, got {err}"
-        );
-    }
-
-    #[tokio::test]
-    async fn active_theme_falls_back_to_default_for_dangling_custom_ref() {
-        let (db, _tmp) = setup_test_db().await;
-        db.execute_unprepared("DROP TRIGGER IF EXISTS trg_custom_theme_config_insert_ref_exists")
-            .await
-            .expect("config insert trigger should be dropped");
-        db.execute_unprepared("DROP TRIGGER IF EXISTS trg_custom_theme_config_update_ref_exists")
-            .await
-            .expect("config update trigger should be dropped");
-        ConfigService::set(&db, ACTIVE_THEME_KEY, "custom:999")
-            .await
-            .expect("config should be set");
-
-        let response = CustomThemeService::active_theme(&db, true)
-            .await
-            .expect("dangling stored custom ref should fall back");
-
-        assert_eq!(response.r#ref, DEFAULT_REF);
-        assert!(matches!(
-            response.theme,
-            ThemeResolved::Preset { ref id } if id == "default"
-        ));
-    }
-
-    #[tokio::test]
-    async fn active_theme_falls_back_to_default_when_config_missing() {
-        let (db, _tmp) = setup_test_db().await;
-
-        let response = CustomThemeService::active_theme(&db, true)
-            .await
-            .expect("missing config should fall back");
-
-        assert_eq!(response.r#ref, DEFAULT_REF);
-        assert!(matches!(
-            response.theme,
-            ThemeResolved::Preset { ref id } if id == "default"
-        ));
-    }
-
-    #[tokio::test]
-    async fn active_theme_falls_back_to_default_for_malformed_stored_ref() {
-        let (db, _tmp) = setup_test_db().await;
-        ConfigService::set(&db, ACTIVE_THEME_KEY, "not-a-theme-ref")
-            .await
-            .expect("malformed legacy config should be stored");
-
-        let response = CustomThemeService::active_theme(&db, true)
-            .await
-            .expect("malformed stored ref should fall back");
-
-        assert_eq!(response.r#ref, DEFAULT_REF);
-        assert!(matches!(
-            response.theme,
-            ThemeResolved::Preset { ref id } if id == "default"
-        ));
-    }
-
-    #[tokio::test]
-    async fn update_rejects_blank_name() {
-        let (db, _tmp) = setup_test_db().await;
-        let theme = CustomThemeService::create(&db, create_input("Ocean"), "user-1")
-            .await
-            .expect("valid theme should be created");
-
-        let message =
-            validation_message(CustomThemeService::update(&db, theme.id, update_input(" ")).await);
-
-        assert_eq!(message, "theme name cannot be empty");
-    }
-
-    #[tokio::test]
-    async fn update_rejects_overlong_name() {
-        let (db, _tmp) = setup_test_db().await;
-        let theme = CustomThemeService::create(&db, create_input("Ocean"), "user-1")
-            .await
-            .expect("valid theme should be created");
-
-        let message = validation_message(
-            CustomThemeService::update(&db, theme.id, update_input(&"x".repeat(121))).await,
-        );
-
-        assert_eq!(message, "theme name cannot exceed 120 characters");
-    }
-
-    #[tokio::test]
-    async fn create_rejects_whitespace_only_name() {
-        let (db, _tmp) = setup_test_db().await;
-
-        let message = validation_message(
-            CustomThemeService::create(&db, create_input("   "), "user-1").await,
-        );
-
-        assert_eq!(message, "theme name cannot be empty");
-    }
-
-    #[tokio::test]
-    async fn create_trims_valid_name_before_storing() {
-        let (db, _tmp) = setup_test_db().await;
-
-        let theme = CustomThemeService::create(&db, create_input("  Ocean  "), "user-1")
-            .await
-            .expect("valid theme should be created");
-
-        assert_eq!(theme.name, "Ocean");
-    }
-
-    #[tokio::test]
-    async fn create_rejects_unknown_based_on() {
-        let (db, _tmp) = setup_test_db().await;
-        let mut input = create_input("Ocean");
-        input.based_on = Some("not-real".to_string());
-
-        let message = validation_message(CustomThemeService::create(&db, input, "user-1").await);
-
-        assert_eq!(message, "unknown preset: not-real");
-    }
-
-    #[tokio::test]
-    async fn create_treats_blank_based_on_as_none() {
-        let (db, _tmp) = setup_test_db().await;
-        let mut input = create_input("Ocean");
-        input.based_on = Some("   ".to_string());
-
-        let theme = CustomThemeService::create(&db, input, "user-1")
-            .await
-            .expect("blank based_on should be normalized");
-
-        assert_eq!(theme.based_on, None);
-    }
-
-    #[tokio::test]
-    async fn duplicate_truncates_max_length_name_before_copy_suffix() {
-        let (db, _tmp) = setup_test_db().await;
-        let source = CustomThemeService::create(&db, create_input(&"x".repeat(120)), "user-1")
-            .await
-            .expect("max length theme should be created");
-
-        let copy = CustomThemeService::duplicate(&db, source.id, "user-1")
-            .await
-            .expect("duplicate should fit max name length");
-
-        assert_eq!(copy.name.chars().count(), 120);
-        assert!(copy.name.ends_with(" (copy)"));
-    }
-
-    #[tokio::test]
-    async fn delete_rejects_in_use_active_theme() {
-        let (db, _tmp) = setup_test_db().await;
-        let theme = CustomThemeService::create(&db, create_input("Ocean"), "user-1")
-            .await
-            .expect("valid theme should be created");
-        ConfigService::set(&db, ACTIVE_THEME_KEY, &format!("custom:{}", theme.id))
-            .await
-            .expect("config should be set");
-
-        let err = CustomThemeService::delete(&db, theme.id)
-            .await
-            .expect_err("active theme should not be deleted");
-
-        assert!(
-            matches!(err, AppError::Conflict(message) if message == "Theme is in use as the active admin theme; unbind it first.")
-        );
-    }
-
-    #[tokio::test]
-    async fn delete_trigger_blocks_active_theme_ref_when_service_precheck_is_bypassed() {
-        let (db, _tmp) = setup_test_db().await;
-        let theme = CustomThemeService::create(&db, create_input("Ocean"), "user-1")
-            .await
-            .expect("valid theme should be created");
-        ConfigService::set(&db, ACTIVE_THEME_KEY, &format!("custom:{}", theme.id))
-            .await
-            .expect("config should be set");
-
-        let result = custom_theme::Entity::delete_by_id(theme.id).exec(&db).await;
-
-        assert_db_err_contains(result, "custom_theme_ref_in_use");
-    }
-
-    #[tokio::test]
-    async fn config_trigger_blocks_dangling_active_custom_ref() {
-        let (db, _tmp) = setup_test_db().await;
-
-        let err = ConfigService::set(&db, ACTIVE_THEME_KEY, "custom:999")
-            .await
-            .expect_err("dangling active theme ref should be blocked");
-
-        assert!(matches!(err, AppError::Internal(_)));
-    }
-
-    #[tokio::test]
-    async fn local_config_write_maps_missing_theme_ref_trigger() {
-        let (db, _tmp) = setup_test_db().await;
-
-        let err = set_config_value(&db, ACTIVE_THEME_KEY, "custom:999")
-            .await
-            .expect_err("dangling active theme ref should be mapped");
-
-        assert!(
-            matches!(err, AppError::Validation(message) if message == "custom theme reference does not exist")
-        );
-    }
-}
diff --git a/crates/server/src/service/mod.rs b/crates/server/src/service/mod.rs
index cd26b778..2c9a0283 100644
--- a/crates/server/src/service/mod.rs
+++ b/crates/server/src/service/mod.rs
@@ -7,7 +7,6 @@ pub mod auth;
 pub mod checker;
 pub mod config;
 pub mod cost;
-pub mod custom_theme;
 pub mod dashboard;
 pub mod db_error;
 pub mod docker;
@@ -31,12 +30,9 @@ pub mod record;
 pub mod security;
 pub mod server;
 pub mod server_tag;
-pub mod spa_theme;
 pub mod service_monitor;
 pub mod status_page;
 pub mod task_scheduler;
-pub mod theme_ref;
-pub mod theme_validator;
 pub mod traceroute;
 pub mod traceroute_enrich;
 pub mod traffic;
diff --git a/crates/server/src/service/spa_theme/error.rs b/crates/server/src/service/spa_theme/error.rs
deleted file mode 100644
index af6675c5..00000000
--- a/crates/server/src/service/spa_theme/error.rs
+++ /dev/null
@@ -1,178 +0,0 @@
-use axum::http::StatusCode;
-use serde_json::json;
-
-use crate::error::AppError;
-
-#[derive(Debug, thiserror::Error)]
-pub enum SpaThemeError {
-    #[error("multipart upload exceeds the size limit")]
-    UploadTooLarge { limit_bytes: u64 },
-    #[error("multipart payload is malformed")]
-    InvalidMultipart(String),
-    #[error("manifest.json is missing")]
-    MissingManifest,
-    #[error("manifest is invalid")]
-    InvalidManifest { field: &'static str, reason: String },
-    #[error("entry HTML not present in package")]
-    MissingEntry { entry: String },
-    #[error("requires a newer ServerBee than running")]
-    IncompatibleVersion { min: String, running: String },
-    #[error("package contains unsafe path")]
-    ZipSlip { entry: String },
-    #[error("compression ratio too high")]
-    ZipBomb { entry: String, ratio: u64 },
-    #[error("symlinks are not allowed")]
-    SymlinkNotAllowed { entry: String },
-    #[error("duplicate zip entry")]
-    DuplicateEntry { entry: String },
-    #[error("file extension is not allowed")]
-    DisallowedExtension { entry: String, ext: String },
-    #[error("file too large")]
-    FileTooLarge {
-        entry: String,
-        size: u64,
-        limit: u64,
-    },
-    #[error("too many files in package")]
-    TooManyFiles { count: usize, limit: usize },
-    #[error("total uncompressed size exceeded")]
-    TotalSizeExceeded { size: u64, limit: u64 },
-    #[error("preview image too large")]
-    PreviewTooLarge { size: u64, limit: u64 },
-    #[error("version downgrade not allowed")]
-    NoDowngrade { uploaded: String, existing: String },
-    #[error("this version already exists")]
-    VersionExists {
-        manifest_id: String,
-        version: String,
-    },
-    #[error("theme is currently active")]
-    ThemeInUse { uuid: String },
-    #[error("theme not found")]
-    ThemeNotFound { uuid: String },
-}
-
-impl SpaThemeError {
-    pub fn code(&self) -> &'static str {
-        match self {
-            Self::UploadTooLarge { .. } => "UPLOAD_TOO_LARGE",
-            Self::InvalidMultipart(_) => "INVALID_MULTIPART",
-            Self::MissingManifest => "MISSING_MANIFEST",
-            Self::InvalidManifest { .. } => "INVALID_MANIFEST",
-            Self::MissingEntry { .. } => "MISSING_ENTRY",
-            Self::IncompatibleVersion { .. } => "INCOMPATIBLE_VERSION",
-            Self::ZipSlip { .. } => "ZIP_SLIP",
-            Self::ZipBomb { .. } => "ZIP_BOMB",
-            Self::SymlinkNotAllowed { .. } => "SYMLINK_NOT_ALLOWED",
-            Self::DuplicateEntry { .. } => "DUPLICATE_ENTRY",
-            Self::DisallowedExtension { .. } => "DISALLOWED_EXTENSION",
-            Self::FileTooLarge { .. } => "FILE_TOO_LARGE",
-            Self::TooManyFiles { .. } => "TOO_MANY_FILES",
-            Self::TotalSizeExceeded { .. } => "TOTAL_SIZE_EXCEEDED",
-            Self::PreviewTooLarge { .. } => "PREVIEW_TOO_LARGE",
-            Self::NoDowngrade { .. } => "NO_DOWNGRADE",
-            Self::VersionExists { .. } => "VERSION_EXISTS",
-            Self::ThemeInUse { .. } => "THEME_IN_USE",
-            Self::ThemeNotFound { .. } => "THEME_NOT_FOUND",
-        }
-    }
-
-    fn status(&self) -> StatusCode {
-        match self {
-            Self::UploadTooLarge { .. } => StatusCode::PAYLOAD_TOO_LARGE,
-            Self::VersionExists { .. } | Self::ThemeInUse { .. } => StatusCode::CONFLICT,
-            Self::ThemeNotFound { .. } => StatusCode::NOT_FOUND,
-            _ => StatusCode::BAD_REQUEST,
-        }
-    }
-
-    fn details(&self) -> Option<serde_json::Value> {
-        match self {
-            Self::UploadTooLarge { limit_bytes } => Some(json!({ "limit_bytes": limit_bytes })),
-            Self::InvalidMultipart(reason) => Some(json!({ "reason": reason })),
-            Self::InvalidManifest { field, reason } => {
-                Some(json!({ "field": field, "reason": reason }))
-            }
-            Self::MissingEntry { entry } => Some(json!({ "entry": entry })),
-            Self::IncompatibleVersion { min, running } => {
-                Some(json!({ "min": min, "running": running }))
-            }
-            Self::ZipSlip { entry }
-            | Self::SymlinkNotAllowed { entry }
-            | Self::DuplicateEntry { entry } => Some(json!({ "entry": entry })),
-            Self::ZipBomb { entry, ratio } => Some(json!({ "entry": entry, "ratio": ratio })),
-            Self::DisallowedExtension { entry, ext } => Some(json!({ "entry": entry, "ext": ext })),
-            Self::FileTooLarge { entry, size, limit } => {
-                Some(json!({ "entry": entry, "size": size, "limit": limit }))
-            }
-            Self::TooManyFiles { count, limit } => Some(json!({ "count": count, "limit": limit })),
-            Self::TotalSizeExceeded { size, limit } | Self::PreviewTooLarge { size, limit } => {
-                Some(json!({ "size": size, "limit": limit }))
-            }
-            Self::NoDowngrade { uploaded, existing } => {
-                Some(json!({ "uploaded": uploaded, "existing": existing }))
-            }
-            Self::VersionExists {
-                manifest_id,
-                version,
-            } => Some(json!({ "manifest_id": manifest_id, "version": version })),
-            Self::ThemeNotFound { uuid } | Self::ThemeInUse { uuid } => {
-                Some(json!({ "uuid": uuid }))
-            }
-            Self::MissingManifest => None,
-        }
-    }
-}
-
-impl From<SpaThemeError> for AppError {
-    fn from(err: SpaThemeError) -> Self {
-        let status = err.status();
-        let code = err.code();
-        let details = err.details();
-        let message = err.to_string();
-        AppError::Domain {
-            status,
-            code,
-            message,
-            details,
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use axum::body::to_bytes;
-    use axum::response::IntoResponse;
-
-    #[tokio::test]
-    async fn zip_slip_maps_to_domain_error() {
-        let err: AppError = SpaThemeError::ZipSlip {
-            entry: "../etc/passwd".into(),
-        }
-        .into();
-        let resp = err.into_response();
-        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
-        let body = to_bytes(resp.into_body(), 1024).await.unwrap();
-        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
-        assert_eq!(json["error"]["code"], "ZIP_SLIP");
-        assert_eq!(json["error"]["details"]["entry"], "../etc/passwd");
-    }
-
-    #[tokio::test]
-    async fn theme_in_use_is_409() {
-        let err: AppError = SpaThemeError::ThemeInUse { uuid: "abc".into() }.into();
-        let resp = err.into_response();
-        assert_eq!(resp.status(), StatusCode::CONFLICT);
-    }
-
-    #[tokio::test]
-    async fn upload_too_large_is_413() {
-        let err: AppError = SpaThemeError::UploadTooLarge {
-            limit_bytes: crate::service::spa_theme::UPLOAD_LIMIT_BYTES,
-        }
-        .into();
-        let resp = err.into_response();
-        assert_eq!(resp.status(), StatusCode::PAYLOAD_TOO_LARGE);
-    }
-}
diff --git a/crates/server/src/service/spa_theme/extractor.rs b/crates/server/src/service/spa_theme/extractor.rs
deleted file mode 100644
index 534ca0ab..00000000
--- a/crates/server/src/service/spa_theme/extractor.rs
+++ /dev/null
@@ -1,330 +0,0 @@
-use std::collections::{HashMap, HashSet};
-use std::io::Read;
-
-use crate::service::spa_theme::error::SpaThemeError;
-
-pub const MAX_TOTAL_BYTES: u64 = 20 * 1024 * 1024;
-pub const MAX_FILES: usize = 1000;
-pub const MAX_FILE_BYTES: u64 = 5 * 1024 * 1024;
-pub const MAX_PREVIEW_BYTES: u64 = 500 * 1024;
-pub const MAX_PATH_LEN: usize = 255;
-pub const MAX_RATIO: u64 = 100;
-
-pub const ALLOWED_EXTS: &[&str] = &[
-    "html", "htm", "js", "mjs", "css", "png", "jpg", "jpeg", "svg", "webp", "gif", "ico", "woff", "woff2", "ttf",
-    "otf", "json", "txt", "map",
-];
-
-#[derive(Debug)]
-pub struct ExtractedPackage {
-    pub files: HashMap<String, Vec<u8>>,
-    pub manifest_bytes: Vec<u8>,
-    pub preview: Option<(String, Vec<u8>, String /* mime */)>,
-    pub total_bytes: u64,
-}
-
-pub fn extract(zip_bytes: &[u8]) -> Result<ExtractedPackage, SpaThemeError> {
-    let cursor = std::io::Cursor::new(zip_bytes);
-    let mut archive =
-        zip::ZipArchive::new(cursor).map_err(|e| SpaThemeError::InvalidMultipart(format!("zip open: {e}")))?;
-
-    if archive.len() > MAX_FILES {
-        return Err(SpaThemeError::TooManyFiles { count: archive.len(), limit: MAX_FILES });
-    }
-
-    let mut files: HashMap<String, Vec<u8>> = HashMap::new();
-    let mut seen: HashSet<String> = HashSet::new();
-    let mut total: u64 = 0;
-    let mut manifest_bytes: Option<Vec<u8>> = None;
-
-    for i in 0..archive.len() {
-        let mut entry = archive
-            .by_index(i)
-            .map_err(|e| SpaThemeError::InvalidMultipart(format!("zip entry {i}: {e}")))?;
-
-        if let Some(mode) = entry.unix_mode() {
-            const S_IFMT: u32 = 0o170000;
-            const S_IFLNK: u32 = 0o120000;
-            if mode & S_IFMT == S_IFLNK {
-                return Err(SpaThemeError::SymlinkNotAllowed { entry: entry.name().to_string() });
-            }
-        }
-        if entry.is_dir() {
-            continue;
-        }
-
-        let raw = entry.name().to_string();
-        if raw.len() > MAX_PATH_LEN {
-            return Err(SpaThemeError::ZipSlip { entry: raw });
-        }
-        let normalized = normalize_path(&raw).ok_or_else(|| SpaThemeError::ZipSlip { entry: raw.clone() })?;
-
-        if !seen.insert(normalized.clone()) {
-            return Err(SpaThemeError::DuplicateEntry { entry: normalized });
-        }
-
-        let ext = std::path::Path::new(&normalized)
-            .extension()
-            .and_then(|e| e.to_str())
-            .map(|e| e.to_ascii_lowercase())
-            .unwrap_or_default();
-        if !ALLOWED_EXTS.contains(&ext.as_str()) {
-            return Err(SpaThemeError::DisallowedExtension { entry: normalized, ext });
-        }
-
-        let size = entry.size();
-        if size > MAX_FILE_BYTES {
-            return Err(SpaThemeError::FileTooLarge { entry: normalized, size, limit: MAX_FILE_BYTES });
-        }
-
-        let compressed = entry.compressed_size();
-        if compressed > 0 {
-            let ratio = size / compressed.max(1);
-            if ratio > MAX_RATIO {
-                return Err(SpaThemeError::ZipBomb { entry: normalized, ratio });
-            }
-        }
-
-        total = total.saturating_add(size);
-        if total > MAX_TOTAL_BYTES {
-            return Err(SpaThemeError::TotalSizeExceeded { size: total, limit: MAX_TOTAL_BYTES });
-        }
-
-        // Defense-in-depth: the `size` above comes from the zip header and may lie.
-        // Cap the actual read at MAX_FILE_BYTES + 1 so a crafted archive that
-        // declares a small size but contains huge data cannot grow the buffer
-        // unbounded. If the truncated read exceeds MAX_FILE_BYTES, reject.
-        let mut buf = Vec::with_capacity(size.min(MAX_FILE_BYTES) as usize);
-        let mut limited = (&mut entry).take(MAX_FILE_BYTES + 1);
-        limited
-            .read_to_end(&mut buf)
-            .map_err(|e| SpaThemeError::InvalidMultipart(format!("read {normalized}: {e}")))?;
-        if buf.len() as u64 > MAX_FILE_BYTES {
-            return Err(SpaThemeError::FileTooLarge {
-                entry: normalized,
-                size: buf.len() as u64,
-                limit: MAX_FILE_BYTES,
-            });
-        }
-
-        if normalized == "manifest.json" {
-            manifest_bytes = Some(buf.clone());
-        }
-        files.insert(normalized, buf);
-    }
-
-    let manifest_bytes = manifest_bytes.ok_or(SpaThemeError::MissingManifest)?;
-
-    Ok(ExtractedPackage { files, manifest_bytes, preview: None, total_bytes: total })
-}
-
-fn normalize_path(raw: &str) -> Option<String> {
-    if raw.is_empty() {
-        return None;
-    }
-    if raw.starts_with('/') {
-        return None;
-    }
-    if raw.len() >= 2 && raw.as_bytes()[1] == b':' {
-        return None;
-    }
-    if raw.contains('\\') {
-        return None;
-    }
-    let mut parts: Vec<&str> = Vec::new();
-    for part in raw.split('/') {
-        match part {
-            "" | "." => continue,
-            ".." => return None,
-            other => parts.push(other),
-        }
-    }
-    if parts.is_empty() {
-        return None;
-    }
-    Some(parts.join("/"))
-}
-
-pub fn locate_preview(
-    files: &HashMap<String, Vec<u8>>,
-    preview_path: &str,
-) -> Result<Option<(String, Vec<u8>, String)>, SpaThemeError> {
-    let Some(bytes) = files.get(preview_path) else {
-        return Ok(None);
-    };
-    let size = bytes.len() as u64;
-    if size > MAX_PREVIEW_BYTES {
-        return Err(SpaThemeError::PreviewTooLarge { size, limit: MAX_PREVIEW_BYTES });
-    }
-    let mime = match preview_path.rsplit('.').next().unwrap_or("").to_ascii_lowercase().as_str() {
-        "png" => "image/png",
-        "jpg" | "jpeg" => "image/jpeg",
-        "webp" => "image/webp",
-        _ => "application/octet-stream",
-    }
-    .to_string();
-    Ok(Some((preview_path.to_string(), bytes.clone(), mime)))
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use std::io::Write;
-
-    fn build_zip(entries: &[(&str, &[u8])]) -> Vec<u8> {
-        let mut buf = Vec::new();
-        {
-            let mut w = zip::ZipWriter::new(std::io::Cursor::new(&mut buf));
-            let opts: zip::write::SimpleFileOptions =
-                zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Deflated);
-            for (name, data) in entries {
-                w.start_file(*name, opts).unwrap();
-                w.write_all(data).unwrap();
-            }
-            w.finish().unwrap();
-        }
-        buf
-    }
-
-    #[test]
-    fn extracts_minimal_package() {
-        let zip = build_zip(&[
-            ("manifest.json", br#"{"schema_version":1,"id":"a","name":"A","version":"1.0.0"}"#),
-            ("index.html", b"<html></html>"),
-        ]);
-        let pkg = extract(&zip).unwrap();
-        assert!(pkg.files.contains_key("index.html"));
-        assert!(!pkg.manifest_bytes.is_empty());
-    }
-
-    #[test]
-    fn rejects_zip_slip() {
-        let zip = build_zip(&[("../etc/passwd", b"x"), ("manifest.json", b"{}")]);
-        let err = extract(&zip).unwrap_err();
-        assert!(matches!(err, SpaThemeError::ZipSlip { .. }));
-    }
-
-    #[test]
-    fn rejects_absolute_path() {
-        let zip = build_zip(&[("/abs/path.html", b"x"), ("manifest.json", b"{}")]);
-        let err = extract(&zip).unwrap_err();
-        assert!(matches!(err, SpaThemeError::ZipSlip { .. }));
-    }
-
-    #[test]
-    fn rejects_disallowed_extension() {
-        let zip = build_zip(&[("evil.sh", b"#!/bin/sh"), ("manifest.json", b"{}")]);
-        let err = extract(&zip).unwrap_err();
-        assert!(matches!(err, SpaThemeError::DisallowedExtension { .. }));
-    }
-
-    #[test]
-    fn rejects_too_many_files() {
-        let owned: Vec<(String, Vec<u8>)> = {
-            let mut v: Vec<(String, Vec<u8>)> =
-                (0..1001).map(|i| (format!("a{i}.txt"), vec![0u8; 8])).collect();
-            v.push(("manifest.json".into(), b"{}".to_vec()));
-            v
-        };
-        let refs: Vec<(&str, &[u8])> = owned.iter().map(|(n, d)| (n.as_str(), d.as_slice())).collect();
-        let zip = build_zip(&refs);
-        let err = extract(&zip).unwrap_err();
-        assert!(matches!(err, SpaThemeError::TooManyFiles { .. }));
-    }
-
-    #[test]
-    fn rejects_oversize_file() {
-        let big = vec![b'a'; (MAX_FILE_BYTES + 1) as usize];
-        let zip = build_zip(&[("big.js", &big), ("manifest.json", b"{}")]);
-        let err = extract(&zip).unwrap_err();
-        assert!(matches!(err, SpaThemeError::FileTooLarge { .. }));
-    }
-
-    #[test]
-    fn rejects_total_over_limit() {
-        // Use pseudo-random (incompressible) data to avoid triggering the ZipBomb check.
-        // A simple LCG produces varied bytes that compress poorly.
-        fn incompressible(seed: u64, len: usize) -> Vec<u8> {
-            let mut v = Vec::with_capacity(len);
-            let mut x = seed;
-            for _ in 0..len {
-                x = x.wrapping_mul(6364136223846793005).wrapping_add(1442695040888963407);
-                v.push((x >> 56) as u8);
-            }
-            v
-        }
-        let owned: Vec<(String, Vec<u8>)> = {
-            let mut v: Vec<(String, Vec<u8>)> = (0..5u64)
-                .map(|i| (format!("c{i}.css"), incompressible(i + 1, MAX_FILE_BYTES as usize)))
-                .collect();
-            v.push(("manifest.json".into(), b"{}".to_vec()));
-            v
-        };
-        let refs: Vec<(&str, &[u8])> = owned.iter().map(|(n, d)| (n.as_str(), d.as_slice())).collect();
-        let zip = build_zip(&refs);
-        let err = extract(&zip).unwrap_err();
-        assert!(matches!(err, SpaThemeError::TotalSizeExceeded { .. }));
-    }
-
-    #[test]
-    fn rejects_missing_manifest() {
-        let zip = build_zip(&[("index.html", b"<html/>")]);
-        let err = extract(&zip).unwrap_err();
-        assert!(matches!(err, SpaThemeError::MissingManifest));
-    }
-
-    #[test]
-    fn duplicate_entry_variant_exists_and_invalid_zip_handled() {
-        // Coverage gap: the production `seen.insert` guard in extract() is not
-        // exercised here because zip v2 prevents writing duplicate filenames and
-        // silently deduplicates on read, so we cannot construct an archive that
-        // makes by_index() yield the same name twice. The DuplicateEntry variant
-        // remains in the extractor as defense-in-depth for future library swaps
-        // or raw-zip inputs. This test verifies (a) the variant maps correctly
-        // and (b) malformed zip bytes produce InvalidMultipart — the accepted
-        // fallback in the original plan assertion.
-        let buf = {
-            let mut w = zip::ZipWriter::new(std::io::Cursor::new(Vec::<u8>::new()));
-            let opts = zip::write::SimpleFileOptions::default();
-            w.start_file("a.html", opts).unwrap();
-            w.write_all(b"1").unwrap();
-            w.start_file("manifest.json", opts).unwrap();
-            w.write_all(b"{}").unwrap();
-            w.finish().unwrap().into_inner()
-        };
-        let dup_err = SpaThemeError::DuplicateEntry { entry: "a.html".into() };
-        assert_eq!(dup_err.code(), "DUPLICATE_ENTRY");
-        let err = extract(b"PK not a real zip").unwrap_err();
-        assert!(matches!(err, SpaThemeError::InvalidMultipart(_)));
-        extract(&buf).expect("valid zip must succeed");
-    }
-
-    #[test]
-    fn rejects_zip_bomb() {
-        // Highly compressible: 5MB of zeros compresses to ~5KB → ratio ~1000x.
-        let zeros = vec![0u8; MAX_FILE_BYTES as usize];
-        let zip = build_zip(&[("bomb.js", &zeros), ("manifest.json", b"{}")]);
-        let err = extract(&zip).unwrap_err();
-        assert!(matches!(err, SpaThemeError::ZipBomb { .. }));
-    }
-
-    #[test]
-    fn rejects_symlink() {
-        // Build a zip with a real symlink entry via zip v2's add_symlink().
-        // SimpleFileOptions::unix_permissions() masks with 0o777 and normalize()
-        // forces S_IFREG for regular files, so the only way to produce an entry
-        // with S_IFLNK set is the dedicated add_symlink() API.
-        use zip::write::SimpleFileOptions;
-        let mut buf = Vec::new();
-        {
-            let mut w = zip::ZipWriter::new(std::io::Cursor::new(&mut buf));
-            let opts = SimpleFileOptions::default();
-            w.add_symlink("link.html", "target.html", opts).unwrap();
-            w.start_file("manifest.json", opts).unwrap();
-            std::io::Write::write_all(&mut w, b"{}").unwrap();
-            w.finish().unwrap();
-        }
-        let err = extract(&buf).unwrap_err();
-        assert!(matches!(err, SpaThemeError::SymlinkNotAllowed { .. }));
-    }
-}
diff --git a/crates/server/src/service/spa_theme/loaded.rs b/crates/server/src/service/spa_theme/loaded.rs
deleted file mode 100644
index 195cbf30..00000000
--- a/crates/server/src/service/spa_theme/loaded.rs
+++ /dev/null
@@ -1,42 +0,0 @@
-use std::collections::HashMap;
-use std::sync::Arc;
-
-use arc_swap::ArcSwap;
-use axum::body::Bytes;
-
-use crate::service::spa_theme::manifest::ThemeManifest;
-
-#[derive(Debug, Clone)]
-pub struct LoadedTheme {
-    pub uuid: String,
-    pub manifest: ThemeManifest,
-    pub entry: String,
-    pub files: HashMap<String, Bytes>,
-}
-
-pub type ActiveSpaThemeSlot = Arc<ArcSwap<Option<LoadedTheme>>>;
-
-pub fn new_slot() -> ActiveSpaThemeSlot {
-    Arc::new(ArcSwap::from_pointee(None))
-}
-
-impl LoadedTheme {
-    pub fn from_extracted(
-        uuid: String,
-        manifest: ThemeManifest,
-        files: HashMap<String, Vec<u8>>,
-    ) -> Self {
-        let entry = manifest.entry.clone();
-        let files = files.into_iter().map(|(k, v)| (k, Bytes::from(v))).collect();
-        Self { uuid, manifest, entry, files }
-    }
-
-    pub fn get(&self, path: &str) -> Option<Bytes> {
-        let p = if path.is_empty() || path == "/" { self.entry.as_str() } else { path.trim_start_matches('/') };
-        self.files.get(p).cloned()
-    }
-
-    pub fn entry_html(&self) -> Option<Bytes> {
-        self.files.get(&self.entry).cloned()
-    }
-}
diff --git a/crates/server/src/service/spa_theme/manifest.rs b/crates/server/src/service/spa_theme/manifest.rs
deleted file mode 100644
index d9771f61..00000000
--- a/crates/server/src/service/spa_theme/manifest.rs
+++ /dev/null
@@ -1,271 +0,0 @@
-use serde::{Deserialize, Serialize};
-
-use crate::service::spa_theme::error::SpaThemeError;
-
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-pub struct ThemeManifest {
-    pub schema_version: u32,
-    pub id: String,
-    pub name: String,
-    pub version: String,
-    #[serde(default)]
-    pub author: Option<String>,
-    #[serde(default)]
-    pub homepage: Option<String>,
-    #[serde(default)]
-    pub description: Option<String>,
-    #[serde(default = "default_entry")]
-    pub entry: String,
-    #[serde(default)]
-    pub min_serverbee_version: Option<String>,
-    #[serde(default)]
-    pub preview: Option<String>,
-}
-
-fn default_entry() -> String {
-    "index.html".into()
-}
-
-pub const SCHEMA_VERSION: u32 = 1;
-pub const ID_REGEX: &str = r"^[a-z][a-z0-9-]{2,63}$";
-pub const MAX_NAME: usize = 64;
-pub const MAX_AUTHOR: usize = 64;
-pub const MAX_DESCRIPTION: usize = 500;
-
-fn id_regex() -> &'static regex::Regex {
-    static RE: std::sync::OnceLock<regex::Regex> = std::sync::OnceLock::new();
-    RE.get_or_init(|| regex::Regex::new(ID_REGEX).expect("static regex"))
-}
-
-impl ThemeManifest {
-    /// Parse manifest JSON bytes and validate every field. `running_version`
-    /// is the server's semver (used for min_serverbee_version check).
-    /// `file_paths` is the set of paths present in the package (for entry/preview existence).
-    pub fn parse_and_validate(
-        bytes: &[u8],
-        running_version: &semver::Version,
-        file_paths: &std::collections::HashSet<String>,
-    ) -> Result<Self, SpaThemeError> {
-        let mut m: Self = serde_json::from_slice(bytes).map_err(|e| SpaThemeError::InvalidManifest {
-            field: "$",
-            reason: format!("JSON parse: {e}"),
-        })?;
-
-        if m.schema_version != SCHEMA_VERSION {
-            return Err(SpaThemeError::InvalidManifest {
-                field: "schema_version",
-                reason: format!("must be {SCHEMA_VERSION}"),
-            });
-        }
-
-        if !id_regex().is_match(&m.id) {
-            return Err(SpaThemeError::InvalidManifest {
-                field: "id",
-                reason: format!("must match {ID_REGEX}"),
-            });
-        }
-
-        let name_trim = m.name.trim();
-        if name_trim.is_empty() || name_trim.chars().count() > MAX_NAME {
-            return Err(SpaThemeError::InvalidManifest {
-                field: "name",
-                reason: format!("1..={MAX_NAME} chars"),
-            });
-        }
-        m.name = strip_html(name_trim);
-
-        if let Some(a) = &m.author {
-            if a.chars().count() > MAX_AUTHOR {
-                return Err(SpaThemeError::InvalidManifest {
-                    field: "author",
-                    reason: format!("..={MAX_AUTHOR} chars"),
-                });
-            }
-            m.author = Some(strip_html(a));
-        }
-        if let Some(d) = &m.description {
-            if d.chars().count() > MAX_DESCRIPTION {
-                return Err(SpaThemeError::InvalidManifest {
-                    field: "description",
-                    reason: format!("..={MAX_DESCRIPTION} chars"),
-                });
-            }
-            m.description = Some(strip_html(d));
-        }
-        if let Some(h) = &m.homepage {
-            let u = url::Url::parse(h).map_err(|_| SpaThemeError::InvalidManifest {
-                field: "homepage",
-                reason: "invalid URL".into(),
-            })?;
-            if !matches!(u.scheme(), "http" | "https") {
-                return Err(SpaThemeError::InvalidManifest {
-                    field: "homepage",
-                    reason: "must be http(s)".into(),
-                });
-            }
-        }
-
-        semver::Version::parse(&m.version).map_err(|_| SpaThemeError::InvalidManifest {
-            field: "version",
-            reason: "invalid semver".into(),
-        })?;
-
-        if let Some(min) = &m.min_serverbee_version {
-            let parsed = semver::Version::parse(min).map_err(|_| SpaThemeError::InvalidManifest {
-                field: "min_serverbee_version",
-                reason: "invalid semver".into(),
-            })?;
-            if &parsed > running_version {
-                return Err(SpaThemeError::IncompatibleVersion {
-                    min: min.clone(),
-                    running: running_version.to_string(),
-                });
-            }
-        }
-
-        if !m.entry.ends_with(".html") {
-            return Err(SpaThemeError::InvalidManifest {
-                field: "entry",
-                reason: "must end with .html".into(),
-            });
-        }
-        if !file_paths.contains(&m.entry) {
-            return Err(SpaThemeError::MissingEntry { entry: m.entry.clone() });
-        }
-        if let Some(p) = &m.preview {
-            if !file_paths.contains(p) {
-                return Err(SpaThemeError::InvalidManifest {
-                    field: "preview",
-                    reason: format!("not in package: {p}"),
-                });
-            }
-            let lower = p.to_ascii_lowercase();
-            if !(lower.ends_with(".png")
-                || lower.ends_with(".jpg")
-                || lower.ends_with(".jpeg")
-                || lower.ends_with(".webp"))
-            {
-                return Err(SpaThemeError::InvalidManifest {
-                    field: "preview",
-                    reason: "must be png/jpg/webp".into(),
-                });
-            }
-        }
-
-        Ok(m)
-    }
-}
-
-fn strip_html(s: &str) -> String {
-    let mut out = String::with_capacity(s.len());
-    let mut in_tag = false;
-    for c in s.chars() {
-        match c {
-            '<' => in_tag = true,
-            '>' => in_tag = false,
-            other if !in_tag => out.push(other),
-            _ => {}
-        }
-    }
-    out.trim().to_string()
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use std::collections::HashSet;
-
-    fn files(paths: &[&str]) -> HashSet<String> {
-        paths.iter().map(|s| (*s).into()).collect()
-    }
-    fn v(s: &str) -> semver::Version {
-        semver::Version::parse(s).unwrap()
-    }
-
-    fn valid_manifest() -> serde_json::Value {
-        serde_json::json!({
-            "schema_version": 1,
-            "id": "acme",
-            "name": "Acme",
-            "version": "1.0.0",
-        })
-    }
-
-    #[test]
-    fn happy_path() {
-        let m = ThemeManifest::parse_and_validate(
-            valid_manifest().to_string().as_bytes(),
-            &v("1.0.0-alpha.3"),
-            &files(&["index.html"]),
-        )
-        .unwrap();
-        assert_eq!(m.id, "acme");
-        assert_eq!(m.entry, "index.html");
-    }
-
-    #[test]
-    fn rejects_bad_id() {
-        let mut m = valid_manifest();
-        m["id"] = serde_json::json!("Acme!");
-        let err =
-            ThemeManifest::parse_and_validate(m.to_string().as_bytes(), &v("1.0.0"), &files(&["index.html"]))
-                .unwrap_err();
-        assert!(matches!(err, SpaThemeError::InvalidManifest { field: "id", .. }));
-    }
-
-    #[test]
-    fn rejects_wrong_schema_version() {
-        let mut m = valid_manifest();
-        m["schema_version"] = serde_json::json!(2);
-        let err =
-            ThemeManifest::parse_and_validate(m.to_string().as_bytes(), &v("1.0.0"), &files(&["index.html"]))
-                .unwrap_err();
-        assert!(matches!(err, SpaThemeError::InvalidManifest { field: "schema_version", .. }));
-    }
-
-    #[test]
-    fn rejects_missing_entry() {
-        let m = valid_manifest();
-        let err = ThemeManifest::parse_and_validate(m.to_string().as_bytes(), &v("1.0.0"), &files(&[])).unwrap_err();
-        assert!(matches!(err, SpaThemeError::MissingEntry { .. }));
-    }
-
-    #[test]
-    fn rejects_min_version_above_running() {
-        let mut m = valid_manifest();
-        m["min_serverbee_version"] = serde_json::json!("2.0.0");
-        let err =
-            ThemeManifest::parse_and_validate(m.to_string().as_bytes(), &v("1.0.0-alpha.3"), &files(&["index.html"]))
-                .unwrap_err();
-        assert!(matches!(err, SpaThemeError::IncompatibleVersion { .. }));
-    }
-
-    #[test]
-    fn accepts_min_version_lt_alpha() {
-        let mut m = valid_manifest();
-        m["min_serverbee_version"] = serde_json::json!("0.9.0");
-        ThemeManifest::parse_and_validate(m.to_string().as_bytes(), &v("1.0.0-alpha.3"), &files(&["index.html"]))
-            .unwrap();
-    }
-
-    #[test]
-    fn strips_html_from_name() {
-        let mut m = valid_manifest();
-        m["name"] = serde_json::json!("<script>alert(1)</script>Acme");
-        let parsed =
-            ThemeManifest::parse_and_validate(m.to_string().as_bytes(), &v("1.0.0"), &files(&["index.html"]))
-                .unwrap();
-        assert!(!parsed.name.contains('<'));
-        assert!(parsed.name.contains("Acme"));
-    }
-
-    #[test]
-    fn rejects_bad_homepage() {
-        let mut m = valid_manifest();
-        m["homepage"] = serde_json::json!("javascript:alert(1)");
-        let err =
-            ThemeManifest::parse_and_validate(m.to_string().as_bytes(), &v("1.0.0"), &files(&["index.html"]))
-                .unwrap_err();
-        assert!(matches!(err, SpaThemeError::InvalidManifest { field: "homepage", .. }));
-    }
-}
diff --git a/crates/server/src/service/spa_theme/mod.rs b/crates/server/src/service/spa_theme/mod.rs
deleted file mode 100644
index 6aefc8e8..00000000
--- a/crates/server/src/service/spa_theme/mod.rs
+++ /dev/null
@@ -1,17 +0,0 @@
-pub mod error;
-pub mod extractor;
-pub mod loaded;
-pub mod manifest;
-pub mod service;
-
-pub use error::SpaThemeError;
-pub use loaded::LoadedTheme;
-pub use manifest::ThemeManifest;
-pub use service::SpaThemeService;
-
-/// Maximum size (in bytes) of an uploaded `.sbtheme` package.
-///
-/// Re-exported by `router::api::spa_theme` for use in the multipart body
-/// limit and 413 error payload. Centralized here so the error layer can
-/// reference it without depending on the router module.
-pub const UPLOAD_LIMIT_BYTES: u64 = 25 * 1024 * 1024;
diff --git a/crates/server/src/service/spa_theme/service.rs b/crates/server/src/service/spa_theme/service.rs
deleted file mode 100644
index 48d7808d..00000000
--- a/crates/server/src/service/spa_theme/service.rs
+++ /dev/null
@@ -1,449 +0,0 @@
-use sea_orm::prelude::Expr;
-use sea_orm::{FromQueryResult, QuerySelect};
-use sea_orm::*;
-use uuid::Uuid;
-
-use crate::entity::spa_theme;
-use crate::error::AppError;
-use crate::service::config::ConfigService;
-use crate::service::spa_theme::error::SpaThemeError;
-use crate::service::spa_theme::extractor;
-use crate::service::spa_theme::loaded::LoadedTheme;
-use crate::service::spa_theme::manifest::ThemeManifest;
-
-pub const ACTIVE_SPA_THEME_KEY: &str = "active_spa_theme_uuid";
-
-pub struct SpaThemeService;
-
-#[derive(FromQueryResult)]
-struct SummaryRow {
-    uuid: String,
-    manifest_id: String,
-    name: String,
-    version: String,
-    author: Option<String>,
-    description: Option<String>,
-    size_bytes: i64,
-    uploaded_by: String,
-    uploaded_at: chrono::DateTime<chrono::Utc>,
-    is_superseded: i32,
-    preview_present: i32, // SQLite-returned boolean
-}
-
-#[derive(FromQueryResult)]
-struct VersionRow {
-    uuid: String,
-    #[allow(dead_code)]
-    manifest_id: String,
-    version: String,
-}
-
-#[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)]
-pub struct SpaThemeSummary {
-    pub uuid: String,
-    pub manifest_id: String,
-    pub name: String,
-    pub version: String,
-    pub author: Option<String>,
-    pub description: Option<String>,
-    pub size_bytes: i64,
-    pub uploaded_by: String,
-    pub uploaded_at: String,
-    pub is_active: bool,
-    pub is_superseded: bool,
-    pub has_preview: bool,
-}
-
-#[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)]
-pub struct UploadResult {
-    pub uuid: String,
-    pub manifest: serde_json::Value,
-    pub size_bytes: i64,
-    pub preview_url: Option<String>,
-    pub is_upgrade_of: Option<UpgradeOf>,
-}
-
-#[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)]
-pub struct UpgradeOf {
-    pub previous_uuid: String,
-    pub previous_version: String,
-}
-
-impl SpaThemeService {
-    fn running_version() -> semver::Version {
-        let s = env!("CARGO_PKG_VERSION");
-        semver::Version::parse(s).unwrap_or_else(|_| semver::Version::new(0, 0, 0))
-    }
-
-    pub async fn list(db: &DatabaseConnection) -> Result<Vec<SpaThemeSummary>, AppError> {
-        let active = ConfigService::get(db, ACTIVE_SPA_THEME_KEY).await?.unwrap_or_default();
-        let rows: Vec<SummaryRow> = spa_theme::Entity::find()
-            .select_only()
-            .column(spa_theme::Column::Uuid)
-            .column(spa_theme::Column::ManifestId)
-            .column(spa_theme::Column::Name)
-            .column(spa_theme::Column::Version)
-            .column(spa_theme::Column::Author)
-            .column(spa_theme::Column::Description)
-            .column(spa_theme::Column::SizeBytes)
-            .column(spa_theme::Column::UploadedBy)
-            .column(spa_theme::Column::UploadedAt)
-            .column(spa_theme::Column::IsSuperseded)
-            .column_as(
-                Expr::cust("preview_data IS NOT NULL"),
-                "preview_present",
-            )
-            .order_by_desc(spa_theme::Column::UploadedAt)
-            .into_model::<SummaryRow>()
-            .all(db)
-            .await?;
-        Ok(rows.into_iter().map(|r| SpaThemeSummary {
-            is_active: !active.is_empty() && r.uuid == active,
-            is_superseded: r.is_superseded != 0,
-            has_preview: r.preview_present != 0,
-            uuid: r.uuid,
-            manifest_id: r.manifest_id,
-            name: r.name,
-            version: r.version,
-            author: r.author,
-            description: r.description,
-            size_bytes: r.size_bytes,
-            uploaded_by: r.uploaded_by,
-            uploaded_at: r.uploaded_at.to_rfc3339(),
-        }).collect())
-    }
-
-    pub async fn get(db: &DatabaseConnection, uuid: &str) -> Result<spa_theme::Model, AppError> {
-        spa_theme::Entity::find()
-            .filter(spa_theme::Column::Uuid.eq(uuid))
-            .one(db)
-            .await?
-            .ok_or_else(|| SpaThemeError::ThemeNotFound { uuid: uuid.to_string() }.into())
-    }
-
-    pub async fn delete(db: &DatabaseConnection, uuid: &str) -> Result<(), AppError> {
-        let active = ConfigService::get(db, ACTIVE_SPA_THEME_KEY).await?.unwrap_or_default();
-        if active == uuid {
-            return Err(SpaThemeError::ThemeInUse { uuid: uuid.to_string() }.into());
-        }
-        let res = spa_theme::Entity::delete_many()
-            .filter(spa_theme::Column::Uuid.eq(uuid))
-            .exec(db)
-            .await?;
-        if res.rows_affected == 0 {
-            return Err(SpaThemeError::ThemeNotFound { uuid: uuid.to_string() }.into());
-        }
-        Ok(())
-    }
-
-    /// Validate + persist a new theme. Returns the inserted row + upgrade info.
-    pub async fn upload(
-        db: &DatabaseConnection,
-        zip_bytes: Vec<u8>,
-        uploader_user_id: &str,
-    ) -> Result<(spa_theme::Model, Option<UpgradeOf>), AppError> {
-        let extracted = extractor::extract(&zip_bytes).map_err(AppError::from)?;
-        let file_paths: std::collections::HashSet<String> = extracted.files.keys().cloned().collect();
-        let manifest = ThemeManifest::parse_and_validate(
-            &extracted.manifest_bytes,
-            &Self::running_version(),
-            &file_paths,
-        ).map_err(AppError::from)?;
-
-        // Version policy
-        let upgrade_of = Self::check_version_policy(db, &manifest).await?;
-
-        // Preview locate
-        let preview = if let Some(p) = &manifest.preview {
-            extractor::locate_preview(&extracted.files, p).map_err(AppError::from)?
-        } else { None };
-
-        let new_uuid = Uuid::new_v4().to_string();
-        let manifest_json = serde_json::to_string(&manifest).map_err(|e| AppError::Internal(e.to_string()))?;
-        let am = spa_theme::ActiveModel {
-            id: NotSet,
-            uuid: Set(new_uuid.clone()),
-            manifest_id: Set(manifest.id.clone()),
-            name: Set(manifest.name.clone()),
-            version: Set(manifest.version.clone()),
-            author: Set(manifest.author.clone()),
-            description: Set(manifest.description.clone()),
-            manifest_json: Set(manifest_json),
-            package_data: Set(zip_bytes),
-            preview_data: Set(preview.as_ref().map(|(_, b, _)| b.clone())),
-            preview_mime: Set(preview.as_ref().map(|(_, _, m)| m.clone())),
-            size_bytes: Set(extracted.total_bytes as i64),
-            uploaded_by: Set(uploader_user_id.to_string()),
-            uploaded_at: Set(chrono::Utc::now()),
-            is_superseded: Set(0),
-        };
-
-        // Transaction: mark older rows of same manifest_id as superseded, insert new.
-        let txn = db.begin().await?;
-        if upgrade_of.is_some() {
-            spa_theme::Entity::update_many()
-                .col_expr(spa_theme::Column::IsSuperseded, Expr::value(1))
-                .filter(spa_theme::Column::ManifestId.eq(manifest.id.clone()))
-                .exec(&txn).await?;
-        }
-        let inserted = am.insert(&txn).await?;
-        txn.commit().await?;
-
-        Ok((inserted, upgrade_of))
-    }
-
-    async fn check_version_policy(
-        db: &DatabaseConnection,
-        manifest: &ThemeManifest,
-    ) -> Result<Option<UpgradeOf>, AppError> {
-        let rows: Vec<VersionRow> = spa_theme::Entity::find()
-            .select_only()
-            .column(spa_theme::Column::Uuid)
-            .column(spa_theme::Column::ManifestId)
-            .column(spa_theme::Column::Version)
-            .filter(spa_theme::Column::ManifestId.eq(manifest.id.clone()))
-            .order_by_desc(spa_theme::Column::UploadedAt)
-            .into_model::<VersionRow>()
-            .all(db)
-            .await?;
-        if rows.is_empty() { return Ok(None); }
-        let uploaded = semver::Version::parse(&manifest.version)
-            .map_err(|_| SpaThemeError::InvalidManifest { field: "version", reason: "invalid semver".into() })?;
-        let mut best: Option<(semver::Version, VersionRow)> = None;
-        for r in rows {
-            if let Ok(v) = semver::Version::parse(&r.version)
-                && best.as_ref().map(|(b, _)| &v > b).unwrap_or(true)
-            {
-                best = Some((v, r));
-            }
-        }
-        let (latest_v, latest_row) = match best { Some(b) => b, None => return Ok(None) };
-        if uploaded < latest_v {
-            return Err(SpaThemeError::NoDowngrade { uploaded: uploaded.to_string(), existing: latest_v.to_string() }.into());
-        }
-        if uploaded == latest_v {
-            return Err(SpaThemeError::VersionExists { manifest_id: manifest.id.clone(), version: uploaded.to_string() }.into());
-        }
-        Ok(Some(UpgradeOf { previous_uuid: latest_row.uuid, previous_version: latest_v.to_string() }))
-    }
-
-    /// Set the active theme (uuid). None deactivates.
-    pub async fn set_active(
-        db: &DatabaseConnection,
-        slot: &crate::service::spa_theme::loaded::ActiveSpaThemeSlot,
-        uuid: Option<&str>,
-    ) -> Result<Option<String>, AppError> {
-        match uuid {
-            None => {
-                ConfigService::set(db, ACTIVE_SPA_THEME_KEY, "").await?;
-                slot.store(std::sync::Arc::new(None));
-                Ok(None)
-            }
-            Some(u) => {
-                let row = Self::get(db, u).await?;
-                let loaded = Self::load_row(&row)?;
-                ConfigService::set(db, ACTIVE_SPA_THEME_KEY, u).await?;
-                slot.store(std::sync::Arc::new(Some(loaded)));
-                Ok(Some(u.to_string()))
-            }
-        }
-    }
-
-    pub async fn active_uuid(db: &DatabaseConnection) -> Result<Option<String>, AppError> {
-        Ok(ConfigService::get(db, ACTIVE_SPA_THEME_KEY)
-            .await?
-            .filter(|s| !s.is_empty()))
-    }
-
-    pub fn load_row(row: &spa_theme::Model) -> Result<LoadedTheme, AppError> {
-        let extracted = crate::service::spa_theme::extractor::extract(&row.package_data)
-            .map_err(|e| AppError::Internal(format!("re-extract stored theme: {e}")))?;
-        let manifest: ThemeManifest = serde_json::from_str(&row.manifest_json)
-            .map_err(|e| AppError::Internal(format!("manifest json: {e}")))?;
-        Ok(LoadedTheme::from_extracted(row.uuid.clone(), manifest, extracted.files))
-    }
-
-    /// Called on server startup. If active uuid stored but row missing or zip broken,
-    /// log warning and leave slot empty (fall back to default SPA).
-    pub async fn load_on_startup(
-        db: &DatabaseConnection,
-        slot: &crate::service::spa_theme::loaded::ActiveSpaThemeSlot,
-    ) {
-        match Self::active_uuid(db).await {
-            Ok(Some(u)) => match Self::get(db, &u).await {
-                Ok(row) => match Self::load_row(&row) {
-                    Ok(loaded) => slot.store(std::sync::Arc::new(Some(loaded))),
-                    Err(e) => tracing::warn!("active SPA theme {u} failed to load: {e}; falling back to default"),
-                },
-                Err(AppError::Domain { code: "THEME_NOT_FOUND", .. }) => {
-                    tracing::warn!("active SPA theme {u} not found; falling back to default");
-                }
-                Err(e) => {
-                    tracing::warn!("active SPA theme {u} lookup failed: {e}; falling back to default");
-                }
-            },
-            Ok(None) => {}
-            Err(e) => tracing::warn!("read active spa theme key failed: {e}"),
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::migration::Migrator;
-    use sea_orm_migration::MigratorTrait;
-
-    async fn db() -> DatabaseConnection {
-        let conn = Database::connect("sqlite::memory:").await.unwrap();
-        Migrator::up(&conn, None).await.unwrap();
-        conn
-    }
-
-    fn zip_of(manifest: serde_json::Value) -> Vec<u8> {
-        use std::io::Write;
-        let mut buf = Vec::new();
-        {
-            let mut w = zip::ZipWriter::new(std::io::Cursor::new(&mut buf));
-            let opts: zip::write::SimpleFileOptions = Default::default();
-            w.start_file("manifest.json", opts).unwrap();
-            w.write_all(manifest.to_string().as_bytes()).unwrap();
-            w.start_file("index.html", opts).unwrap();
-            w.write_all(b"<html></html>").unwrap();
-            w.finish().unwrap();
-        }
-        buf
-    }
-
-    fn manifest_json(id: &str, v: &str) -> serde_json::Value {
-        // Pad id to satisfy ID_REGEX: ^[a-z][a-z0-9-]{2,63}$  (min 3 chars)
-        let padded = if id.len() < 3 { format!("{id}xx") } else { id.to_string() };
-        serde_json::json!({"schema_version":1,"id":padded,"name":id,"version":v})
-    }
-
-    async fn ensure_user(db: &DatabaseConnection, id: &str) {
-        use crate::entity::user;
-        if user::Entity::find_by_id(id.to_string()).one(db).await.unwrap().is_none() {
-            let _ = user::ActiveModel {
-                id: Set(id.to_string()),
-                username: Set(id.to_string()),
-                password_hash: Set("x".into()),
-                role: Set("admin".into()),
-                totp_secret: Set(None),
-                must_change_password: Set(false),
-                created_at: Set(chrono::Utc::now()),
-                updated_at: Set(chrono::Utc::now()),
-            }.insert(db).await;
-        }
-    }
-
-    #[tokio::test]
-    async fn upload_succeeds_and_lists() {
-        let db = db().await;
-        ensure_user(&db, "u1").await;
-        let zip = zip_of(manifest_json("acme", "1.0.0"));
-        let (m, up) = SpaThemeService::upload(&db, zip, "u1").await.unwrap();
-        assert!(up.is_none());
-        let list = SpaThemeService::list(&db).await.unwrap();
-        assert_eq!(list.len(), 1);
-        assert_eq!(list[0].uuid, m.uuid);
-        assert!(!list[0].is_active);
-    }
-
-    #[tokio::test]
-    async fn rejects_downgrade() {
-        let db = db().await; ensure_user(&db, "u1").await;
-        SpaThemeService::upload(&db, zip_of(manifest_json("a", "1.1.0")), "u1").await.unwrap();
-        let err = SpaThemeService::upload(&db, zip_of(manifest_json("a", "1.0.0")), "u1").await.unwrap_err();
-        if let AppError::Domain { code, .. } = err { assert_eq!(code, "NO_DOWNGRADE"); } else { panic!() }
-    }
-
-    #[tokio::test]
-    async fn rejects_same_version() {
-        let db = db().await; ensure_user(&db, "u1").await;
-        SpaThemeService::upload(&db, zip_of(manifest_json("a", "1.0.0")), "u1").await.unwrap();
-        let err = SpaThemeService::upload(&db, zip_of(manifest_json("a", "1.0.0")), "u1").await.unwrap_err();
-        if let AppError::Domain { code, .. } = err { assert_eq!(code, "VERSION_EXISTS"); } else { panic!() }
-    }
-
-    #[tokio::test]
-    async fn upgrade_marks_superseded() {
-        let db = db().await; ensure_user(&db, "u1").await;
-        SpaThemeService::upload(&db, zip_of(manifest_json("a", "1.0.0")), "u1").await.unwrap();
-        let (_, up) = SpaThemeService::upload(&db, zip_of(manifest_json("a", "1.1.0")), "u1").await.unwrap();
-        assert!(up.is_some());
-        let list = SpaThemeService::list(&db).await.unwrap();
-        assert_eq!(list.len(), 2);
-        let superseded: Vec<_> = list.iter().filter(|s| s.is_superseded).collect();
-        assert_eq!(superseded.len(), 1);
-        assert_eq!(superseded[0].version, "1.0.0");
-    }
-
-    #[tokio::test]
-    async fn delete_active_rejected() {
-        let db = db().await; ensure_user(&db, "u1").await;
-        let (m, _) = SpaThemeService::upload(&db, zip_of(manifest_json("a", "1.0.0")), "u1").await.unwrap();
-        ConfigService::set(&db, ACTIVE_SPA_THEME_KEY, &m.uuid).await.unwrap();
-        let err = SpaThemeService::delete(&db, &m.uuid).await.unwrap_err();
-        if let AppError::Domain { code, .. } = err { assert_eq!(code, "THEME_IN_USE"); } else { panic!() }
-    }
-
-    #[tokio::test]
-    async fn set_active_loads_into_slot() {
-        let db = db().await; ensure_user(&db, "u1").await;
-        let (m, _) = SpaThemeService::upload(&db, zip_of(manifest_json("a", "1.0.0")), "u1").await.unwrap();
-        let slot = crate::service::spa_theme::loaded::new_slot();
-        SpaThemeService::set_active(&db, &slot, Some(&m.uuid)).await.unwrap();
-        let loaded = slot.load();
-        assert!(loaded.as_ref().is_some());
-        let theme = loaded.as_ref().as_ref().unwrap();
-        assert_eq!(theme.uuid, m.uuid);
-        assert!(theme.entry_html().is_some());
-    }
-
-    #[tokio::test]
-    async fn set_none_deactivates() {
-        let db = db().await; ensure_user(&db, "u1").await;
-        let (m, _) = SpaThemeService::upload(&db, zip_of(manifest_json("a", "1.0.0")), "u1").await.unwrap();
-        let slot = crate::service::spa_theme::loaded::new_slot();
-        SpaThemeService::set_active(&db, &slot, Some(&m.uuid)).await.unwrap();
-        SpaThemeService::set_active(&db, &slot, None).await.unwrap();
-        assert!(slot.load().is_none());
-    }
-
-    #[tokio::test]
-    async fn startup_load_with_dangling_key_falls_back() {
-        let db = db().await;
-        ConfigService::set(&db, ACTIVE_SPA_THEME_KEY, "does-not-exist").await.unwrap();
-        let slot = crate::service::spa_theme::loaded::new_slot();
-        SpaThemeService::load_on_startup(&db, &slot).await;
-        assert!(slot.load().is_none());
-    }
-
-    #[tokio::test]
-    async fn startup_load_with_corrupt_blob_falls_back() {
-        let db = db().await;
-        ensure_user(&db, "u1").await;
-        spa_theme::ActiveModel {
-            id: NotSet,
-            uuid: Set("corrupt-uuid".into()),
-            manifest_id: Set("test-id".into()),
-            name: Set("Test".into()),
-            version: Set("1.0.0".into()),
-            author: Set(None),
-            description: Set(None),
-            manifest_json: Set("{}".into()),
-            package_data: Set(b"not a zip".to_vec()),
-            preview_data: Set(None),
-            preview_mime: Set(None),
-            size_bytes: Set(9),
-            uploaded_by: Set("u1".into()),
-            uploaded_at: Set(chrono::Utc::now()),
-            is_superseded: Set(0),
-        }.insert(&db).await.unwrap();
-        ConfigService::set(&db, ACTIVE_SPA_THEME_KEY, "corrupt-uuid").await.unwrap();
-        let slot = crate::service::spa_theme::loaded::new_slot();
-        SpaThemeService::load_on_startup(&db, &slot).await;
-        assert!(slot.load().is_none());
-    }
-}
diff --git a/crates/server/src/service/theme_ref.rs b/crates/server/src/service/theme_ref.rs
deleted file mode 100644
index 1fbd6db5..00000000
--- a/crates/server/src/service/theme_ref.rs
+++ /dev/null
@@ -1,301 +0,0 @@
-use sea_orm::{DatabaseConnection, EntityTrait};
-use serde::Serialize;
-
-use crate::entity::custom_theme;
-use crate::error::AppError;
-use crate::service::config::ConfigService;
-
-const PRESET_IDS: &[&str] = &[
-    "default",
-    "tokyo-night",
-    "nord",
-    "catppuccin",
-    "dracula",
-    "one-dark",
-    "solarized",
-    "rose-pine",
-];
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum ThemeRef {
-    Preset(String),
-    Custom(i32),
-}
-
-impl ThemeRef {
-    pub fn parse(s: &str) -> Result<Self, AppError> {
-        if let Some(id) = s.strip_prefix("preset:") {
-            if is_preset_id(id) {
-                return Ok(Self::Preset(id.to_string()));
-            }
-
-            return Err(AppError::Validation(format!("unknown preset: {id}")));
-        }
-
-        if let Some(rest) = s.strip_prefix("custom:") {
-            let id = parse_custom_id(rest)?;
-            return Ok(Self::Custom(id));
-        }
-
-        Err(AppError::Validation(format!("malformed theme ref: {s}")))
-    }
-
-    pub fn to_urn(&self) -> String {
-        match self {
-            Self::Preset(id) => format!("preset:{id}"),
-            Self::Custom(id) => format!("custom:{id}"),
-        }
-    }
-}
-
-fn parse_custom_id(rest: &str) -> Result<i32, AppError> {
-    if rest.is_empty() || !rest.bytes().all(|b| b.is_ascii_digit()) || rest.starts_with('0') {
-        return Err(AppError::Validation(format!("invalid custom id: {rest}")));
-    }
-
-    let id = rest
-        .parse::<i32>()
-        .map_err(|_| AppError::Validation(format!("invalid custom id: {rest}")))?;
-
-    if id > 0 {
-        Ok(id)
-    } else {
-        Err(AppError::Validation(format!("invalid custom id: {rest}")))
-    }
-}
-
-pub async fn validate_theme_ref(db: &DatabaseConnection, r: &ThemeRef) -> Result<(), AppError> {
-    match r {
-        ThemeRef::Preset(id) => {
-            if is_preset_id(id) {
-                Ok(())
-            } else {
-                Err(AppError::Validation(format!("unknown preset: {id}")))
-            }
-        }
-        ThemeRef::Custom(id) => {
-            if *id <= 0 {
-                return Err(AppError::Validation(format!("invalid custom id: {id}")));
-            }
-
-            let exists = custom_theme::Entity::find_by_id(*id)
-                .one(db)
-                .await?
-                .is_some();
-            if exists {
-                Ok(())
-            } else {
-                Err(AppError::Validation(format!("custom theme {id} not found")))
-            }
-        }
-    }
-}
-
-pub fn is_preset_id(id: &str) -> bool {
-    PRESET_IDS.contains(&id)
-}
-
-/// Where a custom theme is referenced.
-///
-/// After R1 the public status page no longer carries its own `theme_ref` —
-/// only the admin UI's active theme can pin a custom theme. The previous
-/// `status_pages: Vec<StatusPageRef>` collection has therefore been removed.
-#[derive(Debug, Clone, Serialize, utoipa::ToSchema)]
-pub struct ThemeReferences {
-    pub admin: bool,
-}
-
-pub async fn list_references(
-    db: &DatabaseConnection,
-    custom_id: i32,
-) -> Result<ThemeReferences, AppError> {
-    if custom_id <= 0 {
-        return Err(AppError::Validation(format!(
-            "invalid custom id: {custom_id}"
-        )));
-    }
-
-    let urn = ThemeRef::Custom(custom_id).to_urn();
-    let active_admin_theme = ConfigService::get(db, "active_admin_theme").await?;
-
-    Ok(ThemeReferences {
-        admin: active_admin_theme.as_deref() == Some(urn.as_str()),
-    })
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::test_utils::setup_test_db;
-
-    #[test]
-    fn parses_preset() {
-        assert_eq!(
-            ThemeRef::parse("preset:tokyo-night").expect("preset should parse"),
-            ThemeRef::Preset("tokyo-night".to_string())
-        );
-    }
-
-    #[test]
-    fn parses_custom() {
-        assert_eq!(
-            ThemeRef::parse("custom:42").expect("custom ref should parse"),
-            ThemeRef::Custom(42)
-        );
-    }
-
-    #[test]
-    fn rejects_unknown_preset() {
-        let err = ThemeRef::parse("preset:not-real").expect_err("unknown preset should fail");
-        assert!(
-            matches!(err, AppError::Validation(message) if message == "unknown preset: not-real")
-        );
-    }
-
-    #[test]
-    fn rejects_empty_preset() {
-        let err = ThemeRef::parse("preset:").expect_err("empty preset should fail");
-        assert!(matches!(err, AppError::Validation(message) if message == "unknown preset: "));
-    }
-
-    #[test]
-    fn rejects_bad_custom_id() {
-        let err = ThemeRef::parse("custom:nope").expect_err("bad custom id should fail");
-        assert!(
-            matches!(err, AppError::Validation(message) if message == "invalid custom id: nope")
-        );
-    }
-
-    #[test]
-    fn rejects_empty_custom_id() {
-        let err = ThemeRef::parse("custom:").expect_err("empty custom id should fail");
-        assert!(matches!(err, AppError::Validation(message) if message == "invalid custom id: "));
-    }
-
-    #[test]
-    fn rejects_zero_custom_id() {
-        let err = ThemeRef::parse("custom:0").expect_err("zero custom id should fail");
-        assert!(matches!(err, AppError::Validation(message) if message == "invalid custom id: 0"));
-    }
-
-    #[test]
-    fn rejects_negative_custom_id() {
-        let err = ThemeRef::parse("custom:-1").expect_err("negative custom id should fail");
-        assert!(matches!(err, AppError::Validation(message) if message == "invalid custom id: -1"));
-    }
-
-    #[test]
-    fn rejects_plus_custom_id() {
-        let err = ThemeRef::parse("custom:+1").expect_err("plus custom id should fail");
-        assert!(matches!(err, AppError::Validation(message) if message == "invalid custom id: +1"));
-    }
-
-    #[test]
-    fn rejects_leading_zero_custom_id() {
-        let err = ThemeRef::parse("custom:001").expect_err("leading zero custom id should fail");
-        assert!(
-            matches!(err, AppError::Validation(message) if message == "invalid custom id: 001")
-        );
-    }
-
-    #[test]
-    fn rejects_overflow_custom_id() {
-        let err = ThemeRef::parse("custom:2147483648").expect_err("overflow custom id should fail");
-        assert!(
-            matches!(err, AppError::Validation(message) if message == "invalid custom id: 2147483648")
-        );
-    }
-
-    #[test]
-    fn rejects_whitespace_wrapped_ref() {
-        let err = ThemeRef::parse(" custom:1").expect_err("leading whitespace should fail");
-        assert!(
-            matches!(err, AppError::Validation(message) if message == "malformed theme ref:  custom:1")
-        );
-
-        let err = ThemeRef::parse("custom:1 ").expect_err("trailing whitespace should fail");
-        assert!(matches!(err, AppError::Validation(message) if message == "invalid custom id: 1 "));
-    }
-
-    #[test]
-    fn rejects_unknown_scheme() {
-        let err = ThemeRef::parse("theme:default").expect_err("unknown scheme should fail");
-        assert!(
-            matches!(err, AppError::Validation(message) if message == "malformed theme ref: theme:default")
-        );
-    }
-
-    #[test]
-    fn round_trips_urn() {
-        let refs = [ThemeRef::Preset("default".to_string()), ThemeRef::Custom(7)];
-
-        for theme_ref in refs {
-            assert_eq!(
-                ThemeRef::parse(&theme_ref.to_urn()).expect("serialized ref should parse"),
-                theme_ref
-            );
-        }
-    }
-
-    #[tokio::test]
-    async fn validate_theme_ref_rejects_directly_constructed_unknown_preset() {
-        let (db, _tmp) = setup_test_db().await;
-
-        let err = validate_theme_ref(&db, &ThemeRef::Preset("nonsense".to_string()))
-            .await
-            .expect_err("unknown preset should fail validation");
-
-        assert!(
-            matches!(err, AppError::Validation(message) if message == "unknown preset: nonsense")
-        );
-    }
-
-    #[tokio::test]
-    async fn validate_theme_ref_rejects_directly_constructed_zero_custom_id() {
-        let (db, _tmp) = setup_test_db().await;
-
-        let err = validate_theme_ref(&db, &ThemeRef::Custom(0))
-            .await
-            .expect_err("zero custom id should fail validation");
-
-        assert!(matches!(err, AppError::Validation(message) if message == "invalid custom id: 0"));
-    }
-
-    #[tokio::test]
-    async fn validate_theme_ref_rejects_directly_constructed_negative_custom_id() {
-        let (db, _tmp) = setup_test_db().await;
-
-        let err = validate_theme_ref(&db, &ThemeRef::Custom(-1))
-            .await
-            .expect_err("negative custom id should fail validation");
-
-        assert!(matches!(err, AppError::Validation(message) if message == "invalid custom id: -1"));
-    }
-
-    #[tokio::test]
-    async fn list_references_rejects_zero_custom_id() {
-        let (db, _tmp) = setup_test_db().await;
-
-        let err = list_references(&db, 0)
-            .await
-            .expect_err("zero custom id should fail");
-
-        assert!(matches!(err, AppError::Validation(message) if message == "invalid custom id: 0"));
-    }
-
-    #[tokio::test]
-    async fn list_references_rejects_negative_custom_id() {
-        let (db, _tmp) = setup_test_db().await;
-
-        let err = list_references(&db, -1)
-            .await
-            .expect_err("negative custom id should fail");
-
-        assert!(matches!(err, AppError::Validation(message) if message == "invalid custom id: -1"));
-    }
-
-    // NOTE: The legacy `list_references_orders_status_pages_by_title_then_id`
-    // test was removed in R4 along with the multi-status-page admin surface —
-    // `ThemeReferences` no longer carries a `status_pages` collection because
-    // the singleton status page no longer pins its own theme.
-}
diff --git a/crates/server/src/service/theme_validator.rs b/crates/server/src/service/theme_validator.rs
deleted file mode 100644
index 6321afbe..00000000
--- a/crates/server/src/service/theme_validator.rs
+++ /dev/null
@@ -1,356 +0,0 @@
-use std::collections::{HashMap, HashSet};
-
-use once_cell::sync::Lazy;
-use regex::Regex;
-
-use crate::error::AppError;
-
-pub const REQUIRED_VARS: &[&str] = &[
-    "background",
-    "foreground",
-    "card",
-    "card-foreground",
-    "popover",
-    "popover-foreground",
-    "primary",
-    "primary-foreground",
-    "secondary",
-    "secondary-foreground",
-    "muted",
-    "muted-foreground",
-    "accent",
-    "accent-foreground",
-    "destructive",
-    "border",
-    "input",
-    "ring",
-    "chart-1",
-    "chart-2",
-    "chart-3",
-    "chart-4",
-    "chart-5",
-    "sidebar",
-    "sidebar-foreground",
-    "sidebar-primary",
-    "sidebar-primary-foreground",
-    "sidebar-accent",
-    "sidebar-accent-foreground",
-    "sidebar-border",
-    "sidebar-ring",
-];
-
-static OKLCH_RE: Lazy<Regex> = Lazy::new(|| {
-    Regex::new(r"^oklch\(\s*([\d.]+)\s+([\d.]+)\s+([\d.]+)(?:\s*/\s*([\d.]+)(%)?)?\s*\)$")
-        .expect("static regex")
-});
-
-pub type VarMap = HashMap<String, String>;
-
-pub fn validate_var_map(map: &VarMap) -> Result<(), AppError> {
-    let required: HashSet<&str> = REQUIRED_VARS.iter().copied().collect();
-
-    if let Some(missing) = REQUIRED_VARS.iter().find(|key| !map.contains_key(**key)) {
-        return Err(AppError::Validation(format!("missing variable: {missing}")));
-    }
-
-    let mut unknown_keys = map
-        .keys()
-        .filter(|key| !required.contains(key.as_str()))
-        .map(String::as_str)
-        .collect::<Vec<_>>();
-    unknown_keys.sort_unstable();
-
-    if let Some(extra) = unknown_keys.first() {
-        return Err(AppError::Validation(format!("unknown variable: {extra}")));
-    }
-
-    for key in REQUIRED_VARS {
-        let Some(value) = map.get(*key) else {
-            return Err(AppError::Validation(format!("missing variable: {key}")));
-        };
-        validate_oklch_value(key, value)?;
-    }
-
-    Ok(())
-}
-
-fn validate_oklch_value(key: &str, value: &str) -> Result<(), AppError> {
-    let Some(captures) = OKLCH_RE.captures(value) else {
-        return Err(AppError::Validation(format!(
-            "{key} must be an oklch(L C H) value"
-        )));
-    };
-
-    let lightness = parse_finite_capture(key, value, captures.get(1), "lightness")?;
-    parse_finite_capture(key, value, captures.get(2), "chroma")?;
-    let hue = parse_finite_capture(key, value, captures.get(3), "hue")?;
-
-    if !(0.0..=1.0).contains(&lightness) {
-        return Err(AppError::Validation(format!(
-            "{key} lightness must be between 0 and 1"
-        )));
-    }
-
-    if !(0.0..=360.0).contains(&hue) {
-        return Err(AppError::Validation(format!(
-            "{key} hue must be between 0 and 360"
-        )));
-    }
-
-    if let Some(alpha_match) = captures.get(4) {
-        let alpha = parse_finite_capture(key, value, Some(alpha_match), "alpha")?;
-        let has_percent = captures.get(5).is_some();
-        let valid_alpha = if has_percent {
-            (0.0..=100.0).contains(&alpha)
-        } else {
-            (0.0..=1.0).contains(&alpha)
-        };
-
-        if !valid_alpha {
-            let range = if has_percent { "0 and 100%" } else { "0 and 1" };
-            return Err(AppError::Validation(format!(
-                "{key} alpha must be between {range}"
-            )));
-        }
-    }
-
-    Ok(())
-}
-
-fn parse_finite_capture(
-    key: &str,
-    value: &str,
-    capture: Option<regex::Match<'_>>,
-    component: &str,
-) -> Result<f64, AppError> {
-    let Some(capture) = capture else {
-        return Err(AppError::Validation(format!(
-            "{key} has invalid {component} in {value}"
-        )));
-    };
-
-    let value = capture
-        .as_str()
-        .parse::<f64>()
-        .map_err(|_| AppError::Validation(format!("{key} has invalid {component} in {value}")))?;
-
-    if !value.is_finite() {
-        return Err(AppError::Validation(format!(
-            "{key}: {component} not finite"
-        )));
-    }
-
-    Ok(value)
-}
-
-#[cfg(test)]
-mod tests {
-    use crate::error::AppError;
-
-    use super::{REQUIRED_VARS, VarMap, validate_var_map};
-
-    fn valid_map() -> VarMap {
-        REQUIRED_VARS
-            .iter()
-            .map(|key| ((*key).to_string(), "oklch(0.5 0.1 180)".to_string()))
-            .collect()
-    }
-
-    fn validation_message(result: Result<(), AppError>) -> String {
-        match result {
-            Err(AppError::Validation(message)) => message,
-            other => panic!("expected validation error, got {other:?}"),
-        }
-    }
-
-    #[test]
-    fn accepts_valid_full_map() {
-        let map = valid_map();
-
-        assert!(validate_var_map(&map).is_ok());
-    }
-
-    #[test]
-    fn accepts_alpha_number() {
-        let mut map = valid_map();
-        map.insert(
-            "background".to_string(),
-            "oklch(0.5 0.1 180 / 0.75)".to_string(),
-        );
-
-        assert!(validate_var_map(&map).is_ok());
-    }
-
-    #[test]
-    fn accepts_alpha_percent() {
-        let mut map = valid_map();
-        map.insert(
-            "background".to_string(),
-            "oklch(0.5 0.1 180 / 75%)".to_string(),
-        );
-
-        assert!(validate_var_map(&map).is_ok());
-    }
-
-    #[test]
-    fn rejects_missing_var() {
-        let mut map = valid_map();
-        map.remove("background");
-
-        let message = validation_message(validate_var_map(&map));
-
-        assert!(message.contains("missing variable: background"));
-    }
-
-    #[test]
-    fn rejects_unknown_var() {
-        let mut map = valid_map();
-        map.insert("unknown".to_string(), "oklch(0.5 0.1 180)".to_string());
-
-        let message = validation_message(validate_var_map(&map));
-
-        assert!(message.contains("unknown variable: unknown"));
-    }
-
-    #[test]
-    fn rejects_l_out_of_range() {
-        let mut map = valid_map();
-        map.insert("background".to_string(), "oklch(1.1 0.1 180)".to_string());
-
-        let message = validation_message(validate_var_map(&map));
-
-        assert!(message.contains("background"));
-        assert!(message.contains("lightness"));
-    }
-
-    #[test]
-    fn rejects_h_out_of_range() {
-        let mut map = valid_map();
-        map.insert("background".to_string(), "oklch(0.5 0.1 361)".to_string());
-
-        let message = validation_message(validate_var_map(&map));
-
-        assert!(message.contains("background"));
-        assert!(message.contains("hue"));
-    }
-
-    #[test]
-    fn allows_high_chroma() {
-        let mut map = valid_map();
-        map.insert("background".to_string(), "oklch(0.5 999 180)".to_string());
-
-        assert!(validate_var_map(&map).is_ok());
-    }
-
-    #[test]
-    fn rejects_alpha_over_one() {
-        let mut map = valid_map();
-        map.insert(
-            "background".to_string(),
-            "oklch(0.5 0.1 180 / 1.1)".to_string(),
-        );
-
-        let message = validation_message(validate_var_map(&map));
-
-        assert!(message.contains("background"));
-        assert!(message.contains("alpha"));
-    }
-
-    #[test]
-    fn rejects_alpha_percent_over_hundred() {
-        let mut map = valid_map();
-        map.insert(
-            "background".to_string(),
-            "oklch(0.5 0.1 180 / 101%)".to_string(),
-        );
-
-        let message = validation_message(validate_var_map(&map));
-
-        assert!(message.contains("background"));
-        assert!(message.contains("alpha"));
-    }
-
-    #[test]
-    fn rejects_malformed_numeric_component() {
-        let mut map = valid_map();
-        map.insert("background".to_string(), "oklch(0.5 1..2 180)".to_string());
-
-        let message = validation_message(validate_var_map(&map));
-
-        assert!(message.contains("background"));
-    }
-
-    #[test]
-    fn rejects_css_injection_attempt() {
-        let mut map = valid_map();
-        map.insert(
-            "background".to_string(),
-            "oklch(0.5 0.1 180); color:red".to_string(),
-        );
-
-        let message = validation_message(validate_var_map(&map));
-
-        assert!(message.contains("background"));
-    }
-
-    #[test]
-    fn rejects_negative_values() {
-        let mut map = valid_map();
-        map.insert("background".to_string(), "oklch(-0.1 0.1 180)".to_string());
-
-        let message = validation_message(validate_var_map(&map));
-
-        assert!(message.contains("background"));
-    }
-
-    #[test]
-    fn rejects_alpha_percent_below_zero() {
-        let mut map = valid_map();
-        map.insert(
-            "background".to_string(),
-            "oklch(0.5 0.1 180 / -1%)".to_string(),
-        );
-
-        let message = validation_message(validate_var_map(&map));
-
-        assert!(message.contains("background"));
-    }
-
-    #[test]
-    fn rejects_infinite_chroma() {
-        let mut map = valid_map();
-        let huge_chroma = "9".repeat(500);
-        map.insert(
-            "background".to_string(),
-            format!("oklch(0.5 {huge_chroma} 180)"),
-        );
-
-        let message = validation_message(validate_var_map(&map));
-
-        assert!(message.contains("background"));
-        assert!(message.contains("chroma"));
-        assert!(message.contains("finite"));
-    }
-
-    #[test]
-    fn rejects_first_required_missing_variable_deterministically() {
-        let mut map = valid_map();
-        map.remove("background");
-        map.remove("foreground");
-
-        let message = validation_message(validate_var_map(&map));
-
-        assert!(message.contains("missing variable: background"));
-    }
-
-    #[test]
-    fn rejects_alphabetically_first_unknown_variable_deterministically() {
-        let mut map = valid_map();
-        map.insert("z-unknown".to_string(), "oklch(0.5 0.1 180)".to_string());
-        map.insert("a-unknown".to_string(), "oklch(0.5 0.1 180)".to_string());
-
-        let message = validation_message(validate_var_map(&map));
-
-        assert!(message.contains("unknown variable: a-unknown"));
-    }
-}
diff --git a/crates/server/src/state.rs b/crates/server/src/state.rs
index 8c37e3e8..d1d5ee5e 100644
--- a/crates/server/src/state.rs
+++ b/crates/server/src/state.rs
@@ -88,8 +88,6 @@ pub struct AppState {
     pub exec_audit_contexts: DashMap<String, ExecAuditContext>,
     /// DNS PTR enricher for traceroute hops (shared across requests).
     pub traceroute_enricher: crate::service::traceroute_enrich::TracerouteEnricher,
-    /// Currently active custom SPA theme (hot-swappable, None = default built-in SPA).
-    pub active_spa_theme: crate::service::spa_theme::loaded::ActiveSpaThemeSlot,
 }
 
 static RATE_CHECK_COUNTER: AtomicU64 = AtomicU64::new(0);
@@ -213,8 +211,6 @@ impl AppState {
         let asn_arc = Arc::new(std::sync::RwLock::new(asn));
         let traceroute_enricher =
             crate::service::traceroute_enrich::TracerouteEnricher::new().with_asn(asn_arc.clone());
-        let active_spa_theme = crate::service::spa_theme::loaded::new_slot();
-        crate::service::spa_theme::SpaThemeService::load_on_startup(&db, &active_spa_theme).await;
         Ok(Arc::new(Self {
             db,
             agent_manager,
@@ -242,7 +238,6 @@ impl AppState {
             docker_logs_audit_contexts: DashMap::new(),
             exec_audit_contexts: DashMap::new(),
             traceroute_enricher,
-            active_spa_theme,
         }))
     }
 }
diff --git a/crates/server/tests/custom_theme_integration.rs b/crates/server/tests/custom_theme_integration.rs
deleted file mode 100644
index 1f280d58..00000000
--- a/crates/server/tests/custom_theme_integration.rs
+++ /dev/null
@@ -1,445 +0,0 @@
-use std::time::Duration;
-
-use reqwest::{Client, Method, StatusCode};
-use sea_orm::{ConnectOptions, ConnectionTrait, Database};
-use sea_orm_migration::MigratorTrait;
-use serde_json::{Value, json};
-use serverbee_server::config::{AppConfig, AuthConfig, DatabaseConfig, ServerConfig};
-use serverbee_server::migration::Migrator;
-use serverbee_server::router::create_router;
-use serverbee_server::service::auth::AuthService;
-use serverbee_server::state::AppState;
-
-const LIGHT_VALUE: &str = "oklch(0.5 0.1 180)";
-const DARK_VALUE: &str = "oklch(0.3 0.1 180)";
-
-async fn start_test_server(create_member: bool) -> (String, tempfile::TempDir) {
-    let tmp = tempfile::tempdir().expect("Failed to create temp dir");
-    let data_dir = tmp.path().to_str().unwrap().to_string();
-
-    let config = AppConfig {
-        server: ServerConfig {
-            listen: "127.0.0.1:0".to_string(),
-            data_dir: data_dir.clone(),
-            trusted_proxies: Vec::new(),
-        },
-        database: DatabaseConfig {
-            path: "test.db".to_string(),
-            max_connections: 5,
-        },
-        auth: AuthConfig {
-            session_ttl: 86400,
-            secure_cookie: false,
-            max_servers: 0,
-        },
-        ..AppConfig::default()
-    };
-
-    let db_path = format!("{data_dir}/test.db");
-    let db_url = format!("sqlite://{db_path}?mode=rwc");
-    let mut opt = ConnectOptions::new(&db_url);
-    opt.max_connections(5);
-    opt.sqlx_logging(false);
-
-    let db = Database::connect(opt)
-        .await
-        .expect("Failed to connect to test database");
-
-    db.execute_unprepared("PRAGMA journal_mode=WAL")
-        .await
-        .expect("Failed to enable WAL");
-    db.execute_unprepared("PRAGMA foreign_keys=ON")
-        .await
-        .expect("Failed to enable foreign keys");
-
-    Migrator::up(&db, None)
-        .await
-        .expect("Failed to run migrations");
-
-    AuthService::create_user(&db, "admin", "testpass", "admin")
-        .await
-        .expect("Failed to seed admin");
-
-    if create_member {
-        AuthService::create_user(&db, "member", "memberpass", "member")
-            .await
-            .expect("Failed to create member");
-    }
-
-    let state = AppState::new(db, config)
-        .await
-        .expect("Failed to create AppState");
-    let app = create_router(state);
-
-    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
-        .await
-        .expect("Failed to bind listener");
-    let addr = listener
-        .local_addr()
-        .expect("Failed to read listener address");
-    let base_url = format!("http://{addr}");
-
-    tokio::spawn(async move {
-        axum::serve(
-            listener,
-            app.into_make_service_with_connect_info::<std::net::SocketAddr>(),
-        )
-        .await
-        .expect("Test server failed");
-    });
-
-    tokio::time::sleep(Duration::from_millis(50)).await;
-
-    (base_url, tmp)
-}
-
-fn http_client() -> Client {
-    Client::builder()
-        .cookie_store(true)
-        .timeout(Duration::from_secs(10))
-        .build()
-        .expect("Failed to build HTTP client")
-}
-
-async fn login(client: &Client, base_url: &str, username: &str, password: &str) {
-    let resp = client
-        .post(format!("{base_url}/api/auth/login"))
-        .json(&json!({
-            "username": username,
-            "password": password,
-        }))
-        .send()
-        .await
-        .expect("Login request failed");
-
-    assert_eq!(resp.status(), StatusCode::OK, "Login should succeed");
-}
-
-async fn admin_login(client: &Client, base_url: &str) {
-    login(client, base_url, "admin", "testpass").await;
-}
-
-async fn member_login(client: &Client, base_url: &str) {
-    login(client, base_url, "member", "memberpass").await;
-}
-
-async fn request_json(
-    client: &Client,
-    method: Method,
-    url: String,
-    body: Option<Value>,
-) -> (StatusCode, Value) {
-    let mut request = client.request(method, url);
-    if let Some(body) = body {
-        request = request.json(&body);
-    }
-
-    let resp = request.send().await.expect("Request failed");
-    let status = resp.status();
-    let bytes = resp.bytes().await.expect("Failed to read response body");
-    let body = if bytes.is_empty() {
-        Value::Null
-    } else {
-        serde_json::from_slice(&bytes)
-            .unwrap_or_else(|_| Value::String(String::from_utf8_lossy(&bytes).into_owned()))
-    };
-
-    (status, body)
-}
-
-fn full_vars(value: &str) -> Value {
-    let keys = [
-        "background",
-        "foreground",
-        "card",
-        "card-foreground",
-        "popover",
-        "popover-foreground",
-        "primary",
-        "primary-foreground",
-        "secondary",
-        "secondary-foreground",
-        "muted",
-        "muted-foreground",
-        "accent",
-        "accent-foreground",
-        "destructive",
-        "border",
-        "input",
-        "ring",
-        "chart-1",
-        "chart-2",
-        "chart-3",
-        "chart-4",
-        "chart-5",
-        "sidebar",
-        "sidebar-foreground",
-        "sidebar-primary",
-        "sidebar-primary-foreground",
-        "sidebar-accent",
-        "sidebar-accent-foreground",
-        "sidebar-border",
-        "sidebar-ring",
-    ];
-    let mut m = serde_json::Map::new();
-    for k in keys {
-        m.insert(k.to_string(), Value::String(value.to_string()));
-    }
-    Value::Object(m)
-}
-
-fn theme_body(name: &str) -> Value {
-    json!({
-        "name": name,
-        "description": "Integration test theme",
-        "based_on": "default",
-        "vars_light": full_vars(LIGHT_VALUE),
-        "vars_dark": full_vars(DARK_VALUE),
-    })
-}
-
-async fn create_theme(client: &Client, base_url: &str, name: &str) -> Value {
-    let (status, body) = request_json(
-        client,
-        Method::POST,
-        format!("{base_url}/api/settings/themes"),
-        Some(theme_body(name)),
-    )
-    .await;
-
-    assert_eq!(
-        status,
-        StatusCode::OK,
-        "Theme creation should succeed: {body}"
-    );
-    body["data"].clone()
-}
-
-#[tokio::test]
-async fn admin_can_create_get_update_delete_theme() {
-    let (base_url, _tmp) = start_test_server(false).await;
-    let client = http_client();
-    admin_login(&client, &base_url).await;
-
-    let created = create_theme(&client, &base_url, "Ocean").await;
-    let id = created["id"]
-        .as_i64()
-        .expect("Created theme should have id");
-
-    let (get_status, fetched) = request_json(
-        &client,
-        Method::GET,
-        format!("{base_url}/api/settings/themes/{id}"),
-        None,
-    )
-    .await;
-    assert_eq!(get_status, StatusCode::OK);
-    assert_eq!(fetched["data"]["name"], "Ocean");
-
-    let (list_status, listed) = request_json(
-        &client,
-        Method::GET,
-        format!("{base_url}/api/settings/themes"),
-        None,
-    )
-    .await;
-    assert_eq!(list_status, StatusCode::OK);
-    let themes = listed["data"]
-        .as_array()
-        .expect("Theme list should be an array");
-    assert!(
-        themes.iter().any(|theme| theme["id"].as_i64() == Some(id)),
-        "Theme list should contain created id: {listed}"
-    );
-
-    let (update_status, updated) = request_json(
-        &client,
-        Method::PUT,
-        format!("{base_url}/api/settings/themes/{id}"),
-        Some(theme_body("Ocean Updated")),
-    )
-    .await;
-    assert_eq!(update_status, StatusCode::OK);
-    assert_eq!(updated["data"]["name"], "Ocean Updated");
-
-    let (duplicate_status, duplicated) = request_json(
-        &client,
-        Method::POST,
-        format!("{base_url}/api/settings/themes/{id}/duplicate"),
-        None,
-    )
-    .await;
-    assert_eq!(duplicate_status, StatusCode::OK);
-    let copied_name = duplicated["data"]["name"]
-        .as_str()
-        .expect("Copied theme should have a name");
-    assert!(
-        copied_name.ends_with("(copy)"),
-        "Copied name should end with (copy): {copied_name}"
-    );
-
-    let (delete_status, deleted) = request_json(
-        &client,
-        Method::DELETE,
-        format!("{base_url}/api/settings/themes/{id}"),
-        None,
-    )
-    .await;
-    assert_eq!(
-        delete_status,
-        StatusCode::OK,
-        "Delete should succeed: {deleted}"
-    );
-
-    let (missing_status, _) = request_json(
-        &client,
-        Method::GET,
-        format!("{base_url}/api/settings/themes/{id}"),
-        None,
-    )
-    .await;
-    assert_eq!(missing_status, StatusCode::NOT_FOUND);
-}
-
-#[tokio::test]
-async fn member_cannot_write_themes() {
-    let (base_url, _tmp) = start_test_server(true).await;
-    let client = http_client();
-    member_login(&client, &base_url).await;
-
-    let (status, _) = request_json(
-        &client,
-        Method::POST,
-        format!("{base_url}/api/settings/themes"),
-        Some(theme_body("Member Theme")),
-    )
-    .await;
-
-    assert_eq!(status, StatusCode::FORBIDDEN);
-}
-
-#[tokio::test]
-async fn rejects_missing_variable() {
-    let (base_url, _tmp) = start_test_server(false).await;
-    let client = http_client();
-    admin_login(&client, &base_url).await;
-
-    let mut body = theme_body("Broken Theme");
-    body["vars_light"]
-        .as_object_mut()
-        .expect("vars_light should be an object")
-        .remove("background");
-
-    let (status, response) = request_json(
-        &client,
-        Method::POST,
-        format!("{base_url}/api/settings/themes"),
-        Some(body),
-    )
-    .await;
-
-    assert_eq!(
-        status,
-        StatusCode::UNPROCESSABLE_ENTITY,
-        "Missing variable should be rejected: {response}"
-    );
-}
-
-#[tokio::test]
-async fn delete_blocked_when_theme_is_active() {
-    let (base_url, _tmp) = start_test_server(false).await;
-    let client = http_client();
-    admin_login(&client, &base_url).await;
-
-    let created = create_theme(&client, &base_url, "Active Ocean").await;
-    let id = created["id"]
-        .as_i64()
-        .expect("Created theme should have id");
-
-    let (activate_status, _) = request_json(
-        &client,
-        Method::PUT,
-        format!("{base_url}/api/settings/active-theme"),
-        Some(json!({ "ref": format!("custom:{id}") })),
-    )
-    .await;
-    assert_eq!(activate_status, StatusCode::OK);
-
-    let (blocked_status, blocked) = request_json(
-        &client,
-        Method::DELETE,
-        format!("{base_url}/api/settings/themes/{id}"),
-        None,
-    )
-    .await;
-    assert_eq!(
-        blocked_status,
-        StatusCode::CONFLICT,
-        "Active theme delete should be blocked: {blocked}"
-    );
-
-    let (reset_status, _) = request_json(
-        &client,
-        Method::PUT,
-        format!("{base_url}/api/settings/active-theme"),
-        Some(json!({ "ref": "preset:default" })),
-    )
-    .await;
-    assert_eq!(reset_status, StatusCode::OK);
-
-    let (delete_status, deleted) = request_json(
-        &client,
-        Method::DELETE,
-        format!("{base_url}/api/settings/themes/{id}"),
-        None,
-    )
-    .await;
-    assert_eq!(
-        delete_status,
-        StatusCode::OK,
-        "Delete should succeed: {deleted}"
-    );
-}
-
-#[tokio::test]
-async fn active_theme_returns_resolved_payload() {
-    let (base_url, _tmp) = start_test_server(false).await;
-    let client = http_client();
-    admin_login(&client, &base_url).await;
-
-    let created = create_theme(&client, &base_url, "Resolved Ocean").await;
-    let id = created["id"]
-        .as_i64()
-        .expect("Created theme should have id");
-
-    let (activate_status, _) = request_json(
-        &client,
-        Method::PUT,
-        format!("{base_url}/api/settings/active-theme"),
-        Some(json!({ "ref": format!("custom:{id}") })),
-    )
-    .await;
-    assert_eq!(activate_status, StatusCode::OK);
-
-    let (status, active) = request_json(
-        &client,
-        Method::GET,
-        format!("{base_url}/api/settings/active-theme"),
-        None,
-    )
-    .await;
-
-    assert_eq!(status, StatusCode::OK);
-    assert_eq!(active["data"]["ref"], format!("custom:{id}"));
-    assert_eq!(active["data"]["theme"]["kind"], "custom");
-    assert_eq!(active["data"]["theme"]["id"], id);
-    assert_eq!(active["data"]["theme"]["name"], "Resolved Ocean");
-    assert_eq!(
-        active["data"]["theme"]["vars_light"]["background"],
-        LIGHT_VALUE
-    );
-    assert_eq!(
-        active["data"]["theme"]["vars_dark"]["background"],
-        DARK_VALUE
-    );
-}
diff --git a/crates/server/tests/spa_theme_integration.rs b/crates/server/tests/spa_theme_integration.rs
deleted file mode 100644
index 0f230611..00000000
--- a/crates/server/tests/spa_theme_integration.rs
+++ /dev/null
@@ -1,669 +0,0 @@
-/// Integration test suite for the Custom SPA Theme feature.
-///
-/// Covers all 16 scenarios from plan Task 16:
-///  1.  Non-admin POST → 403
-///  2.  Admin upload valid fixture → 200, uuid + manifest
-///  3.  Upload same id + higher version → 200 + is_upgrade_of set
-///  4.  Upload same id + lower version → 400 NO_DOWNGRADE
-///  5.  Upload same id + same version → 409 VERSION_EXISTS
-///  6.  Admin activate via PUT → 200; GET / returns theme body
-///  7.  GET /?theme=default returns default SPA body + sets sb_force_default cookie
-///  8.  Subsequent GET / with sb_force_default cookie returns default
-///  9.  GET /?theme=active clears cookie and returns active theme
-/// 10.  GET /?theme=preview:<uuid> as admin returns that theme + sets sb_preview_theme cookie
-/// 11.  Same preview query as non-admin returns active (preview ignored)
-/// 12.  DELETE active theme → 409 THEME_IN_USE
-/// 13.  DELETE inactive theme → 204; row removed
-/// 14.  Upload zip-slip fixture → 400 ZIP_SLIP
-/// 15.  Upload zip-bomb fixture → 400 ZIP_BOMB
-/// 16.  Upload package > 25 MB → 413 UPLOAD_TOO_LARGE
-use std::time::Duration;
-
-use reqwest::{Client, StatusCode, multipart};
-use sea_orm::{ConnectOptions, ConnectionTrait, Database};
-use sea_orm_migration::MigratorTrait;
-use serde_json::{Value, json};
-use serverbee_server::config::{AppConfig, AuthConfig, DatabaseConfig, ServerConfig};
-use serverbee_server::migration::Migrator;
-use serverbee_server::router::create_router;
-use serverbee_server::service::auth::AuthService;
-use serverbee_server::state::AppState;
-
-// ---------------------------------------------------------------------------
-// Bootstrap helpers
-// ---------------------------------------------------------------------------
-
-/// Start a test server. If `create_member` is true, also seeds `member/memberpass`.
-async fn start_test_server(create_member: bool) -> (String, tempfile::TempDir) {
-    let tmp = tempfile::tempdir().expect("Failed to create temp dir");
-    let data_dir = tmp.path().to_str().unwrap().to_string();
-
-    let config = AppConfig {
-        server: ServerConfig {
-            listen: "127.0.0.1:0".to_string(),
-            data_dir: data_dir.clone(),
-            trusted_proxies: Vec::new(),
-        },
-        database: DatabaseConfig {
-            path: "test.db".to_string(),
-            max_connections: 5,
-        },
-        auth: AuthConfig {
-            session_ttl: 86400,
-            secure_cookie: false,
-            max_servers: 0,
-        },
-        ..AppConfig::default()
-    };
-
-    let db_path = format!("{data_dir}/test.db");
-    let db_url = format!("sqlite://{db_path}?mode=rwc");
-    let mut opt = ConnectOptions::new(&db_url);
-    opt.max_connections(5);
-    opt.sqlx_logging(false);
-
-    let db = Database::connect(opt)
-        .await
-        .expect("Failed to connect to test database");
-
-    db.execute_unprepared("PRAGMA journal_mode=WAL").await.unwrap();
-    db.execute_unprepared("PRAGMA foreign_keys=ON").await.unwrap();
-
-    Migrator::up(&db, None).await.expect("Failed to run migrations");
-
-    AuthService::create_user(&db, "admin", "testpass", "admin")
-        .await
-        .expect("Failed to seed admin");
-
-    if create_member {
-        AuthService::create_user(&db, "member", "memberpass", "member")
-            .await
-            .expect("Failed to seed member");
-    }
-
-    let state = AppState::new(db, config).await.expect("Failed to create AppState");
-    let app = create_router(state);
-
-    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
-        .await
-        .expect("Failed to bind listener");
-    let addr = listener.local_addr().unwrap();
-    let base_url = format!("http://{addr}");
-
-    tokio::spawn(async move {
-        axum::serve(listener, app.into_make_service_with_connect_info::<std::net::SocketAddr>())
-            .await
-            .unwrap();
-    });
-
-    tokio::time::sleep(Duration::from_millis(50)).await;
-    (base_url, tmp)
-}
-
-fn http_client() -> Client {
-    Client::builder()
-        .cookie_store(true)
-        .timeout(Duration::from_secs(15))
-        .build()
-        .expect("Failed to build HTTP client")
-}
-
-async fn login(client: &Client, base_url: &str, username: &str, password: &str) {
-    let resp = client
-        .post(format!("{base_url}/api/auth/login"))
-        .json(&json!({ "username": username, "password": password }))
-        .send()
-        .await
-        .expect("Login request failed");
-    assert_eq!(resp.status(), StatusCode::OK, "Login should succeed for {username}");
-}
-
-// ---------------------------------------------------------------------------
-// Zip-building helpers (duplicated from extractor.rs #[cfg(test)])
-// ---------------------------------------------------------------------------
-
-fn build_zip(entries: &[(&str, &[u8])]) -> Vec<u8> {
-    use std::io::Write;
-    let mut buf = Vec::new();
-    {
-        let mut w = zip::ZipWriter::new(std::io::Cursor::new(&mut buf));
-        let opts = zip::write::SimpleFileOptions::default()
-            .compression_method(zip::CompressionMethod::Deflated);
-        for (name, data) in entries {
-            w.start_file(*name, opts).unwrap();
-            w.write_all(data).unwrap();
-        }
-        w.finish().unwrap();
-    }
-    buf
-}
-
-fn build_zip_stored(entries: &[(&str, &[u8])]) -> Vec<u8> {
-    use std::io::Write;
-    let mut buf = Vec::new();
-    {
-        let mut w = zip::ZipWriter::new(std::io::Cursor::new(&mut buf));
-        let opts = zip::write::SimpleFileOptions::default()
-            .compression_method(zip::CompressionMethod::Stored);
-        for (name, data) in entries {
-            w.start_file(*name, opts).unwrap();
-            w.write_all(data).unwrap();
-        }
-        w.finish().unwrap();
-    }
-    buf
-}
-
-/// Build a minimal valid theme zip.
-fn valid_theme_zip(id: &str, version: &str) -> Vec<u8> {
-    let manifest = serde_json::json!({
-        "schema_version": 1,
-        "id": id,
-        "name": id,
-        "version": version,
-    })
-    .to_string();
-    build_zip(&[("manifest.json", manifest.as_bytes()), ("index.html", b"<html><body>theme</body></html>")])
-}
-
-/// Upload a zip as admin and return the parsed JSON response body.
-async fn upload_theme(client: &Client, base_url: &str, zip_bytes: Vec<u8>) -> (StatusCode, Value) {
-    let part = multipart::Part::bytes(zip_bytes)
-        .file_name("theme.sbtheme")
-        .mime_str("application/zip")
-        .unwrap();
-    let form = multipart::Form::new().part("package", part);
-
-    let resp = client
-        .post(format!("{base_url}/api/settings/spa-themes"))
-        .multipart(form)
-        .send()
-        .await
-        .expect("Upload request failed");
-
-    let status = resp.status();
-    let body_bytes = resp.bytes().await.expect("Failed to read upload response body");
-    let body: Value = if body_bytes.is_empty() {
-        Value::Null
-    } else {
-        serde_json::from_slice(&body_bytes).unwrap_or_else(|_| {
-            Value::String(String::from_utf8_lossy(&body_bytes).into_owned())
-        })
-    };
-    (status, body)
-}
-
-// ---------------------------------------------------------------------------
-// Scenarios 1–5: upload policy + auth
-// ---------------------------------------------------------------------------
-
-#[tokio::test]
-async fn scenario_1_non_admin_upload_is_403() {
-    let (base_url, _tmp) = start_test_server(true).await;
-    let client = http_client();
-    login(&client, &base_url, "member", "memberpass").await;
-
-    let zip = valid_theme_zip("acme-test", "1.0.0");
-    let (status, body) = upload_theme(&client, &base_url, zip).await;
-
-    assert_eq!(status, StatusCode::FORBIDDEN, "scenario 1: non-admin upload must be 403; body={body}");
-}
-
-#[tokio::test]
-async fn scenarios_2_to_5_upload_version_policy() {
-    let (base_url, _tmp) = start_test_server(false).await;
-    let client = http_client();
-    login(&client, &base_url, "admin", "testpass").await;
-
-    // Scenario 2: admin upload valid fixture → 200, uuid + manifest
-    let zip_v1 = valid_theme_zip("acme-test", "1.0.0");
-    let (status, body) = upload_theme(&client, &base_url, zip_v1).await;
-    assert_eq!(status, StatusCode::OK, "scenario 2: valid upload must be 200; body={body}");
-    let uuid_v1 = body["data"]["uuid"].as_str().expect("scenario 2: must have uuid").to_string();
-    assert!(!uuid_v1.is_empty(), "scenario 2: uuid must not be empty");
-    let manifest_id = body["data"]["manifest"]["id"]
-        .as_str()
-        .expect("scenario 2: must have manifest.id");
-    assert_eq!(manifest_id, "acme-test", "scenario 2: manifest id must match");
-    assert!(
-        body["data"]["is_upgrade_of"].is_null(),
-        "scenario 2: first upload must not have is_upgrade_of"
-    );
-
-    // Scenario 3: same id + higher version → 200 + is_upgrade_of set
-    let zip_v2 = valid_theme_zip("acme-test", "1.1.0");
-    let (status, body) = upload_theme(&client, &base_url, zip_v2).await;
-    assert_eq!(status, StatusCode::OK, "scenario 3: upgrade must be 200; body={body}");
-    let is_upgrade_of = &body["data"]["is_upgrade_of"];
-    assert!(
-        !is_upgrade_of.is_null(),
-        "scenario 3: upgrade must have is_upgrade_of set; body={body}"
-    );
-    assert_eq!(
-        is_upgrade_of["previous_uuid"].as_str().unwrap_or(""),
-        uuid_v1,
-        "scenario 3: is_upgrade_of.previous_uuid must match v1 uuid"
-    );
-    assert_eq!(
-        is_upgrade_of["previous_version"].as_str().unwrap_or(""),
-        "1.0.0",
-        "scenario 3: is_upgrade_of.previous_version must be 1.0.0"
-    );
-
-    // Scenario 4: same id + lower version → 400 NO_DOWNGRADE
-    let zip_old = valid_theme_zip("acme-test", "0.9.0");
-    let (status, body) = upload_theme(&client, &base_url, zip_old).await;
-    assert_eq!(status, StatusCode::BAD_REQUEST, "scenario 4: downgrade must be 400; body={body}");
-    assert_eq!(
-        body["error"]["code"].as_str().unwrap_or(""),
-        "NO_DOWNGRADE",
-        "scenario 4: error code must be NO_DOWNGRADE"
-    );
-
-    // Scenario 5: same id + same version → 409 VERSION_EXISTS
-    let zip_same = valid_theme_zip("acme-test", "1.1.0");
-    let (status, body) = upload_theme(&client, &base_url, zip_same).await;
-    assert_eq!(status, StatusCode::CONFLICT, "scenario 5: same version must be 409; body={body}");
-    assert_eq!(
-        body["error"]["code"].as_str().unwrap_or(""),
-        "VERSION_EXISTS",
-        "scenario 5: error code must be VERSION_EXISTS"
-    );
-}
-
-// ---------------------------------------------------------------------------
-// Scenarios 6–11: activate + SPA serve + cookie precedence
-// ---------------------------------------------------------------------------
-
-#[tokio::test]
-async fn scenarios_6_to_11_activate_and_serve() {
-    let (base_url, _tmp) = start_test_server(true).await;
-
-    // Admin client (with session cookie)
-    let admin = http_client();
-    login(&admin, &base_url, "admin", "testpass").await;
-
-    // Upload a theme
-    let html_body = b"<html><body>CUSTOM_THEME_CONTENT</body></html>";
-    let manifest = serde_json::json!({
-        "schema_version": 1,
-        "id": "my-theme",
-        "name": "my-theme",
-        "version": "1.0.0",
-    })
-    .to_string();
-    let zip = build_zip(&[("manifest.json", manifest.as_bytes()), ("index.html", html_body)]);
-    let (status, body) = upload_theme(&admin, &base_url, zip).await;
-    assert_eq!(status, StatusCode::OK, "setup: upload must succeed; body={body}");
-    let uuid = body["data"]["uuid"].as_str().expect("setup: must have uuid").to_string();
-
-    // Scenario 6: activate via PUT → 200; GET / returns theme body
-    let activate_resp = admin
-        .put(format!("{base_url}/api/settings/active-spa-theme"))
-        .json(&json!({ "theme_id": uuid }))
-        .send()
-        .await
-        .expect("activate request failed");
-    assert_eq!(
-        activate_resp.status(),
-        StatusCode::OK,
-        "scenario 6: activate must be 200"
-    );
-    let activate_body: Value = activate_resp.json().await.unwrap();
-    assert_eq!(
-        activate_body["data"]["theme_id"].as_str().unwrap_or(""),
-        uuid,
-        "scenario 6: activate response must echo back theme_id"
-    );
-
-    // GET / — separate non-authenticated client so no admin session cookie
-    let anon = http_client();
-    let serve_resp = anon
-        .get(format!("{base_url}/"))
-        .send()
-        .await
-        .expect("GET / failed");
-    assert_eq!(serve_resp.status(), StatusCode::OK, "scenario 6: GET / must be 200");
-    let serve_body = serve_resp.text().await.expect("body text");
-    assert!(
-        serve_body.contains("CUSTOM_THEME_CONTENT"),
-        "scenario 6: GET / must return theme content; got={serve_body:.200}"
-    );
-
-    // Scenario 7: GET /?theme=default returns default SPA body + sets sb_force_default cookie.
-    //
-    // In test environments the embedded SPA (apps/web/dist) may be absent, causing
-    // serve_default() to return 404. That is acceptable here — what we care about is:
-    //   (a) the response sets the sb_force_default cookie
-    //   (b) the body does NOT contain our custom theme sentinel
-    let default_resp = anon
-        .get(format!("{base_url}/?theme=default"))
-        .send()
-        .await
-        .expect("GET /?theme=default failed");
-    let default_status = default_resp.status();
-    assert!(
-        default_status == StatusCode::OK || default_status == StatusCode::NOT_FOUND,
-        "scenario 7: GET /?theme=default must be 200 or 404 (no dist in test env); got={default_status}"
-    );
-    // Cookie jar in reqwest stores cookies — verify via Set-Cookie header before body is consumed.
-    let set_cookie = default_resp
-        .headers()
-        .get_all("set-cookie")
-        .iter()
-        .map(|v| v.to_str().unwrap_or("").to_string())
-        .collect::<Vec<_>>();
-    assert!(
-        set_cookie.iter().any(|c| c.starts_with("sb_force_default=")),
-        "scenario 7: must set sb_force_default cookie; headers={set_cookie:?}"
-    );
-    let default_body = default_resp.text().await.expect("body text");
-    assert!(
-        !default_body.contains("CUSTOM_THEME_CONTENT"),
-        "scenario 7: default SPA must not contain theme content; got={default_body:.200}"
-    );
-
-    // Scenario 8: subsequent GET / with the sb_force_default cookie returns default (not the theme).
-    // reqwest's cookie store has already persisted the cookie from scenario 7.
-    // Again, 404 is acceptable when the embedded SPA is absent.
-    let after_default_resp = anon
-        .get(format!("{base_url}/"))
-        .send()
-        .await
-        .expect("GET / with cookie failed");
-    let after_status = after_default_resp.status();
-    assert!(
-        after_status == StatusCode::OK || after_status == StatusCode::NOT_FOUND,
-        "scenario 8: GET / with sb_force_default must be 200 or 404; got={after_status}"
-    );
-    let after_default_body = after_default_resp.text().await.expect("body text");
-    assert!(
-        !after_default_body.contains("CUSTOM_THEME_CONTENT"),
-        "scenario 8: recovery cookie must keep serving default; got={after_default_body:.200}"
-    );
-
-    // Scenario 9: GET /?theme=active clears cookie and returns active theme
-    let active_resp = anon
-        .get(format!("{base_url}/?theme=active"))
-        .send()
-        .await
-        .expect("GET /?theme=active failed");
-    assert_eq!(
-        active_resp.status(),
-        StatusCode::OK,
-        "scenario 9: GET /?theme=active must be 200"
-    );
-    // Verify Set-Cookie clears sb_force_default (Max-Age=0)
-    let clear_cookies = active_resp
-        .headers()
-        .get_all("set-cookie")
-        .iter()
-        .map(|v| v.to_str().unwrap_or("").to_string())
-        .collect::<Vec<_>>();
-    assert!(
-        clear_cookies
-            .iter()
-            .any(|c| c.contains("sb_force_default=") && c.contains("Max-Age=0")),
-        "scenario 9: must clear sb_force_default cookie; headers={clear_cookies:?}"
-    );
-    let active_body = active_resp.text().await.expect("body text");
-    assert!(
-        active_body.contains("CUSTOM_THEME_CONTENT"),
-        "scenario 9: GET /?theme=active must return theme; got={active_body:.200}"
-    );
-
-    // Scenario 10: GET /?theme=preview:<uuid> as admin returns theme + sets sb_preview_theme cookie
-    let preview_resp = admin
-        .get(format!("{base_url}/?theme=preview:{uuid}"))
-        .send()
-        .await
-        .expect("GET /?theme=preview:<uuid> failed");
-    assert_eq!(
-        preview_resp.status(),
-        StatusCode::OK,
-        "scenario 10: admin preview must be 200"
-    );
-    let preview_cookies = preview_resp
-        .headers()
-        .get_all("set-cookie")
-        .iter()
-        .map(|v| v.to_str().unwrap_or("").to_string())
-        .collect::<Vec<_>>();
-    assert!(
-        preview_cookies
-            .iter()
-            .any(|c| c.starts_with("sb_preview_theme=") && c.contains(&uuid)),
-        "scenario 10: admin preview must set sb_preview_theme cookie with uuid; headers={preview_cookies:?}"
-    );
-    let preview_body = preview_resp.text().await.expect("body text");
-    assert!(
-        preview_body.contains("CUSTOM_THEME_CONTENT"),
-        "scenario 10: admin preview must return theme content; got={preview_body:.200}"
-    );
-    // Preview mode injects a banner
-    assert!(
-        preview_body.contains("__sb_preview"),
-        "scenario 10: admin preview must inject banner; got={preview_body:.200}"
-    );
-
-    // Scenario 11: same preview query as non-admin returns active (preview ignored)
-    // Use a fresh non-admin client (no session, no preview cookie).
-    let non_admin = http_client();
-    let non_admin_preview_resp = non_admin
-        .get(format!("{base_url}/?theme=preview:{uuid}"))
-        .send()
-        .await
-        .expect("non-admin preview GET failed");
-    assert_eq!(
-        non_admin_preview_resp.status(),
-        StatusCode::OK,
-        "scenario 11: non-admin preview must be 200"
-    );
-    // Should NOT set a preview cookie
-    let na_cookies = non_admin_preview_resp
-        .headers()
-        .get_all("set-cookie")
-        .iter()
-        .map(|v| v.to_str().unwrap_or("").to_string())
-        .collect::<Vec<_>>();
-    assert!(
-        !na_cookies.iter().any(|c| c.starts_with("sb_preview_theme=")),
-        "scenario 11: non-admin must not get sb_preview_theme cookie; headers={na_cookies:?}"
-    );
-    // Should serve active theme (since there is an active theme), not with banner.
-    let na_body = non_admin_preview_resp.text().await.expect("body text");
-    assert!(
-        na_body.contains("CUSTOM_THEME_CONTENT"),
-        "scenario 11: non-admin falls through to active theme; got={na_body:.200}"
-    );
-    assert!(
-        !na_body.contains("__sb_preview"),
-        "scenario 11: non-admin must not see preview banner; got={na_body:.200}"
-    );
-}
-
-// ---------------------------------------------------------------------------
-// Scenarios 12–13: delete active / inactive theme
-// ---------------------------------------------------------------------------
-
-#[tokio::test]
-async fn scenarios_12_13_delete_active_and_inactive() {
-    let (base_url, _tmp) = start_test_server(false).await;
-    let client = http_client();
-    login(&client, &base_url, "admin", "testpass").await;
-
-    // Upload two themes with different ids
-    let zip_a = valid_theme_zip("theme-alpha", "1.0.0");
-    let (_, body_a) = upload_theme(&client, &base_url, zip_a).await;
-    let uuid_a = body_a["data"]["uuid"].as_str().expect("uuid_a").to_string();
-
-    let zip_b = valid_theme_zip("theme-beta", "1.0.0");
-    let (_, body_b) = upload_theme(&client, &base_url, zip_b).await;
-    let uuid_b = body_b["data"]["uuid"].as_str().expect("uuid_b").to_string();
-
-    // Activate theme A
-    let act = client
-        .put(format!("{base_url}/api/settings/active-spa-theme"))
-        .json(&json!({ "theme_id": uuid_a }))
-        .send()
-        .await
-        .expect("activate failed");
-    assert_eq!(act.status(), StatusCode::OK, "activate must succeed");
-
-    // Scenario 12: DELETE active theme → 409 THEME_IN_USE
-    let del_resp = client
-        .delete(format!("{base_url}/api/settings/spa-themes/{uuid_a}"))
-        .send()
-        .await
-        .expect("delete request failed");
-    assert_eq!(
-        del_resp.status(),
-        StatusCode::CONFLICT,
-        "scenario 12: deleting active theme must be 409"
-    );
-    let del_body: Value = del_resp.json().await.unwrap();
-    assert_eq!(
-        del_body["error"]["code"].as_str().unwrap_or(""),
-        "THEME_IN_USE",
-        "scenario 12: error code must be THEME_IN_USE"
-    );
-
-    // Scenario 13: DELETE inactive theme B → 204; row removed
-    let del_b = client
-        .delete(format!("{base_url}/api/settings/spa-themes/{uuid_b}"))
-        .send()
-        .await
-        .expect("delete inactive request failed");
-    assert_eq!(
-        del_b.status(),
-        StatusCode::NO_CONTENT,
-        "scenario 13: deleting inactive theme must be 204"
-    );
-
-    // Verify it's gone from the list
-    let list_resp = client
-        .get(format!("{base_url}/api/settings/spa-themes"))
-        .send()
-        .await
-        .expect("list failed");
-    let list_body: Value = list_resp.json().await.unwrap();
-    let empty = vec![];
-    let uuids: Vec<_> = list_body["data"]
-        .as_array()
-        .unwrap_or(&empty)
-        .iter()
-        .filter_map(|e| e["uuid"].as_str())
-        .collect();
-    assert!(
-        !uuids.contains(&uuid_b.as_str()),
-        "scenario 13: deleted theme must not appear in list; list={uuids:?}"
-    );
-}
-
-// ---------------------------------------------------------------------------
-// Scenarios 14–15: zip-slip + zip-bomb rejections
-// ---------------------------------------------------------------------------
-
-#[tokio::test]
-async fn scenario_14_zip_slip_is_rejected() {
-    let (base_url, _tmp) = start_test_server(false).await;
-    let client = http_client();
-    login(&client, &base_url, "admin", "testpass").await;
-
-    // Build a zip with a path traversal entry
-    let zip = build_zip(&[("../etc/passwd", b"root:x:0:0"), ("manifest.json", b"{}")]);
-    let (status, body) = upload_theme(&client, &base_url, zip).await;
-
-    assert_eq!(
-        status,
-        StatusCode::BAD_REQUEST,
-        "scenario 14: zip-slip must be 400; body={body}"
-    );
-    assert_eq!(
-        body["error"]["code"].as_str().unwrap_or(""),
-        "ZIP_SLIP",
-        "scenario 14: error code must be ZIP_SLIP"
-    );
-}
-
-#[tokio::test]
-async fn scenario_15_zip_bomb_is_rejected() {
-    let (base_url, _tmp) = start_test_server(false).await;
-    let client = http_client();
-    login(&client, &base_url, "admin", "testpass").await;
-
-    // Highly compressible: 5 MB of zeros → ratio >> 100x
-    let zeros = vec![0u8; 5 * 1024 * 1024];
-    let zip = build_zip(&[("bomb.js", &zeros), ("manifest.json", b"{}")]);
-    let (status, body) = upload_theme(&client, &base_url, zip).await;
-
-    assert_eq!(
-        status,
-        StatusCode::BAD_REQUEST,
-        "scenario 15: zip-bomb must be 400; body={body}"
-    );
-    assert_eq!(
-        body["error"]["code"].as_str().unwrap_or(""),
-        "ZIP_BOMB",
-        "scenario 15: error code must be ZIP_BOMB"
-    );
-}
-
-// ---------------------------------------------------------------------------
-// Scenario 16: upload > 25 MB → 413 UPLOAD_TOO_LARGE
-// ---------------------------------------------------------------------------
-
-#[tokio::test]
-async fn scenario_16_upload_too_large_is_413() {
-    let (base_url, _tmp) = start_test_server(false).await;
-    let client = http_client();
-    login(&client, &base_url, "admin", "testpass").await;
-
-    // Build a zip with incompressible (LCG pseudo-random) data > 25 MB using STORED method
-    // so the zip file itself stays at the raw size without requiring decompression.
-    // 26 MB of incompressible data stored uncompressed → zip is ~26 MB.
-    const SIZE: usize = 26 * 1024 * 1024;
-    let mut data = Vec::with_capacity(SIZE);
-    let mut x: u64 = 0xdeadbeef_cafebabe;
-    for _ in 0..SIZE {
-        x = x.wrapping_mul(6364136223846793005).wrapping_add(1442695040888963407);
-        data.push((x >> 56) as u8);
-    }
-
-    // Use STORED (no compression) so the zip payload stays large.
-    // The individual file is 26 MB which exceeds MAX_FILE_BYTES (5 MB), but the
-    // axum body limit (25 MB) fires before the extractor even runs because the
-    // entire multipart body is rejected by DefaultBodyLimit before it's read.
-    let zip = build_zip_stored(&[("big.js", &data)]);
-
-    let part = multipart::Part::bytes(zip)
-        .file_name("huge.sbtheme")
-        .mime_str("application/zip")
-        .unwrap();
-    let form = multipart::Form::new().part("package", part);
-
-    let resp = client
-        .post(format!("{base_url}/api/settings/spa-themes"))
-        .multipart(form)
-        .send()
-        .await
-        .expect("large upload request failed");
-
-    let status = resp.status();
-    let body_bytes = resp.bytes().await.expect("Failed to read body");
-
-    assert_eq!(
-        status,
-        StatusCode::PAYLOAD_TOO_LARGE,
-        "scenario 16: 26 MB upload must be 413"
-    );
-
-    // Response must be JSON with our error contract
-    let body: Value = serde_json::from_slice(&body_bytes)
-        .expect("scenario 16: 413 response must be valid JSON");
-    assert_eq!(
-        body["error"]["code"].as_str().unwrap_or(""),
-        "UPLOAD_TOO_LARGE",
-        "scenario 16: error code must be UPLOAD_TOO_LARGE; body={body}"
-    );
-}

From 6b6a791b80e1a45337b68832c2c7e9082ec99878 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 22:02:39 +0800
Subject: [PATCH 36/64] refactor(web): delete legacy theme code
 (preset/custom/spa)

Strip the preset/custom/spa theme UI now that widget modules own
runtime customization. Collapses theme-provider to a pure light /
dark / system toggle, replaces the Appearance settings page with a
notice linking to /settings/widgets plus the existing brand
section, and drops the now-orphaned APIs, components, preset CSS
bundles, routes, and i18n strings.
---
 apps/web/src/api/spa-themes.ts                | 120 ----
 apps/web/src/api/themes.ts                    | 122 ----
 .../activate-spa-theme-dialog.test.tsx        |  47 --
 .../spa-theme/activate-spa-theme-dialog.tsx   |  59 --
 .../spa-theme/custom-spa-theme-section.tsx    | 158 -----
 .../spa-theme/preview-confirm-dialog.test.tsx |  15 -
 .../spa-theme/preview-confirm-dialog.tsx      |  37 --
 .../spa-theme/spa-theme-card.test.tsx         |  61 --
 .../components/spa-theme/spa-theme-card.tsx   |  67 --
 .../spa-theme-details-drawer.test.tsx         |  35 -
 .../spa-theme/spa-theme-details-drawer.tsx    |  92 ---
 .../spa-theme/spa-theme-upload-card.test.tsx  |  37 --
 .../spa-theme/spa-theme-upload-card.tsx       |  69 --
 apps/web/src/components/theme-provider.tsx    | 199 +-----
 .../theme/delete-theme-dialog.test.tsx        |  73 ---
 .../components/theme/delete-theme-dialog.tsx  |  76 ---
 .../components/theme/oklch-picker.test.tsx    |  27 -
 .../web/src/components/theme/oklch-picker.tsx |  89 ---
 .../src/components/theme/theme-card.test.tsx  |  48 --
 apps/web/src/components/theme/theme-card.tsx  |  97 ---
 .../components/theme/theme-editor.test.tsx    |  82 ---
 .../web/src/components/theme/theme-editor.tsx | 290 ---------
 .../components/theme/theme-preview.test.tsx   |  21 -
 .../src/components/theme/theme-preview.tsx    |  56 --
 apps/web/src/lib/i18n.ts                      |   4 -
 apps/web/src/lib/theme-ref.test.ts            |  62 --
 apps/web/src/lib/theme-ref.ts                 |  33 -
 apps/web/src/locales/en/settings.json         |  43 +-
 apps/web/src/locales/en/spa-theme.json        |  72 ---
 apps/web/src/locales/zh/settings.json         |  43 +-
 apps/web/src/locales/zh/spa-theme.json        |  72 ---
 apps/web/src/routeTree.gen.ts                 |  68 +-
 .../_authed/settings/appearance.test.tsx      | 128 +---
 .../routes/_authed/settings/appearance.tsx    | 295 +--------
 .../settings/appearance/themes.new.test.tsx   |  70 --
 .../settings/appearance/themes.new.tsx        |  80 ---
 .../settings/appearance/themes/$id.tsx        |  11 -
 apps/web/src/themes/catppuccin.css            |  67 --
 apps/web/src/themes/dracula.css               |  67 --
 apps/web/src/themes/index.ts                  | 110 ----
 apps/web/src/themes/nord.css                  |  67 --
 apps/web/src/themes/one-dark.css              |  67 --
 apps/web/src/themes/preset-vars.test.ts       |  63 --
 apps/web/src/themes/preset-vars.ts            | 608 ------------------
 apps/web/src/themes/rose-pine.css             |  67 --
 apps/web/src/themes/solarized.css             |  67 --
 apps/web/src/themes/tokyo-night.css           |  67 --
 47 files changed, 54 insertions(+), 4154 deletions(-)
 delete mode 100644 apps/web/src/api/spa-themes.ts
 delete mode 100644 apps/web/src/api/themes.ts
 delete mode 100644 apps/web/src/components/spa-theme/activate-spa-theme-dialog.test.tsx
 delete mode 100644 apps/web/src/components/spa-theme/activate-spa-theme-dialog.tsx
 delete mode 100644 apps/web/src/components/spa-theme/custom-spa-theme-section.tsx
 delete mode 100644 apps/web/src/components/spa-theme/preview-confirm-dialog.test.tsx
 delete mode 100644 apps/web/src/components/spa-theme/preview-confirm-dialog.tsx
 delete mode 100644 apps/web/src/components/spa-theme/spa-theme-card.test.tsx
 delete mode 100644 apps/web/src/components/spa-theme/spa-theme-card.tsx
 delete mode 100644 apps/web/src/components/spa-theme/spa-theme-details-drawer.test.tsx
 delete mode 100644 apps/web/src/components/spa-theme/spa-theme-details-drawer.tsx
 delete mode 100644 apps/web/src/components/spa-theme/spa-theme-upload-card.test.tsx
 delete mode 100644 apps/web/src/components/spa-theme/spa-theme-upload-card.tsx
 delete mode 100644 apps/web/src/components/theme/delete-theme-dialog.test.tsx
 delete mode 100644 apps/web/src/components/theme/delete-theme-dialog.tsx
 delete mode 100644 apps/web/src/components/theme/oklch-picker.test.tsx
 delete mode 100644 apps/web/src/components/theme/oklch-picker.tsx
 delete mode 100644 apps/web/src/components/theme/theme-card.test.tsx
 delete mode 100644 apps/web/src/components/theme/theme-card.tsx
 delete mode 100644 apps/web/src/components/theme/theme-editor.test.tsx
 delete mode 100644 apps/web/src/components/theme/theme-editor.tsx
 delete mode 100644 apps/web/src/components/theme/theme-preview.test.tsx
 delete mode 100644 apps/web/src/components/theme/theme-preview.tsx
 delete mode 100644 apps/web/src/lib/theme-ref.test.ts
 delete mode 100644 apps/web/src/lib/theme-ref.ts
 delete mode 100644 apps/web/src/locales/en/spa-theme.json
 delete mode 100644 apps/web/src/locales/zh/spa-theme.json
 delete mode 100644 apps/web/src/routes/_authed/settings/appearance/themes.new.test.tsx
 delete mode 100644 apps/web/src/routes/_authed/settings/appearance/themes.new.tsx
 delete mode 100644 apps/web/src/routes/_authed/settings/appearance/themes/$id.tsx
 delete mode 100644 apps/web/src/themes/catppuccin.css
 delete mode 100644 apps/web/src/themes/dracula.css
 delete mode 100644 apps/web/src/themes/index.ts
 delete mode 100644 apps/web/src/themes/nord.css
 delete mode 100644 apps/web/src/themes/one-dark.css
 delete mode 100644 apps/web/src/themes/preset-vars.test.ts
 delete mode 100644 apps/web/src/themes/preset-vars.ts
 delete mode 100644 apps/web/src/themes/rose-pine.css
 delete mode 100644 apps/web/src/themes/solarized.css
 delete mode 100644 apps/web/src/themes/tokyo-night.css

diff --git a/apps/web/src/api/spa-themes.ts b/apps/web/src/api/spa-themes.ts
deleted file mode 100644
index dc11e235..00000000
--- a/apps/web/src/api/spa-themes.ts
+++ /dev/null
@@ -1,120 +0,0 @@
-import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
-import { api } from '@/lib/api-client'
-
-export interface SpaThemeSummary {
-  author?: string | null
-  description?: string | null
-  has_preview: boolean
-  is_active: boolean
-  is_superseded: boolean
-  manifest_id: string
-  name: string
-  size_bytes: number
-  uploaded_at: string
-  uploaded_by: string
-  uuid: string
-  version: string
-}
-
-export interface UploadResult {
-  is_upgrade_of: { previous_uuid: string; previous_version: string } | null
-  manifest: Record<string, unknown>
-  preview_url: string | null
-  size_bytes: number
-  uuid: string
-}
-
-/**
- * Structured error envelope returned by the SPA theme endpoints.
- *
- * The server responds with `{ error: { code, message, details } }` for known failure modes;
- * we surface those fields so callers can render `t(\`errors.${code}\`, details)`.
- */
-export interface ApiError extends Error {
-  code?: string
-  details?: Record<string, unknown>
-}
-
-interface ErrorEnvelope {
-  error?: { code?: string; message?: string; details?: Record<string, unknown> }
-}
-
-async function parseErrorBody(res: Response): Promise<ApiError> {
-  const text = await res.text().catch(() => '')
-  let parsed: unknown = null
-  try {
-    parsed = text ? JSON.parse(text) : null
-  } catch {
-    parsed = null
-  }
-  const envelope = (parsed as ErrorEnvelope | null)?.error
-  const err = new Error(envelope?.message ?? text ?? res.statusText) as ApiError
-  err.code = envelope?.code
-  err.details = envelope?.details
-  return err
-}
-
-export function useSpaThemes() {
-  return useQuery<SpaThemeSummary[]>({
-    queryKey: ['spa-themes'],
-    queryFn: () => api.get<SpaThemeSummary[]>('/api/settings/spa-themes')
-  })
-}
-
-export function useActiveSpaTheme() {
-  return useQuery<{ theme_id: string | null }>({
-    queryKey: ['active-spa-theme'],
-    queryFn: () => api.get('/api/settings/active-spa-theme'),
-    staleTime: 30_000
-  })
-}
-
-export function useActivateSpaTheme() {
-  const qc = useQueryClient()
-  return useMutation({
-    mutationFn: (themeId: string | null) =>
-      api.put<{ theme_id: string | null }>('/api/settings/active-spa-theme', { theme_id: themeId }),
-    onSuccess: () => {
-      qc.invalidateQueries({ queryKey: ['active-spa-theme'] })
-      qc.invalidateQueries({ queryKey: ['spa-themes'] })
-    }
-  })
-}
-
-export function useDeleteSpaTheme() {
-  const qc = useQueryClient()
-  return useMutation<void, ApiError, string>({
-    mutationFn: async (uuid: string) => {
-      const res = await fetch(`/api/settings/spa-themes/${uuid}`, { method: 'DELETE', credentials: 'include' })
-      if (!res.ok) {
-        throw await parseErrorBody(res)
-      }
-    },
-    onSuccess: () => qc.invalidateQueries({ queryKey: ['spa-themes'] })
-  })
-}
-
-export function useUploadSpaTheme() {
-  const qc = useQueryClient()
-  return useMutation<UploadResult, ApiError, File>({
-    mutationFn: async (file: File) => {
-      const fd = new FormData()
-      fd.append('package', file)
-      const res = await fetch('/api/settings/spa-themes', {
-        method: 'POST',
-        credentials: 'include',
-        body: fd
-      })
-      if (!res.ok) {
-        throw await parseErrorBody(res)
-      }
-      const text = await res.text()
-      const parsed = text ? (JSON.parse(text) as { data: UploadResult }) : null
-      if (!parsed) {
-        throw new Error('Upload succeeded but response body was empty')
-      }
-      return parsed.data
-    },
-    onSuccess: () => qc.invalidateQueries({ queryKey: ['spa-themes'] })
-  })
-}
diff --git a/apps/web/src/api/themes.ts b/apps/web/src/api/themes.ts
deleted file mode 100644
index dfe88640..00000000
--- a/apps/web/src/api/themes.ts
+++ /dev/null
@@ -1,122 +0,0 @@
-import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
-import { api } from '@/lib/api-client'
-import type { components } from '@/lib/api-types'
-
-export type ThemeResolved = components['schemas']['ThemeResolved']
-export type ActiveThemeResponse = components['schemas']['ActiveThemeResponse']
-export type CreateThemeInput = components['schemas']['CreateThemeInput']
-export type ExportPayload = components['schemas']['ExportPayload']
-export type FullTheme = components['schemas']['Theme']
-export type ThemeReferences = components['schemas']['ThemeReferences']
-export type ThemeSummary = components['schemas']['ThemeSummary']
-export type UpdateThemeInput = components['schemas']['UpdateThemeInput']
-
-export function useActiveTheme() {
-  return useQuery<ActiveThemeResponse>({
-    queryKey: ['active-theme'],
-    queryFn: () => api.get<ActiveThemeResponse>('/api/settings/active-theme'),
-    staleTime: 30_000
-  })
-}
-
-export function useSetActiveTheme() {
-  const queryClient = useQueryClient()
-
-  return useMutation({
-    mutationFn: (ref: string) => api.put<ActiveThemeResponse>('/api/settings/active-theme', { ref }),
-    onSuccess: (data) => {
-      queryClient.setQueryData(['active-theme'], data)
-      queryClient.invalidateQueries({ queryKey: ['active-theme'] }).catch(() => undefined)
-    }
-  })
-}
-
-export function useCustomThemes() {
-  return useQuery<ThemeSummary[]>({
-    queryKey: ['themes'],
-    queryFn: () => api.get<ThemeSummary[]>('/api/settings/themes')
-  })
-}
-
-export function useThemeQuery(id: number) {
-  return useQuery<FullTheme>({
-    queryKey: ['themes', id],
-    queryFn: () => api.get<FullTheme>(`/api/settings/themes/${id}`),
-    enabled: Number.isInteger(id) && id > 0
-  })
-}
-
-export function useCreateTheme() {
-  const queryClient = useQueryClient()
-
-  return useMutation({
-    mutationFn: (input: CreateThemeInput) => api.post<FullTheme>('/api/settings/themes', input),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['themes'] }).catch(() => undefined)
-    }
-  })
-}
-
-export function useUpdateTheme() {
-  const queryClient = useQueryClient()
-
-  return useMutation({
-    mutationFn: ({ id, body }: { body: UpdateThemeInput; id: number }) =>
-      api.put<FullTheme>(`/api/settings/themes/${id}`, body),
-    onSuccess: (_data, variables) => {
-      queryClient.invalidateQueries({ queryKey: ['themes'] }).catch(() => undefined)
-      queryClient.invalidateQueries({ queryKey: ['themes', variables.id] }).catch(() => undefined)
-      queryClient.invalidateQueries({ queryKey: ['active-theme'] }).catch(() => undefined)
-    }
-  })
-}
-
-export function useThemeReferences(id: number) {
-  return useQuery<ThemeReferences>({
-    queryKey: ['themes', id, 'references'],
-    queryFn: () => api.get<ThemeReferences>(`/api/settings/themes/${id}/references`),
-    enabled: Number.isInteger(id) && id > 0
-  })
-}
-
-export function useDeleteTheme() {
-  const queryClient = useQueryClient()
-
-  return useMutation({
-    mutationFn: (id: number) => api.delete<string>(`/api/settings/themes/${id}`),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['themes'] }).catch(() => undefined)
-      queryClient.invalidateQueries({ queryKey: ['active-theme'] }).catch(() => undefined)
-    }
-  })
-}
-
-export function useDuplicateTheme() {
-  const queryClient = useQueryClient()
-
-  return useMutation({
-    mutationFn: (id: number) => api.post<FullTheme>(`/api/settings/themes/${id}/duplicate`, {}),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['themes'] }).catch(() => undefined)
-    }
-  })
-}
-
-export function useExportTheme(id: number) {
-  return useQuery<ExportPayload>({
-    queryKey: ['themes', id, 'export'],
-    queryFn: () => api.get<ExportPayload>(`/api/settings/themes/${id}/export`),
-    enabled: false
-  })
-}
-
-export function useImportTheme() {
-  const queryClient = useQueryClient()
-
-  return useMutation({
-    mutationFn: (payload: ExportPayload) => api.post<FullTheme>('/api/settings/themes/import', payload),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['themes'] }).catch(() => undefined)
-    }
-  })
-}
diff --git a/apps/web/src/components/spa-theme/activate-spa-theme-dialog.test.tsx b/apps/web/src/components/spa-theme/activate-spa-theme-dialog.test.tsx
deleted file mode 100644
index a4fa2b60..00000000
--- a/apps/web/src/components/spa-theme/activate-spa-theme-dialog.test.tsx
+++ /dev/null
@@ -1,47 +0,0 @@
-import { fireEvent, render, screen } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
-import type { SpaThemeSummary } from '@/api/spa-themes'
-import '@/lib/i18n'
-import { ActivateSpaThemeDialog } from './activate-spa-theme-dialog'
-
-const ACTIVATE_RE = /^Activate$/
-const CHECKBOX_RE = /I understand/
-
-const theme: SpaThemeSummary = {
-  author: 'Acme Inc.',
-  description: null,
-  has_preview: false,
-  is_active: false,
-  is_superseded: false,
-  manifest_id: 'm',
-  name: 'Acme',
-  size_bytes: 1,
-  uploaded_at: '2026-05-26',
-  uploaded_by: 'u',
-  uuid: 'u1',
-  version: '1.0.0'
-}
-
-describe('ActivateSpaThemeDialog', () => {
-  it('disables confirm until the checkbox is ticked', () => {
-    const onConfirm = vi.fn()
-    render(<ActivateSpaThemeDialog onConfirm={onConfirm} onOpenChange={vi.fn()} open theme={theme} />)
-
-    const confirmBtn = screen.getByRole('button', { name: ACTIVATE_RE }) as HTMLButtonElement
-    expect(confirmBtn).toBeDisabled()
-
-    // The Base UI Checkbox renders inside a <label>; clicking the label text toggles it.
-    fireEvent.click(screen.getByText(CHECKBOX_RE))
-
-    expect(confirmBtn).toBeEnabled()
-    fireEvent.click(confirmBtn)
-    expect(onConfirm).toHaveBeenCalledTimes(1)
-  })
-
-  it('renders nothing when theme is null', () => {
-    const { container } = render(
-      <ActivateSpaThemeDialog onConfirm={vi.fn()} onOpenChange={vi.fn()} open theme={null} />
-    )
-    expect(container).toBeEmptyDOMElement()
-  })
-})
diff --git a/apps/web/src/components/spa-theme/activate-spa-theme-dialog.tsx b/apps/web/src/components/spa-theme/activate-spa-theme-dialog.tsx
deleted file mode 100644
index a59bd9da..00000000
--- a/apps/web/src/components/spa-theme/activate-spa-theme-dialog.tsx
+++ /dev/null
@@ -1,59 +0,0 @@
-import { useState } from 'react'
-import { useTranslation } from 'react-i18next'
-import type { SpaThemeSummary } from '@/api/spa-themes'
-import { Button } from '@/components/ui/button'
-import { Checkbox } from '@/components/ui/checkbox'
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogFooter,
-  DialogHeader,
-  DialogTitle
-} from '@/components/ui/dialog'
-
-interface Props {
-  onConfirm: () => void
-  onOpenChange: (v: boolean) => void
-  open: boolean
-  theme: SpaThemeSummary | null
-}
-
-export function ActivateSpaThemeDialog({ theme, open, onOpenChange, onConfirm }: Props) {
-  const { t } = useTranslation('spa-theme')
-  const [agreed, setAgreed] = useState(false)
-
-  if (!theme) {
-    return null
-  }
-
-  const handleOpenChange = (v: boolean) => {
-    setAgreed(false)
-    onOpenChange(v)
-  }
-
-  return (
-    <Dialog onOpenChange={handleOpenChange} open={open}>
-      <DialogContent>
-        <DialogHeader>
-          <DialogTitle>{t('activate_dialog.title', { name: theme.name, version: theme.version })}</DialogTitle>
-          <DialogDescription>{t('activate_dialog.body')}</DialogDescription>
-        </DialogHeader>
-        <p className="text-muted-foreground text-sm">{t('activate_dialog.recovery_hint')}</p>
-        {/* biome-ignore lint/a11y/noLabelWithoutControl: Checkbox renders as a labelable button element */}
-        <label className="flex cursor-pointer items-center gap-2 text-sm">
-          <Checkbox checked={agreed} onCheckedChange={(v) => setAgreed(v === true)} />
-          {t('activate_dialog.confirm_checkbox')}
-        </label>
-        <DialogFooter>
-          <Button onClick={() => onOpenChange(false)} variant="outline">
-            {t('activate_dialog.cancel')}
-          </Button>
-          <Button disabled={!agreed} onClick={onConfirm}>
-            {t('activate_dialog.confirm')}
-          </Button>
-        </DialogFooter>
-      </DialogContent>
-    </Dialog>
-  )
-}
diff --git a/apps/web/src/components/spa-theme/custom-spa-theme-section.tsx b/apps/web/src/components/spa-theme/custom-spa-theme-section.tsx
deleted file mode 100644
index 66848870..00000000
--- a/apps/web/src/components/spa-theme/custom-spa-theme-section.tsx
+++ /dev/null
@@ -1,158 +0,0 @@
-import { useState } from 'react'
-import { useTranslation } from 'react-i18next'
-import { toast } from 'sonner'
-import {
-  type ApiError,
-  type SpaThemeSummary,
-  useActivateSpaTheme,
-  useDeleteSpaTheme,
-  useSpaThemes
-} from '@/api/spa-themes'
-import {
-  AlertDialog,
-  AlertDialogAction,
-  AlertDialogCancel,
-  AlertDialogContent,
-  AlertDialogDescription,
-  AlertDialogFooter,
-  AlertDialogHeader,
-  AlertDialogTitle
-} from '@/components/ui/alert-dialog'
-import { Badge } from '@/components/ui/badge'
-import { ActivateSpaThemeDialog } from './activate-spa-theme-dialog'
-import { PreviewConfirmDialog } from './preview-confirm-dialog'
-import { SpaThemeCard } from './spa-theme-card'
-import { SpaThemeDetailsDrawer } from './spa-theme-details-drawer'
-import { SpaThemeUploadCard } from './spa-theme-upload-card'
-
-function reloadPage() {
-  window.location.reload()
-}
-
-function showActivatedToast(message: string, reloadLabel: string) {
-  toast.success(message, {
-    action: { label: reloadLabel, onClick: reloadPage }
-  })
-}
-
-export function CustomSpaThemeSection() {
-  const { t } = useTranslation('spa-theme')
-  const themes = useSpaThemes()
-  const activate = useActivateSpaTheme()
-  const del = useDeleteSpaTheme()
-
-  const [pendingActivate, setPendingActivate] = useState<SpaThemeSummary | null>(null)
-  const [pendingPreview, setPendingPreview] = useState<SpaThemeSummary | null>(null)
-  const [pendingDelete, setPendingDelete] = useState<SpaThemeSummary | null>(null)
-  const [drawer, setDrawer] = useState<SpaThemeSummary | null>(null)
-
-  const showApiErrorToast = (err: ApiError) => {
-    const code = err.code ?? 'default'
-    const details = (err.details ?? {}) as Record<string, unknown>
-    toast.error(t(`errors.${code}` as never, { ...details, message: err.message }))
-  }
-
-  const handleActivateConfirm = () => {
-    if (!pendingActivate) {
-      return
-    }
-    const target = pendingActivate
-    activate.mutate(target.uuid, {
-      onSuccess: () => showActivatedToast(t('theme_activated'), t('reload'))
-    })
-    setPendingActivate(null)
-  }
-
-  const handleDeactivate = () => {
-    activate.mutate(null, {
-      onSuccess: () => showActivatedToast(t('theme_deactivated'), t('reload'))
-    })
-  }
-
-  const handleDeleteConfirm = () => {
-    if (!pendingDelete) {
-      return
-    }
-    del.mutate(pendingDelete.uuid, {
-      onError: showApiErrorToast
-    })
-    setPendingDelete(null)
-  }
-
-  const handlePreviewConfirm = () => {
-    if (pendingPreview) {
-      window.open(`/?theme=preview:${pendingPreview.uuid}`, '_blank', 'noopener,noreferrer')
-    }
-    setPendingPreview(null)
-  }
-
-  return (
-    <section className="mb-6 rounded-lg border-2 border-amber-300/40 bg-amber-50/30 p-4 dark:bg-amber-950/20">
-      <header className="mb-3 flex items-center gap-2">
-        <h2 className="font-semibold text-lg">{t('section_title')}</h2>
-        <Badge variant="outline">{t('section_badge')}</Badge>
-      </header>
-      <p className="mb-4 text-muted-foreground text-sm">{t('section_description')}</p>
-
-      <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
-        <SpaThemeUploadCard />
-        {(themes.data ?? []).map((th) => (
-          <SpaThemeCard
-            key={th.uuid}
-            onActivate={() => setPendingActivate(th)}
-            onDeactivate={handleDeactivate}
-            onDelete={() => setPendingDelete(th)}
-            onOpenDetails={() => setDrawer(th)}
-            onPreview={() => setPendingPreview(th)}
-            theme={th}
-          />
-        ))}
-      </div>
-
-      <PreviewConfirmDialog
-        onConfirm={handlePreviewConfirm}
-        onOpenChange={(v) => !v && setPendingPreview(null)}
-        open={pendingPreview !== null}
-      />
-
-      <ActivateSpaThemeDialog
-        onConfirm={handleActivateConfirm}
-        onOpenChange={(v) => !v && setPendingActivate(null)}
-        open={pendingActivate !== null}
-        theme={pendingActivate}
-      />
-
-      <AlertDialog onOpenChange={(v) => !v && setPendingDelete(null)} open={pendingDelete !== null}>
-        <AlertDialogContent>
-          <AlertDialogHeader>
-            <AlertDialogTitle>{t('delete_dialog.title')}</AlertDialogTitle>
-            <AlertDialogDescription>
-              {t('delete_dialog.description', { name: pendingDelete?.name ?? '' })}
-            </AlertDialogDescription>
-          </AlertDialogHeader>
-          <AlertDialogFooter>
-            <AlertDialogCancel>{t('delete_dialog.cancel')}</AlertDialogCancel>
-            <AlertDialogAction onClick={handleDeleteConfirm} variant="destructive">
-              {t('delete_dialog.confirm')}
-            </AlertDialogAction>
-          </AlertDialogFooter>
-        </AlertDialogContent>
-      </AlertDialog>
-
-      <SpaThemeDetailsDrawer onClose={() => setDrawer(null)} theme={drawer} />
-    </section>
-  )
-}
-
-interface BannerProps {
-  message?: string
-}
-
-export function CustomSpaThemeBanner({ message }: BannerProps) {
-  const { t } = useTranslation('spa-theme')
-  return (
-    <div className="mb-4 rounded-lg border border-amber-300/60 bg-amber-50/50 p-3 text-sm dark:bg-amber-950/30">
-      {message ?? t('color_brand_disabled_banner')}
-    </div>
-  )
-}
diff --git a/apps/web/src/components/spa-theme/preview-confirm-dialog.test.tsx b/apps/web/src/components/spa-theme/preview-confirm-dialog.test.tsx
deleted file mode 100644
index 132b84a9..00000000
--- a/apps/web/src/components/spa-theme/preview-confirm-dialog.test.tsx
+++ /dev/null
@@ -1,15 +0,0 @@
-import { fireEvent, render, screen } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
-import '@/lib/i18n'
-import { PreviewConfirmDialog } from './preview-confirm-dialog'
-
-const OPEN_PREVIEW_RE = /Open preview/
-
-describe('PreviewConfirmDialog', () => {
-  it('calls onConfirm when the confirm button is clicked', () => {
-    const onConfirm = vi.fn()
-    render(<PreviewConfirmDialog onConfirm={onConfirm} onOpenChange={vi.fn()} open />)
-    fireEvent.click(screen.getByRole('button', { name: OPEN_PREVIEW_RE }))
-    expect(onConfirm).toHaveBeenCalledTimes(1)
-  })
-})
diff --git a/apps/web/src/components/spa-theme/preview-confirm-dialog.tsx b/apps/web/src/components/spa-theme/preview-confirm-dialog.tsx
deleted file mode 100644
index 8c2dc7f8..00000000
--- a/apps/web/src/components/spa-theme/preview-confirm-dialog.tsx
+++ /dev/null
@@ -1,37 +0,0 @@
-import { useTranslation } from 'react-i18next'
-import { Button } from '@/components/ui/button'
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogFooter,
-  DialogHeader,
-  DialogTitle
-} from '@/components/ui/dialog'
-
-interface Props {
-  onConfirm: () => void
-  onOpenChange: (v: boolean) => void
-  open: boolean
-}
-
-export function PreviewConfirmDialog({ open, onOpenChange, onConfirm }: Props) {
-  const { t } = useTranslation('spa-theme')
-
-  return (
-    <Dialog onOpenChange={onOpenChange} open={open}>
-      <DialogContent>
-        <DialogHeader>
-          <DialogTitle>{t('preview_dialog.title')}</DialogTitle>
-          <DialogDescription>{t('preview_dialog.body')}</DialogDescription>
-        </DialogHeader>
-        <DialogFooter>
-          <Button onClick={() => onOpenChange(false)} variant="outline">
-            {t('preview_dialog.cancel')}
-          </Button>
-          <Button onClick={onConfirm}>{t('preview_dialog.confirm')}</Button>
-        </DialogFooter>
-      </DialogContent>
-    </Dialog>
-  )
-}
diff --git a/apps/web/src/components/spa-theme/spa-theme-card.test.tsx b/apps/web/src/components/spa-theme/spa-theme-card.test.tsx
deleted file mode 100644
index 6102a44b..00000000
--- a/apps/web/src/components/spa-theme/spa-theme-card.test.tsx
+++ /dev/null
@@ -1,61 +0,0 @@
-import { fireEvent, render, screen } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
-import type { SpaThemeSummary } from '@/api/spa-themes'
-import '@/lib/i18n'
-import { SpaThemeCard } from './spa-theme-card'
-
-const base: SpaThemeSummary = {
-  author: 'Inc',
-  description: null,
-  has_preview: false,
-  is_active: false,
-  is_superseded: false,
-  manifest_id: 'm',
-  name: 'Acme',
-  size_bytes: 1,
-  uploaded_at: '2026-05-26',
-  uploaded_by: 'u',
-  uuid: 'u1',
-  version: '1.0.0'
-}
-
-const noop = () => {
-  // intentionally empty
-}
-
-const ACTIVATE_RE = /Activate/
-const DELETE_RE = /Delete/
-
-describe('SpaThemeCard', () => {
-  it('shows activate when not active', () => {
-    render(
-      <SpaThemeCard
-        onActivate={noop}
-        onDeactivate={noop}
-        onDelete={noop}
-        onOpenDetails={noop}
-        onPreview={noop}
-        theme={base}
-      />
-    )
-    expect(screen.getByText(ACTIVATE_RE)).toBeInTheDocument()
-  })
-
-  it('disables delete when active', () => {
-    const onDelete = vi.fn()
-    render(
-      <SpaThemeCard
-        onActivate={noop}
-        onDeactivate={noop}
-        onDelete={onDelete}
-        onOpenDetails={noop}
-        onPreview={noop}
-        theme={{ ...base, is_active: true }}
-      />
-    )
-    const btn = screen.getByText(DELETE_RE) as HTMLButtonElement
-    expect(btn).toBeDisabled()
-    fireEvent.click(btn)
-    expect(onDelete).not.toHaveBeenCalled()
-  })
-})
diff --git a/apps/web/src/components/spa-theme/spa-theme-card.tsx b/apps/web/src/components/spa-theme/spa-theme-card.tsx
deleted file mode 100644
index 273fd35c..00000000
--- a/apps/web/src/components/spa-theme/spa-theme-card.tsx
+++ /dev/null
@@ -1,67 +0,0 @@
-import { useTranslation } from 'react-i18next'
-import type { SpaThemeSummary } from '@/api/spa-themes'
-import { Badge } from '@/components/ui/badge'
-import { Button } from '@/components/ui/button'
-
-interface Props {
-  onActivate: () => void
-  onDeactivate: () => void
-  onDelete: () => void
-  onOpenDetails: () => void
-  onPreview: () => void
-  theme: SpaThemeSummary
-}
-
-export function SpaThemeCard({ theme, onPreview, onActivate, onDeactivate, onDelete, onOpenDetails }: Props) {
-  const { t } = useTranslation('spa-theme')
-  const previewUrl = theme.has_preview ? `/api/settings/spa-themes/${theme.uuid}/preview` : null
-
-  return (
-    <div className="flex flex-col overflow-hidden rounded-lg border" data-testid={`spa-theme-card-${theme.uuid}`}>
-      <div className="aspect-video bg-muted">
-        {previewUrl ? (
-          <img alt="" className="h-full w-full object-cover" height={180} src={previewUrl} width={320} />
-        ) : null}
-      </div>
-      <div className="flex flex-1 flex-col gap-2 p-3">
-        <div className="flex items-center justify-between gap-2">
-          <div className="truncate font-medium" title={theme.name}>
-            {theme.name}
-          </div>
-          {theme.is_active ? <Badge variant="default">{t('active_indicator')}</Badge> : null}
-          {theme.is_superseded && !theme.is_active ? <Badge variant="secondary">{t('superseded')}</Badge> : null}
-        </div>
-        <div className="text-muted-foreground text-xs">
-          v{theme.version}
-          {theme.author ? ` · ${theme.author}` : ''}
-        </div>
-        <div className="mt-auto flex flex-wrap gap-2">
-          <Button onClick={onPreview} size="sm" variant="outline">
-            {t('actions.preview')}
-          </Button>
-          {theme.is_active ? (
-            <Button onClick={onDeactivate} size="sm" variant="outline">
-              {t('actions.deactivate')}
-            </Button>
-          ) : (
-            <Button onClick={onActivate} size="sm">
-              {t('actions.activate')}
-            </Button>
-          )}
-          <Button onClick={onOpenDetails} size="sm" variant="ghost">
-            {t('actions.details')}
-          </Button>
-          <Button
-            disabled={theme.is_active}
-            onClick={onDelete}
-            size="sm"
-            title={theme.is_active ? t('delete_active_blocked') : undefined}
-            variant="destructive"
-          >
-            {t('actions.delete')}
-          </Button>
-        </div>
-      </div>
-    </div>
-  )
-}
diff --git a/apps/web/src/components/spa-theme/spa-theme-details-drawer.test.tsx b/apps/web/src/components/spa-theme/spa-theme-details-drawer.test.tsx
deleted file mode 100644
index 481a1cd0..00000000
--- a/apps/web/src/components/spa-theme/spa-theme-details-drawer.test.tsx
+++ /dev/null
@@ -1,35 +0,0 @@
-import { render, screen } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
-import type { SpaThemeSummary } from '@/api/spa-themes'
-import '@/lib/i18n'
-import { SpaThemeDetailsDrawer } from './spa-theme-details-drawer'
-
-const DOWNLOAD_RE = /Download package/
-
-const theme: SpaThemeSummary = {
-  author: 'Acme Inc.',
-  description: 'A pretty theme',
-  has_preview: true,
-  is_active: false,
-  is_superseded: false,
-  manifest_id: 'com.acme.theme',
-  name: 'Acme',
-  size_bytes: 2048,
-  uploaded_at: '2026-05-26T10:00:00Z',
-  uploaded_by: 'admin',
-  uuid: 'aaaa-bbbb',
-  version: '1.0.0'
-}
-
-describe('SpaThemeDetailsDrawer', () => {
-  it('renders summary fields and a download link when a theme is provided', () => {
-    render(<SpaThemeDetailsDrawer onClose={vi.fn()} theme={theme} />)
-
-    expect(screen.getByText('com.acme.theme')).toBeInTheDocument()
-    expect(screen.getByText('aaaa-bbbb')).toBeInTheDocument()
-    expect(screen.getByText('A pretty theme')).toBeInTheDocument()
-
-    const link = screen.getByRole('link', { name: DOWNLOAD_RE }) as HTMLAnchorElement
-    expect(link.getAttribute('href')).toBe('/api/settings/spa-themes/aaaa-bbbb/package')
-  })
-})
diff --git a/apps/web/src/components/spa-theme/spa-theme-details-drawer.tsx b/apps/web/src/components/spa-theme/spa-theme-details-drawer.tsx
deleted file mode 100644
index 0a952e7c..00000000
--- a/apps/web/src/components/spa-theme/spa-theme-details-drawer.tsx
+++ /dev/null
@@ -1,92 +0,0 @@
-import { Download } from 'lucide-react'
-import { useTranslation } from 'react-i18next'
-import type { SpaThemeSummary } from '@/api/spa-themes'
-import { Badge } from '@/components/ui/badge'
-import { buttonVariants } from '@/components/ui/button'
-import { ScrollArea } from '@/components/ui/scroll-area'
-import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle } from '@/components/ui/sheet'
-import { cn, formatBytes } from '@/lib/utils'
-
-interface Props {
-  onClose: () => void
-  theme: SpaThemeSummary | null
-}
-
-export function SpaThemeDetailsDrawer({ theme, onClose }: Props) {
-  const { t } = useTranslation('spa-theme')
-
-  const open = theme !== null
-  const downloadUrl = theme ? `/api/settings/spa-themes/${theme.uuid}/package` : '#'
-
-  // We render the manifest summary directly from the SpaThemeSummary fields the list endpoint returns.
-  // For a future "show file list" view, fetch /api/settings/spa-themes/:uuid here.
-  const manifestPreview = theme
-    ? JSON.stringify(
-        {
-          author: theme.author,
-          description: theme.description,
-          manifest_id: theme.manifest_id,
-          name: theme.name,
-          version: theme.version
-        },
-        null,
-        2
-      )
-    : ''
-
-  return (
-    <Sheet onOpenChange={(v) => !v && onClose()} open={open}>
-      <SheetContent className="flex w-full max-w-md flex-col sm:w-[28rem]" side="right">
-        <SheetHeader>
-          <SheetTitle className="flex items-center gap-2">
-            {theme?.name ?? ''}
-            {theme?.is_active ? <Badge variant="default">{t('active_indicator')}</Badge> : null}
-            {theme?.is_superseded && !theme.is_active ? <Badge variant="secondary">{t('superseded')}</Badge> : null}
-          </SheetTitle>
-          <SheetDescription>
-            v{theme?.version ?? ''}
-            {theme?.author ? ` · ${theme.author}` : ''}
-          </SheetDescription>
-        </SheetHeader>
-
-        <ScrollArea className="min-h-0 flex-1 px-4" data-testid="spa-theme-details-scroll">
-          <div className="space-y-4 pb-4">
-            <dl className="grid grid-cols-[auto_1fr] gap-x-3 gap-y-1 text-sm">
-              <dt className="text-muted-foreground">manifest_id</dt>
-              <dd className="font-mono text-xs">{theme?.manifest_id ?? ''}</dd>
-              <dt className="text-muted-foreground">uuid</dt>
-              <dd className="break-all font-mono text-xs">{theme?.uuid ?? ''}</dd>
-              <dt className="text-muted-foreground">{t('details_drawer.size')}</dt>
-              <dd>{theme ? formatBytes(theme.size_bytes) : ''}</dd>
-              <dt className="text-muted-foreground">{t('details_drawer.uploaded_by')}</dt>
-              <dd>{theme?.uploaded_by ?? ''}</dd>
-              <dt className="text-muted-foreground">{t('details_drawer.uploaded_at')}</dt>
-              <dd className="font-mono text-xs">{theme?.uploaded_at ?? ''}</dd>
-            </dl>
-
-            {theme?.description ? <p className="text-muted-foreground text-sm">{theme.description}</p> : null}
-
-            <div>
-              <div className="mb-1 font-medium text-sm">{t('details_drawer.manifest_heading')}</div>
-              <pre className="overflow-x-auto rounded-md border bg-muted/40 p-3 font-mono text-xs">
-                {manifestPreview}
-              </pre>
-            </div>
-          </div>
-        </ScrollArea>
-
-        <div className="border-t p-4">
-          <a
-            className={cn(buttonVariants({ variant: 'outline' }), 'w-full', !theme && 'pointer-events-none opacity-50')}
-            href={downloadUrl}
-            rel="noreferrer"
-            target="_blank"
-          >
-            <Download className="size-4" />
-            {t('actions.download')}
-          </a>
-        </div>
-      </SheetContent>
-    </Sheet>
-  )
-}
diff --git a/apps/web/src/components/spa-theme/spa-theme-upload-card.test.tsx b/apps/web/src/components/spa-theme/spa-theme-upload-card.test.tsx
deleted file mode 100644
index 89b62c3a..00000000
--- a/apps/web/src/components/spa-theme/spa-theme-upload-card.test.tsx
+++ /dev/null
@@ -1,37 +0,0 @@
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { fireEvent, render, screen } from '@testing-library/react'
-import type { ReactNode } from 'react'
-import { describe, expect, it, vi } from 'vitest'
-import '@/lib/i18n'
-import { SpaThemeUploadCard } from './spa-theme-upload-card'
-
-const DRAG_PROMPT_RE = /Drag .sbtheme/
-
-function wrap(node: ReactNode) {
-  return <QueryClientProvider client={new QueryClient()}>{node}</QueryClientProvider>
-}
-
-describe('SpaThemeUploadCard', () => {
-  it('renders the drag prompt', () => {
-    render(wrap(<SpaThemeUploadCard />))
-    expect(screen.getByText(DRAG_PROMPT_RE)).toBeInTheDocument()
-  })
-
-  it('submits a multipart POST when a file is selected', async () => {
-    const spy = vi.spyOn(global, 'fetch').mockResolvedValue(
-      new Response(
-        JSON.stringify({
-          data: { uuid: 'u', manifest: {}, size_bytes: 1, preview_url: null, is_upgrade_of: null }
-        }),
-        { status: 200 }
-      )
-    )
-    render(wrap(<SpaThemeUploadCard />))
-    const input = document.querySelector('input[type=file]') as HTMLInputElement
-    const file = new File(['x'], 'a.sbtheme', { type: 'application/zip' })
-    fireEvent.change(input, { target: { files: [file] } })
-    await vi.waitFor(() => expect(spy).toHaveBeenCalled())
-    expect(spy.mock.calls[0][1]?.method).toBe('POST')
-    spy.mockRestore()
-  })
-})
diff --git a/apps/web/src/components/spa-theme/spa-theme-upload-card.tsx b/apps/web/src/components/spa-theme/spa-theme-upload-card.tsx
deleted file mode 100644
index b64d5587..00000000
--- a/apps/web/src/components/spa-theme/spa-theme-upload-card.tsx
+++ /dev/null
@@ -1,69 +0,0 @@
-import { Upload } from 'lucide-react'
-import { type ChangeEvent, type DragEvent, useRef, useState } from 'react'
-import { useTranslation } from 'react-i18next'
-import { toast } from 'sonner'
-import { type ApiError, type UploadResult, useUploadSpaTheme } from '@/api/spa-themes'
-
-export function SpaThemeUploadCard() {
-  const { t } = useTranslation('spa-theme')
-  const upload = useUploadSpaTheme()
-  const inputRef = useRef<HTMLInputElement>(null)
-  const [dragOver, setDragOver] = useState(false)
-
-  function pick() {
-    inputRef.current?.click()
-  }
-
-  function submit(file: File) {
-    upload.mutate(file, {
-      onError: (err: ApiError) => {
-        const code = err.code ?? 'default'
-        const details = (err.details ?? {}) as Record<string, unknown>
-        toast.error(t(`errors.${code}` as never, { ...details, message: err.message }))
-      },
-      onSuccess: (result: UploadResult) => {
-        if (result.is_upgrade_of) {
-          toast.success(t('upload_upgrade_success', { previous_version: result.is_upgrade_of.previous_version }))
-        } else {
-          toast.success(t('upload_success'))
-        }
-      }
-    })
-  }
-
-  function onChange(e: ChangeEvent<HTMLInputElement>) {
-    const f = e.target.files?.[0]
-    if (f) {
-      submit(f)
-    }
-  }
-
-  function onDrop(e: DragEvent<HTMLButtonElement>) {
-    e.preventDefault()
-    setDragOver(false)
-    const f = e.dataTransfer.files?.[0]
-    if (f) {
-      submit(f)
-    }
-  }
-
-  return (
-    <button
-      className={`flex aspect-video w-full cursor-pointer flex-col items-center justify-center rounded-lg border-2 border-dashed bg-transparent text-left transition ${
-        dragOver ? 'border-primary bg-accent/40' : 'border-muted'
-      }`}
-      onClick={pick}
-      onDragLeave={() => setDragOver(false)}
-      onDragOver={(e) => {
-        e.preventDefault()
-        setDragOver(true)
-      }}
-      onDrop={onDrop}
-      type="button"
-    >
-      <input accept=".sbtheme,.zip,application/zip" className="hidden" onChange={onChange} ref={inputRef} type="file" />
-      <Upload className="mb-2 size-6 text-muted-foreground" />
-      <div className="text-muted-foreground text-sm">{upload.isPending ? t('upload_progress') : t('upload_drag')}</div>
-    </button>
-  )
-}
diff --git a/apps/web/src/components/theme-provider.tsx b/apps/web/src/components/theme-provider.tsx
index 81356cee..86849dfc 100644
--- a/apps/web/src/components/theme-provider.tsx
+++ b/apps/web/src/components/theme-provider.tsx
@@ -1,31 +1,22 @@
 /* eslint-disable react-refresh/only-export-components */
 import { createContext, type ReactNode, useCallback, useContext, useEffect, useMemo, useState } from 'react'
-import { type ActiveThemeResponse, useActiveTheme, useSetActiveTheme } from '@/api/themes'
-import { type ColorTheme, isColorTheme, loadThemeCSS } from '@/themes'
 
 type Theme = 'dark' | 'light' | 'system'
 type ResolvedTheme = 'dark' | 'light'
 
 interface ThemeProviderProps {
   children: ReactNode
-  colorThemeStorageKey?: string
   defaultTheme?: Theme
   disableTransitionOnChange?: boolean
   storageKey?: string
 }
 
 interface ThemeProviderState {
-  activeTheme: ActiveThemeResponse | null
-  colorTheme: ColorTheme
-  setActiveThemeRef: (ref: string) => void
-  setColorTheme: (colorTheme: ColorTheme) => void
   setTheme: (theme: Theme) => void
   theme: Theme
 }
 
 const COLOR_SCHEME_QUERY = '(prefers-color-scheme: dark)'
-const ACTIVE_THEME_CACHE_KEY = 'active-theme-cache'
-const THEME_RUNTIME_STYLE_ID = 'theme-runtime-style'
 const THEME_VALUES: Theme[] = ['dark', 'light', 'system']
 
 const ThemeProviderContext = createContext<ThemeProviderState | undefined>(undefined)
@@ -38,99 +29,6 @@ function isTheme(value: string | null): value is Theme {
   return THEME_VALUES.includes(value as Theme)
 }
 
-function isStringRecord(value: unknown): value is Record<string, string> {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-    return false
-  }
-
-  return Object.values(value).every((entry) => typeof entry === 'string')
-}
-
-function isActiveThemeResponse(value: unknown): value is ActiveThemeResponse {
-  if (value === null || typeof value !== 'object') {
-    return false
-  }
-
-  const candidate = value as Partial<ActiveThemeResponse>
-  if (typeof candidate.ref !== 'string' || candidate.theme === null || typeof candidate.theme !== 'object') {
-    return false
-  }
-
-  if (candidate.theme.kind === 'preset') {
-    return typeof candidate.theme.id === 'string'
-  }
-
-  if (candidate.theme.kind === 'custom') {
-    return (
-      typeof candidate.theme.id === 'number' &&
-      typeof candidate.theme.name === 'string' &&
-      typeof candidate.theme.updated_at === 'string' &&
-      isStringRecord(candidate.theme.vars_light) &&
-      isStringRecord(candidate.theme.vars_dark)
-    )
-  }
-
-  return false
-}
-
-function readActiveThemeCache(): ActiveThemeResponse | null {
-  return parseActiveThemeCache(localStorage.getItem(ACTIVE_THEME_CACHE_KEY))
-}
-
-function parseActiveThemeCache(value: string | null): ActiveThemeResponse | null {
-  if (value === null) {
-    return null
-  }
-
-  try {
-    const parsed: unknown = JSON.parse(value)
-    if (isActiveThemeResponse(parsed)) {
-      return parsed
-    }
-  } catch {
-    return null
-  }
-
-  return null
-}
-
-function removeRuntimeStyle() {
-  document.getElementById(THEME_RUNTIME_STYLE_ID)?.remove()
-}
-
-function cssVariableName(key: string) {
-  return key.startsWith('--') ? key : `--${key}`
-}
-
-function serializeThemeVars(selector: string, vars: Record<string, string>) {
-  const declarations = Object.entries(vars)
-    .map(([key, value]) => `  ${cssVariableName(key)}: ${value};`)
-    .join('\n')
-
-  return `${selector} {\n${declarations}\n}`
-}
-
-function applyCustomTheme(activeTheme: ActiveThemeResponse) {
-  if (activeTheme.theme.kind !== 'custom') {
-    return
-  }
-
-  const style = document.createElement('style')
-  style.id = THEME_RUNTIME_STYLE_ID
-  style.textContent = [
-    serializeThemeVars(':root', activeTheme.theme.vars_light),
-    serializeThemeVars('.dark', activeTheme.theme.vars_dark)
-  ].join('\n\n')
-  document.head.appendChild(style)
-}
-
-function applyActiveThemeCacheStorageChange(
-  newValue: string | null,
-  setActiveThemeState: (theme: ActiveThemeResponse | null) => void
-) {
-  setActiveThemeState(parseActiveThemeCache(newValue))
-}
-
 function getSystemTheme(): ResolvedTheme {
   if (window.matchMedia(COLOR_SCHEME_QUERY).matches) {
     return 'dark'
@@ -187,12 +85,9 @@ export function ThemeProvider({
   children,
   defaultTheme = 'system',
   storageKey = 'theme',
-  colorThemeStorageKey: _colorThemeStorageKey = 'color-theme',
   disableTransitionOnChange = true,
   ...props
 }: ThemeProviderProps) {
-  const activeThemeQuery = useActiveTheme()
-  const { mutate: setActiveTheme } = useSetActiveTheme()
   const [theme, setThemeState] = useState<Theme>(() => {
     const storedTheme = localStorage.getItem(storageKey)
     if (isTheme(storedTheme)) {
@@ -201,7 +96,6 @@ export function ThemeProvider({
 
     return defaultTheme
   })
-  const [activeTheme, setActiveThemeState] = useState<ActiveThemeResponse | null>(() => readActiveThemeCache())
 
   const setTheme = useCallback(
     (nextTheme: Theme) => {
@@ -211,20 +105,6 @@ export function ThemeProvider({
     [storageKey]
   )
 
-  const setActiveThemeRef = useCallback(
-    (ref: string) => {
-      setActiveTheme(ref)
-    },
-    [setActiveTheme]
-  )
-
-  const setColorTheme = useCallback(
-    (nextColorTheme: ColorTheme) => {
-      setActiveThemeRef(`preset:${nextColorTheme}`)
-    },
-    [setActiveThemeRef]
-  )
-
   const applyTheme = useCallback(
     (nextTheme: Theme) => {
       const root = document.documentElement
@@ -241,15 +121,6 @@ export function ThemeProvider({
     [disableTransitionOnChange]
   )
 
-  useEffect(() => {
-    if (activeThemeQuery.data === undefined) {
-      return
-    }
-
-    setActiveThemeState(activeThemeQuery.data)
-    localStorage.setItem(ACTIVE_THEME_CACHE_KEY, JSON.stringify(activeThemeQuery.data))
-  }, [activeThemeQuery.data])
-
   // Apply light/dark theme
   useEffect(() => {
     applyTheme(theme)
@@ -270,47 +141,6 @@ export function ThemeProvider({
     }
   }, [theme, applyTheme])
 
-  // Apply resolved color theme
-  useEffect(() => {
-    const root = document.documentElement
-    let cancelled = false
-
-    removeRuntimeStyle()
-
-    if (activeTheme === null) {
-      return undefined
-    }
-
-    if (activeTheme.theme.kind === 'custom') {
-      root.removeAttribute('data-theme')
-      applyCustomTheme(activeTheme)
-      return undefined
-    }
-
-    const presetId = activeTheme.theme.id
-    if (presetId === 'default') {
-      root.removeAttribute('data-theme')
-      return undefined
-    }
-
-    if (!isColorTheme(presetId)) {
-      root.removeAttribute('data-theme')
-      return undefined
-    }
-
-    loadThemeCSS(presetId).then(() => {
-      if (cancelled) {
-        return
-      }
-
-      root.setAttribute('data-theme', presetId)
-    })
-
-    return () => {
-      cancelled = true
-    }
-  }, [activeTheme])
-
   useEffect(() => {
     const handleKeyDown = (event: KeyboardEvent) => {
       if (event.repeat) {
@@ -349,18 +179,15 @@ export function ThemeProvider({
         return
       }
 
-      if (event.key === storageKey) {
-        if (isTheme(event.newValue)) {
-          setThemeState(event.newValue)
-          return
-        }
-        setThemeState(defaultTheme)
+      if (event.key !== storageKey) {
         return
       }
 
-      if (event.key === ACTIVE_THEME_CACHE_KEY) {
-        applyActiveThemeCacheStorageChange(event.newValue, setActiveThemeState)
+      if (isTheme(event.newValue)) {
+        setThemeState(event.newValue)
+        return
       }
+      setThemeState(defaultTheme)
     }
 
     window.addEventListener('storage', handleStorageChange)
@@ -370,24 +197,12 @@ export function ThemeProvider({
     }
   }, [defaultTheme, storageKey])
 
-  const colorTheme = useMemo<ColorTheme>(() => {
-    if (activeTheme?.theme.kind !== 'preset') {
-      return 'default'
-    }
-
-    return isColorTheme(activeTheme.theme.id) ? activeTheme.theme.id : 'default'
-  }, [activeTheme])
-
   const value = useMemo(
     () => ({
       theme,
-      setTheme,
-      activeTheme,
-      colorTheme,
-      setColorTheme,
-      setActiveThemeRef
+      setTheme
     }),
-    [theme, setTheme, activeTheme, colorTheme, setColorTheme, setActiveThemeRef]
+    [theme, setTheme]
   )
 
   return (
diff --git a/apps/web/src/components/theme/delete-theme-dialog.test.tsx b/apps/web/src/components/theme/delete-theme-dialog.test.tsx
deleted file mode 100644
index 4a8d3b45..00000000
--- a/apps/web/src/components/theme/delete-theme-dialog.test.tsx
+++ /dev/null
@@ -1,73 +0,0 @@
-import { fireEvent, render, screen } from '@testing-library/react'
-import type { ReactNode } from 'react'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-
-const mockDeleteMutate = vi.fn()
-let mockReferences: { admin: boolean } | undefined
-
-vi.mock('react-i18next', () => ({
-  useTranslation: () => ({
-    t: (key: string, options?: Record<string, unknown>) => {
-      if (typeof options?.name === 'string') {
-        return `${key}:${options.name}`
-      }
-      return key
-    }
-  })
-}))
-
-vi.mock('sonner', () => ({
-  toast: {
-    error: vi.fn(),
-    success: vi.fn()
-  }
-}))
-
-vi.mock('@/api/themes', () => ({
-  useDeleteTheme: () => ({
-    isPending: false,
-    mutate: mockDeleteMutate
-  }),
-  useThemeReferences: () => ({
-    data: mockReferences,
-    isLoading: false
-  })
-}))
-
-vi.mock('@/components/ui/dialog', () => ({
-  Dialog: ({ children }: { children?: ReactNode }) => <div>{children}</div>,
-  DialogContent: ({ children }: { children?: ReactNode }) => <div>{children}</div>,
-  DialogFooter: ({ children }: { children?: ReactNode }) => <div>{children}</div>,
-  DialogHeader: ({ children }: { children?: ReactNode }) => <div>{children}</div>,
-  DialogTitle: ({ children }: { children?: ReactNode }) => <h2>{children}</h2>
-}))
-
-const { DeleteThemeDialog } = await import('./delete-theme-dialog')
-
-describe('DeleteThemeDialog', () => {
-  beforeEach(() => {
-    mockDeleteMutate.mockReset()
-    mockReferences = undefined
-  })
-
-  it('blocks deletion when a theme is referenced as the admin active theme', () => {
-    mockReferences = {
-      admin: true
-    }
-
-    render(<DeleteThemeDialog onClose={vi.fn()} theme={{ id: 7, name: 'In Use' }} />)
-
-    expect(screen.getByText('appearance.custom_themes.delete_used_admin')).toBeInTheDocument()
-    expect(screen.queryByRole('button', { name: 'common:delete' })).not.toBeInTheDocument()
-  })
-
-  it('calls delete mutation when no references exist', () => {
-    mockReferences = { admin: false }
-
-    render(<DeleteThemeDialog onClose={vi.fn()} theme={{ id: 7, name: 'Unused' }} />)
-
-    fireEvent.click(screen.getByRole('button', { name: 'common:delete' }))
-
-    expect(mockDeleteMutate).toHaveBeenCalledWith(7, expect.any(Object))
-  })
-})
diff --git a/apps/web/src/components/theme/delete-theme-dialog.tsx b/apps/web/src/components/theme/delete-theme-dialog.tsx
deleted file mode 100644
index 42999e54..00000000
--- a/apps/web/src/components/theme/delete-theme-dialog.tsx
+++ /dev/null
@@ -1,76 +0,0 @@
-import { useTranslation } from 'react-i18next'
-import { toast } from 'sonner'
-import { useDeleteTheme, useThemeReferences } from '@/api/themes'
-import { Button } from '@/components/ui/button'
-import { Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle } from '@/components/ui/dialog'
-
-interface DeleteThemeDialogProps {
-  onClose: () => void
-  theme: {
-    id: number
-    name: string
-  }
-}
-
-export function DeleteThemeDialog({ onClose, theme }: DeleteThemeDialogProps) {
-  const { t } = useTranslation(['settings', 'common'])
-  const { data: references, isLoading } = useThemeReferences(theme.id)
-  const deleteTheme = useDeleteTheme()
-  const blocked = references?.admin === true
-
-  return (
-    <Dialog
-      onOpenChange={(open) => {
-        if (!open) {
-          onClose()
-        }
-      }}
-      open
-    >
-      <DialogContent>
-        <DialogHeader>
-          <DialogTitle>{t('appearance.custom_themes.delete_title', { name: theme.name })}</DialogTitle>
-        </DialogHeader>
-
-        {isLoading && <p className="text-muted-foreground text-sm">{t('common:loading')}</p>}
-
-        {references && !blocked && <p className="text-sm">{t('appearance.custom_themes.delete_confirm')}</p>}
-
-        {blocked && references && (
-          <div className="space-y-2 text-sm">
-            <p>{t('appearance.custom_themes.delete_blocked')}</p>
-            <ul className="list-disc pl-6">
-              {references.admin && <li>{t('appearance.custom_themes.delete_used_admin')}</li>}
-            </ul>
-          </div>
-        )}
-
-        <DialogFooter>
-          <Button onClick={onClose} type="button" variant="outline">
-            {t('common:cancel')}
-          </Button>
-          {!blocked && (
-            <Button
-              disabled={!references || deleteTheme.isPending}
-              onClick={() => {
-                deleteTheme.mutate(theme.id, {
-                  onError: (error) => {
-                    toast.error(error instanceof Error ? error.message : t('common:errors.operation_failed'))
-                  },
-                  onSuccess: () => {
-                    toast.success(t('appearance.custom_themes.deleted'))
-                    onClose()
-                  }
-                })
-              }}
-              type="button"
-              variant="destructive"
-            >
-              {t('common:delete')}
-            </Button>
-          )}
-        </DialogFooter>
-      </DialogContent>
-    </Dialog>
-  )
-}
diff --git a/apps/web/src/components/theme/oklch-picker.test.tsx b/apps/web/src/components/theme/oklch-picker.test.tsx
deleted file mode 100644
index 5dec41eb..00000000
--- a/apps/web/src/components/theme/oklch-picker.test.tsx
+++ /dev/null
@@ -1,27 +0,0 @@
-import { fireEvent, render, screen } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
-import { OklchPicker } from './oklch-picker'
-
-const OKLCH_PREFIX_RE = /^oklch\(/
-
-describe('OklchPicker', () => {
-  it('updates the L channel through the slider', () => {
-    const onChange = vi.fn()
-
-    render(<OklchPicker onChange={onChange} value="oklch(0.5 0.1 180)" />)
-
-    fireEvent.change(screen.getByLabelText('L'), { target: { value: '0.75' } })
-
-    expect(onChange).toHaveBeenCalledWith('oklch(0.75 0.1 180)')
-  })
-
-  it('converts valid hex input to OKLCH', () => {
-    const onChange = vi.fn()
-
-    render(<OklchPicker onChange={onChange} value="oklch(0.5 0.1 180)" />)
-
-    fireEvent.change(screen.getByPlaceholderText('#rrggbb'), { target: { value: '#ff0000' } })
-
-    expect(onChange).toHaveBeenCalledWith(expect.stringMatching(OKLCH_PREFIX_RE))
-  })
-})
diff --git a/apps/web/src/components/theme/oklch-picker.tsx b/apps/web/src/components/theme/oklch-picker.tsx
deleted file mode 100644
index 6a70dc16..00000000
--- a/apps/web/src/components/theme/oklch-picker.tsx
+++ /dev/null
@@ -1,89 +0,0 @@
-import { useEffect, useState } from 'react'
-import { Input } from '@/components/ui/input'
-import { formatOklch, hexToOklch, oklchToHex, parseOklch } from '@/lib/oklch'
-
-const HEX_COLOR_RE = /^#[0-9a-fA-F]{6}$/
-
-interface OklchPickerProps {
-  onChange: (next: string) => void
-  showHex?: boolean
-  value: string
-}
-
-export function OklchPicker({ onChange, showHex = true, value }: OklchPickerProps) {
-  const parsed = parseOklch(value) ?? { c: 0.1, h: 0, l: 0.5 }
-  const [hex, setHex] = useState(() => oklchToHex(value) ?? '')
-
-  useEffect(() => {
-    const nextHex = oklchToHex(value)
-    if (nextHex) {
-      setHex(nextHex)
-    }
-  }, [value])
-
-  const update = (next: Partial<typeof parsed>) => {
-    onChange(formatOklch({ ...parsed, ...next }))
-  }
-
-  const onHexChange = (nextHex: string) => {
-    setHex(nextHex)
-    if (HEX_COLOR_RE.test(nextHex)) {
-      const oklch = hexToOklch(nextHex)
-      if (oklch) {
-        onChange(oklch)
-      }
-    }
-  }
-
-  return (
-    <div className="flex items-center gap-2">
-      <div className="size-6 rounded border" style={{ background: value }} />
-      <div className="grid flex-1 grid-cols-3 gap-1">
-        <ChannelSlider label="L" max={1} min={0} onChange={(l) => update({ l })} step={0.01} value={parsed.l} />
-        <ChannelSlider label="C" max={0.5} min={0} onChange={(c) => update({ c })} step={0.005} value={parsed.c} />
-        <ChannelSlider label="H" max={360} min={0} onChange={(h) => update({ h })} step={1} value={parsed.h} />
-      </div>
-      {showHex && (
-        <Input
-          className="w-24"
-          onChange={(event) => onHexChange(event.target.value)}
-          placeholder="#rrggbb"
-          value={hex}
-        />
-      )}
-    </div>
-  )
-}
-
-function ChannelSlider({
-  label,
-  max,
-  min,
-  onChange,
-  step,
-  value
-}: {
-  label: string
-  max: number
-  min: number
-  onChange: (value: number) => void
-  step: number
-  value: number
-}) {
-  return (
-    <label className="flex items-center gap-1 text-xs">
-      <span className="w-3 text-muted-foreground">{label}</span>
-      <input
-        aria-label={label}
-        className="flex-1"
-        max={max}
-        min={min}
-        onChange={(event) => onChange(Number(event.target.value))}
-        step={step}
-        type="range"
-        value={value}
-      />
-      <span className="w-10 text-right tabular-nums">{value.toFixed(label === 'H' ? 0 : 2)}</span>
-    </label>
-  )
-}
diff --git a/apps/web/src/components/theme/theme-card.test.tsx b/apps/web/src/components/theme/theme-card.test.tsx
deleted file mode 100644
index b604e57c..00000000
--- a/apps/web/src/components/theme/theme-card.test.tsx
+++ /dev/null
@@ -1,48 +0,0 @@
-import { fireEvent, render, screen } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
-
-vi.mock('react-i18next', () => ({
-  useTranslation: () => ({ t: (key: string) => key })
-}))
-
-import { ThemeCard } from './theme-card'
-
-const TOKYO_NIGHT_RE = /Tokyo Night/
-
-describe('ThemeCard', () => {
-  it('activates the theme from the main card button', () => {
-    const onActivate = vi.fn()
-
-    render(<ThemeCard active={false} name="Tokyo Night" onActivate={onActivate} preview={['#111111', '#222222']} />)
-
-    fireEvent.click(screen.getByRole('button', { name: TOKYO_NIGHT_RE }))
-
-    expect(onActivate).toHaveBeenCalledTimes(1)
-  })
-
-  it('renders edit, duplicate, and delete actions without activating the theme', () => {
-    const onActivate = vi.fn()
-    const onEdit = vi.fn()
-    const onDuplicate = vi.fn()
-    const onDelete = vi.fn()
-
-    render(
-      <ThemeCard
-        actions={{ onDelete, onDuplicate, onEdit }}
-        active
-        name="Custom Theme"
-        onActivate={onActivate}
-        preview={['#111111']}
-      />
-    )
-
-    fireEvent.click(screen.getByRole('button', { name: 'appearance.custom_themes.edit' }))
-    fireEvent.click(screen.getByRole('button', { name: 'appearance.custom_themes.duplicate' }))
-    fireEvent.click(screen.getByRole('button', { name: 'appearance.custom_themes.delete' }))
-
-    expect(onEdit).toHaveBeenCalledTimes(1)
-    expect(onDuplicate).toHaveBeenCalledTimes(1)
-    expect(onDelete).toHaveBeenCalledTimes(1)
-    expect(onActivate).not.toHaveBeenCalled()
-  })
-})
diff --git a/apps/web/src/components/theme/theme-card.tsx b/apps/web/src/components/theme/theme-card.tsx
deleted file mode 100644
index 03500d70..00000000
--- a/apps/web/src/components/theme/theme-card.tsx
+++ /dev/null
@@ -1,97 +0,0 @@
-import { Check, Copy, Pencil, Trash2 } from 'lucide-react'
-import { useTranslation } from 'react-i18next'
-import { Button } from '@/components/ui/button'
-
-interface ThemeCardActions {
-  onDelete?: () => void
-  onDuplicate?: () => void
-  onEdit?: () => void
-}
-
-interface ThemeCardProps {
-  actions?: ThemeCardActions
-  active: boolean
-  name: string
-  onActivate: () => void
-  preview: string[]
-}
-
-export function ThemeCard({ actions, active, name, onActivate, preview }: ThemeCardProps) {
-  const { t } = useTranslation('settings')
-  const hasActions = actions !== undefined
-  const swatches =
-    preview.length > 0 ? preview : ['var(--primary)', 'var(--accent)', 'var(--background)', 'var(--foreground)']
-
-  return (
-    <div className="group relative">
-      <button
-        className={`w-full rounded-lg border-2 p-3 text-left transition-all hover:shadow-md ${
-          active ? 'border-primary shadow-sm' : 'border-border hover:border-primary/50'
-        }`}
-        onClick={onActivate}
-        type="button"
-      >
-        <div className="mb-2 flex gap-1.5">
-          {swatches.map((color) => (
-            <div
-              className="size-6 rounded-full border border-black/10"
-              key={`${name}-${color}`}
-              style={{ backgroundColor: color }}
-            />
-          ))}
-        </div>
-        <div className="flex items-center gap-1.5">
-          <span className="font-medium text-sm">{name}</span>
-          {active && <Check className="size-3.5 text-primary" />}
-        </div>
-      </button>
-
-      {hasActions && (
-        <div className="absolute top-2 right-2 hidden gap-1 group-focus-within:flex group-hover:flex">
-          {actions.onEdit && (
-            <Button
-              aria-label={t('appearance.custom_themes.edit')}
-              onClick={(event) => {
-                event.stopPropagation()
-                actions.onEdit?.()
-              }}
-              size="icon-sm"
-              type="button"
-              variant="ghost"
-            >
-              <Pencil className="size-3.5" />
-            </Button>
-          )}
-          {actions.onDuplicate && (
-            <Button
-              aria-label={t('appearance.custom_themes.duplicate')}
-              onClick={(event) => {
-                event.stopPropagation()
-                actions.onDuplicate?.()
-              }}
-              size="icon-sm"
-              type="button"
-              variant="ghost"
-            >
-              <Copy className="size-3.5" />
-            </Button>
-          )}
-          {actions.onDelete && (
-            <Button
-              aria-label={t('appearance.custom_themes.delete')}
-              onClick={(event) => {
-                event.stopPropagation()
-                actions.onDelete?.()
-              }}
-              size="icon-sm"
-              type="button"
-              variant="ghost"
-            >
-              <Trash2 className="size-3.5" />
-            </Button>
-          )}
-        </div>
-      )}
-    </div>
-  )
-}
diff --git a/apps/web/src/components/theme/theme-editor.test.tsx b/apps/web/src/components/theme/theme-editor.test.tsx
deleted file mode 100644
index 9fbdda0c..00000000
--- a/apps/web/src/components/theme/theme-editor.test.tsx
+++ /dev/null
@@ -1,82 +0,0 @@
-import { fireEvent, render, screen } from '@testing-library/react'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-
-const mockNavigate = vi.fn()
-const mockUpdateMutate = vi.fn()
-
-const theme = {
-  based_on: 'default',
-  created_at: '2026-04-30T00:00:00Z',
-  description: null,
-  id: 7,
-  name: 'Original',
-  updated_at: '2026-04-30T00:00:00Z',
-  vars_dark: {
-    background: 'oklch(0.1 0 0)',
-    foreground: 'oklch(0.9 0 0)',
-    primary: 'oklch(0.7 0.1 180)'
-  },
-  vars_light: {
-    background: 'oklch(1 0 0)',
-    foreground: 'oklch(0 0 0)',
-    primary: 'oklch(0.5 0.1 180)'
-  }
-}
-
-vi.mock('@tanstack/react-router', () => ({
-  useNavigate: () => mockNavigate
-}))
-
-vi.mock('react-i18next', () => ({
-  useTranslation: () => ({
-    t: (key: string) => key
-  })
-}))
-
-vi.mock('sonner', () => ({
-  toast: {
-    error: vi.fn(),
-    success: vi.fn()
-  }
-}))
-
-vi.mock('@/api/themes', () => ({
-  useThemeQuery: () => ({
-    data: theme,
-    isLoading: false
-  }),
-  useUpdateTheme: () => ({
-    isPending: false,
-    mutate: mockUpdateMutate
-  })
-}))
-
-const { ThemeEditor } = await import('./theme-editor')
-
-describe('ThemeEditor', () => {
-  beforeEach(() => {
-    mockNavigate.mockReset()
-    mockUpdateMutate.mockReset()
-  })
-
-  it('saves the edited theme name with both variable maps', () => {
-    render(<ThemeEditor themeId={7} />)
-
-    fireEvent.change(screen.getByDisplayValue('Original'), { target: { value: 'Renamed' } })
-    fireEvent.click(screen.getByRole('button', { name: 'common:save' }))
-
-    expect(mockUpdateMutate).toHaveBeenCalledWith(
-      {
-        body: {
-          based_on: 'default',
-          description: null,
-          name: 'Renamed',
-          vars_dark: theme.vars_dark,
-          vars_light: theme.vars_light
-        },
-        id: 7
-      },
-      expect.any(Object)
-    )
-  })
-})
diff --git a/apps/web/src/components/theme/theme-editor.tsx b/apps/web/src/components/theme/theme-editor.tsx
deleted file mode 100644
index c7fe4a68..00000000
--- a/apps/web/src/components/theme/theme-editor.tsx
+++ /dev/null
@@ -1,290 +0,0 @@
-import { useNavigate } from '@tanstack/react-router'
-import { useEffect, useState } from 'react'
-import { useTranslation } from 'react-i18next'
-import { toast } from 'sonner'
-import { type ExportPayload, type FullTheme, useThemeQuery, useUpdateTheme } from '@/api/themes'
-import { Button } from '@/components/ui/button'
-import { Input } from '@/components/ui/input'
-import { ScrollArea } from '@/components/ui/scroll-area'
-import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs'
-import { api } from '@/lib/api-client'
-import { isColorTheme } from '@/themes'
-import { type PresetVarKey, presetVars } from '@/themes/preset-vars'
-import { OklchPicker } from './oklch-picker'
-import { ThemePreview } from './theme-preview'
-
-type ThemeMode = 'dark' | 'light'
-
-const VAR_GROUPS: { id: string; vars: PresetVarKey[] }[] = [
-  { id: 'surface', vars: ['background', 'foreground', 'card', 'card-foreground', 'popover', 'popover-foreground'] },
-  { id: 'primary', vars: ['primary', 'primary-foreground', 'secondary', 'secondary-foreground'] },
-  { id: 'state', vars: ['muted', 'muted-foreground', 'accent', 'accent-foreground', 'destructive'] },
-  { id: 'border', vars: ['border', 'input', 'ring'] },
-  { id: 'chart', vars: ['chart-1', 'chart-2', 'chart-3', 'chart-4', 'chart-5'] },
-  {
-    id: 'sidebar',
-    vars: [
-      'sidebar',
-      'sidebar-foreground',
-      'sidebar-primary',
-      'sidebar-primary-foreground',
-      'sidebar-accent',
-      'sidebar-accent-foreground',
-      'sidebar-border',
-      'sidebar-ring'
-    ]
-  }
-]
-
-interface ThemeEditorProps {
-  themeId: number
-}
-
-function isThemeMode(value: string | null): value is ThemeMode {
-  return value === 'dark' || value === 'light'
-}
-
-function initialStateFromTheme(theme: FullTheme) {
-  return {
-    dark: theme.vars_dark,
-    light: theme.vars_light,
-    name: theme.name
-  }
-}
-
-function downloadJsonFile(filename: string, payload: unknown) {
-  const blob = new Blob([JSON.stringify(payload, null, 2)], { type: 'application/json' })
-  const url = URL.createObjectURL(blob)
-  const anchor = document.createElement('a')
-  anchor.href = url
-  anchor.download = filename
-  anchor.click()
-  URL.revokeObjectURL(url)
-}
-
-function safeFilename(name: string) {
-  return (
-    name
-      .trim()
-      .replaceAll(/[^a-zA-Z0-9._-]+/g, '-')
-      .replaceAll(/^-|-$/g, '') || 'theme'
-  )
-}
-
-function forkVarsForMode(theme: FullTheme, editingMode: ThemeMode) {
-  if (!(theme.based_on && isColorTheme(theme.based_on))) {
-    return null
-  }
-
-  if (editingMode === 'light') {
-    return presetVars[theme.based_on].light
-  }
-
-  return presetVars[theme.based_on].dark
-}
-
-export function ThemeEditor({ themeId }: ThemeEditorProps) {
-  const { t } = useTranslation(['settings', 'common'])
-  const navigate = useNavigate()
-  const { data, isLoading } = useThemeQuery(themeId)
-  const updateTheme = useUpdateTheme()
-  const [name, setName] = useState('')
-  const [light, setLight] = useState<Record<string, string>>({})
-  const [dark, setDark] = useState<Record<string, string>>({})
-  const [editingMode, setEditingMode] = useState<ThemeMode>('light')
-  const [previewMode, setPreviewMode] = useState<ThemeMode | null>(null)
-  const [dirty, setDirty] = useState(false)
-  const [exporting, setExporting] = useState(false)
-
-  useEffect(() => {
-    if (!data || dirty) {
-      return
-    }
-
-    const initial = initialStateFromTheme(data)
-    setName(initial.name)
-    setLight(initial.light)
-    setDark(initial.dark)
-  }, [data, dirty])
-
-  useEffect(() => {
-    if (!dirty) {
-      return undefined
-    }
-
-    const handler = (event: BeforeUnloadEvent) => {
-      event.preventDefault()
-      event.returnValue = ''
-    }
-    window.addEventListener('beforeunload', handler)
-
-    return () => window.removeEventListener('beforeunload', handler)
-  }, [dirty])
-
-  if (isLoading || !data) {
-    return <div className="p-6 text-muted-foreground text-sm">{t('common:loading')}</div>
-  }
-
-  const currentMap = editingMode === 'light' ? light : dark
-  const forkVars = forkVarsForMode(data, editingMode)
-  const previewWhich = previewMode ?? editingMode
-
-  const setVar = (key: PresetVarKey, value: string) => {
-    if (editingMode === 'light') {
-      setLight((current) => ({ ...current, [key]: value }))
-    } else {
-      setDark((current) => ({ ...current, [key]: value }))
-    }
-    setDirty(true)
-  }
-
-  const resetVar = (key: PresetVarKey) => {
-    const value = forkVars?.[key]
-    if (!value) {
-      return
-    }
-    setVar(key, value)
-  }
-
-  const save = () => {
-    updateTheme.mutate(
-      {
-        body: {
-          based_on: data.based_on,
-          description: data.description,
-          name,
-          vars_dark: dark,
-          vars_light: light
-        },
-        id: themeId
-      },
-      {
-        onError: (error) => {
-          toast.error(error instanceof Error ? error.message : t('common:errors.operation_failed'))
-        },
-        onSuccess: () => {
-          toast.success(t('appearance.editor.saved'))
-          setDirty(false)
-          navigate({ to: '/settings/appearance' })
-        }
-      }
-    )
-  }
-
-  const exportTheme = async () => {
-    setExporting(true)
-    try {
-      const payload = await api.get<ExportPayload>(`/api/settings/themes/${themeId}/export`)
-      downloadJsonFile(`${safeFilename(name)}.theme.json`, payload)
-    } catch (error) {
-      toast.error(error instanceof Error ? error.message : t('common:errors.operation_failed'))
-    } finally {
-      setExporting(false)
-    }
-  }
-
-  return (
-    <div className="flex h-full min-h-0 flex-col">
-      <div className="flex flex-wrap items-center gap-3 border-b p-4">
-        <Input
-          className="max-w-xs"
-          onChange={(event) => {
-            setName(event.target.value)
-            setDirty(true)
-          }}
-          value={name}
-        />
-        {data.based_on && (
-          <span className="text-muted-foreground text-sm">
-            {t('appearance.editor.based_on', { name: data.based_on })}
-          </span>
-        )}
-        <div className="ml-auto flex gap-2">
-          <Button disabled={exporting} onClick={exportTheme} type="button" variant="outline">
-            {t('appearance.custom_themes.export')}
-          </Button>
-          <Button onClick={() => navigate({ to: '/settings/appearance' })} type="button" variant="outline">
-            {t('common:cancel')}
-          </Button>
-          <Button disabled={!dirty || updateTheme.isPending} onClick={save} type="button">
-            {t('common:save')}
-          </Button>
-        </div>
-      </div>
-
-      <div className="grid min-h-0 flex-1 grid-cols-1 lg:grid-cols-2">
-        <div className="min-h-0 border-r">
-          <ScrollArea className="h-full">
-            <div className="p-3">
-              <Tabs
-                onValueChange={(value) => {
-                  if (isThemeMode(value)) {
-                    setEditingMode(value)
-                  }
-                }}
-                value={editingMode}
-              >
-                <TabsList className="mb-3">
-                  <TabsTrigger value="light">{t('appearance.editor.light')}</TabsTrigger>
-                  <TabsTrigger value="dark">{t('appearance.editor.dark')}</TabsTrigger>
-                </TabsList>
-              </Tabs>
-
-              <div className="space-y-4">
-                {VAR_GROUPS.map((group) => (
-                  <section className="rounded-lg border p-3" key={group.id}>
-                    <h2 className="mb-3 font-medium text-sm">{t(`appearance.editor.groups.${group.id}`)}</h2>
-                    <div className="space-y-2">
-                      {group.vars.map((key) => (
-                        <div className="grid gap-2 sm:grid-cols-[8rem_1fr_auto] sm:items-center" key={key}>
-                          <span className="font-mono text-xs">{key}</span>
-                          <OklchPicker onChange={(value) => setVar(key, value)} value={currentMap[key] ?? ''} />
-                          {forkVars && (
-                            <Button onClick={() => resetVar(key)} size="sm" type="button" variant="ghost">
-                              {t('appearance.editor.reset')}
-                            </Button>
-                          )}
-                        </div>
-                      ))}
-                    </div>
-                  </section>
-                ))}
-              </div>
-            </div>
-          </ScrollArea>
-        </div>
-
-        <div className="flex min-h-0 flex-col">
-          <ThemePreview dark={previewWhich === 'dark'} vars={previewWhich === 'light' ? light : dark} />
-          <div className="flex flex-wrap items-center gap-2 border-t p-3 text-xs">
-            <span>{t('appearance.editor.preview_mode')}</span>
-            <Button
-              onClick={() => setPreviewMode(null)}
-              size="sm"
-              type="button"
-              variant={previewMode === null ? 'default' : 'outline'}
-            >
-              {t('appearance.editor.linked')}
-            </Button>
-            <Button
-              onClick={() => setPreviewMode('light')}
-              size="sm"
-              type="button"
-              variant={previewMode === 'light' ? 'default' : 'outline'}
-            >
-              {t('appearance.editor.light')}
-            </Button>
-            <Button
-              onClick={() => setPreviewMode('dark')}
-              size="sm"
-              type="button"
-              variant={previewMode === 'dark' ? 'default' : 'outline'}
-            >
-              {t('appearance.editor.dark')}
-            </Button>
-          </div>
-        </div>
-      </div>
-    </div>
-  )
-}
diff --git a/apps/web/src/components/theme/theme-preview.test.tsx b/apps/web/src/components/theme/theme-preview.test.tsx
deleted file mode 100644
index 3314436f..00000000
--- a/apps/web/src/components/theme/theme-preview.test.tsx
+++ /dev/null
@@ -1,21 +0,0 @@
-import { render, screen } from '@testing-library/react'
-import { describe, expect, it } from 'vitest'
-import { ThemePreview } from './theme-preview'
-
-describe('ThemePreview', () => {
-  it('applies theme variables to the preview root', () => {
-    render(<ThemePreview dark={false} vars={{ background: 'oklch(1 0 0)', foreground: 'oklch(0 0 0)' }} />)
-
-    const preview = screen.getByTestId('theme-preview')
-
-    expect(preview).toHaveStyle('--background: oklch(1 0 0)')
-    expect(preview).toHaveStyle('--foreground: oklch(0 0 0)')
-    expect(preview).not.toHaveClass('dark')
-  })
-
-  it('adds the dark class for dark preview mode', () => {
-    render(<ThemePreview dark vars={{ background: 'oklch(0 0 0)' }} />)
-
-    expect(screen.getByTestId('theme-preview')).toHaveClass('dark')
-  })
-})
diff --git a/apps/web/src/components/theme/theme-preview.tsx b/apps/web/src/components/theme/theme-preview.tsx
deleted file mode 100644
index 26983d31..00000000
--- a/apps/web/src/components/theme/theme-preview.tsx
+++ /dev/null
@@ -1,56 +0,0 @@
-import type { CSSProperties } from 'react'
-import { Badge } from '@/components/ui/badge'
-import { Button } from '@/components/ui/button'
-import { Input } from '@/components/ui/input'
-
-interface ThemePreviewProps {
-  dark: boolean
-  vars: Record<string, string>
-}
-
-function cssVariableKey(key: string): `--${string}` {
-  return key.startsWith('--') ? `--${key.slice(2)}` : `--${key}`
-}
-
-export function ThemePreview({ dark, vars }: ThemePreviewProps) {
-  const style: CSSProperties & Record<`--${string}`, string> = {
-    background: 'var(--background)',
-    color: 'var(--foreground)'
-  }
-
-  for (const [key, value] of Object.entries(vars)) {
-    style[cssVariableKey(key)] = value
-  }
-
-  return (
-    <div className={`flex-1 p-6 ${dark ? 'dark' : ''}`} data-testid="theme-preview" data-theme-preview style={style}>
-      <div className="rounded-lg border p-4" style={{ background: 'var(--card)', borderColor: 'var(--border)' }}>
-        <h3 className="mb-2 font-semibold">Sample Card</h3>
-        <p className="mb-3 text-sm" style={{ color: 'var(--muted-foreground)' }}>
-          Preview of typography, buttons, and inputs.
-        </p>
-        <div className="mb-3 flex flex-wrap gap-2">
-          <Button type="button">Primary</Button>
-          <Button type="button" variant="secondary">
-            Secondary
-          </Button>
-          <Button type="button" variant="destructive">
-            Destructive
-          </Button>
-        </div>
-        <Input className="mb-3" placeholder="Input field" />
-        <div className="flex flex-wrap gap-2">
-          <Badge>Default</Badge>
-          <Badge variant="secondary">Secondary</Badge>
-          <Badge variant="outline">Outline</Badge>
-        </div>
-      </div>
-
-      <div className="mt-4 grid grid-cols-5 gap-2">
-        {[1, 2, 3, 4, 5].map((index) => (
-          <div className="h-16 rounded" key={index} style={{ background: `var(--chart-${index})` }} />
-        ))}
-      </div>
-    </div>
-  )
-}
diff --git a/apps/web/src/lib/i18n.ts b/apps/web/src/lib/i18n.ts
index acee3458..4e93d1b6 100644
--- a/apps/web/src/lib/i18n.ts
+++ b/apps/web/src/lib/i18n.ts
@@ -15,7 +15,6 @@ import enSecurity from '@/locales/en/security.json'
 import enServers from '@/locales/en/servers.json'
 import enServiceMonitors from '@/locales/en/service-monitors.json'
 import enSettings from '@/locales/en/settings.json'
-import enSpaTheme from '@/locales/en/spa-theme.json'
 import enStatus from '@/locales/en/status.json'
 import enTerminal from '@/locales/en/terminal.json'
 
@@ -32,7 +31,6 @@ import zhSecurity from '@/locales/zh/security.json'
 import zhServers from '@/locales/zh/servers.json'
 import zhServiceMonitors from '@/locales/zh/service-monitors.json'
 import zhSettings from '@/locales/zh/settings.json'
-import zhSpaTheme from '@/locales/zh/spa-theme.json'
 import zhStatus from '@/locales/zh/status.json'
 import zhTerminal from '@/locales/zh/terminal.json'
 
@@ -55,7 +53,6 @@ i18next
         servers: enServers,
         'service-monitors': enServiceMonitors,
         settings: enSettings,
-        'spa-theme': enSpaTheme,
         status: enStatus,
         terminal: enTerminal
       },
@@ -73,7 +70,6 @@ i18next
         servers: zhServers,
         'service-monitors': zhServiceMonitors,
         settings: zhSettings,
-        'spa-theme': zhSpaTheme,
         status: zhStatus,
         terminal: zhTerminal
       }
diff --git a/apps/web/src/lib/theme-ref.test.ts b/apps/web/src/lib/theme-ref.test.ts
deleted file mode 100644
index bc363f46..00000000
--- a/apps/web/src/lib/theme-ref.test.ts
+++ /dev/null
@@ -1,62 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { parseThemeRef, themeRefToString } from './theme-ref'
-
-describe('parseThemeRef', () => {
-  it('parses preset theme refs', () => {
-    expect(parseThemeRef('preset:default')).toEqual({ kind: 'preset', id: 'default' })
-  })
-
-  it('parses custom theme refs', () => {
-    expect(parseThemeRef('custom:42')).toEqual({ kind: 'custom', id: 42 })
-  })
-
-  it('parses the largest supported custom theme id', () => {
-    expect(parseThemeRef('custom:2147483647')).toEqual({ kind: 'custom', id: 2_147_483_647 })
-  })
-
-  it('rejects unknown preset ids', () => {
-    expect(parseThemeRef('preset:nonsense')).toBeNull()
-  })
-
-  it('rejects malformed custom ids', () => {
-    for (const ref of [
-      'custom:abc',
-      'custom:0',
-      'custom:-1',
-      'custom:+1',
-      'custom:1.2',
-      'custom:1e2',
-      'custom:001',
-      'custom:2147483648'
-    ]) {
-      expect(parseThemeRef(ref)).toBeNull()
-    }
-  })
-
-  it('rejects empty suffixes', () => {
-    expect(parseThemeRef('preset:')).toBeNull()
-    expect(parseThemeRef('custom:')).toBeNull()
-  })
-
-  it('rejects custom ids with surrounding whitespace', () => {
-    expect(parseThemeRef('custom: 1')).toBeNull()
-    expect(parseThemeRef('custom:1 ')).toBeNull()
-  })
-
-  it('rejects unknown schemes', () => {
-    expect(parseThemeRef('foo:bar')).toBeNull()
-  })
-})
-
-describe('themeRefToString', () => {
-  it('round trips theme refs through strings', () => {
-    const refs = [
-      { kind: 'custom', id: 42 },
-      { kind: 'preset', id: 'nord' }
-    ] as const
-
-    for (const ref of refs) {
-      expect(parseThemeRef(themeRefToString(ref))).toEqual(ref)
-    }
-  })
-})
diff --git a/apps/web/src/lib/theme-ref.ts b/apps/web/src/lib/theme-ref.ts
deleted file mode 100644
index 7e25818e..00000000
--- a/apps/web/src/lib/theme-ref.ts
+++ /dev/null
@@ -1,33 +0,0 @@
-import { type ColorTheme, isColorTheme } from '@/themes'
-
-export type ThemeRef = { kind: 'preset'; id: ColorTheme } | { kind: 'custom'; id: number }
-
-const CUSTOM_ID_PATTERN = /^[1-9]\d*$/
-const MAX_CUSTOM_ID = 2_147_483_647
-
-export function parseThemeRef(s: string): ThemeRef | null {
-  if (s.startsWith('preset:')) {
-    const id = s.slice('preset:'.length)
-    return isColorTheme(id) ? { kind: 'preset', id } : null
-  }
-
-  if (s.startsWith('custom:')) {
-    const id = parseCustomId(s.slice('custom:'.length))
-    return id === null ? null : { kind: 'custom', id }
-  }
-
-  return null
-}
-
-export function themeRefToString(r: ThemeRef): string {
-  return r.kind === 'preset' ? `preset:${r.id}` : `custom:${r.id}`
-}
-
-function parseCustomId(raw: string): number | null {
-  if (!CUSTOM_ID_PATTERN.test(raw)) {
-    return null
-  }
-
-  const id = Number(raw)
-  return id <= MAX_CUSTOM_ID ? id : null
-}
diff --git a/apps/web/src/locales/en/settings.json b/apps/web/src/locales/en/settings.json
index 12887585..1d77d05a 100644
--- a/apps/web/src/locales/en/settings.json
+++ b/apps/web/src/locales/en/settings.json
@@ -279,8 +279,9 @@
   "tasks.scheduled.confirm_delete": "Delete this scheduled task?",
 
   "appearance.title": "Appearance",
-  "appearance.color_theme": "Color Theme",
-  "appearance.color_theme_description": "Choose a color theme for the dashboard. The theme applies to both light and dark modes.",
+  "appearance.theme_moved_title": "Themes have moved",
+  "appearance.theme_moved_description": "Color themes and custom theme packages have been replaced by installable widget modules. Manage them on the Widgets page.",
+  "appearance.theme_moved_cta": "Go to Widgets",
   "appearance.brand_settings": "Brand Settings",
   "appearance.brand_description": "Customize the logo, site title, footer text, and favicon.",
   "appearance.site_title": "Site Title",
@@ -495,44 +496,6 @@
   "section_about": "About",
   "data_sources_attribution": "Data provided by DB-IP, licensed under CC BY 4.0.",
 
-  "appearance.legacy_theme_migration.detected": "Detected your previous browser theme \"{{theme}}\". Apply it as the global dashboard theme?",
-  "appearance.legacy_theme_migration.ignore": "Ignore",
-  "appearance.legacy_theme_migration.apply": "Apply",
-  "appearance.custom_themes.title": "My themes",
-  "appearance.custom_themes.description": "Custom themes you can fork, edit, import, and export.",
-  "appearance.custom_themes.new": "New theme",
-  "appearance.custom_themes.import": "Import",
-  "appearance.custom_themes.imported": "Theme imported",
-  "appearance.custom_themes.import_failed": "Failed to import theme",
-  "appearance.custom_themes.import_invalid_json": "Invalid theme JSON file",
-  "appearance.custom_themes.export": "Export",
-  "appearance.custom_themes.edit": "Edit theme",
-  "appearance.custom_themes.duplicate": "Duplicate theme",
-  "appearance.custom_themes.delete": "Delete theme",
-  "appearance.custom_themes.delete_title": "Delete \"{{name}}\"?",
-  "appearance.custom_themes.delete_confirm": "This action cannot be undone.",
-  "appearance.custom_themes.delete_blocked": "This theme is currently in use:",
-  "appearance.custom_themes.delete_used_admin": "Active for the admin dashboard",
-  "appearance.custom_themes.delete_used_status_page": "Status page \"{{name}}\"",
-  "appearance.custom_themes.deleted": "Theme deleted",
-  "appearance.editor.new_title": "New theme",
-  "appearance.editor.name_placeholder": "Theme name",
-  "appearance.editor.fork_from": "Fork from",
-  "appearance.editor.untitled": "Untitled theme",
-  "appearance.editor.based_on": "Based on {{name}}",
-  "appearance.editor.saved": "Theme saved",
-  "appearance.editor.light": "Light",
-  "appearance.editor.dark": "Dark",
-  "appearance.editor.linked": "Linked",
-  "appearance.editor.preview_mode": "Preview:",
-  "appearance.editor.reset": "Reset",
-  "appearance.editor.groups.surface": "Surfaces",
-  "appearance.editor.groups.primary": "Primary & Secondary",
-  "appearance.editor.groups.state": "States",
-  "appearance.editor.groups.border": "Borders & Inputs",
-  "appearance.editor.groups.chart": "Charts",
-  "appearance.editor.groups.sidebar": "Sidebar",
-
   "rate_limit.title": "Rate Limits",
   "rate_limit.description": "Per-IP rate limit windows. Each window resets after {{minutes}} minutes; clearing one lets the IP retry immediately.",
   "rate_limit.refresh": "Refresh",
diff --git a/apps/web/src/locales/en/spa-theme.json b/apps/web/src/locales/en/spa-theme.json
deleted file mode 100644
index e782ce02..00000000
--- a/apps/web/src/locales/en/spa-theme.json
+++ /dev/null
@@ -1,72 +0,0 @@
-{
-  "section_title": "Custom Frontend",
-  "section_badge": "Beta",
-  "section_description": "Replace the entire ServerBee UI with a custom theme. Recovery: append ?theme=default to any URL.",
-  "upload_drag": "Drag .sbtheme here or click",
-  "upload_progress": "Uploading…",
-  "upload_success": "Theme uploaded",
-  "upload_upgrade_success": "Theme upgraded from v{{previous_version}}",
-  "active_indicator": "Active",
-  "superseded": "Superseded",
-  "actions": {
-    "preview": "Preview",
-    "activate": "Activate",
-    "deactivate": "Deactivate",
-    "delete": "Delete",
-    "details": "Details",
-    "download": "Download package"
-  },
-  "details_drawer": {
-    "size": "Size",
-    "uploaded_by": "Uploaded by",
-    "uploaded_at": "Uploaded at",
-    "manifest_heading": "manifest.json"
-  },
-  "preview_dialog": {
-    "title": "Open preview in a new tab?",
-    "body": "Preview is browser-wide for up to 15 minutes. Any tab that reloads / in this browser will see the preview theme until you exit. If you need the management UI live during preview, use a separate browser or an incognito window.",
-    "confirm": "Open preview",
-    "cancel": "Cancel"
-  },
-  "activate_dialog": {
-    "title": "Activate {{name}} v{{version}}?",
-    "body": "This will replace the entire UI for ALL users (including the login page).",
-    "recovery_hint": "Recovery: if the theme breaks, open any URL with ?theme=default to restore the built-in UI.",
-    "confirm_checkbox": "I understand and want to activate",
-    "confirm": "Activate",
-    "cancel": "Cancel"
-  },
-  "delete_dialog": {
-    "title": "Delete theme?",
-    "description": "Delete \"{{name}}\"? This cannot be undone.",
-    "confirm": "Delete",
-    "cancel": "Cancel"
-  },
-  "delete_active_blocked": "Cannot delete the active theme. Deactivate first.",
-  "color_brand_disabled_banner": "A custom frontend is active. The color theme and brand settings below have no effect until it is deactivated.",
-  "theme_activated": "Theme activated — reload to see changes",
-  "theme_deactivated": "Custom theme deactivated",
-  "reload": "Reload",
-  "errors": {
-    "UPLOAD_TOO_LARGE": "Package exceeds the 25 MB upload limit.",
-    "INVALID_MULTIPART": "Upload form is malformed: {{message}}",
-    "MISSING_MANIFEST": "manifest.json is missing from the package.",
-    "INVALID_MANIFEST": "manifest is invalid: {{reason}}",
-    "MISSING_ENTRY": "Entry HTML {{entry}} is not in the package.",
-    "INCOMPATIBLE_VERSION": "Requires ServerBee {{min}}; running {{running}}.",
-    "ZIP_SLIP": "Package contains an unsafe path: {{entry}}",
-    "ZIP_BOMB": "Compression ratio too high on {{entry}}",
-    "SYMLINK_NOT_ALLOWED": "Symlinks are not allowed: {{entry}}",
-    "DUPLICATE_ENTRY": "Duplicate entry: {{entry}}",
-    "DISALLOWED_EXTENSION": "File extension not allowed: {{entry}} ({{ext}})",
-    "FILE_TOO_LARGE": "{{entry}} is too large ({{size}} bytes; limit {{limit}}).",
-    "TOO_MANY_FILES": "Too many files ({{count}}; limit {{limit}}).",
-    "TOTAL_SIZE_EXCEEDED": "Total size exceeded ({{size}} bytes; limit {{limit}}).",
-    "PREVIEW_TOO_LARGE": "Preview image too large ({{size}} bytes; limit {{limit}}).",
-    "NO_DOWNGRADE": "Cannot downgrade: uploaded {{uploaded}}, existing {{existing}}.",
-    "VERSION_EXISTS": "Version {{version}} of {{manifest_id}} already exists.",
-    "THEME_IN_USE": "Cannot delete: this theme is currently active.",
-    "THEME_NOT_FOUND": "Theme {{uuid}} not found.",
-    "default": "Operation failed: {{message}}"
-  }
-}
diff --git a/apps/web/src/locales/zh/settings.json b/apps/web/src/locales/zh/settings.json
index ede40fd7..ef450c5e 100644
--- a/apps/web/src/locales/zh/settings.json
+++ b/apps/web/src/locales/zh/settings.json
@@ -279,8 +279,9 @@
   "tasks.scheduled.confirm_delete": "确定删除此定时任务？",
 
   "appearance.title": "外观",
-  "appearance.color_theme": "颜色主题",
-  "appearance.color_theme_description": "选择仪表盘的颜色主题，主题同时适用于浅色和深色模式。",
+  "appearance.theme_moved_title": "主题已迁移",
+  "appearance.theme_moved_description": "颜色主题和自定义主题包已被可安装的 Widget 模块取代，请前往 Widgets 页面管理。",
+  "appearance.theme_moved_cta": "前往 Widgets",
   "appearance.brand_settings": "品牌设置",
   "appearance.brand_description": "自定义 Logo、站点标题、页脚文本和网站图标。",
   "appearance.site_title": "站点标题",
@@ -476,44 +477,6 @@
   "section_about": "关于",
   "data_sources_attribution": "数据由 DB-IP 提供，授权协议 CC BY 4.0。",
 
-  "appearance.legacy_theme_migration.detected": "检测到此浏览器之前使用过「{{theme}}」主题。要把它应用为全局后台主题吗？",
-  "appearance.legacy_theme_migration.ignore": "忽略",
-  "appearance.legacy_theme_migration.apply": "应用",
-  "appearance.custom_themes.title": "我的主题",
-  "appearance.custom_themes.description": "可基于预设创建、编辑、导入和导出的自定义主题。",
-  "appearance.custom_themes.new": "新建主题",
-  "appearance.custom_themes.import": "导入",
-  "appearance.custom_themes.imported": "主题已导入",
-  "appearance.custom_themes.import_failed": "导入主题失败",
-  "appearance.custom_themes.import_invalid_json": "无效的主题 JSON 文件",
-  "appearance.custom_themes.export": "导出",
-  "appearance.custom_themes.edit": "编辑主题",
-  "appearance.custom_themes.duplicate": "复制主题",
-  "appearance.custom_themes.delete": "删除主题",
-  "appearance.custom_themes.delete_title": "删除「{{name}}」？",
-  "appearance.custom_themes.delete_confirm": "此操作不可撤销。",
-  "appearance.custom_themes.delete_blocked": "此主题正在被使用：",
-  "appearance.custom_themes.delete_used_admin": "后台当前激活主题",
-  "appearance.custom_themes.delete_used_status_page": "状态页「{{name}}」",
-  "appearance.custom_themes.deleted": "主题已删除",
-  "appearance.editor.new_title": "新建主题",
-  "appearance.editor.name_placeholder": "主题名称",
-  "appearance.editor.fork_from": "基于预设",
-  "appearance.editor.untitled": "未命名主题",
-  "appearance.editor.based_on": "基于 {{name}}",
-  "appearance.editor.saved": "主题已保存",
-  "appearance.editor.light": "浅色",
-  "appearance.editor.dark": "深色",
-  "appearance.editor.linked": "跟随编辑",
-  "appearance.editor.preview_mode": "预览：",
-  "appearance.editor.reset": "重置",
-  "appearance.editor.groups.surface": "表面色",
-  "appearance.editor.groups.primary": "主色与次级色",
-  "appearance.editor.groups.state": "状态色",
-  "appearance.editor.groups.border": "边框与输入框",
-  "appearance.editor.groups.chart": "图表",
-  "appearance.editor.groups.sidebar": "侧边栏",
-
   "rate_limit.title": "速率限制",
   "rate_limit.description": "按 IP 维度的速率限制窗口。每个窗口 {{minutes}} 分钟后自动重置；清除某条可让该 IP 立即重试。",
   "rate_limit.refresh": "刷新",
diff --git a/apps/web/src/locales/zh/spa-theme.json b/apps/web/src/locales/zh/spa-theme.json
deleted file mode 100644
index 70f62b24..00000000
--- a/apps/web/src/locales/zh/spa-theme.json
+++ /dev/null
@@ -1,72 +0,0 @@
-{
-  "section_title": "自定义前端",
-  "section_badge": "Beta",
-  "section_description": "用自定义主题替换整个 ServerBee 界面。恢复方法：在任意 URL 后追加 ?theme=default。",
-  "upload_drag": "拖拽 .sbtheme 到此处或点击上传",
-  "upload_progress": "上传中…",
-  "upload_success": "主题已上传",
-  "upload_upgrade_success": "已从 v{{previous_version}} 升级主题",
-  "active_indicator": "已激活",
-  "superseded": "已被替代",
-  "actions": {
-    "preview": "预览",
-    "activate": "激活",
-    "deactivate": "停用",
-    "delete": "删除",
-    "details": "详情",
-    "download": "下载包"
-  },
-  "details_drawer": {
-    "size": "大小",
-    "uploaded_by": "上传者",
-    "uploaded_at": "上传时间",
-    "manifest_heading": "manifest.json"
-  },
-  "preview_dialog": {
-    "title": "在新标签页中打开预览？",
-    "body": "预览作用于整个浏览器，最长 15 分钟。期间本浏览器中任何重新加载的标签页都会显示预览主题。如需在预览时保留管理界面，请使用独立浏览器或无痕窗口。",
-    "confirm": "打开预览",
-    "cancel": "取消"
-  },
-  "activate_dialog": {
-    "title": "激活 {{name}} v{{version}}？",
-    "body": "这将为所有用户（包括登录页）替换整个界面。",
-    "recovery_hint": "恢复：若主题异常，在任意 URL 后追加 ?theme=default 即可恢复内置界面。",
-    "confirm_checkbox": "我已了解，确认激活",
-    "confirm": "激活",
-    "cancel": "取消"
-  },
-  "delete_dialog": {
-    "title": "删除主题？",
-    "description": "删除「{{name}}」？此操作不可撤销。",
-    "confirm": "删除",
-    "cancel": "取消"
-  },
-  "delete_active_blocked": "无法删除已激活的主题，请先停用。",
-  "color_brand_disabled_banner": "自定义前端已激活，停用前以下颜色主题和品牌设置不生效。",
-  "theme_activated": "主题已激活 — 重新加载以查看效果",
-  "theme_deactivated": "自定义主题已停用",
-  "reload": "重新加载",
-  "errors": {
-    "UPLOAD_TOO_LARGE": "包超过 25 MB 上传限制。",
-    "INVALID_MULTIPART": "上传表单格式错误：{{message}}",
-    "MISSING_MANIFEST": "包中缺少 manifest.json。",
-    "INVALID_MANIFEST": "manifest 无效：{{reason}}",
-    "MISSING_ENTRY": "包中不含入口 HTML {{entry}}。",
-    "INCOMPATIBLE_VERSION": "需要 ServerBee {{min}}，当前运行 {{running}}。",
-    "ZIP_SLIP": "包含不安全路径：{{entry}}",
-    "ZIP_BOMB": "{{entry}} 压缩比过高",
-    "SYMLINK_NOT_ALLOWED": "不允许符号链接：{{entry}}",
-    "DUPLICATE_ENTRY": "重复条目：{{entry}}",
-    "DISALLOWED_EXTENSION": "不允许的文件扩展名：{{entry}}（{{ext}}）",
-    "FILE_TOO_LARGE": "{{entry}} 过大（{{size}} 字节；限制 {{limit}}）。",
-    "TOO_MANY_FILES": "文件数量过多（{{count}}；限制 {{limit}}）。",
-    "TOTAL_SIZE_EXCEEDED": "总大小超限（{{size}} 字节；限制 {{limit}}）。",
-    "PREVIEW_TOO_LARGE": "预览图过大（{{size}} 字节；限制 {{limit}}）。",
-    "NO_DOWNGRADE": "不可降级：上传 {{uploaded}}，已有 {{existing}}。",
-    "VERSION_EXISTS": "{{manifest_id}} 的版本 {{version}} 已存在。",
-    "THEME_IN_USE": "无法删除：该主题当前处于激活状态。",
-    "THEME_NOT_FOUND": "主题 {{uuid}} 不存在。",
-    "default": "操作失败：{{message}}"
-  }
-}
diff --git a/apps/web/src/routeTree.gen.ts b/apps/web/src/routeTree.gen.ts
index 7d8f500b..0443b54e 100644
--- a/apps/web/src/routeTree.gen.ts
+++ b/apps/web/src/routeTree.gen.ts
@@ -51,8 +51,6 @@ import { Route as AuthedSecurityServerIdRouteImport } from './routes/_authed/sec
 import { Route as AuthedNetworkServerIdRouteImport } from './routes/_authed/network/$serverId'
 import { Route as AuthedFilesServerIdRouteImport } from './routes/_authed/files.$serverId'
 import { Route as AuthedServersServerIdDockerIndexRouteImport } from './routes/_authed/servers/$serverId/docker/index'
-import { Route as AuthedSettingsAppearanceThemesNewRouteImport } from './routes/_authed/settings/appearance/themes.new'
-import { Route as AuthedSettingsAppearanceThemesIdRouteImport } from './routes/_authed/settings/appearance/themes/$id'
 
 const StatusRoute = StatusRouteImport.update({
   id: '/status',
@@ -272,18 +270,6 @@ const AuthedServersServerIdDockerIndexRoute =
     path: '/servers/$serverId/docker/',
     getParentRoute: () => AuthedRoute,
   } as any)
-const AuthedSettingsAppearanceThemesNewRoute =
-  AuthedSettingsAppearanceThemesNewRouteImport.update({
-    id: '/themes/new',
-    path: '/themes/new',
-    getParentRoute: () => AuthedSettingsAppearanceRoute,
-  } as any)
-const AuthedSettingsAppearanceThemesIdRoute =
-  AuthedSettingsAppearanceThemesIdRouteImport.update({
-    id: '/themes/$id',
-    path: '/themes/$id',
-    getParentRoute: () => AuthedSettingsAppearanceRoute,
-  } as any)
 
 export interface FileRoutesByFullPath {
   '/': typeof AuthedIndexRoute
@@ -301,7 +287,7 @@ export interface FileRoutesByFullPath {
   '/service-monitors/$id': typeof AuthedServiceMonitorsIdRoute
   '/settings/alerts': typeof AuthedSettingsAlertsRoute
   '/settings/api-keys': typeof AuthedSettingsApiKeysRoute
-  '/settings/appearance': typeof AuthedSettingsAppearanceRouteWithChildren
+  '/settings/appearance': typeof AuthedSettingsAppearanceRoute
   '/settings/audit-logs': typeof AuthedSettingsAuditLogsRoute
   '/settings/capabilities': typeof AuthedSettingsCapabilitiesRoute
   '/settings/firewall': typeof AuthedSettingsFirewallRoute
@@ -326,8 +312,6 @@ export interface FileRoutesByFullPath {
   '/settings/': typeof AuthedSettingsIndexRoute
   '/traffic/': typeof AuthedTrafficIndexRoute
   '/status/network/': typeof StatusNetworkIndexRoute
-  '/settings/appearance/themes/$id': typeof AuthedSettingsAppearanceThemesIdRoute
-  '/settings/appearance/themes/new': typeof AuthedSettingsAppearanceThemesNewRoute
   '/servers/$serverId/docker/': typeof AuthedServersServerIdDockerIndexRoute
 }
 export interface FileRoutesByTo {
@@ -344,7 +328,7 @@ export interface FileRoutesByTo {
   '/service-monitors/$id': typeof AuthedServiceMonitorsIdRoute
   '/settings/alerts': typeof AuthedSettingsAlertsRoute
   '/settings/api-keys': typeof AuthedSettingsApiKeysRoute
-  '/settings/appearance': typeof AuthedSettingsAppearanceRouteWithChildren
+  '/settings/appearance': typeof AuthedSettingsAppearanceRoute
   '/settings/audit-logs': typeof AuthedSettingsAuditLogsRoute
   '/settings/capabilities': typeof AuthedSettingsCapabilitiesRoute
   '/settings/firewall': typeof AuthedSettingsFirewallRoute
@@ -369,8 +353,6 @@ export interface FileRoutesByTo {
   '/settings': typeof AuthedSettingsIndexRoute
   '/traffic': typeof AuthedTrafficIndexRoute
   '/status/network': typeof StatusNetworkIndexRoute
-  '/settings/appearance/themes/$id': typeof AuthedSettingsAppearanceThemesIdRoute
-  '/settings/appearance/themes/new': typeof AuthedSettingsAppearanceThemesNewRoute
   '/servers/$serverId/docker': typeof AuthedServersServerIdDockerIndexRoute
 }
 export interface FileRoutesById {
@@ -391,7 +373,7 @@ export interface FileRoutesById {
   '/_authed/service-monitors/$id': typeof AuthedServiceMonitorsIdRoute
   '/_authed/settings/alerts': typeof AuthedSettingsAlertsRoute
   '/_authed/settings/api-keys': typeof AuthedSettingsApiKeysRoute
-  '/_authed/settings/appearance': typeof AuthedSettingsAppearanceRouteWithChildren
+  '/_authed/settings/appearance': typeof AuthedSettingsAppearanceRoute
   '/_authed/settings/audit-logs': typeof AuthedSettingsAuditLogsRoute
   '/_authed/settings/capabilities': typeof AuthedSettingsCapabilitiesRoute
   '/_authed/settings/firewall': typeof AuthedSettingsFirewallRoute
@@ -416,8 +398,6 @@ export interface FileRoutesById {
   '/_authed/settings/': typeof AuthedSettingsIndexRoute
   '/_authed/traffic/': typeof AuthedTrafficIndexRoute
   '/status/network/': typeof StatusNetworkIndexRoute
-  '/_authed/settings/appearance/themes/$id': typeof AuthedSettingsAppearanceThemesIdRoute
-  '/_authed/settings/appearance/themes/new': typeof AuthedSettingsAppearanceThemesNewRoute
   '/_authed/servers/$serverId/docker/': typeof AuthedServersServerIdDockerIndexRoute
 }
 export interface FileRouteTypes {
@@ -463,8 +443,6 @@ export interface FileRouteTypes {
     | '/settings/'
     | '/traffic/'
     | '/status/network/'
-    | '/settings/appearance/themes/$id'
-    | '/settings/appearance/themes/new'
     | '/servers/$serverId/docker/'
   fileRoutesByTo: FileRoutesByTo
   to:
@@ -506,8 +484,6 @@ export interface FileRouteTypes {
     | '/settings'
     | '/traffic'
     | '/status/network'
-    | '/settings/appearance/themes/$id'
-    | '/settings/appearance/themes/new'
     | '/servers/$serverId/docker'
   id:
     | '__root__'
@@ -552,8 +528,6 @@ export interface FileRouteTypes {
     | '/_authed/settings/'
     | '/_authed/traffic/'
     | '/status/network/'
-    | '/_authed/settings/appearance/themes/$id'
-    | '/_authed/settings/appearance/themes/new'
     | '/_authed/servers/$serverId/docker/'
   fileRoutesById: FileRoutesById
 }
@@ -860,41 +834,9 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof AuthedServersServerIdDockerIndexRouteImport
       parentRoute: typeof AuthedRoute
     }
-    '/_authed/settings/appearance/themes/new': {
-      id: '/_authed/settings/appearance/themes/new'
-      path: '/themes/new'
-      fullPath: '/settings/appearance/themes/new'
-      preLoaderRoute: typeof AuthedSettingsAppearanceThemesNewRouteImport
-      parentRoute: typeof AuthedSettingsAppearanceRoute
-    }
-    '/_authed/settings/appearance/themes/$id': {
-      id: '/_authed/settings/appearance/themes/$id'
-      path: '/themes/$id'
-      fullPath: '/settings/appearance/themes/$id'
-      preLoaderRoute: typeof AuthedSettingsAppearanceThemesIdRouteImport
-      parentRoute: typeof AuthedSettingsAppearanceRoute
-    }
   }
 }
 
-interface AuthedSettingsAppearanceRouteChildren {
-  AuthedSettingsAppearanceThemesIdRoute: typeof AuthedSettingsAppearanceThemesIdRoute
-  AuthedSettingsAppearanceThemesNewRoute: typeof AuthedSettingsAppearanceThemesNewRoute
-}
-
-const AuthedSettingsAppearanceRouteChildren: AuthedSettingsAppearanceRouteChildren =
-  {
-    AuthedSettingsAppearanceThemesIdRoute:
-      AuthedSettingsAppearanceThemesIdRoute,
-    AuthedSettingsAppearanceThemesNewRoute:
-      AuthedSettingsAppearanceThemesNewRoute,
-  }
-
-const AuthedSettingsAppearanceRouteWithChildren =
-  AuthedSettingsAppearanceRoute._addFileChildren(
-    AuthedSettingsAppearanceRouteChildren,
-  )
-
 interface AuthedRouteChildren {
   AuthedIpQualityRoute: typeof AuthedIpQualityRoute
   AuthedIndexRoute: typeof AuthedIndexRoute
@@ -905,7 +847,7 @@ interface AuthedRouteChildren {
   AuthedServiceMonitorsIdRoute: typeof AuthedServiceMonitorsIdRoute
   AuthedSettingsAlertsRoute: typeof AuthedSettingsAlertsRoute
   AuthedSettingsApiKeysRoute: typeof AuthedSettingsApiKeysRoute
-  AuthedSettingsAppearanceRoute: typeof AuthedSettingsAppearanceRouteWithChildren
+  AuthedSettingsAppearanceRoute: typeof AuthedSettingsAppearanceRoute
   AuthedSettingsAuditLogsRoute: typeof AuthedSettingsAuditLogsRoute
   AuthedSettingsCapabilitiesRoute: typeof AuthedSettingsCapabilitiesRoute
   AuthedSettingsFirewallRoute: typeof AuthedSettingsFirewallRoute
@@ -940,7 +882,7 @@ const AuthedRouteChildren: AuthedRouteChildren = {
   AuthedServiceMonitorsIdRoute: AuthedServiceMonitorsIdRoute,
   AuthedSettingsAlertsRoute: AuthedSettingsAlertsRoute,
   AuthedSettingsApiKeysRoute: AuthedSettingsApiKeysRoute,
-  AuthedSettingsAppearanceRoute: AuthedSettingsAppearanceRouteWithChildren,
+  AuthedSettingsAppearanceRoute: AuthedSettingsAppearanceRoute,
   AuthedSettingsAuditLogsRoute: AuthedSettingsAuditLogsRoute,
   AuthedSettingsCapabilitiesRoute: AuthedSettingsCapabilitiesRoute,
   AuthedSettingsFirewallRoute: AuthedSettingsFirewallRoute,
diff --git a/apps/web/src/routes/_authed/settings/appearance.test.tsx b/apps/web/src/routes/_authed/settings/appearance.test.tsx
index 62f162ee..6988c41b 100644
--- a/apps/web/src/routes/_authed/settings/appearance.test.tsx
+++ b/apps/web/src/routes/_authed/settings/appearance.test.tsx
@@ -1,13 +1,8 @@
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { fireEvent, render, screen } from '@testing-library/react'
+import { render, screen } from '@testing-library/react'
 import type { ReactNode } from 'react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
-const mockSetActiveThemeRef = vi.fn()
-let mockRole = 'admin'
-let mockActiveThemeRef = 'preset:default'
-let mockActiveSpaThemeId: string | null = null
-
 function createMemoryStorage(): Storage {
   const store = new Map<string, string>()
 
@@ -27,56 +22,25 @@ function createMemoryStorage(): Storage {
   }
 }
 
-const mockNavigate = vi.fn()
-
 vi.mock('@tanstack/react-router', () => ({
-  createFileRoute: () => (config: Record<string, unknown>) => ({
-    ...config,
-    useNavigate: () => mockNavigate
-  })
+  createFileRoute: () => (config: Record<string, unknown>) => config,
+  Link: ({ children, to }: { children: ReactNode; to: string }) => <a href={to}>{children}</a>
 }))
 
 vi.mock('react-i18next', () => ({
   useTranslation: () => ({
-    t: (key: string, options?: Record<string, unknown>) =>
-      key === 'appearance.legacy_theme_migration.detected' ? `Detected ${String(options?.theme ?? '')}` : key
-  })
-}))
-
-vi.mock('@/components/theme-provider', () => ({
-  useTheme: () => ({
-    activeTheme: { ref: mockActiveThemeRef, theme: { kind: 'preset', id: 'default' } },
-    setActiveThemeRef: mockSetActiveThemeRef
+    t: (key: string) => key
   })
 }))
 
-vi.mock('@/hooks/use-auth', () => ({
-  useAuth: () => ({
-    user: { role: mockRole }
-  })
-}))
-
-// SPA-theme API mocks. The hooks live in @/api/spa-themes; tests need to
-// control useActiveSpaTheme + useSpaThemes return values to drive the
-// CustomSpaThemeSection/Banner render paths.
-vi.mock('@/api/spa-themes', () => ({
-  useActiveSpaTheme: () => ({ data: { theme_id: mockActiveSpaThemeId } }),
-  useSpaThemes: () => ({ data: [] }),
-  useActivateSpaTheme: () => ({ mutate: vi.fn() }),
-  useDeleteSpaTheme: () => ({ mutate: vi.fn() }),
-  useUploadSpaTheme: () => ({ mutate: vi.fn(), isPending: false })
-}))
-
-// Legacy color-theme APIs used by ThemeGrid; we don't need their behaviour, just
-// to keep the page from blowing up during render.
-vi.mock('@/api/themes', () => ({
-  useCustomThemes: () => ({ data: [] }),
-  useDuplicateTheme: () => ({ mutate: vi.fn() }),
-  useImportTheme: () => ({ mutate: vi.fn() }),
-  useThemeQuery: () => ({ data: undefined })
+vi.mock('@/lib/api-client', () => ({
+  api: {
+    get: vi.fn().mockResolvedValue({}),
+    put: vi.fn().mockResolvedValue(undefined)
+  }
 }))
 
-const { AppearancePage, LegacyMigrationPrompt } = await import('./appearance')
+const { AppearancePage } = await import('./appearance')
 
 function wrap(node: ReactNode) {
   const queryClient = new QueryClient({
@@ -88,83 +52,27 @@ function wrap(node: ReactNode) {
   return <QueryClientProvider client={queryClient}>{node}</QueryClientProvider>
 }
 
-describe('LegacyMigrationPrompt', () => {
-  beforeEach(() => {
-    vi.stubGlobal('localStorage', createMemoryStorage())
-    mockSetActiveThemeRef.mockReset()
-    mockRole = 'admin'
-    mockActiveThemeRef = 'preset:default'
-  })
-
-  it('lets admins apply the old browser color theme as the global active theme', () => {
-    localStorage.setItem('color-theme', 'tokyo-night')
-
-    render(<LegacyMigrationPrompt />)
-
-    expect(screen.getByText('Detected tokyo-night')).toBeInTheDocument()
-
-    fireEvent.click(screen.getByRole('button', { name: 'appearance.legacy_theme_migration.apply' }))
-
-    expect(mockSetActiveThemeRef).toHaveBeenCalledWith('preset:tokyo-night')
-    expect(localStorage.getItem('theme-migration-prompted')).toBe('1')
-    expect(localStorage.getItem('color-theme')).toBeNull()
-  })
-
-  it('does not prompt members', () => {
-    localStorage.setItem('color-theme', 'tokyo-night')
-    mockRole = 'member'
-
-    render(<LegacyMigrationPrompt />)
-
-    expect(screen.queryByText('Detected tokyo-night')).not.toBeInTheDocument()
-  })
-
-  it('does not prompt when the active theme is already customized', () => {
-    localStorage.setItem('color-theme', 'tokyo-night')
-    mockActiveThemeRef = 'preset:nord'
-
-    render(<LegacyMigrationPrompt />)
-
-    expect(screen.queryByText('Detected tokyo-night')).not.toBeInTheDocument()
-  })
-})
-
 describe('AppearancePage', () => {
   beforeEach(() => {
     vi.stubGlobal('localStorage', createMemoryStorage())
-    // ThemeGrid → useResolvedIsDark calls window.matchMedia; jsdom doesn't provide it.
     vi.stubGlobal('matchMedia', (_query: string) => ({
       matches: false,
       addEventListener: () => undefined,
       removeEventListener: () => undefined
     }))
-    mockNavigate.mockReset()
-    mockRole = 'admin'
-    mockActiveThemeRef = 'preset:default'
-    mockActiveSpaThemeId = null
-  })
-
-  it('renders the custom SPA theme section for admin users', () => {
-    mockRole = 'admin'
-    render(wrap(<AppearancePage />))
-    expect(screen.getByText('section_title')).toBeInTheDocument()
-  })
-
-  it('hides the custom SPA theme section from member users', () => {
-    mockRole = 'member'
-    render(wrap(<AppearancePage />))
-    expect(screen.queryByText('section_title')).not.toBeInTheDocument()
   })
 
-  it('shows the color/brand disabled banner when an SPA theme is active', () => {
-    mockActiveSpaThemeId = 'some-uuid'
+  it('renders the brand settings section', () => {
     render(wrap(<AppearancePage />))
-    expect(screen.getByText('color_brand_disabled_banner')).toBeInTheDocument()
+    expect(screen.getByText('appearance.brand_settings')).toBeInTheDocument()
   })
 
-  it('hides the banner when no SPA theme is active', () => {
-    mockActiveSpaThemeId = null
+  it('renders the widget modules notice linking to /settings/widgets', () => {
     render(wrap(<AppearancePage />))
-    expect(screen.queryByText('color_brand_disabled_banner')).not.toBeInTheDocument()
+    expect(screen.getByText('appearance.theme_moved_title')).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: 'appearance.theme_moved_cta' })).toHaveAttribute(
+      'href',
+      '/settings/widgets'
+    )
   })
 })
diff --git a/apps/web/src/routes/_authed/settings/appearance.tsx b/apps/web/src/routes/_authed/settings/appearance.tsx
index ba7c638a..aa943114 100644
--- a/apps/web/src/routes/_authed/settings/appearance.tsx
+++ b/apps/web/src/routes/_authed/settings/appearance.tsx
@@ -1,21 +1,12 @@
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
-import { createFileRoute } from '@tanstack/react-router'
-import { Loader2, Plus, Upload } from 'lucide-react'
-import { type ChangeEvent, type FormEvent, useEffect, useRef, useState } from 'react'
+import { createFileRoute, Link } from '@tanstack/react-router'
+import { Loader2, Upload } from 'lucide-react'
+import { type ChangeEvent, type FormEvent, useRef, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import { toast } from 'sonner'
-import { useActiveSpaTheme } from '@/api/spa-themes'
-import { type ExportPayload, useCustomThemes, useDuplicateTheme, useImportTheme, useThemeQuery } from '@/api/themes'
-import { CustomSpaThemeBanner, CustomSpaThemeSection } from '@/components/spa-theme/custom-spa-theme-section'
-import { DeleteThemeDialog } from '@/components/theme/delete-theme-dialog'
-import { ThemeCard } from '@/components/theme/theme-card'
-import { useTheme } from '@/components/theme-provider'
-import { Button } from '@/components/ui/button'
+import { Button, buttonVariants } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
-import { useAuth } from '@/hooks/use-auth'
 import { api } from '@/lib/api-client'
-import { oklchToHex } from '@/lib/oklch'
-import { isColorTheme, themes } from '@/themes'
 
 export const Route = createFileRoute('/_authed/settings/appearance')({
   component: AppearancePage
@@ -28,261 +19,6 @@ interface BrandSettings {
   site_title?: string
 }
 
-function useResolvedIsDark(theme: 'dark' | 'light' | 'system') {
-  const [systemDark, setSystemDark] = useState(() => window.matchMedia('(prefers-color-scheme: dark)').matches)
-
-  useEffect(() => {
-    if (theme !== 'system') {
-      return undefined
-    }
-
-    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
-    const handleChange = () => setSystemDark(mediaQuery.matches)
-    handleChange()
-    mediaQuery.addEventListener('change', handleChange)
-
-    return () => mediaQuery.removeEventListener('change', handleChange)
-  }, [theme])
-
-  return theme === 'dark' || (theme === 'system' && systemDark)
-}
-
-function useThemePreviewColors(id: number, dark: boolean) {
-  const { data } = useThemeQuery(id)
-  if (!data) {
-    return []
-  }
-
-  const vars = dark ? data.vars_dark : data.vars_light
-  return ['primary', 'accent', 'background', 'foreground'].map((key) => {
-    const value = vars[key]
-    if (!value) {
-      return 'transparent'
-    }
-
-    return oklchToHex(value) ?? value
-  })
-}
-
-function isStringMap(value: unknown): value is Record<string, string> {
-  return (
-    value !== null &&
-    typeof value === 'object' &&
-    !Array.isArray(value) &&
-    Object.values(value).every((entry) => typeof entry === 'string')
-  )
-}
-
-function hasProperty<Key extends string>(value: object, key: Key): value is Record<Key, unknown> {
-  return key in value
-}
-
-function isThemeImportPayload(value: unknown): value is ExportPayload {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-    return false
-  }
-
-  if (
-    !(
-      hasProperty(value, 'version') &&
-      hasProperty(value, 'name') &&
-      hasProperty(value, 'vars_light') &&
-      hasProperty(value, 'vars_dark')
-    )
-  ) {
-    return false
-  }
-
-  return (
-    value.version === 1 &&
-    typeof value.name === 'string' &&
-    isStringMap(value.vars_light) &&
-    isStringMap(value.vars_dark)
-  )
-}
-
-function CustomThemeCard({
-  active,
-  id,
-  name,
-  onActivate,
-  onDelete,
-  onDuplicate,
-  onEdit,
-  previewDark
-}: {
-  active: boolean
-  id: number
-  name: string
-  onActivate: () => void
-  onDelete: () => void
-  onDuplicate: () => void
-  onEdit: () => void
-  previewDark: boolean
-}) {
-  const preview = useThemePreviewColors(id, previewDark)
-
-  return (
-    <ThemeCard
-      actions={{ onDelete, onDuplicate, onEdit }}
-      active={active}
-      name={name}
-      onActivate={onActivate}
-      preview={preview}
-    />
-  )
-}
-
-export function ThemeGrid() {
-  const { t } = useTranslation('settings')
-  const navigate = Route.useNavigate()
-  const { activeTheme, setActiveThemeRef, theme } = useTheme()
-  const isDark = useResolvedIsDark(theme)
-  const { data: customThemes } = useCustomThemes()
-  const duplicateTheme = useDuplicateTheme()
-  const importTheme = useImportTheme()
-  const fileInputRef = useRef<HTMLInputElement>(null)
-  const [pendingDelete, setPendingDelete] = useState<{ id: number; name: string } | null>(null)
-  const isActive = (themeRef: string) => activeTheme?.ref === themeRef
-  const onImportFileChange = async (event: ChangeEvent<HTMLInputElement>) => {
-    const file = event.target.files?.[0]
-    event.target.value = ''
-    if (!file) {
-      return
-    }
-
-    try {
-      const parsed: unknown = JSON.parse(await file.text())
-      if (!isThemeImportPayload(parsed)) {
-        toast.error(t('appearance.custom_themes.import_invalid_json'))
-        return
-      }
-
-      importTheme.mutate(parsed, {
-        onError: (error) => {
-          toast.error(error instanceof Error ? error.message : t('appearance.custom_themes.import_failed'))
-        },
-        onSuccess: () => {
-          toast.success(t('appearance.custom_themes.imported'))
-        }
-      })
-    } catch {
-      toast.error(t('appearance.custom_themes.import_invalid_json'))
-    }
-  }
-
-  return (
-    <>
-      <div className="rounded-lg border bg-card p-6">
-        <h2 className="mb-1 font-semibold text-lg">{t('appearance.color_theme')}</h2>
-        <p className="mb-4 text-muted-foreground text-sm">{t('appearance.color_theme_description')}</p>
-
-        <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-4">
-          {themes.map((themeInfo) => (
-            <ThemeCard
-              active={isActive(`preset:${themeInfo.id}`)}
-              key={themeInfo.id}
-              name={themeInfo.name}
-              onActivate={() => setActiveThemeRef(`preset:${themeInfo.id}`)}
-              preview={isDark ? themeInfo.previewColors.dark : themeInfo.previewColors.light}
-            />
-          ))}
-        </div>
-      </div>
-
-      <div className="rounded-lg border bg-card p-6">
-        <div className="mb-4 flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
-          <div className="min-w-0">
-            <h2 className="font-semibold text-lg">{t('appearance.custom_themes.title')}</h2>
-            <p className="text-muted-foreground text-sm">{t('appearance.custom_themes.description')}</p>
-          </div>
-          <div className="flex flex-wrap gap-2">
-            <input
-              accept="application/json"
-              className="hidden"
-              onChange={onImportFileChange}
-              ref={fileInputRef}
-              type="file"
-            />
-            <Button onClick={() => fileInputRef.current?.click()} type="button" variant="outline">
-              <Upload className="size-4" />
-              {t('appearance.custom_themes.import')}
-            </Button>
-            <Button onClick={() => navigate({ to: '/settings/appearance/themes/new' })} type="button">
-              <Plus className="size-4" />
-              {t('appearance.custom_themes.new')}
-            </Button>
-          </div>
-        </div>
-
-        <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-4">
-          {(customThemes ?? []).map((customTheme) => (
-            <CustomThemeCard
-              active={isActive(`custom:${customTheme.id}`)}
-              id={customTheme.id}
-              key={customTheme.id}
-              name={customTheme.name}
-              onActivate={() => setActiveThemeRef(`custom:${customTheme.id}`)}
-              onDelete={() => setPendingDelete({ id: customTheme.id, name: customTheme.name })}
-              onDuplicate={() => duplicateTheme.mutate(customTheme.id)}
-              onEdit={() =>
-                navigate({
-                  params: { id: String(customTheme.id) },
-                  to: '/settings/appearance/themes/$id'
-                })
-              }
-              previewDark={isDark}
-            />
-          ))}
-        </div>
-      </div>
-
-      {pendingDelete && <DeleteThemeDialog onClose={() => setPendingDelete(null)} theme={pendingDelete} />}
-    </>
-  )
-}
-
-export function LegacyMigrationPrompt() {
-  const { t } = useTranslation('settings')
-  const { user } = useAuth()
-  const { activeTheme, setActiveThemeRef } = useTheme()
-  const [dismissed, setDismissed] = useState(() => localStorage.getItem('theme-migration-prompted') === '1')
-
-  if (dismissed || user?.role !== 'admin') {
-    return null
-  }
-
-  const legacy = localStorage.getItem('color-theme')
-  if (!(legacy && isColorTheme(legacy)) || activeTheme?.ref !== 'preset:default') {
-    return null
-  }
-
-  const dismiss = () => {
-    localStorage.setItem('theme-migration-prompted', '1')
-    localStorage.removeItem('color-theme')
-    setDismissed(true)
-  }
-
-  const apply = () => {
-    setActiveThemeRef(`preset:${legacy}`)
-    dismiss()
-  }
-
-  return (
-    <div className="mb-4 flex items-center justify-between gap-3 rounded-lg border bg-muted p-4">
-      <span className="text-sm">{t('appearance.legacy_theme_migration.detected', { theme: legacy })}</span>
-      <div className="flex gap-2">
-        <Button onClick={dismiss} size="sm" type="button" variant="outline">
-          {t('appearance.legacy_theme_migration.ignore')}
-        </Button>
-        <Button onClick={apply} size="sm" type="button">
-          {t('appearance.legacy_theme_migration.apply')}
-        </Button>
-      </div>
-    </div>
-  )
-}
-
 function BrandSettingsSection() {
   const { t } = useTranslation(['settings', 'common'])
   const queryClient = useQueryClient()
@@ -316,7 +52,6 @@ function BrandSettingsSection() {
 
   const mutation = useMutation({
     mutationFn: async (payload: BrandSettings) => {
-      // If files are selected, upload them first via FormData
       if (logoFile || faviconFile) {
         const formData = new FormData()
         if (logoFile) {
@@ -482,21 +217,27 @@ function BrandSettingsSection() {
   )
 }
 
+function WidgetModulesNotice() {
+  const { t } = useTranslation('settings')
+  return (
+    <div className="rounded-lg border bg-card p-6">
+      <h2 className="mb-1 font-semibold text-lg">{t('appearance.theme_moved_title')}</h2>
+      <p className="mb-4 text-muted-foreground text-sm">{t('appearance.theme_moved_description')}</p>
+      <Link className={buttonVariants()} to="/settings/widgets">
+        {t('appearance.theme_moved_cta')}
+      </Link>
+    </div>
+  )
+}
+
 export function AppearancePage() {
   const { t } = useTranslation('settings')
-  const { user } = useAuth()
-  const isAdmin = user?.role === 'admin'
-  const { data: activeSpaTheme } = useActiveSpaTheme()
-  const spaThemeActive = activeSpaTheme?.theme_id != null
 
   return (
     <div>
       <h1 className="mb-6 font-bold text-2xl">{t('appearance.title')}</h1>
-      {isAdmin ? <CustomSpaThemeSection /> : null}
-      <LegacyMigrationPrompt />
       <div className="max-w-3xl space-y-6">
-        {spaThemeActive ? <CustomSpaThemeBanner /> : null}
-        <ThemeGrid />
+        <WidgetModulesNotice />
         <BrandSettingsSection />
       </div>
     </div>
diff --git a/apps/web/src/routes/_authed/settings/appearance/themes.new.test.tsx b/apps/web/src/routes/_authed/settings/appearance/themes.new.test.tsx
deleted file mode 100644
index 60b9eba0..00000000
--- a/apps/web/src/routes/_authed/settings/appearance/themes.new.test.tsx
+++ /dev/null
@@ -1,70 +0,0 @@
-import { fireEvent, render, screen } from '@testing-library/react'
-import type { ReactNode } from 'react'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-
-const mockCreateMutate = vi.fn()
-const mockNavigate = vi.fn()
-
-vi.mock('@tanstack/react-router', () => ({
-  createFileRoute: () => (config: Record<string, unknown>) => ({
-    ...config,
-    useNavigate: () => mockNavigate
-  })
-}))
-
-vi.mock('react-i18next', () => ({
-  useTranslation: () => ({
-    t: (key: string) => key
-  })
-}))
-
-vi.mock('@/api/themes', () => ({
-  useCreateTheme: () => ({
-    isPending: false,
-    mutate: mockCreateMutate
-  })
-}))
-
-vi.mock('@/components/ui/select', () => ({
-  Select: ({ children }: { children?: ReactNode }) => <div>{children}</div>,
-  SelectContent: ({ children }: { children?: ReactNode }) => <div>{children}</div>,
-  SelectItem: ({ children }: { children?: ReactNode }) => <div>{children}</div>,
-  SelectTrigger: ({ children }: { children?: ReactNode }) => <div>{children}</div>,
-  SelectValue: () => <span />
-}))
-
-const { NewThemePage } = await import('./themes.new')
-
-describe('NewThemePage', () => {
-  beforeEach(() => {
-    mockCreateMutate.mockReset()
-    mockNavigate.mockReset()
-  })
-
-  it('creates a theme forked from the default preset and navigates to the editor', () => {
-    mockCreateMutate.mockImplementation((_body: unknown, options: { onSuccess: (theme: { id: number }) => void }) => {
-      options.onSuccess({ id: 42 })
-    })
-
-    render(<NewThemePage />)
-
-    fireEvent.change(screen.getByPlaceholderText('appearance.editor.name_placeholder'), {
-      target: { value: 'My Theme' }
-    })
-    fireEvent.click(screen.getByRole('button', { name: 'common:create' }))
-
-    expect(mockCreateMutate).toHaveBeenCalledWith(
-      expect.objectContaining({
-        based_on: 'default',
-        name: 'My Theme',
-        vars_dark: expect.any(Object),
-        vars_light: expect.any(Object)
-      }),
-      expect.any(Object)
-    )
-    expect(mockNavigate).toHaveBeenCalledWith({
-      params: { id: '42' },
-      to: '/settings/appearance/themes/$id'
-    })
-  })
-})
diff --git a/apps/web/src/routes/_authed/settings/appearance/themes.new.tsx b/apps/web/src/routes/_authed/settings/appearance/themes.new.tsx
deleted file mode 100644
index dd0ef83e..00000000
--- a/apps/web/src/routes/_authed/settings/appearance/themes.new.tsx
+++ /dev/null
@@ -1,80 +0,0 @@
-import { createFileRoute } from '@tanstack/react-router'
-import { useState } from 'react'
-import { useTranslation } from 'react-i18next'
-import { useCreateTheme } from '@/api/themes'
-import { Button } from '@/components/ui/button'
-import { Input } from '@/components/ui/input'
-import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
-import { type ColorTheme, themes } from '@/themes'
-import { presetVars } from '@/themes/preset-vars'
-
-export const Route = createFileRoute('/_authed/settings/appearance/themes/new')({
-  component: NewThemePage
-})
-
-export function NewThemePage() {
-  const { t } = useTranslation(['settings', 'common'])
-  const navigate = Route.useNavigate()
-  const createTheme = useCreateTheme()
-  const [name, setName] = useState('')
-  const [forkFrom, setForkFrom] = useState<ColorTheme>('default')
-
-  const submit = () => {
-    const source = presetVars[forkFrom]
-    createTheme.mutate(
-      {
-        based_on: forkFrom,
-        name: name.trim() || t('appearance.editor.untitled'),
-        vars_dark: source.dark,
-        vars_light: source.light
-      },
-      {
-        onSuccess: (created) => {
-          navigate({
-            params: { id: String(created.id) },
-            to: '/settings/appearance/themes/$id'
-          })
-        }
-      }
-    )
-  }
-
-  return (
-    <div className="max-w-md space-y-4 p-6">
-      <h1 className="font-bold text-2xl">{t('appearance.editor.new_title')}</h1>
-      <Input
-        onChange={(event) => setName(event.target.value)}
-        placeholder={t('appearance.editor.name_placeholder')}
-        value={name}
-      />
-      <Select
-        items={Object.fromEntries(themes.map((theme) => [theme.id, theme.name]))}
-        onValueChange={(value) => {
-          if (value !== null) {
-            setForkFrom(value as ColorTheme)
-          }
-        }}
-        value={forkFrom}
-      >
-        <SelectTrigger>
-          <SelectValue placeholder={t('appearance.editor.fork_from')} />
-        </SelectTrigger>
-        <SelectContent>
-          {themes.map((theme) => (
-            <SelectItem key={theme.id} value={theme.id}>
-              {theme.name}
-            </SelectItem>
-          ))}
-        </SelectContent>
-      </Select>
-      <div className="flex gap-2">
-        <Button onClick={() => navigate({ to: '/settings/appearance' })} type="button" variant="outline">
-          {t('common:cancel')}
-        </Button>
-        <Button disabled={createTheme.isPending} onClick={submit} type="button">
-          {t('common:create')}
-        </Button>
-      </div>
-    </div>
-  )
-}
diff --git a/apps/web/src/routes/_authed/settings/appearance/themes/$id.tsx b/apps/web/src/routes/_authed/settings/appearance/themes/$id.tsx
deleted file mode 100644
index 5e5b0803..00000000
--- a/apps/web/src/routes/_authed/settings/appearance/themes/$id.tsx
+++ /dev/null
@@ -1,11 +0,0 @@
-import { createFileRoute } from '@tanstack/react-router'
-import { ThemeEditor } from '@/components/theme/theme-editor'
-
-export const Route = createFileRoute('/_authed/settings/appearance/themes/$id')({
-  component: EditThemePage
-})
-
-function EditThemePage() {
-  const { id } = Route.useParams()
-  return <ThemeEditor themeId={Number(id)} />
-}
diff --git a/apps/web/src/themes/catppuccin.css b/apps/web/src/themes/catppuccin.css
deleted file mode 100644
index 256bf518..00000000
--- a/apps/web/src/themes/catppuccin.css
+++ /dev/null
@@ -1,67 +0,0 @@
-[data-theme="catppuccin"] {
-  --background: oklch(0.96 0.01 290);
-  --foreground: oklch(0.3 0.03 290);
-  --card: oklch(0.97 0.008 290);
-  --card-foreground: oklch(0.3 0.03 290);
-  --popover: oklch(0.97 0.008 290);
-  --popover-foreground: oklch(0.3 0.03 290);
-  --primary: oklch(0.6 0.18 310);
-  --primary-foreground: oklch(0.98 0.005 290);
-  --secondary: oklch(0.93 0.015 290);
-  --secondary-foreground: oklch(0.35 0.03 290);
-  --muted: oklch(0.93 0.015 290);
-  --muted-foreground: oklch(0.55 0.02 290);
-  --accent: oklch(0.92 0.018 290);
-  --accent-foreground: oklch(0.35 0.03 290);
-  --destructive: oklch(0.6 0.2 20);
-  --border: oklch(0.89 0.018 290);
-  --input: oklch(0.89 0.018 290);
-  --ring: oklch(0.6 0.18 310);
-  --chart-1: oklch(0.65 0.18 310);
-  --chart-2: oklch(0.7 0.12 190);
-  --chart-3: oklch(0.75 0.15 60);
-  --chart-4: oklch(0.6 0.15 350);
-  --chart-5: oklch(0.65 0.14 140);
-  --sidebar: oklch(0.95 0.012 290);
-  --sidebar-foreground: oklch(0.3 0.03 290);
-  --sidebar-primary: oklch(0.6 0.18 310);
-  --sidebar-primary-foreground: oklch(0.98 0.005 290);
-  --sidebar-accent: oklch(0.92 0.018 290);
-  --sidebar-accent-foreground: oklch(0.35 0.03 290);
-  --sidebar-border: oklch(0.89 0.018 290);
-  --sidebar-ring: oklch(0.6 0.18 310);
-}
-
-[data-theme="catppuccin"].dark {
-  --background: oklch(0.2 0.02 290);
-  --foreground: oklch(0.87 0.015 290);
-  --card: oklch(0.24 0.025 290);
-  --card-foreground: oklch(0.87 0.015 290);
-  --popover: oklch(0.24 0.025 290);
-  --popover-foreground: oklch(0.87 0.015 290);
-  --primary: oklch(0.72 0.17 310);
-  --primary-foreground: oklch(0.18 0.02 290);
-  --secondary: oklch(0.3 0.03 290);
-  --secondary-foreground: oklch(0.87 0.015 290);
-  --muted: oklch(0.3 0.03 290);
-  --muted-foreground: oklch(0.62 0.02 290);
-  --accent: oklch(0.32 0.035 290);
-  --accent-foreground: oklch(0.87 0.015 290);
-  --destructive: oklch(0.65 0.2 15);
-  --border: oklch(0.35 0.035 290);
-  --input: oklch(0.35 0.035 290);
-  --ring: oklch(0.72 0.17 310);
-  --chart-1: oklch(0.72 0.17 310);
-  --chart-2: oklch(0.75 0.12 190);
-  --chart-3: oklch(0.8 0.15 60);
-  --chart-4: oklch(0.65 0.15 350);
-  --chart-5: oklch(0.7 0.14 140);
-  --sidebar: oklch(0.18 0.02 290);
-  --sidebar-foreground: oklch(0.87 0.015 290);
-  --sidebar-primary: oklch(0.72 0.17 310);
-  --sidebar-primary-foreground: oklch(0.98 0.005 290);
-  --sidebar-accent: oklch(0.3 0.03 290);
-  --sidebar-accent-foreground: oklch(0.87 0.015 290);
-  --sidebar-border: oklch(0.35 0.035 290);
-  --sidebar-ring: oklch(0.72 0.17 310);
-}
diff --git a/apps/web/src/themes/dracula.css b/apps/web/src/themes/dracula.css
deleted file mode 100644
index 71e03faf..00000000
--- a/apps/web/src/themes/dracula.css
+++ /dev/null
@@ -1,67 +0,0 @@
-[data-theme="dracula"] {
-  --background: oklch(0.97 0.008 280);
-  --foreground: oklch(0.28 0.03 280);
-  --card: oklch(0.98 0.006 280);
-  --card-foreground: oklch(0.28 0.03 280);
-  --popover: oklch(0.98 0.006 280);
-  --popover-foreground: oklch(0.28 0.03 280);
-  --primary: oklch(0.55 0.2 280);
-  --primary-foreground: oklch(0.98 0.005 280);
-  --secondary: oklch(0.94 0.012 280);
-  --secondary-foreground: oklch(0.32 0.03 280);
-  --muted: oklch(0.94 0.012 280);
-  --muted-foreground: oklch(0.55 0.02 280);
-  --accent: oklch(0.92 0.015 280);
-  --accent-foreground: oklch(0.32 0.03 280);
-  --destructive: oklch(0.6 0.22 15);
-  --border: oklch(0.89 0.015 280);
-  --input: oklch(0.89 0.015 280);
-  --ring: oklch(0.55 0.2 280);
-  --chart-1: oklch(0.55 0.2 280);
-  --chart-2: oklch(0.72 0.14 170);
-  --chart-3: oklch(0.8 0.14 100);
-  --chart-4: oklch(0.7 0.2 340);
-  --chart-5: oklch(0.65 0.12 220);
-  --sidebar: oklch(0.96 0.01 280);
-  --sidebar-foreground: oklch(0.28 0.03 280);
-  --sidebar-primary: oklch(0.55 0.2 280);
-  --sidebar-primary-foreground: oklch(0.98 0.005 280);
-  --sidebar-accent: oklch(0.92 0.015 280);
-  --sidebar-accent-foreground: oklch(0.32 0.03 280);
-  --sidebar-border: oklch(0.89 0.015 280);
-  --sidebar-ring: oklch(0.55 0.2 280);
-}
-
-[data-theme="dracula"].dark {
-  --background: oklch(0.2 0.03 280);
-  --foreground: oklch(0.9 0.01 280);
-  --card: oklch(0.24 0.035 280);
-  --card-foreground: oklch(0.9 0.01 280);
-  --popover: oklch(0.24 0.035 280);
-  --popover-foreground: oklch(0.9 0.01 280);
-  --primary: oklch(0.68 0.2 280);
-  --primary-foreground: oklch(0.15 0.025 280);
-  --secondary: oklch(0.3 0.04 280);
-  --secondary-foreground: oklch(0.9 0.01 280);
-  --muted: oklch(0.3 0.04 280);
-  --muted-foreground: oklch(0.62 0.02 280);
-  --accent: oklch(0.32 0.045 280);
-  --accent-foreground: oklch(0.9 0.01 280);
-  --destructive: oklch(0.65 0.22 15);
-  --border: oklch(0.36 0.045 280);
-  --input: oklch(0.36 0.045 280);
-  --ring: oklch(0.68 0.2 280);
-  --chart-1: oklch(0.68 0.2 280);
-  --chart-2: oklch(0.75 0.14 170);
-  --chart-3: oklch(0.82 0.14 100);
-  --chart-4: oklch(0.72 0.2 340);
-  --chart-5: oklch(0.68 0.12 220);
-  --sidebar: oklch(0.18 0.03 280);
-  --sidebar-foreground: oklch(0.9 0.01 280);
-  --sidebar-primary: oklch(0.68 0.2 280);
-  --sidebar-primary-foreground: oklch(0.98 0.005 280);
-  --sidebar-accent: oklch(0.3 0.04 280);
-  --sidebar-accent-foreground: oklch(0.9 0.01 280);
-  --sidebar-border: oklch(0.36 0.045 280);
-  --sidebar-ring: oklch(0.68 0.2 280);
-}
diff --git a/apps/web/src/themes/index.ts b/apps/web/src/themes/index.ts
deleted file mode 100644
index 2ae1d22c..00000000
--- a/apps/web/src/themes/index.ts
+++ /dev/null
@@ -1,110 +0,0 @@
-export type ColorTheme =
-  | 'default'
-  | 'tokyo-night'
-  | 'nord'
-  | 'catppuccin'
-  | 'dracula'
-  | 'one-dark'
-  | 'solarized'
-  | 'rose-pine'
-
-export interface ThemeInfo {
-  id: ColorTheme
-  name: string
-  previewColors: { light: string[]; dark: string[] }
-}
-
-export const themes: ThemeInfo[] = [
-  {
-    id: 'default',
-    name: 'Default',
-    previewColors: {
-      light: ['#000', '#fff', '#f5f5f5', '#e5e5e5'],
-      dark: ['#fafafa', '#171717', '#262626', '#404040']
-    }
-  },
-  {
-    id: 'tokyo-night',
-    name: 'Tokyo Night',
-    previewColors: {
-      light: ['#7a5af5', '#f0edf8', '#534080', '#c4b5f0'],
-      dark: ['#bb9af7', '#1a1b2e', '#2a2b45', '#7aa2f7']
-    }
-  },
-  {
-    id: 'nord',
-    name: 'Nord',
-    previewColors: {
-      light: ['#5e81ac', '#eceff4', '#4c566a', '#d8dee9'],
-      dark: ['#88c0d0', '#2e3440', '#3b4252', '#81a1c1']
-    }
-  },
-  {
-    id: 'catppuccin',
-    name: 'Catppuccin',
-    previewColors: {
-      light: ['#ca7cf8', '#f2ecf8', '#6c4a8a', '#e6d0f5'],
-      dark: ['#cba6f7', '#1e1e2e', '#313244', '#f5c2e7']
-    }
-  },
-  {
-    id: 'dracula',
-    name: 'Dracula',
-    previewColors: {
-      light: ['#7c3aed', '#f2eff8', '#503a80', '#c4b0f0'],
-      dark: ['#bd93f9', '#282a36', '#44475a', '#ff79c6']
-    }
-  },
-  {
-    id: 'one-dark',
-    name: 'One Dark',
-    previewColors: {
-      light: ['#4078f2', '#f0f2f5', '#383c44', '#c8ccd4'],
-      dark: ['#61afef', '#282c34', '#3e4452', '#e5c07b']
-    }
-  },
-  {
-    id: 'solarized',
-    name: 'Solarized',
-    previewColors: {
-      light: ['#268bd2', '#fdf6e3', '#586e75', '#eee8d5'],
-      dark: ['#2aa198', '#002b36', '#073642', '#b58900']
-    }
-  },
-  {
-    id: 'rose-pine',
-    name: 'Rose Pine',
-    previewColors: {
-      light: ['#d7827e', '#f4ede8', '#575279', '#dfdad9'],
-      dark: ['#ebbcba', '#191724', '#26233a', '#f6c177']
-    }
-  }
-]
-
-const COLOR_THEME_VALUES: ColorTheme[] = [
-  'default',
-  'tokyo-night',
-  'nord',
-  'catppuccin',
-  'dracula',
-  'one-dark',
-  'solarized',
-  'rose-pine'
-]
-
-export function isColorTheme(value: string | null): value is ColorTheme {
-  if (value === null) {
-    return false
-  }
-  return COLOR_THEME_VALUES.includes(value as ColorTheme)
-}
-
-const loadedThemes = new Set<string>()
-
-export async function loadThemeCSS(themeId: ColorTheme): Promise<void> {
-  if (themeId === 'default' || loadedThemes.has(themeId)) {
-    return
-  }
-  await import(/* @vite-ignore */ `./${themeId}.css`)
-  loadedThemes.add(themeId)
-}
diff --git a/apps/web/src/themes/nord.css b/apps/web/src/themes/nord.css
deleted file mode 100644
index 594bc18e..00000000
--- a/apps/web/src/themes/nord.css
+++ /dev/null
@@ -1,67 +0,0 @@
-[data-theme="nord"] {
-  --background: oklch(0.97 0.005 230);
-  --foreground: oklch(0.3 0.02 230);
-  --card: oklch(0.98 0.004 230);
-  --card-foreground: oklch(0.3 0.02 230);
-  --popover: oklch(0.98 0.004 230);
-  --popover-foreground: oklch(0.3 0.02 230);
-  --primary: oklch(0.6 0.1 230);
-  --primary-foreground: oklch(0.98 0.004 230);
-  --secondary: oklch(0.93 0.01 230);
-  --secondary-foreground: oklch(0.35 0.025 230);
-  --muted: oklch(0.93 0.01 230);
-  --muted-foreground: oklch(0.55 0.015 230);
-  --accent: oklch(0.92 0.012 230);
-  --accent-foreground: oklch(0.35 0.025 230);
-  --destructive: oklch(0.6 0.2 20);
-  --border: oklch(0.88 0.015 230);
-  --input: oklch(0.88 0.015 230);
-  --ring: oklch(0.6 0.1 230);
-  --chart-1: oklch(0.6 0.1 230);
-  --chart-2: oklch(0.65 0.12 160);
-  --chart-3: oklch(0.75 0.12 80);
-  --chart-4: oklch(0.65 0.15 20);
-  --chart-5: oklch(0.6 0.12 300);
-  --sidebar: oklch(0.96 0.006 230);
-  --sidebar-foreground: oklch(0.3 0.02 230);
-  --sidebar-primary: oklch(0.6 0.1 230);
-  --sidebar-primary-foreground: oklch(0.98 0.004 230);
-  --sidebar-accent: oklch(0.92 0.012 230);
-  --sidebar-accent-foreground: oklch(0.35 0.025 230);
-  --sidebar-border: oklch(0.88 0.015 230);
-  --sidebar-ring: oklch(0.6 0.1 230);
-}
-
-[data-theme="nord"].dark {
-  --background: oklch(0.22 0.02 230);
-  --foreground: oklch(0.88 0.01 230);
-  --card: oklch(0.26 0.022 230);
-  --card-foreground: oklch(0.88 0.01 230);
-  --popover: oklch(0.26 0.022 230);
-  --popover-foreground: oklch(0.88 0.01 230);
-  --primary: oklch(0.7 0.1 230);
-  --primary-foreground: oklch(0.2 0.02 230);
-  --secondary: oklch(0.3 0.025 230);
-  --secondary-foreground: oklch(0.88 0.01 230);
-  --muted: oklch(0.3 0.025 230);
-  --muted-foreground: oklch(0.65 0.015 230);
-  --accent: oklch(0.32 0.028 230);
-  --accent-foreground: oklch(0.88 0.01 230);
-  --destructive: oklch(0.65 0.18 20);
-  --border: oklch(0.35 0.03 230);
-  --input: oklch(0.35 0.03 230);
-  --ring: oklch(0.7 0.1 230);
-  --chart-1: oklch(0.7 0.1 230);
-  --chart-2: oklch(0.7 0.12 160);
-  --chart-3: oklch(0.8 0.12 80);
-  --chart-4: oklch(0.7 0.15 20);
-  --chart-5: oklch(0.65 0.12 300);
-  --sidebar: oklch(0.2 0.02 230);
-  --sidebar-foreground: oklch(0.88 0.01 230);
-  --sidebar-primary: oklch(0.7 0.1 230);
-  --sidebar-primary-foreground: oklch(0.98 0.004 230);
-  --sidebar-accent: oklch(0.3 0.025 230);
-  --sidebar-accent-foreground: oklch(0.88 0.01 230);
-  --sidebar-border: oklch(0.35 0.03 230);
-  --sidebar-ring: oklch(0.7 0.1 230);
-}
diff --git a/apps/web/src/themes/one-dark.css b/apps/web/src/themes/one-dark.css
deleted file mode 100644
index aaf3b30d..00000000
--- a/apps/web/src/themes/one-dark.css
+++ /dev/null
@@ -1,67 +0,0 @@
-[data-theme="one-dark"] {
-  --background: oklch(0.97 0.005 240);
-  --foreground: oklch(0.28 0.02 240);
-  --card: oklch(0.98 0.004 240);
-  --card-foreground: oklch(0.28 0.02 240);
-  --popover: oklch(0.98 0.004 240);
-  --popover-foreground: oklch(0.28 0.02 240);
-  --primary: oklch(0.58 0.14 240);
-  --primary-foreground: oklch(0.98 0.004 240);
-  --secondary: oklch(0.93 0.008 240);
-  --secondary-foreground: oklch(0.32 0.025 240);
-  --muted: oklch(0.93 0.008 240);
-  --muted-foreground: oklch(0.55 0.015 240);
-  --accent: oklch(0.92 0.01 240);
-  --accent-foreground: oklch(0.32 0.025 240);
-  --destructive: oklch(0.6 0.2 20);
-  --border: oklch(0.89 0.01 240);
-  --input: oklch(0.89 0.01 240);
-  --ring: oklch(0.58 0.14 240);
-  --chart-1: oklch(0.58 0.14 240);
-  --chart-2: oklch(0.72 0.16 45);
-  --chart-3: oklch(0.7 0.14 160);
-  --chart-4: oklch(0.65 0.18 310);
-  --chart-5: oklch(0.6 0.16 15);
-  --sidebar: oklch(0.96 0.006 240);
-  --sidebar-foreground: oklch(0.28 0.02 240);
-  --sidebar-primary: oklch(0.58 0.14 240);
-  --sidebar-primary-foreground: oklch(0.98 0.004 240);
-  --sidebar-accent: oklch(0.92 0.01 240);
-  --sidebar-accent-foreground: oklch(0.32 0.025 240);
-  --sidebar-border: oklch(0.89 0.01 240);
-  --sidebar-ring: oklch(0.58 0.14 240);
-}
-
-[data-theme="one-dark"].dark {
-  --background: oklch(0.2 0.015 240);
-  --foreground: oklch(0.85 0.015 240);
-  --card: oklch(0.25 0.018 240);
-  --card-foreground: oklch(0.85 0.015 240);
-  --popover: oklch(0.25 0.018 240);
-  --popover-foreground: oklch(0.85 0.015 240);
-  --primary: oklch(0.68 0.14 240);
-  --primary-foreground: oklch(0.18 0.015 240);
-  --secondary: oklch(0.3 0.02 240);
-  --secondary-foreground: oklch(0.85 0.015 240);
-  --muted: oklch(0.3 0.02 240);
-  --muted-foreground: oklch(0.62 0.015 240);
-  --accent: oklch(0.32 0.022 240);
-  --accent-foreground: oklch(0.85 0.015 240);
-  --destructive: oklch(0.65 0.2 15);
-  --border: oklch(0.35 0.02 240);
-  --input: oklch(0.35 0.02 240);
-  --ring: oklch(0.68 0.14 240);
-  --chart-1: oklch(0.68 0.14 240);
-  --chart-2: oklch(0.76 0.16 45);
-  --chart-3: oklch(0.72 0.14 160);
-  --chart-4: oklch(0.7 0.18 310);
-  --chart-5: oklch(0.65 0.16 15);
-  --sidebar: oklch(0.18 0.015 240);
-  --sidebar-foreground: oklch(0.85 0.015 240);
-  --sidebar-primary: oklch(0.68 0.14 240);
-  --sidebar-primary-foreground: oklch(0.98 0.004 240);
-  --sidebar-accent: oklch(0.3 0.02 240);
-  --sidebar-accent-foreground: oklch(0.85 0.015 240);
-  --sidebar-border: oklch(0.35 0.02 240);
-  --sidebar-ring: oklch(0.68 0.14 240);
-}
diff --git a/apps/web/src/themes/preset-vars.test.ts b/apps/web/src/themes/preset-vars.test.ts
deleted file mode 100644
index d0f4aa7a..00000000
--- a/apps/web/src/themes/preset-vars.test.ts
+++ /dev/null
@@ -1,63 +0,0 @@
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { describe, expect, test } from 'vitest'
-import type { ColorTheme } from './index'
-import { PRESET_VAR_KEYS, presetVars } from './preset-vars'
-
-const THEME_IDS: ColorTheme[] = [
-  'default',
-  'tokyo-night',
-  'nord',
-  'catppuccin',
-  'dracula',
-  'one-dark',
-  'solarized',
-  'rose-pine'
-]
-
-const THEME_FILE_BY_ID: Record<ColorTheme, string> = {
-  default: join(process.cwd(), 'src/index.css'),
-  'tokyo-night': join(process.cwd(), 'src/themes/tokyo-night.css'),
-  nord: join(process.cwd(), 'src/themes/nord.css'),
-  catppuccin: join(process.cwd(), 'src/themes/catppuccin.css'),
-  dracula: join(process.cwd(), 'src/themes/dracula.css'),
-  'one-dark': join(process.cwd(), 'src/themes/one-dark.css'),
-  solarized: join(process.cwd(), 'src/themes/solarized.css'),
-  'rose-pine': join(process.cwd(), 'src/themes/rose-pine.css')
-}
-
-function escapeRegex(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-}
-
-function readVars(selector: string, cssFile: string): Record<string, string> {
-  const css = readFileSync(cssFile, 'utf8')
-  const blockMatch = css.match(new RegExp(`${escapeRegex(selector)}\\s*\\{(?<body>[\\s\\S]*?)\\}`))
-
-  if (!blockMatch?.groups?.body) {
-    throw new Error(`Missing CSS block for ${selector}`)
-  }
-
-  return Object.fromEntries(
-    Array.from(blockMatch.groups.body.matchAll(/--(?<key>[\w-]+):\s*(?<value>[^;]+);/g)).map((match) => [
-      match.groups?.key ?? '',
-      match.groups?.value.trim() ?? ''
-    ])
-  )
-}
-
-describe('presetVars', () => {
-  test.each(THEME_IDS)('matches CSS variables for %s', (themeId) => {
-    const lightSelector = themeId === 'default' ? ':root' : `[data-theme="${themeId}"]`
-    const darkSelector = themeId === 'default' ? '.dark' : `[data-theme="${themeId}"].dark`
-    const cssFile = THEME_FILE_BY_ID[themeId]
-
-    const lightVars = readVars(lightSelector, cssFile)
-    const darkVars = readVars(darkSelector, cssFile)
-
-    for (const key of PRESET_VAR_KEYS) {
-      expect(presetVars[themeId].light[key], `${themeId} light ${key}`).toBe(lightVars[key])
-      expect(presetVars[themeId].dark[key], `${themeId} dark ${key}`).toBe(darkVars[key])
-    }
-  })
-})
diff --git a/apps/web/src/themes/preset-vars.ts b/apps/web/src/themes/preset-vars.ts
deleted file mode 100644
index a8b5377e..00000000
--- a/apps/web/src/themes/preset-vars.ts
+++ /dev/null
@@ -1,608 +0,0 @@
-import type { ColorTheme } from './index'
-
-export const PRESET_VAR_KEYS = [
-  'background',
-  'foreground',
-  'card',
-  'card-foreground',
-  'popover',
-  'popover-foreground',
-  'primary',
-  'primary-foreground',
-  'secondary',
-  'secondary-foreground',
-  'muted',
-  'muted-foreground',
-  'accent',
-  'accent-foreground',
-  'destructive',
-  'border',
-  'input',
-  'ring',
-  'chart-1',
-  'chart-2',
-  'chart-3',
-  'chart-4',
-  'chart-5',
-  'sidebar',
-  'sidebar-foreground',
-  'sidebar-primary',
-  'sidebar-primary-foreground',
-  'sidebar-accent',
-  'sidebar-accent-foreground',
-  'sidebar-border',
-  'sidebar-ring'
-] as const
-
-export type PresetVarKey = (typeof PRESET_VAR_KEYS)[number]
-
-export type VarMap = Record<PresetVarKey, string>
-
-export interface PresetVars {
-  dark: VarMap
-  light: VarMap
-}
-
-type PresetVarValues = readonly string[]
-
-function createVarMap(values: PresetVarValues): VarMap {
-  if (values.length !== PRESET_VAR_KEYS.length) {
-    throw new Error(`Expected ${PRESET_VAR_KEYS.length} preset variable values, received ${values.length}`)
-  }
-
-  return Object.fromEntries(PRESET_VAR_KEYS.map((key, index) => [key, values[index]])) as VarMap
-}
-
-function createPresetVars(light: PresetVarValues, dark: PresetVarValues): PresetVars {
-  return {
-    light: createVarMap(light),
-    dark: createVarMap(dark)
-  }
-}
-
-export const presetVars: Record<ColorTheme, PresetVars> = {
-  default: createPresetVars(
-    [
-      'oklch(1 0 0)',
-      'oklch(0.145 0 0)',
-      'oklch(1 0 0)',
-      'oklch(0.145 0 0)',
-      'oklch(1 0 0)',
-      'oklch(0.145 0 0)',
-      'oklch(0.205 0 0)',
-      'oklch(0.985 0 0)',
-      'oklch(0.97 0 0)',
-      'oklch(0.205 0 0)',
-      'oklch(0.97 0 0)',
-      'oklch(0.556 0 0)',
-      'oklch(0.97 0 0)',
-      'oklch(0.205 0 0)',
-      'oklch(0.577 0.245 27.325)',
-      'oklch(0.922 0 0)',
-      'oklch(0.922 0 0)',
-      'oklch(0.708 0 0)',
-      'oklch(0.67 0.14 241.966)',
-      'oklch(0.67 0.13 163.225)',
-      'oklch(0.8 0.16 55.934)',
-      'oklch(0.71 0.2 16.439)',
-      'oklch(0.63 0.17 293.745)',
-      'oklch(0.985 0 0)',
-      'oklch(0.145 0 0)',
-      'oklch(0.205 0 0)',
-      'oklch(0.985 0 0)',
-      'oklch(0.97 0 0)',
-      'oklch(0.205 0 0)',
-      'oklch(0.922 0 0)',
-      'oklch(0.708 0 0)'
-    ],
-    [
-      'oklch(0.145 0 0)',
-      'oklch(0.985 0 0)',
-      'oklch(0.205 0 0)',
-      'oklch(0.985 0 0)',
-      'oklch(0.205 0 0)',
-      'oklch(0.985 0 0)',
-      'oklch(0.922 0 0)',
-      'oklch(0.205 0 0)',
-      'oklch(0.269 0 0)',
-      'oklch(0.985 0 0)',
-      'oklch(0.269 0 0)',
-      'oklch(0.708 0 0)',
-      'oklch(0.269 0 0)',
-      'oklch(0.985 0 0)',
-      'oklch(0.704 0.191 22.216)',
-      'oklch(1 0 0 / 10%)',
-      'oklch(1 0 0 / 15%)',
-      'oklch(0.556 0 0)',
-      'oklch(0.707 0.165 254.624)',
-      'oklch(0.696 0.17 162.48)',
-      'oklch(0.769 0.188 70.08)',
-      'oklch(0.704 0.191 22.216)',
-      'oklch(0.65 0.2 293.745)',
-      'oklch(0.205 0 0)',
-      'oklch(0.985 0 0)',
-      'oklch(0.488 0.243 264.376)',
-      'oklch(0.985 0 0)',
-      'oklch(0.269 0 0)',
-      'oklch(0.985 0 0)',
-      'oklch(1 0 0 / 10%)',
-      'oklch(0.556 0 0)'
-    ]
-  ),
-  'tokyo-night': createPresetVars(
-    [
-      'oklch(0.97 0.008 270)',
-      'oklch(0.25 0.03 270)',
-      'oklch(0.98 0.006 270)',
-      'oklch(0.25 0.03 270)',
-      'oklch(0.98 0.006 270)',
-      'oklch(0.25 0.03 270)',
-      'oklch(0.55 0.18 270)',
-      'oklch(0.98 0.005 270)',
-      'oklch(0.94 0.012 270)',
-      'oklch(0.3 0.04 270)',
-      'oklch(0.94 0.012 270)',
-      'oklch(0.55 0.02 270)',
-      'oklch(0.93 0.015 270)',
-      'oklch(0.3 0.04 270)',
-      'oklch(0.577 0.245 27.325)',
-      'oklch(0.9 0.015 270)',
-      'oklch(0.9 0.015 270)',
-      'oklch(0.55 0.18 270)',
-      'oklch(0.6 0.18 270)',
-      'oklch(0.7 0.15 190)',
-      'oklch(0.75 0.12 80)',
-      'oklch(0.65 0.18 320)',
-      'oklch(0.7 0.14 140)',
-      'oklch(0.96 0.01 270)',
-      'oklch(0.25 0.03 270)',
-      'oklch(0.55 0.18 270)',
-      'oklch(0.98 0.005 270)',
-      'oklch(0.93 0.015 270)',
-      'oklch(0.3 0.04 270)',
-      'oklch(0.9 0.015 270)',
-      'oklch(0.55 0.18 270)'
-    ],
-    [
-      'oklch(0.18 0.025 260)',
-      'oklch(0.85 0.02 250)',
-      'oklch(0.22 0.03 260)',
-      'oklch(0.85 0.02 250)',
-      'oklch(0.22 0.03 260)',
-      'oklch(0.85 0.02 250)',
-      'oklch(0.7 0.17 270)',
-      'oklch(0.15 0.02 260)',
-      'oklch(0.28 0.035 260)',
-      'oklch(0.85 0.02 250)',
-      'oklch(0.28 0.035 260)',
-      'oklch(0.6 0.03 250)',
-      'oklch(0.3 0.04 260)',
-      'oklch(0.85 0.02 250)',
-      'oklch(0.65 0.2 15)',
-      'oklch(0.32 0.04 260)',
-      'oklch(0.32 0.04 260)',
-      'oklch(0.7 0.17 270)',
-      'oklch(0.7 0.17 270)',
-      'oklch(0.75 0.14 190)',
-      'oklch(0.8 0.15 80)',
-      'oklch(0.7 0.18 320)',
-      'oklch(0.72 0.14 140)',
-      'oklch(0.16 0.025 260)',
-      'oklch(0.85 0.02 250)',
-      'oklch(0.7 0.17 270)',
-      'oklch(0.98 0.005 270)',
-      'oklch(0.28 0.035 260)',
-      'oklch(0.85 0.02 250)',
-      'oklch(0.32 0.04 260)',
-      'oklch(0.7 0.17 270)'
-    ]
-  ),
-  nord: createPresetVars(
-    [
-      'oklch(0.97 0.005 230)',
-      'oklch(0.3 0.02 230)',
-      'oklch(0.98 0.004 230)',
-      'oklch(0.3 0.02 230)',
-      'oklch(0.98 0.004 230)',
-      'oklch(0.3 0.02 230)',
-      'oklch(0.6 0.1 230)',
-      'oklch(0.98 0.004 230)',
-      'oklch(0.93 0.01 230)',
-      'oklch(0.35 0.025 230)',
-      'oklch(0.93 0.01 230)',
-      'oklch(0.55 0.015 230)',
-      'oklch(0.92 0.012 230)',
-      'oklch(0.35 0.025 230)',
-      'oklch(0.6 0.2 20)',
-      'oklch(0.88 0.015 230)',
-      'oklch(0.88 0.015 230)',
-      'oklch(0.6 0.1 230)',
-      'oklch(0.6 0.1 230)',
-      'oklch(0.65 0.12 160)',
-      'oklch(0.75 0.12 80)',
-      'oklch(0.65 0.15 20)',
-      'oklch(0.6 0.12 300)',
-      'oklch(0.96 0.006 230)',
-      'oklch(0.3 0.02 230)',
-      'oklch(0.6 0.1 230)',
-      'oklch(0.98 0.004 230)',
-      'oklch(0.92 0.012 230)',
-      'oklch(0.35 0.025 230)',
-      'oklch(0.88 0.015 230)',
-      'oklch(0.6 0.1 230)'
-    ],
-    [
-      'oklch(0.22 0.02 230)',
-      'oklch(0.88 0.01 230)',
-      'oklch(0.26 0.022 230)',
-      'oklch(0.88 0.01 230)',
-      'oklch(0.26 0.022 230)',
-      'oklch(0.88 0.01 230)',
-      'oklch(0.7 0.1 230)',
-      'oklch(0.2 0.02 230)',
-      'oklch(0.3 0.025 230)',
-      'oklch(0.88 0.01 230)',
-      'oklch(0.3 0.025 230)',
-      'oklch(0.65 0.015 230)',
-      'oklch(0.32 0.028 230)',
-      'oklch(0.88 0.01 230)',
-      'oklch(0.65 0.18 20)',
-      'oklch(0.35 0.03 230)',
-      'oklch(0.35 0.03 230)',
-      'oklch(0.7 0.1 230)',
-      'oklch(0.7 0.1 230)',
-      'oklch(0.7 0.12 160)',
-      'oklch(0.8 0.12 80)',
-      'oklch(0.7 0.15 20)',
-      'oklch(0.65 0.12 300)',
-      'oklch(0.2 0.02 230)',
-      'oklch(0.88 0.01 230)',
-      'oklch(0.7 0.1 230)',
-      'oklch(0.98 0.004 230)',
-      'oklch(0.3 0.025 230)',
-      'oklch(0.88 0.01 230)',
-      'oklch(0.35 0.03 230)',
-      'oklch(0.7 0.1 230)'
-    ]
-  ),
-  catppuccin: createPresetVars(
-    [
-      'oklch(0.96 0.01 290)',
-      'oklch(0.3 0.03 290)',
-      'oklch(0.97 0.008 290)',
-      'oklch(0.3 0.03 290)',
-      'oklch(0.97 0.008 290)',
-      'oklch(0.3 0.03 290)',
-      'oklch(0.6 0.18 310)',
-      'oklch(0.98 0.005 290)',
-      'oklch(0.93 0.015 290)',
-      'oklch(0.35 0.03 290)',
-      'oklch(0.93 0.015 290)',
-      'oklch(0.55 0.02 290)',
-      'oklch(0.92 0.018 290)',
-      'oklch(0.35 0.03 290)',
-      'oklch(0.6 0.2 20)',
-      'oklch(0.89 0.018 290)',
-      'oklch(0.89 0.018 290)',
-      'oklch(0.6 0.18 310)',
-      'oklch(0.65 0.18 310)',
-      'oklch(0.7 0.12 190)',
-      'oklch(0.75 0.15 60)',
-      'oklch(0.6 0.15 350)',
-      'oklch(0.65 0.14 140)',
-      'oklch(0.95 0.012 290)',
-      'oklch(0.3 0.03 290)',
-      'oklch(0.6 0.18 310)',
-      'oklch(0.98 0.005 290)',
-      'oklch(0.92 0.018 290)',
-      'oklch(0.35 0.03 290)',
-      'oklch(0.89 0.018 290)',
-      'oklch(0.6 0.18 310)'
-    ],
-    [
-      'oklch(0.2 0.02 290)',
-      'oklch(0.87 0.015 290)',
-      'oklch(0.24 0.025 290)',
-      'oklch(0.87 0.015 290)',
-      'oklch(0.24 0.025 290)',
-      'oklch(0.87 0.015 290)',
-      'oklch(0.72 0.17 310)',
-      'oklch(0.18 0.02 290)',
-      'oklch(0.3 0.03 290)',
-      'oklch(0.87 0.015 290)',
-      'oklch(0.3 0.03 290)',
-      'oklch(0.62 0.02 290)',
-      'oklch(0.32 0.035 290)',
-      'oklch(0.87 0.015 290)',
-      'oklch(0.65 0.2 15)',
-      'oklch(0.35 0.035 290)',
-      'oklch(0.35 0.035 290)',
-      'oklch(0.72 0.17 310)',
-      'oklch(0.72 0.17 310)',
-      'oklch(0.75 0.12 190)',
-      'oklch(0.8 0.15 60)',
-      'oklch(0.65 0.15 350)',
-      'oklch(0.7 0.14 140)',
-      'oklch(0.18 0.02 290)',
-      'oklch(0.87 0.015 290)',
-      'oklch(0.72 0.17 310)',
-      'oklch(0.98 0.005 290)',
-      'oklch(0.3 0.03 290)',
-      'oklch(0.87 0.015 290)',
-      'oklch(0.35 0.035 290)',
-      'oklch(0.72 0.17 310)'
-    ]
-  ),
-  dracula: createPresetVars(
-    [
-      'oklch(0.97 0.008 280)',
-      'oklch(0.28 0.03 280)',
-      'oklch(0.98 0.006 280)',
-      'oklch(0.28 0.03 280)',
-      'oklch(0.98 0.006 280)',
-      'oklch(0.28 0.03 280)',
-      'oklch(0.55 0.2 280)',
-      'oklch(0.98 0.005 280)',
-      'oklch(0.94 0.012 280)',
-      'oklch(0.32 0.03 280)',
-      'oklch(0.94 0.012 280)',
-      'oklch(0.55 0.02 280)',
-      'oklch(0.92 0.015 280)',
-      'oklch(0.32 0.03 280)',
-      'oklch(0.6 0.22 15)',
-      'oklch(0.89 0.015 280)',
-      'oklch(0.89 0.015 280)',
-      'oklch(0.55 0.2 280)',
-      'oklch(0.55 0.2 280)',
-      'oklch(0.72 0.14 170)',
-      'oklch(0.8 0.14 100)',
-      'oklch(0.7 0.2 340)',
-      'oklch(0.65 0.12 220)',
-      'oklch(0.96 0.01 280)',
-      'oklch(0.28 0.03 280)',
-      'oklch(0.55 0.2 280)',
-      'oklch(0.98 0.005 280)',
-      'oklch(0.92 0.015 280)',
-      'oklch(0.32 0.03 280)',
-      'oklch(0.89 0.015 280)',
-      'oklch(0.55 0.2 280)'
-    ],
-    [
-      'oklch(0.2 0.03 280)',
-      'oklch(0.9 0.01 280)',
-      'oklch(0.24 0.035 280)',
-      'oklch(0.9 0.01 280)',
-      'oklch(0.24 0.035 280)',
-      'oklch(0.9 0.01 280)',
-      'oklch(0.68 0.2 280)',
-      'oklch(0.15 0.025 280)',
-      'oklch(0.3 0.04 280)',
-      'oklch(0.9 0.01 280)',
-      'oklch(0.3 0.04 280)',
-      'oklch(0.62 0.02 280)',
-      'oklch(0.32 0.045 280)',
-      'oklch(0.9 0.01 280)',
-      'oklch(0.65 0.22 15)',
-      'oklch(0.36 0.045 280)',
-      'oklch(0.36 0.045 280)',
-      'oklch(0.68 0.2 280)',
-      'oklch(0.68 0.2 280)',
-      'oklch(0.75 0.14 170)',
-      'oklch(0.82 0.14 100)',
-      'oklch(0.72 0.2 340)',
-      'oklch(0.68 0.12 220)',
-      'oklch(0.18 0.03 280)',
-      'oklch(0.9 0.01 280)',
-      'oklch(0.68 0.2 280)',
-      'oklch(0.98 0.005 280)',
-      'oklch(0.3 0.04 280)',
-      'oklch(0.9 0.01 280)',
-      'oklch(0.36 0.045 280)',
-      'oklch(0.68 0.2 280)'
-    ]
-  ),
-  'one-dark': createPresetVars(
-    [
-      'oklch(0.97 0.005 240)',
-      'oklch(0.28 0.02 240)',
-      'oklch(0.98 0.004 240)',
-      'oklch(0.28 0.02 240)',
-      'oklch(0.98 0.004 240)',
-      'oklch(0.28 0.02 240)',
-      'oklch(0.58 0.14 240)',
-      'oklch(0.98 0.004 240)',
-      'oklch(0.93 0.008 240)',
-      'oklch(0.32 0.025 240)',
-      'oklch(0.93 0.008 240)',
-      'oklch(0.55 0.015 240)',
-      'oklch(0.92 0.01 240)',
-      'oklch(0.32 0.025 240)',
-      'oklch(0.6 0.2 20)',
-      'oklch(0.89 0.01 240)',
-      'oklch(0.89 0.01 240)',
-      'oklch(0.58 0.14 240)',
-      'oklch(0.58 0.14 240)',
-      'oklch(0.72 0.16 45)',
-      'oklch(0.7 0.14 160)',
-      'oklch(0.65 0.18 310)',
-      'oklch(0.6 0.16 15)',
-      'oklch(0.96 0.006 240)',
-      'oklch(0.28 0.02 240)',
-      'oklch(0.58 0.14 240)',
-      'oklch(0.98 0.004 240)',
-      'oklch(0.92 0.01 240)',
-      'oklch(0.32 0.025 240)',
-      'oklch(0.89 0.01 240)',
-      'oklch(0.58 0.14 240)'
-    ],
-    [
-      'oklch(0.2 0.015 240)',
-      'oklch(0.85 0.015 240)',
-      'oklch(0.25 0.018 240)',
-      'oklch(0.85 0.015 240)',
-      'oklch(0.25 0.018 240)',
-      'oklch(0.85 0.015 240)',
-      'oklch(0.68 0.14 240)',
-      'oklch(0.18 0.015 240)',
-      'oklch(0.3 0.02 240)',
-      'oklch(0.85 0.015 240)',
-      'oklch(0.3 0.02 240)',
-      'oklch(0.62 0.015 240)',
-      'oklch(0.32 0.022 240)',
-      'oklch(0.85 0.015 240)',
-      'oklch(0.65 0.2 15)',
-      'oklch(0.35 0.02 240)',
-      'oklch(0.35 0.02 240)',
-      'oklch(0.68 0.14 240)',
-      'oklch(0.68 0.14 240)',
-      'oklch(0.76 0.16 45)',
-      'oklch(0.72 0.14 160)',
-      'oklch(0.7 0.18 310)',
-      'oklch(0.65 0.16 15)',
-      'oklch(0.18 0.015 240)',
-      'oklch(0.85 0.015 240)',
-      'oklch(0.68 0.14 240)',
-      'oklch(0.98 0.004 240)',
-      'oklch(0.3 0.02 240)',
-      'oklch(0.85 0.015 240)',
-      'oklch(0.35 0.02 240)',
-      'oklch(0.68 0.14 240)'
-    ]
-  ),
-  solarized: createPresetVars(
-    [
-      'oklch(0.95 0.01 85)',
-      'oklch(0.35 0.03 230)',
-      'oklch(0.96 0.008 85)',
-      'oklch(0.35 0.03 230)',
-      'oklch(0.96 0.008 85)',
-      'oklch(0.35 0.03 230)',
-      'oklch(0.55 0.12 200)',
-      'oklch(0.96 0.008 85)',
-      'oklch(0.92 0.015 85)',
-      'oklch(0.4 0.03 230)',
-      'oklch(0.92 0.015 85)',
-      'oklch(0.55 0.02 230)',
-      'oklch(0.9 0.018 85)',
-      'oklch(0.4 0.03 230)',
-      'oklch(0.57 0.2 20)',
-      'oklch(0.87 0.02 85)',
-      'oklch(0.87 0.02 85)',
-      'oklch(0.55 0.12 200)',
-      'oklch(0.55 0.12 200)',
-      'oklch(0.65 0.14 160)',
-      'oklch(0.78 0.15 85)',
-      'oklch(0.6 0.18 20)',
-      'oklch(0.55 0.16 280)',
-      'oklch(0.93 0.012 85)',
-      'oklch(0.35 0.03 230)',
-      'oklch(0.55 0.12 200)',
-      'oklch(0.96 0.008 85)',
-      'oklch(0.9 0.018 85)',
-      'oklch(0.4 0.03 230)',
-      'oklch(0.87 0.02 85)',
-      'oklch(0.55 0.12 200)'
-    ],
-    [
-      'oklch(0.18 0.02 230)',
-      'oklch(0.82 0.02 85)',
-      'oklch(0.22 0.025 230)',
-      'oklch(0.82 0.02 85)',
-      'oklch(0.22 0.025 230)',
-      'oklch(0.82 0.02 85)',
-      'oklch(0.65 0.12 200)',
-      'oklch(0.16 0.02 230)',
-      'oklch(0.26 0.025 230)',
-      'oklch(0.82 0.02 85)',
-      'oklch(0.26 0.025 230)',
-      'oklch(0.6 0.02 85)',
-      'oklch(0.28 0.028 230)',
-      'oklch(0.82 0.02 85)',
-      'oklch(0.62 0.2 20)',
-      'oklch(0.32 0.025 230)',
-      'oklch(0.32 0.025 230)',
-      'oklch(0.65 0.12 200)',
-      'oklch(0.65 0.12 200)',
-      'oklch(0.68 0.14 160)',
-      'oklch(0.8 0.15 85)',
-      'oklch(0.65 0.18 20)',
-      'oklch(0.6 0.16 280)',
-      'oklch(0.16 0.02 230)',
-      'oklch(0.82 0.02 85)',
-      'oklch(0.65 0.12 200)',
-      'oklch(0.96 0.008 85)',
-      'oklch(0.26 0.025 230)',
-      'oklch(0.82 0.02 85)',
-      'oklch(0.32 0.025 230)',
-      'oklch(0.65 0.12 200)'
-    ]
-  ),
-  'rose-pine': createPresetVars(
-    [
-      'oklch(0.96 0.008 340)',
-      'oklch(0.3 0.025 340)',
-      'oklch(0.97 0.006 340)',
-      'oklch(0.3 0.025 340)',
-      'oklch(0.97 0.006 340)',
-      'oklch(0.3 0.025 340)',
-      'oklch(0.58 0.14 340)',
-      'oklch(0.97 0.005 340)',
-      'oklch(0.93 0.012 340)',
-      'oklch(0.35 0.025 340)',
-      'oklch(0.93 0.012 340)',
-      'oklch(0.55 0.018 340)',
-      'oklch(0.91 0.015 340)',
-      'oklch(0.35 0.025 340)',
-      'oklch(0.58 0.2 15)',
-      'oklch(0.88 0.015 340)',
-      'oklch(0.88 0.015 340)',
-      'oklch(0.58 0.14 340)',
-      'oklch(0.58 0.14 340)',
-      'oklch(0.72 0.1 75)',
-      'oklch(0.65 0.12 250)',
-      'oklch(0.7 0.12 170)',
-      'oklch(0.6 0.16 300)',
-      'oklch(0.95 0.01 340)',
-      'oklch(0.3 0.025 340)',
-      'oklch(0.58 0.14 340)',
-      'oklch(0.97 0.005 340)',
-      'oklch(0.91 0.015 340)',
-      'oklch(0.35 0.025 340)',
-      'oklch(0.88 0.015 340)',
-      'oklch(0.58 0.14 340)'
-    ],
-    [
-      'oklch(0.19 0.02 300)',
-      'oklch(0.85 0.015 340)',
-      'oklch(0.23 0.025 300)',
-      'oklch(0.85 0.015 340)',
-      'oklch(0.23 0.025 300)',
-      'oklch(0.85 0.015 340)',
-      'oklch(0.68 0.14 340)',
-      'oklch(0.17 0.02 300)',
-      'oklch(0.28 0.025 300)',
-      'oklch(0.85 0.015 340)',
-      'oklch(0.28 0.025 300)',
-      'oklch(0.6 0.018 340)',
-      'oklch(0.3 0.03 300)',
-      'oklch(0.85 0.015 340)',
-      'oklch(0.62 0.2 15)',
-      'oklch(0.34 0.03 300)',
-      'oklch(0.34 0.03 300)',
-      'oklch(0.68 0.14 340)',
-      'oklch(0.68 0.14 340)',
-      'oklch(0.75 0.1 75)',
-      'oklch(0.68 0.12 250)',
-      'oklch(0.72 0.12 170)',
-      'oklch(0.65 0.16 300)',
-      'oklch(0.17 0.02 300)',
-      'oklch(0.85 0.015 340)',
-      'oklch(0.68 0.14 340)',
-      'oklch(0.97 0.005 340)',
-      'oklch(0.28 0.025 300)',
-      'oklch(0.85 0.015 340)',
-      'oklch(0.34 0.03 300)',
-      'oklch(0.68 0.14 340)'
-    ]
-  )
-}
diff --git a/apps/web/src/themes/rose-pine.css b/apps/web/src/themes/rose-pine.css
deleted file mode 100644
index f200d1b0..00000000
--- a/apps/web/src/themes/rose-pine.css
+++ /dev/null
@@ -1,67 +0,0 @@
-[data-theme="rose-pine"] {
-  --background: oklch(0.96 0.008 340);
-  --foreground: oklch(0.3 0.025 340);
-  --card: oklch(0.97 0.006 340);
-  --card-foreground: oklch(0.3 0.025 340);
-  --popover: oklch(0.97 0.006 340);
-  --popover-foreground: oklch(0.3 0.025 340);
-  --primary: oklch(0.58 0.14 340);
-  --primary-foreground: oklch(0.97 0.005 340);
-  --secondary: oklch(0.93 0.012 340);
-  --secondary-foreground: oklch(0.35 0.025 340);
-  --muted: oklch(0.93 0.012 340);
-  --muted-foreground: oklch(0.55 0.018 340);
-  --accent: oklch(0.91 0.015 340);
-  --accent-foreground: oklch(0.35 0.025 340);
-  --destructive: oklch(0.58 0.2 15);
-  --border: oklch(0.88 0.015 340);
-  --input: oklch(0.88 0.015 340);
-  --ring: oklch(0.58 0.14 340);
-  --chart-1: oklch(0.58 0.14 340);
-  --chart-2: oklch(0.72 0.1 75);
-  --chart-3: oklch(0.65 0.12 250);
-  --chart-4: oklch(0.7 0.12 170);
-  --chart-5: oklch(0.6 0.16 300);
-  --sidebar: oklch(0.95 0.01 340);
-  --sidebar-foreground: oklch(0.3 0.025 340);
-  --sidebar-primary: oklch(0.58 0.14 340);
-  --sidebar-primary-foreground: oklch(0.97 0.005 340);
-  --sidebar-accent: oklch(0.91 0.015 340);
-  --sidebar-accent-foreground: oklch(0.35 0.025 340);
-  --sidebar-border: oklch(0.88 0.015 340);
-  --sidebar-ring: oklch(0.58 0.14 340);
-}
-
-[data-theme="rose-pine"].dark {
-  --background: oklch(0.19 0.02 300);
-  --foreground: oklch(0.85 0.015 340);
-  --card: oklch(0.23 0.025 300);
-  --card-foreground: oklch(0.85 0.015 340);
-  --popover: oklch(0.23 0.025 300);
-  --popover-foreground: oklch(0.85 0.015 340);
-  --primary: oklch(0.68 0.14 340);
-  --primary-foreground: oklch(0.17 0.02 300);
-  --secondary: oklch(0.28 0.025 300);
-  --secondary-foreground: oklch(0.85 0.015 340);
-  --muted: oklch(0.28 0.025 300);
-  --muted-foreground: oklch(0.6 0.018 340);
-  --accent: oklch(0.3 0.03 300);
-  --accent-foreground: oklch(0.85 0.015 340);
-  --destructive: oklch(0.62 0.2 15);
-  --border: oklch(0.34 0.03 300);
-  --input: oklch(0.34 0.03 300);
-  --ring: oklch(0.68 0.14 340);
-  --chart-1: oklch(0.68 0.14 340);
-  --chart-2: oklch(0.75 0.1 75);
-  --chart-3: oklch(0.68 0.12 250);
-  --chart-4: oklch(0.72 0.12 170);
-  --chart-5: oklch(0.65 0.16 300);
-  --sidebar: oklch(0.17 0.02 300);
-  --sidebar-foreground: oklch(0.85 0.015 340);
-  --sidebar-primary: oklch(0.68 0.14 340);
-  --sidebar-primary-foreground: oklch(0.97 0.005 340);
-  --sidebar-accent: oklch(0.28 0.025 300);
-  --sidebar-accent-foreground: oklch(0.85 0.015 340);
-  --sidebar-border: oklch(0.34 0.03 300);
-  --sidebar-ring: oklch(0.68 0.14 340);
-}
diff --git a/apps/web/src/themes/solarized.css b/apps/web/src/themes/solarized.css
deleted file mode 100644
index 84d7770e..00000000
--- a/apps/web/src/themes/solarized.css
+++ /dev/null
@@ -1,67 +0,0 @@
-[data-theme="solarized"] {
-  --background: oklch(0.95 0.01 85);
-  --foreground: oklch(0.35 0.03 230);
-  --card: oklch(0.96 0.008 85);
-  --card-foreground: oklch(0.35 0.03 230);
-  --popover: oklch(0.96 0.008 85);
-  --popover-foreground: oklch(0.35 0.03 230);
-  --primary: oklch(0.55 0.12 200);
-  --primary-foreground: oklch(0.96 0.008 85);
-  --secondary: oklch(0.92 0.015 85);
-  --secondary-foreground: oklch(0.4 0.03 230);
-  --muted: oklch(0.92 0.015 85);
-  --muted-foreground: oklch(0.55 0.02 230);
-  --accent: oklch(0.9 0.018 85);
-  --accent-foreground: oklch(0.4 0.03 230);
-  --destructive: oklch(0.57 0.2 20);
-  --border: oklch(0.87 0.02 85);
-  --input: oklch(0.87 0.02 85);
-  --ring: oklch(0.55 0.12 200);
-  --chart-1: oklch(0.55 0.12 200);
-  --chart-2: oklch(0.65 0.14 160);
-  --chart-3: oklch(0.78 0.15 85);
-  --chart-4: oklch(0.6 0.18 20);
-  --chart-5: oklch(0.55 0.16 280);
-  --sidebar: oklch(0.93 0.012 85);
-  --sidebar-foreground: oklch(0.35 0.03 230);
-  --sidebar-primary: oklch(0.55 0.12 200);
-  --sidebar-primary-foreground: oklch(0.96 0.008 85);
-  --sidebar-accent: oklch(0.9 0.018 85);
-  --sidebar-accent-foreground: oklch(0.4 0.03 230);
-  --sidebar-border: oklch(0.87 0.02 85);
-  --sidebar-ring: oklch(0.55 0.12 200);
-}
-
-[data-theme="solarized"].dark {
-  --background: oklch(0.18 0.02 230);
-  --foreground: oklch(0.82 0.02 85);
-  --card: oklch(0.22 0.025 230);
-  --card-foreground: oklch(0.82 0.02 85);
-  --popover: oklch(0.22 0.025 230);
-  --popover-foreground: oklch(0.82 0.02 85);
-  --primary: oklch(0.65 0.12 200);
-  --primary-foreground: oklch(0.16 0.02 230);
-  --secondary: oklch(0.26 0.025 230);
-  --secondary-foreground: oklch(0.82 0.02 85);
-  --muted: oklch(0.26 0.025 230);
-  --muted-foreground: oklch(0.6 0.02 85);
-  --accent: oklch(0.28 0.028 230);
-  --accent-foreground: oklch(0.82 0.02 85);
-  --destructive: oklch(0.62 0.2 20);
-  --border: oklch(0.32 0.025 230);
-  --input: oklch(0.32 0.025 230);
-  --ring: oklch(0.65 0.12 200);
-  --chart-1: oklch(0.65 0.12 200);
-  --chart-2: oklch(0.68 0.14 160);
-  --chart-3: oklch(0.8 0.15 85);
-  --chart-4: oklch(0.65 0.18 20);
-  --chart-5: oklch(0.6 0.16 280);
-  --sidebar: oklch(0.16 0.02 230);
-  --sidebar-foreground: oklch(0.82 0.02 85);
-  --sidebar-primary: oklch(0.65 0.12 200);
-  --sidebar-primary-foreground: oklch(0.96 0.008 85);
-  --sidebar-accent: oklch(0.26 0.025 230);
-  --sidebar-accent-foreground: oklch(0.82 0.02 85);
-  --sidebar-border: oklch(0.32 0.025 230);
-  --sidebar-ring: oklch(0.65 0.12 200);
-}
diff --git a/apps/web/src/themes/tokyo-night.css b/apps/web/src/themes/tokyo-night.css
deleted file mode 100644
index 05c9d0c9..00000000
--- a/apps/web/src/themes/tokyo-night.css
+++ /dev/null
@@ -1,67 +0,0 @@
-[data-theme="tokyo-night"] {
-  --background: oklch(0.97 0.008 270);
-  --foreground: oklch(0.25 0.03 270);
-  --card: oklch(0.98 0.006 270);
-  --card-foreground: oklch(0.25 0.03 270);
-  --popover: oklch(0.98 0.006 270);
-  --popover-foreground: oklch(0.25 0.03 270);
-  --primary: oklch(0.55 0.18 270);
-  --primary-foreground: oklch(0.98 0.005 270);
-  --secondary: oklch(0.94 0.012 270);
-  --secondary-foreground: oklch(0.3 0.04 270);
-  --muted: oklch(0.94 0.012 270);
-  --muted-foreground: oklch(0.55 0.02 270);
-  --accent: oklch(0.93 0.015 270);
-  --accent-foreground: oklch(0.3 0.04 270);
-  --destructive: oklch(0.577 0.245 27.325);
-  --border: oklch(0.9 0.015 270);
-  --input: oklch(0.9 0.015 270);
-  --ring: oklch(0.55 0.18 270);
-  --chart-1: oklch(0.6 0.18 270);
-  --chart-2: oklch(0.7 0.15 190);
-  --chart-3: oklch(0.75 0.12 80);
-  --chart-4: oklch(0.65 0.18 320);
-  --chart-5: oklch(0.7 0.14 140);
-  --sidebar: oklch(0.96 0.01 270);
-  --sidebar-foreground: oklch(0.25 0.03 270);
-  --sidebar-primary: oklch(0.55 0.18 270);
-  --sidebar-primary-foreground: oklch(0.98 0.005 270);
-  --sidebar-accent: oklch(0.93 0.015 270);
-  --sidebar-accent-foreground: oklch(0.3 0.04 270);
-  --sidebar-border: oklch(0.9 0.015 270);
-  --sidebar-ring: oklch(0.55 0.18 270);
-}
-
-[data-theme="tokyo-night"].dark {
-  --background: oklch(0.18 0.025 260);
-  --foreground: oklch(0.85 0.02 250);
-  --card: oklch(0.22 0.03 260);
-  --card-foreground: oklch(0.85 0.02 250);
-  --popover: oklch(0.22 0.03 260);
-  --popover-foreground: oklch(0.85 0.02 250);
-  --primary: oklch(0.7 0.17 270);
-  --primary-foreground: oklch(0.15 0.02 260);
-  --secondary: oklch(0.28 0.035 260);
-  --secondary-foreground: oklch(0.85 0.02 250);
-  --muted: oklch(0.28 0.035 260);
-  --muted-foreground: oklch(0.6 0.03 250);
-  --accent: oklch(0.3 0.04 260);
-  --accent-foreground: oklch(0.85 0.02 250);
-  --destructive: oklch(0.65 0.2 15);
-  --border: oklch(0.32 0.04 260);
-  --input: oklch(0.32 0.04 260);
-  --ring: oklch(0.7 0.17 270);
-  --chart-1: oklch(0.7 0.17 270);
-  --chart-2: oklch(0.75 0.14 190);
-  --chart-3: oklch(0.8 0.15 80);
-  --chart-4: oklch(0.7 0.18 320);
-  --chart-5: oklch(0.72 0.14 140);
-  --sidebar: oklch(0.16 0.025 260);
-  --sidebar-foreground: oklch(0.85 0.02 250);
-  --sidebar-primary: oklch(0.7 0.17 270);
-  --sidebar-primary-foreground: oklch(0.98 0.005 270);
-  --sidebar-accent: oklch(0.28 0.035 260);
-  --sidebar-accent-foreground: oklch(0.85 0.02 250);
-  --sidebar-border: oklch(0.32 0.04 260);
-  --sidebar-ring: oklch(0.7 0.17 270);
-}

From 3958e80cf975eb0f10c25a3442fe5c2e2fba4053 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 22:05:27 +0800
Subject: [PATCH 37/64] feat(server): widget module .zip collection install

Sniff the magic bytes on POST /api/widget-modules and dispatch single
.js uploads to install_single_file as before, while .zip uploads now go
through a new install_collection_from_zip path. A zip bundle must contain
a top-level collection.json listing one or more entries, each pointing to
a .js or .mjs file with a valid @serverbee-widget JSDoc manifest. Widget
ids must be unique within the bundle. All widgets in a collection share
the same blob; each becomes its own row with entry_path set to the path
inside the zip.

serve_asset now mirrors the Builtin resolution behavior for zip blobs:
the requested asset path is resolved relative to the entry's folder so
that requests like /api/widget-modules/<id>/index.js find weather/index.js
inside the bundle. The single-file path is unchanged.

The endpoint response shape is documented in the utoipa annotation:
single-file installs return { id, version } and zip collections return
an array of { id, version }.

Adds five integration tests covering the happy path, missing
collection.json, duplicate ids, zip-slip in collection.json entries, and
entries missing a JSDoc manifest.
---
 crates/server/src/openapi.rs                  |   2 +-
 crates/server/src/router/api/widget_module.rs |  30 +-
 .../src/service/widget_module/service.rs      | 190 +++++++++++-
 .../server/tests/widget_module_integration.rs | 274 ++++++++++++++++++
 4 files changed, 482 insertions(+), 14 deletions(-)

diff --git a/crates/server/src/openapi.rs b/crates/server/src/openapi.rs
index d89743dd..c147bcd0 100644
--- a/crates/server/src/openapi.rs
+++ b/crates/server/src/openapi.rs
@@ -155,7 +155,7 @@ impl Modify for SecurityAddon {
         // widget-modules
         crate::router::api::widget_module::list_modules,
         crate::router::api::widget_module::serve_asset,
-        crate::router::api::widget_module::install_module,
+        crate::router::api::widget_module::install_widget_module,
         crate::router::api::widget_module::uninstall_module,
         // service-monitors
         crate::router::api::service_monitor::list_monitors,
diff --git a/crates/server/src/router/api/widget_module.rs b/crates/server/src/router/api/widget_module.rs
index 44e829ea..57d19917 100644
--- a/crates/server/src/router/api/widget_module.rs
+++ b/crates/server/src/router/api/widget_module.rs
@@ -27,7 +27,7 @@ pub fn read_router() -> Router<Arc<AppState>> {
 
 pub fn write_router() -> Router<Arc<AppState>> {
     Router::new()
-        .route("/widget-modules", post(install_module))
+        .route("/widget-modules", post(install_widget_module))
         .route("/widget-modules/{id}", delete(uninstall_module))
 }
 
@@ -117,19 +117,22 @@ fn is_private_host(host: &str) -> bool {
     path = "/api/widget-modules",
     tag = "widget-modules",
     params(
-        ("url" = Option<String>, Query, description = "HTTPS URL to fetch the single-file widget JS from"),
+        ("url" = Option<String>, Query, description = "HTTPS URL to fetch the widget bundle from. Accepts either a single `.js` file or a `.zip` collection bundle."),
     ),
     request_body(
         content_type = "multipart/form-data",
-        description = "Alternatively, upload the widget JS in a `file` field",
+        description = "Alternatively, upload the widget bundle in a `file` field. Accepts either a single `.js` file or a `.zip` collection bundle.",
     ),
     responses(
-        (status = 200, description = "Installed (or upgraded) widget module"),
+        (
+            status = 200,
+            description = "Installed (or upgraded) widget module(s). For a single `.js` file the response is `{ data: { id, version } }`. For a `.zip` collection it is `{ data: [{ id, version }, ...] }` — one entry per widget in the collection.",
+        ),
         (status = 400, description = "Bad URL, unsupported source, or invalid manifest"),
     ),
     security(("session_cookie" = []), ("api_key" = []))
 )]
-pub async fn install_module(
+pub async fn install_widget_module(
     State(state): State<Arc<AppState>>,
     Extension(user): Extension<CurrentUser>,
     Query(q): Query<InstallQuery>,
@@ -204,8 +207,21 @@ pub async fn install_module(
         ));
     };
 
-    let row = WidgetModuleService::install_single_file(&state.db, bytes, from, user_id).await?;
-    ok(serde_json::json!({ "id": row.id, "version": row.version }))
+    if bytes.starts_with(b"PK\x03\x04") {
+        let rows = WidgetModuleService::install_collection_from_zip(
+            &state.db, bytes, from, user_id,
+        )
+        .await?;
+        let payload: Vec<serde_json::Value> = rows
+            .into_iter()
+            .map(|r| serde_json::json!({ "id": r.id, "version": r.version }))
+            .collect();
+        ok(serde_json::Value::Array(payload))
+    } else {
+        let row =
+            WidgetModuleService::install_single_file(&state.db, bytes, from, user_id).await?;
+        ok(serde_json::json!({ "id": row.id, "version": row.version }))
+    }
 }
 
 #[utoipa::path(
diff --git a/crates/server/src/service/widget_module/service.rs b/crates/server/src/service/widget_module/service.rs
index cf7d9c42..95560d42 100644
--- a/crates/server/src/service/widget_module/service.rs
+++ b/crates/server/src/service/widget_module/service.rs
@@ -73,6 +73,10 @@ impl WidgetModuleService {
     ) -> Result<(Vec<u8>, String), WidgetModuleError> {
         let row = Self::get(db, id).await?;
 
+        if requested.contains("..") {
+            return Err(WidgetModuleError::InvalidAssetPath);
+        }
+
         if matches!(
             row.source_type,
             crate::entity::widget_module::SourceType::Builtin
@@ -90,9 +94,6 @@ impl WidgetModuleService {
             } else {
                 format!("{folder}/{requested}")
             };
-            if full.contains("..") {
-                return Err(WidgetModuleError::InvalidAssetPath);
-            }
             let bytes = crate::service::widget_module::builtin::builtin_asset_bytes(&full)
                 .ok_or(WidgetModuleError::InvalidAssetPath)?;
             return Ok((bytes, mime_for(&full)));
@@ -102,17 +103,36 @@ impl WidgetModuleService {
             .package_blob
             .ok_or_else(|| WidgetModuleError::NotFound(format!("{id}: no blob")))?;
 
-        let package = if blob.starts_with(b"PK\x03\x04") {
+        let is_zip = blob.starts_with(b"PK\x03\x04");
+        let package = if is_zip {
             UnpackedPackage::from_zip(&blob)?
         } else {
             UnpackedPackage::from_single_file(&row.entry_path, blob)
         };
 
+        // For zip collections, asset requests are resolved relative to the
+        // entry's folder inside the zip (mirrors Builtin behavior). For single
+        // files there is no folder so we look up the requested path verbatim.
+        let lookup_path = if is_zip {
+            let folder = row
+                .entry_path
+                .rsplit_once('/')
+                .map(|(d, _)| d)
+                .unwrap_or("");
+            if folder.is_empty() {
+                requested.to_string()
+            } else {
+                format!("{folder}/{requested}")
+            }
+        } else {
+            requested.to_string()
+        };
+
         let bytes = package
-            .get(requested)
+            .get(&lookup_path)
             .ok_or(WidgetModuleError::InvalidAssetPath)?
             .to_vec();
-        let mime = mime_for(requested);
+        let mime = mime_for(&lookup_path);
         Ok((bytes, mime))
     }
 
@@ -189,6 +209,164 @@ impl WidgetModuleService {
         Self::get(db, &id_clone).await
     }
 
+    /// Install (or upgrade) a collection of widget modules packaged as a zip
+    /// bundle. The zip must contain a top-level `collection.json` listing one
+    /// or more entries; each entry must point to a `.js` (or `.mjs`) file with
+    /// an `@serverbee-widget` JSDoc manifest. All widgets in the collection
+    /// share the same blob storage.
+    pub async fn install_collection_from_zip(
+        db: &DatabaseConnection,
+        blob: Vec<u8>,
+        from: InstalledFrom,
+        installed_by: Option<i64>,
+    ) -> Result<Vec<crate::entity::widget_module::Model>, WidgetModuleError> {
+        use std::collections::HashSet;
+
+        use chrono::Utc;
+        use sea_orm::sea_query::OnConflict;
+        use sea_orm::{ActiveValue::Set, EntityTrait};
+        use sha2::{Digest, Sha256};
+
+        use crate::entity::widget_module::{self, SourceType};
+
+        let package = UnpackedPackage::from_zip(&blob)?;
+
+        let manifest_bytes = package.get("collection.json").ok_or_else(|| {
+            WidgetModuleError::ManifestExtraction("missing collection.json".into())
+        })?;
+        let manifest_str = std::str::from_utf8(manifest_bytes).map_err(|e| {
+            WidgetModuleError::ManifestExtraction(format!("collection.json not utf-8: {e}"))
+        })?;
+
+        #[derive(serde::Deserialize)]
+        struct CollectionEntry {
+            entry: String,
+        }
+        #[derive(serde::Deserialize)]
+        struct CollectionManifest {
+            widgets: Vec<CollectionEntry>,
+        }
+
+        let collection: CollectionManifest = serde_json::from_str(manifest_str)
+            .map_err(|e| {
+                WidgetModuleError::ManifestExtraction(format!("collection.json invalid: {e}"))
+            })?;
+
+        if collection.widgets.is_empty() {
+            return Err(WidgetModuleError::ManifestValidation(
+                "collection.json: widgets array must not be empty".into(),
+            ));
+        }
+
+        // Validate every entry up front before touching the database.
+        let mut prepared: Vec<(
+            super::extractor::WidgetManifest,
+            String, // entry path inside the zip
+            String, // sha256 of this entry's bytes
+        )> = Vec::with_capacity(collection.widgets.len());
+        let mut seen_ids: HashSet<String> = HashSet::new();
+
+        for entry in collection.widgets.iter() {
+            let entry_path = entry.entry.trim_start_matches('/').to_string();
+            if entry_path.is_empty()
+                || entry_path.contains("..")
+                || entry_path.starts_with('/')
+            {
+                return Err(WidgetModuleError::ManifestValidation(format!(
+                    "invalid entry path: {entry_path}"
+                )));
+            }
+            let lower = entry_path.to_ascii_lowercase();
+            if !(lower.ends_with(".js") || lower.ends_with(".mjs")) {
+                return Err(WidgetModuleError::ManifestValidation(format!(
+                    "entry must be .js or .mjs: {entry_path}"
+                )));
+            }
+
+            let bytes = package.get(&entry_path).ok_or_else(|| {
+                WidgetModuleError::ManifestExtraction(format!(
+                    "entry not found in zip: {entry_path}"
+                ))
+            })?;
+            let source = std::str::from_utf8(bytes).map_err(|e| {
+                WidgetModuleError::ManifestExtraction(format!(
+                    "entry {entry_path} not utf-8: {e}"
+                ))
+            })?;
+            let manifest = super::extractor::extract_manifest(source)?;
+
+            if !seen_ids.insert(manifest.id.clone()) {
+                return Err(WidgetModuleError::ManifestValidation(format!(
+                    "duplicate widget id in collection: {}",
+                    manifest.id
+                )));
+            }
+
+            let sha = {
+                let mut h = Sha256::new();
+                h.update(bytes);
+                format!("{:x}", h.finalize())
+            };
+
+            prepared.push((manifest, entry_path, sha));
+        }
+
+        let (source_type, source_url) = match from {
+            InstalledFrom::Url(u) => (SourceType::Url, Some(u)),
+            InstalledFrom::Upload(name) => (SourceType::Upload, Some(name)),
+        };
+
+        let now = Utc::now();
+        let mut installed: Vec<widget_module::Model> = Vec::with_capacity(prepared.len());
+
+        for (manifest, entry_path, sha) in prepared.into_iter() {
+            let manifest_json = serde_json::to_string(&manifest).map_err(|e| {
+                WidgetModuleError::ManifestValidation(format!("serialize manifest: {e}"))
+            })?;
+            let id_clone = manifest.id.clone();
+            let version_clone = manifest.version.clone();
+
+            let active = widget_module::ActiveModel {
+                id: Set(manifest.id),
+                version: Set(version_clone),
+                source_type: Set(source_type.clone()),
+                source_url: Set(source_url.clone()),
+                bundled_by_theme_id: Set(None),
+                manifest_json: Set(manifest_json),
+                code_sha256: Set(sha),
+                entry_path: Set(entry_path),
+                package_blob: Set(Some(blob.clone())),
+                installed_by: Set(installed_by),
+                installed_at: Set(now),
+                enabled: Set(true),
+            };
+
+            widget_module::Entity::insert(active)
+                .on_conflict(
+                    OnConflict::column(widget_module::Column::Id)
+                        .update_columns([
+                            widget_module::Column::Version,
+                            widget_module::Column::SourceType,
+                            widget_module::Column::SourceUrl,
+                            widget_module::Column::ManifestJson,
+                            widget_module::Column::CodeSha256,
+                            widget_module::Column::EntryPath,
+                            widget_module::Column::PackageBlob,
+                            widget_module::Column::InstalledBy,
+                            widget_module::Column::InstalledAt,
+                            widget_module::Column::Enabled,
+                        ])
+                        .to_owned(),
+                )
+                .exec(db)
+                .await?;
+
+            installed.push(Self::get(db, &id_clone).await?);
+        }
+
+        Ok(installed)
+    }
+
     /// Delete a widget module row. Refuses to delete Builtin rows.
     pub async fn uninstall(db: &DatabaseConnection, id: &str) -> Result<(), WidgetModuleError> {
         let row = Self::get(db, id).await?;
diff --git a/crates/server/tests/widget_module_integration.rs b/crates/server/tests/widget_module_integration.rs
index 7b1eb83a..137b548c 100644
--- a/crates/server/tests/widget_module_integration.rs
+++ b/crates/server/tests/widget_module_integration.rs
@@ -1,3 +1,4 @@
+use std::io::Write;
 use std::time::Duration;
 
 use chrono::Utc;
@@ -478,3 +479,276 @@ async fn serve_builtin_asset_returns_js_bytes() {
         &body[..body.len().min(200)]
     );
 }
+
+// ---------- zip collection install tests ----------
+
+/// Build a single-file widget JS source with the given id baked into the
+/// JSDoc manifest and the body so we can confirm it round-trips.
+fn build_widget_js(id: &str) -> String {
+    format!(
+        r#"/**
+ * @serverbee-widget {{
+ *   "id": "{id}",
+ *   "version": "1.0.0",
+ *   "name": "Test {id}",
+ *   "category": "Real-time",
+ *   "sizing": {{ "defaultW": 3, "defaultH": 3, "minW": 2, "minH": 2, "strategy": "aspect-square" }},
+ *   "sdkVersion": "^0.1.0"
+ * }}
+ */
+export default {{ id: "{id}" }};
+"#
+    )
+}
+
+/// Build an in-memory zip collection bundle from a list of `(folder, id)`
+/// pairs. Each pair becomes a file at `{folder}/index.js`, and a top-level
+/// `collection.json` is added listing every entry.
+fn build_collection_zip(widgets: &[(&str, &str)]) -> Vec<u8> {
+    use zip::write::SimpleFileOptions;
+
+    let mut buf: Vec<u8> = Vec::new();
+    {
+        let cursor = std::io::Cursor::new(&mut buf);
+        let mut zw = zip::ZipWriter::new(cursor);
+        let opts =
+            SimpleFileOptions::default().compression_method(zip::CompressionMethod::Deflated);
+
+        let entries: Vec<serde_json::Value> = widgets
+            .iter()
+            .map(|(folder, _)| json!({ "entry": format!("{folder}/index.js") }))
+            .collect();
+        let manifest = json!({ "widgets": entries });
+        zw.start_file("collection.json", opts).unwrap();
+        zw.write_all(serde_json::to_string_pretty(&manifest).unwrap().as_bytes())
+            .unwrap();
+
+        for (folder, id) in widgets {
+            zw.start_file(format!("{folder}/index.js"), opts).unwrap();
+            zw.write_all(build_widget_js(id).as_bytes()).unwrap();
+        }
+
+        zw.finish().unwrap();
+    }
+    buf
+}
+
+#[tokio::test]
+async fn install_collection_zip_returns_array_of_widgets() {
+    let ctx = start_test_server_with_db().await;
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    let zip = build_collection_zip(&[
+        ("weather", "com.test.weather"),
+        ("clock", "com.test.clock"),
+    ]);
+
+    let form = reqwest::multipart::Form::new().part(
+        "file",
+        reqwest::multipart::Part::bytes(zip).file_name("pack.zip"),
+    );
+
+    let res = client
+        .post(format!("{}/api/widget-modules", ctx.base_url))
+        .multipart(form)
+        .send()
+        .await
+        .expect("install zip request failed");
+    assert_eq!(res.status(), 200, "zip install should return 200");
+    let body: serde_json::Value = res.json().await.expect("invalid JSON");
+    let arr = body["data"].as_array().expect("data should be array");
+    assert_eq!(arr.len(), 2);
+    let ids: Vec<String> = arr
+        .iter()
+        .map(|v| v["id"].as_str().unwrap().to_string())
+        .collect();
+    assert!(ids.contains(&"com.test.weather".to_string()));
+    assert!(ids.contains(&"com.test.clock".to_string()));
+
+    // Each widget served at its own /{id}/index.js, resolving inside its zip folder.
+    for id in ["com.test.weather", "com.test.clock"] {
+        let res = client
+            .get(format!("{}/api/widget-modules/{id}/index.js", ctx.base_url))
+            .send()
+            .await
+            .expect("asset get failed");
+        assert_eq!(res.status(), 200, "asset {id} should be 200");
+        let body = res.text().await.expect("body text");
+        assert!(
+            body.contains(id),
+            "expected body for {id} to contain its id, got: {}",
+            &body[..body.len().min(160)]
+        );
+    }
+
+    // List endpoint exposes both.
+    let res = client
+        .get(format!("{}/api/widget-modules", ctx.base_url))
+        .send()
+        .await
+        .expect("list request failed");
+    let listed: serde_json::Value = res.json().await.expect("invalid JSON");
+    let listed_ids: Vec<String> = listed["data"]
+        .as_array()
+        .expect("array")
+        .iter()
+        .map(|m| m["id"].as_str().unwrap().to_string())
+        .collect();
+    assert!(listed_ids.contains(&"com.test.weather".to_string()));
+    assert!(listed_ids.contains(&"com.test.clock".to_string()));
+
+    // Deleting one leaves the other intact.
+    let del = client
+        .delete(format!(
+            "{}/api/widget-modules/com.test.weather",
+            ctx.base_url
+        ))
+        .send()
+        .await
+        .expect("delete failed");
+    assert_eq!(del.status(), 204);
+
+    let res = client
+        .get(format!(
+            "{}/api/widget-modules/com.test.clock/index.js",
+            ctx.base_url
+        ))
+        .send()
+        .await
+        .expect("asset get failed");
+    assert_eq!(
+        res.status(),
+        200,
+        "remaining widget should still be served after sibling is removed"
+    );
+}
+
+#[tokio::test]
+async fn install_zip_missing_collection_json_is_400() {
+    let ctx = start_test_server_with_db().await;
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    // Build a zip with just a widget file but no collection.json.
+    let mut buf: Vec<u8> = Vec::new();
+    {
+        let cursor = std::io::Cursor::new(&mut buf);
+        let mut zw = zip::ZipWriter::new(cursor);
+        let opts = zip::write::SimpleFileOptions::default()
+            .compression_method(zip::CompressionMethod::Deflated);
+        zw.start_file("weather/index.js", opts).unwrap();
+        zw.write_all(build_widget_js("com.test.weather").as_bytes())
+            .unwrap();
+        zw.finish().unwrap();
+    }
+
+    let form = reqwest::multipart::Form::new().part(
+        "file",
+        reqwest::multipart::Part::bytes(buf).file_name("bad.zip"),
+    );
+    let res = client
+        .post(format!("{}/api/widget-modules", ctx.base_url))
+        .multipart(form)
+        .send()
+        .await
+        .expect("install request failed");
+    assert_eq!(res.status(), 400);
+}
+
+#[tokio::test]
+async fn install_zip_duplicate_ids_is_400() {
+    let ctx = start_test_server_with_db().await;
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    // Two folders point to widgets that declare the same id.
+    let zip = build_collection_zip(&[
+        ("a", "com.test.dup"),
+        ("b", "com.test.dup"),
+    ]);
+
+    let form = reqwest::multipart::Form::new().part(
+        "file",
+        reqwest::multipart::Part::bytes(zip).file_name("dup.zip"),
+    );
+    let res = client
+        .post(format!("{}/api/widget-modules", ctx.base_url))
+        .multipart(form)
+        .send()
+        .await
+        .expect("install request failed");
+    assert_eq!(res.status(), 400);
+}
+
+#[tokio::test]
+async fn install_zip_entry_with_dotdot_is_400() {
+    let ctx = start_test_server_with_db().await;
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    // Manually craft a zip whose collection.json points outside the bundle.
+    let mut buf: Vec<u8> = Vec::new();
+    {
+        let cursor = std::io::Cursor::new(&mut buf);
+        let mut zw = zip::ZipWriter::new(cursor);
+        let opts = zip::write::SimpleFileOptions::default()
+            .compression_method(zip::CompressionMethod::Deflated);
+
+        let manifest = json!({ "widgets": [{ "entry": "../escape.js" }] });
+        zw.start_file("collection.json", opts).unwrap();
+        zw.write_all(manifest.to_string().as_bytes()).unwrap();
+
+        // A regular widget at a sibling location too so the zip itself is valid.
+        zw.start_file("weather/index.js", opts).unwrap();
+        zw.write_all(build_widget_js("com.test.weather").as_bytes())
+            .unwrap();
+        zw.finish().unwrap();
+    }
+
+    let form = reqwest::multipart::Form::new().part(
+        "file",
+        reqwest::multipart::Part::bytes(buf).file_name("evil.zip"),
+    );
+    let res = client
+        .post(format!("{}/api/widget-modules", ctx.base_url))
+        .multipart(form)
+        .send()
+        .await
+        .expect("install request failed");
+    assert_eq!(res.status(), 400);
+}
+
+#[tokio::test]
+async fn install_zip_entry_missing_jsdoc_is_400() {
+    let ctx = start_test_server_with_db().await;
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    let mut buf: Vec<u8> = Vec::new();
+    {
+        let cursor = std::io::Cursor::new(&mut buf);
+        let mut zw = zip::ZipWriter::new(cursor);
+        let opts = zip::write::SimpleFileOptions::default()
+            .compression_method(zip::CompressionMethod::Deflated);
+        let manifest = json!({ "widgets": [{ "entry": "weather/index.js" }] });
+        zw.start_file("collection.json", opts).unwrap();
+        zw.write_all(manifest.to_string().as_bytes()).unwrap();
+        // Body has no @serverbee-widget block.
+        zw.start_file("weather/index.js", opts).unwrap();
+        zw.write_all(b"export default {};").unwrap();
+        zw.finish().unwrap();
+    }
+
+    let form = reqwest::multipart::Form::new().part(
+        "file",
+        reqwest::multipart::Part::bytes(buf).file_name("missing.zip"),
+    );
+    let res = client
+        .post(format!("{}/api/widget-modules", ctx.base_url))
+        .multipart(form)
+        .send()
+        .await
+        .expect("install request failed");
+    assert_eq!(res.status(), 400);
+}

From 9f66a18a02e5294d9f7a53e86f90f1ec3f743316 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 22:17:59 +0800
Subject: [PATCH 38/64] docs: bilingual custom widget guide (replaces theme
 docs)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Delete the legacy custom-themes and custom-frontend pages in both
languages — the underlying theme/spa-override system was removed in
recent commits. Replace both with a single custom-widgets page (cn + en)
that documents the new widget module system end to end:

- concept overview and trust model (admin-only, same-origin)
- method B: single .widget.js file (JSDoc manifest, defineWidget, build
  config that preserves the manifest comment, UI + API install flows)
- method C: .zip collection bundle with a collection.json schema, folder
  layout, per-entry asset resolution rules, build/pack walkthrough, and
  the array response shape
- sizing strategies, SDK surface, uninstall, size/SSRF/zip-slip limits

Update meta.json in both languages to drop the two removed entries and
insert custom-widgets under the Features section. Repoint the two
remaining cross-references (status-page footer card, index card) at the
new page.
---
 apps/docs/content/docs/cn/custom-frontend.mdx | 222 --------------
 apps/docs/content/docs/cn/custom-themes.mdx   | 101 ------
 apps/docs/content/docs/cn/custom-widgets.mdx  | 289 ++++++++++++++++++
 apps/docs/content/docs/cn/index.mdx           |   2 +-
 apps/docs/content/docs/cn/meta.json           |   3 +-
 apps/docs/content/docs/cn/status-page.mdx     |   2 +-
 apps/docs/content/docs/en/custom-frontend.mdx | 222 --------------
 apps/docs/content/docs/en/custom-themes.mdx   | 101 ------
 apps/docs/content/docs/en/custom-widgets.mdx  | 289 ++++++++++++++++++
 apps/docs/content/docs/en/index.mdx           |   2 +-
 apps/docs/content/docs/en/meta.json           |   3 +-
 apps/docs/content/docs/en/status-page.mdx     |   2 +-
 12 files changed, 584 insertions(+), 654 deletions(-)
 delete mode 100644 apps/docs/content/docs/cn/custom-frontend.mdx
 delete mode 100644 apps/docs/content/docs/cn/custom-themes.mdx
 create mode 100644 apps/docs/content/docs/cn/custom-widgets.mdx
 delete mode 100644 apps/docs/content/docs/en/custom-frontend.mdx
 delete mode 100644 apps/docs/content/docs/en/custom-themes.mdx
 create mode 100644 apps/docs/content/docs/en/custom-widgets.mdx

diff --git a/apps/docs/content/docs/cn/custom-frontend.mdx b/apps/docs/content/docs/cn/custom-frontend.mdx
deleted file mode 100644
index d7485a39..00000000
--- a/apps/docs/content/docs/cn/custom-frontend.mdx
+++ /dev/null
@@ -1,222 +0,0 @@
----
-title: 自定义前端主题
-description: 将整个 ServerBee 仪表盘替换为你上传的自定义 React/Vue/Svelte SPA（.sbtheme 包）。
----
-
-ServerBee 允许管理员将内置仪表盘替换为任意上传的 `.sbtheme` 包。自定义前端与服务端同源运行，使用相同的 REST 和 WebSocket API，可以是一个精简的只读视图、深度品牌定制的白标产品，或者完全自定义的监控界面。
-
-这是一次完整的 SPA 替换，而非插件或颜色主题叠加。当自定义前端激活后，它接管所有路由（登录页、仪表盘、设置等）。现有的[自定义主题](/cn/docs/custom-themes)颜色变量系统和品牌设置在自定义前端激活期间不起作用，界面会显示相应提示。
-
-## 可以和不可以自定义的内容
-
-| 可以做的 | 不可以做的 |
-|----------|-----------|
-| 替换完整的 HTML/CSS/JS 前端 | 添加服务端代码、数据库迁移或 Rust crate |
-| 实现自己的路由、登录页和品牌 | 访问 `/api/*`、`/swagger-ui/*` 或 `/__system/*` 下的路由——这些始终由服务端处理 |
-| 调用所有现有的 REST 或 WebSocket API | 加载外部脚本、样式表、字体，或发起跨域 fetch/XHR/WebSocket 请求（CSP 限制） |
-| 使用任意 JS 框架（React、Vue、Svelte、原生 JS） | 在其他来源的 iframe 中嵌入前端（CSP `frame-ancestors: none`） |
-| 使用自己的颜色、字体、图标和资源 | 超过 20 MB 的未压缩内容或超过 1000 个文件 |
-| 通过现有认证 API 读取当前用户会话 | 按用户设置主题——全系统只有一个激活主题 |
-
-**信任模型：** 管理员安装的主题与服务端同源运行，具有与当前登录用户相同的数据访问权限——等同于管理员直接替换磁盘上的内置 SPA。CSP 是纵深防御（可阻止被动资源加载等机会性泄露途径），但**不是**隔离边界。请只安装你信任的主题。
-
-## 快速上手
-
-**前置条件：** 已安装 [bun](https://bun.sh) 并有一个正在运行的 ServerBee 服务端。
-
-### 1. 脚手架初始化
-
-```bash
-npx degit ZingerLittleBee/ServerBee/templates/serverbee-theme-starter my-theme
-cd my-theme
-bun install
-```
-
-Starter 包含一个极简的 Vite + TypeScript SPA，内置预接好的 API 客户端（`src/lib/serverbee.ts`），使用同源 Session 认证。
-
-### 2. 编辑与构建
-
-修改 `src/App.tsx` 及其他源文件，运行 `bun run dev` 在本地针对任意运行中的 ServerBee 服务端进行迭代开发（在 `vite.config.ts` 中配置 dev proxy）。
-
-### 3. 打包
-
-```bash
-bun run pack
-```
-
-该命令会执行 Vite 生产构建，按照服务端相同的约束（文件大小、扩展名、manifest）验证输出，并在项目根目录生成一个确定性的 `.sbtheme` zip 文件（如 `my-theme-1.0.0.sbtheme`）。
-
-### 4. 上传
-
-在 ServerBee 中打开 **设置 → 外观**。管理员用户可以在顶部看到**自定义前端**区域。将 `.sbtheme` 文件拖到上传卡片，或点击选择文件。
-
-上传后，点击 **预览** 在新标签页中打开主题，不会影响全局激活状态。确认后，点击 **激活**。
-
-<Callout type="warn">
-激活操作立即全局生效。每个重新加载根路径的用户都会看到新主题。激活前请使用**预览**进行验证。如果出现问题，可访问 `?theme=default` 进行恢复（参见[恢复与调试](#恢复与调试)）。
-</Callout>
-
-## Manifest 参考
-
-每个 `.sbtheme` 包的 zip 根目录下必须包含 `manifest.json`：
-
-```json
-{
-  "schema_version": 1,
-  "id": "acme-dashboard",
-  "name": "Acme Corp Dashboard",
-  "version": "1.2.0",
-  "author": "Acme Inc",
-  "homepage": "https://acme.example.com",
-  "description": "Branded dashboard for Acme.",
-  "entry": "index.html",
-  "preview": "preview.png"
-}
-```
-
-| 字段 | 必填 | 约束 |
-|------|------|------|
-| `schema_version` | 是 | 整数；当前只接受 `1` |
-| `id` | 是 | 匹配 `^[a-z][a-z0-9-]{2,63}$` |
-| `name` | 是 | 1–64 字符；HTML 标签会被过滤 |
-| `version` | 是 | 合法的 semver（如 `1.2.0`） |
-| `author` | 否 | ≤ 64 字符；HTML 标签会被过滤 |
-| `homepage` | 否 | 合法的 `http(s)://` URL |
-| `description` | 否 | ≤ 500 字符；HTML 标签会被过滤 |
-| `entry` | 否 | 默认为 `index.html`；路径必须存在于包中且以 `.html` 结尾 |
-| `min_serverbee_version` | 否 | semver；上传时若运行中的服务端版本低于此值，上传将被拒绝 |
-| `preview` | 否 | 预览图的相对路径；必须存在；≤ 500 KB；仅支持 `png`、`jpg`、`webp` |
-
-<Callout type="warn">
-**`min_serverbee_version` 与预发布版本：** semver 规定正式版（如 `1.0.0`）**大于**预发布版（如 `1.0.0-alpha.3`）。如果你的目标部署运行的是预发布构建，设置 `"min_serverbee_version": "1.0.0"` 会导致上传被拒绝。除非你确实依赖某个更新的服务端特性，否则请不要填写此字段。
-</Callout>
-
-`id` 字段作为主题系列标识符。同一 `id` 可以上传多个版本，服务端会保留完整历史，允许激活其中任意一个。上传的版本号低于同 `id` 最新版本时，将以 `NO_DOWNGRADE` 拒绝。
-
-## 大小与文件限制
-
-| 限制项 | 限制值 |
-|--------|--------|
-| multipart 上传硬上限 | 25 MB |
-| 解压后内容总大小 | 20 MB |
-| 单文件大小 | 5 MB |
-| 文件数量 | 1000 |
-| 单文件路径长度 | 255 字符 |
-| 预览图大小 | 500 KB |
-
-**允许的文件扩展名**（大小写不敏感）：`html`、`htm`、`js`、`mjs`、`css`、`png`、`jpg`、`jpeg`、`svg`、`webp`、`gif`、`ico`、`woff`、`woff2`、`ttf`、`otf`、`json`、`txt`、`map`。
-
-服务端还会执行压缩比检查：任意单个 zip 条目的解压大小超过压缩大小 100 倍以上时，将被拒绝（防止 zip 炸弹）。
-
-以下情况会直接拒绝：目录穿越条目（`../`）、绝对路径、Windows 盘符、符号链接 zip 条目和重复条目。
-
-<Callout type="info">
-不要将文档、README 和源码 map 文件放入 `.sbtheme` 包。它们会消耗大小配额，服务端也永远不会提供这些文件。建议将它们放在主题源码仓库中单独分发。
-</Callout>
-
-## API 与 WebSocket 参考
-
-自定义前端调用与内置仪表盘相同的 HTTP REST API 和 WebSocket 端点，不需要单独的"主题 SDK"。
-
-- **完整 REST API 文档：** [`/swagger-ui/`](/swagger-ui/) — 在你的运行实例上实时可用
-- **OpenAPI 文档：** [`/api-docs/openapi.json`](/api-docs/openapi.json)
-- **认证：** Session cookie 由 `POST /api/auth/login` 设置，同源请求自动携带。也支持通过 `X-API-Key` 请求头进行 API Key 认证。
-- **WebSocket（服务器更新）：** 连接到 `GET /api/ws/servers`（浏览器 WebSocket）。服务端推送 `BrowserMessage` JSON 帧，包含 `FullSync`、`Update`、`ServerOnline`、`ServerOffline` 等变体。
-- **终端：** 在 `/api/ws/terminal/:sessionId` 使用 Binary WebSocket 帧，前 16 字节为 Session UUID，其余为原始 PTY 数据。
-
-`/__system/*` 前缀始终由默认 SPA 提供服务，自定义主题无法覆盖。该路径提供恢复 UI 以及 `POST /__system/clear-recovery` / `POST /__system/clear-preview` 端点。
-
-## CSP 约束
-
-服务自定义主题文件的所有响应都包含以下 Content Security Policy：
-
-```
-Content-Security-Policy:
-  default-src 'self';
-  script-src 'self' 'unsafe-inline' 'unsafe-eval';
-  style-src 'self' 'unsafe-inline';
-  img-src 'self' data: blob:;
-  font-src 'self' data:;
-  connect-src 'self';
-  frame-ancestors 'none';
-  base-uri 'self';
-  form-action 'self';
-```
-
-**`connect-src 'self'` 对主题开发者意味着什么：**
-
-- fetch、XHR 和 WebSocket 连接限制为同源。主题可以自由调用 `/api/*`，以及连接同一服务端上的 WebSocket 端点。
-- 外部 URL 的连接（如 `https://api.example.com`、`wss://external.host`）会被浏览器拦截。
-- 如果你的主题集成了向外部发起网络请求的埋点、错误上报 SDK 或 CDN 资源，这些请求将被拦截。
-
-**CSP 不会阻止的内容：**
-
-- 顶层导航泄露（`location.href = 'https://...'`）。理论上可覆盖此场景的 CSP3 `navigate-to` 指令在浏览器中实际上不被支持。
-- 同源 API 访问——主题携带用户会话，可以读取用户有权访问的任何数据。
-
-`unsafe-eval` 为了兼容大多数 React、Vue、Svelte 和 wasm-bindgen 构建而默认开启。
-
-以上头信息仅对自定义主题响应生效，不影响内置默认 SPA。
-
-## 恢复与调试
-
-### 从损坏的主题中恢复
-
-如果自定义主题导致 UI 无法使用，无法导航到管理页面：
-
-1. 在浏览器中访问 `/?theme=default`。服务端会立即返回内置默认 SPA（无论当前激活的主题是什么），并设置一个恢复 cookie（`sb_force_default`），让该来源在一小时内保持在默认 SPA 上。
-2. 此时你已回到默认 SPA。导航到 **设置 → 外观**，停用或删除损坏的主题。
-3. 要手动退出恢复状态并返回自定义主题，点击默认 SPA 上的**退出恢复**按钮，或访问 `/?theme=active`。这会调用 `POST /__system/clear-recovery` 并清除 cookie。
-
-<Callout type="info">
-恢复 cookie 的作用域为整个浏览器（同源），有效期为一小时。在 cookie 过期或恢复被清除之前，同一浏览器中重新加载的任何标签页都会看到默认 SPA。
-</Callout>
-
-### 激活前预览
-
-在系统范围内激活主题前，可以先安全地预览：
-
-1. 上传主题。不会自动激活。
-2. 点击主题卡片上的**预览**。弹窗会说明预览是浏览器范围的。
-3. 确认后，新标签页在 `/?theme=preview:<uuid>` 打开，主题内会出现一个固定横幅，显示剩余时间和**退出预览**按钮。
-4. 查看主题。完成后，点击横幅中的**退出预览**。标签页会返回默认 SPA。
-5. 在管理界面点击**激活**，完成全局切换。
-
-预览使用一个有效期 15 分钟的 cookie（`sb_preview_theme`）。它的作用域是整个浏览器：同一浏览器中重新加载的任何标签页都会看到预览主题。如果你需要在长时间预览期间保持管理界面可用，请使用另一个浏览器或无痕窗口。
-
-### 强制显示激活主题
-
-访问 `/?theme=active` 可同时清除恢复和预览两个 cookie，并返回当前激活的主题（若未激活任何主题，则返回默认 SPA）。
-
-### 调试 CSP 违规
-
-打开浏览器 **DevTools → Console**。CSP 违规会以错误形式显示，包含被拦截的 URL 和违反的指令。常见原因：
-
-- 被 `connect-src 'self'` 拦截的外部 fetch 或 WebSocket 请求——将请求迁移到你自己的代理端点，或移除对外部依赖的引用。
-- 被 `font-src`/`img-src` 拦截的外部字体或图片——从 `.sbtheme` 包内提供资源，或改用 `data:` URI。
-- `eval()` 调用被拦截——自定义主题的 CSP 已包含 `unsafe-eval`，正常情况下不应出现此错误。如果仍然报错，检查浏览器扩展是否覆盖了 CSP。
-
-## 最佳实践
-
-### 资源 URL 与 SPA history 路由
-
-在 Vite 配置中设置 `base: '/'`（Starter 默认值）。服务端会将任意未匹配到已知资源的深层路径（如 `/servers/abc`）回退为你的 `index.html`。使用 `base: '/'` 时，资源 URL 为绝对路径（`/assets/app.js`），无论当前 SPA 路由如何都能正确解析。使用 `base: './'` 时，在 `/servers/abc` 刷新会请求 `./assets/app.js` → `/servers/assets/app.js` → 404。
-
-### 国际化
-
-尽可能使用与内置 SPA 相同的语言键。用户偏好语言可通过 `Accept-Language` 请求头（服务端）或 `navigator.language`（客户端）获取。如果主题面向广泛用户，建议至少提供中英文两套翻译。
-
-### 深色模式
-
-使用 `prefers-color-scheme` 检测用户配色偏好，或将其持久化到 `localStorage`。内置 SPA 使用 OKLCH 变量——如果希望与现有颜色主题基础设施互操作，可在 `<html>` 上暴露 `data-theme` 属性并使用相同的变量名。
-
-### 无障碍
-
-- 确保足够的颜色对比度（WCAG AA：正文 4.5:1，大字 3:1）。
-- 为交互组件使用语义化 HTML 和 ARIA role。
-- 所有交互元素必须支持键盘导航。
-
-### 移动端
-
-在 375 px 视口宽度下进行测试，避免固定宽度布局。Starter 已内置响应式基础，不要删除 `<meta name="viewport">` 标签。
-
diff --git a/apps/docs/content/docs/cn/custom-themes.mdx b/apps/docs/content/docs/cn/custom-themes.mdx
deleted file mode 100644
index f2aa7eee..00000000
--- a/apps/docs/content/docs/cn/custom-themes.mdx
+++ /dev/null
@@ -1,101 +0,0 @@
----
-title: 自定义主题
-description: 创建、分享并应用你自己的 ServerBee 主题变量。
----
-
-ServerBee 内置多套预设主题，管理员也可以创建完整的自定义主题。自定义主题会把浅色和深色模式的 OKLCH CSS 变量保存到数据库中，后台和公共状态页都能解析同一套主题。
-
-## 概念
-
-- 预设主题是应用内置的，不可直接修改。
-- 自定义主题保存在服务端数据库中。
-- 后台激活主题会影响所有用户看到的仪表盘主题。
-- 每个公共状态页可以绑定独立主题，也可以跟随后台激活主题。
-
-## 创建主题
-
-1. 打开 **设置 → 外观**。
-2. 在 **我的主题** 区域点击 **新建主题**。
-3. 输入名称，并选择一个预设作为基础。
-4. 在编辑器中分别调整浅色和深色变量。
-5. 保存主题。
-
-## 应用主题
-
-- 后台：在 **设置 → 外观** 中点击任意预设或自定义主题卡片。
-- 状态页：编辑状态页，在 **主题** 下拉框中选择主题。
-- 如果状态页要继承后台主题，选择 **跟随后台默认**。
-
-## 导入和导出
-
-在编辑器中点击 **导出** 可以下载主题 JSON 文件。在外观页面点击 **导入** 可以上传主题文件。
-
-导入格式如下：
-
-```json
-{
-  "version": 1,
-  "name": "Theme name",
-  "description": "Optional description",
-  "based_on": "default",
-  "vars_light": {},
-  "vars_dark": {}
-}
-```
-
-当前只接受 `version: 1`。
-
-## 校验规则
-
-- 浅色和深色变量表都必须包含全部必需变量。
-- 值必须使用 `oklch(L C H)` 或 `oklch(L C H / alpha)` 语法。
-- `L` 必须在 `0` 到 `1` 之间。
-- `H` 必须在 `0` 到 `360` 之间。
-- Alpha 必须在 `0` 到 `1` 之间，或在 `0%` 到 `100%` 之间。
-- Chroma 不设硬上限。浏览器可能会对无法显示的颜色做色域裁切。
-
-## 品牌和白标
-
-同一个 **设置 → 外观** 页面也用于控制基础品牌信息。品牌设置保存在服务端数据库中，后台外壳和公开页面都会读取。
-
-| 字段 | 说明 |
-|------|------|
-| `site_title` | UI 显示的浏览器/应用标题 |
-| `footer_text` | UI 渲染产品页脚时显示的文本 |
-| `logo_path` | 上传 Logo 的公开路径，通常为 `/api/brand/logo` |
-| `favicon_path` | 上传 Favicon 的公开路径，通常为 `/api/brand/favicon` |
-
-公开端点：
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| GET | `/api/settings/brand` | 无需认证读取品牌配置 |
-| GET | `/api/brand/logo` | 返回上传的 Logo |
-| GET | `/api/brand/favicon` | 返回上传的 Favicon |
-
-管理员端点：
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| PUT | `/api/settings/brand` | 以 JSON 更新 `site_title`、`footer_text`、`logo_path` 和 `favicon_path` |
-| POST | `/api/settings/brand/logo` | 通过 multipart 字段 `file` 上传 Logo |
-| POST | `/api/settings/brand/favicon` | 通过 multipart 字段 `file` 上传 Favicon |
-
-Logo 和 Favicon 仅支持 PNG 或 ICO 文件，大小上限为 512 KB。上传新资源会替换同类型旧资源。
-
-<Callout type="info">
-`PUT /api/settings/brand` 期望 JSON。图片文件需要通过独立的 logo/favicon 上传端点提交，而不是通过 JSON 更新端点提交。
-</Callout>
-
-## 禁用自定义主题
-
-设置：
-
-```toml
-[feature]
-custom_themes = false
-```
-
-也可以设置 `SERVERBEE_FEATURE__CUSTOM_THEMES=false`。
-
-禁用后，自定义主题写入接口会拒绝请求，任何激活的 `custom:*` 引用会在读取时解析为默认预设。已保存的主题数据会保留。
diff --git a/apps/docs/content/docs/cn/custom-widgets.mdx b/apps/docs/content/docs/cn/custom-widgets.mdx
new file mode 100644
index 00000000..dd712208
--- /dev/null
+++ b/apps/docs/content/docs/cn/custom-widgets.mdx
@@ -0,0 +1,289 @@
+---
+title: 自定义组件
+description: 用 React + Zod 编写自定义仪表盘组件，通过单文件或 zip 集合包安装到 ServerBee。
+icon: Puzzle
+---
+
+ServerBee 的仪表盘原生支持自定义组件（Widget Module）。每个组件就是一个独立的 ES 模块，由管理员安装后即可像内置组件一样拖拽到任意仪表盘上。本指南介绍两种安装方式：
+
+- **方式 B** — 单个 `.js` 文件（一个组件 = 一个文件）
+- **方式 C** — `.zip` 集合包（一次安装多个组件，可共享同一份发布产物）
+
+## 概念
+
+一个 Widget Module 包含三部分：
+
+1. **静态 JSDoc 清单** — 文件顶部的 `@serverbee-widget {...}` JSON 块，描述组件的 `id`、`version`、`name`、`category`、默认尺寸、所需 SDK 版本等。清单必须**可静态解析**：服务端不会执行模块代码就能完成索引与权限校验，离线扫描也能识别。
+2. **默认导出** — 调用 `defineWidget({ configSchema, component, actions? })` 返回的对象。`configSchema` 是一个 Zod schema，用来描述组件可配置项；`component` 是一个 React 组件，运行时收到 `{ config, size, isEditing, actions }` props。
+3. **运行时依赖** — 通过 `import` 引用 `react`、`react/jsx-runtime`、`@serverbee/widget-sdk`。这些都是**宿主提供**的依赖，打包时必须声明为 `external`，浏览器加载时会重用主应用已有的实例。
+
+### 信任模型
+
+自定义组件**仅管理员可安装**，且运行在**同源**的浏览器环境中，与登录用户共享同一份会话。这意味着：
+
+- 一个被批准的组件可以发出任何当前用户有权访问的 API 请求；
+- 组件之间共享同一个全局 React 上下文，不要在组件里塞入会破坏其它组件的全局副作用；
+- 平台不沙箱执行组件——所以**只安装你信任的代码**。
+
+## 方式 B — 单文件 `.widget.js`
+
+### 文件结构
+
+```js
+/**
+ * @serverbee-widget {
+ *   "id": "com.example.hello",
+ *   "version": "1.0.0",
+ *   "name": "Hello",
+ *   "description": "最小可行示例。",
+ *   "author": "Your Name",
+ *   "category": "Real-time",
+ *   "sizing": { "defaultW": 3, "defaultH": 2, "minW": 2, "minH": 2, "strategy": "free" },
+ *   "sdkVersion": "^0.1.0"
+ * }
+ */
+import { defineWidget, useServers, useTheme, z } from '@serverbee/widget-sdk'
+
+const ConfigSchema = z.object({
+  greeting: z.string().describe('问候语').default('Hello, ServerBee')
+})
+
+export default defineWidget({
+  configSchema: ConfigSchema,
+  component: ({ config }) => {
+    const servers = useServers()
+    const theme = useTheme()
+    const online = servers.filter((s) => s.online).length
+    const { greeting } = config
+    return (
+      <div style={{ padding: 12 }}>
+        <div style={{ fontSize: 16, fontWeight: 600 }}>{greeting}</div>
+        <div style={{ marginTop: 8, color: 'var(--muted-foreground)' }}>
+          {online} / {servers.length} 在线 · {theme.mode} 模式
+        </div>
+      </div>
+    )
+  }
+})
+```
+
+### 清单字段
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `id` | ✅ | 反向域名风格的唯一标识，例如 `com.example.cpu` |
+| `version` | ✅ | 语义化版本号 `MAJOR.MINOR.PATCH` |
+| `name` | ✅ | 在组件选择器中展示的名称 |
+| `description` | – | 描述文本 |
+| `author` | – | 作者名或组织 |
+| `category` | ✅ | 取值 `Real-time`、`Charts` 或 `Status` |
+| `sizing.defaultW/H` | ✅ | 在网格中的默认宽 / 高（格子数） |
+| `sizing.minW/H` | ✅ | 允许的最小尺寸 |
+| `sizing.maxW/H` | – | 可选的最大尺寸 |
+| `sizing.strategy` | ✅ | `free` / `fixed` / `aspect-square` / `content-height` |
+| `sdkVersion` | ✅ | SDK 版本范围，例如 `^0.1.0` |
+
+### 打包要求
+
+自定义组件必须输出 **ES Module** 格式，且把以下依赖声明为 `external`：
+
+- `react`
+- `react/jsx-runtime`
+- `@serverbee/widget-sdk`
+
+更重要的是：**JSDoc 清单注释必须原样保留在输出文件顶部**。多数压缩器默认会删掉注释，记得开启「保留特定注释」选项。
+
+Vite + Terser 的典型配置：
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    lib: {
+      entry: 'src/index.tsx',
+      formats: ['es'],
+      fileName: () => 'index.js'
+    },
+    rollupOptions: {
+      external: ['react', 'react/jsx-runtime', '@serverbee/widget-sdk']
+    },
+    minify: 'terser',
+    terserOptions: {
+      format: {
+        // 保留 @serverbee-widget 清单注释
+        comments: /@serverbee-widget/
+      }
+    }
+  }
+})
+```
+
+### 通过 UI 安装
+
+1. 用管理员账号登录。
+2. 打开 **Settings → Widget Modules**。
+3. 选择 **Upload `.js`** 上传本地文件，或选择 **Import URL** 填入 HTTPS 链接。
+4. 安装成功后，到任意仪表盘点击 **Edit** → **Add Widget**，新组件就会出现在列表里。
+
+### 通过 API 安装
+
+```bash
+# 上传本地文件
+curl -X POST "https://your-host/api/widget-modules" \
+  -H "X-API-Key: $SERVERBEE_API_KEY" \
+  -F file=@my.widget.js
+
+# 从 URL 安装
+curl -X POST "https://your-host/api/widget-modules?url=https://cdn.example.com/my.widget.js" \
+  -H "X-API-Key: $SERVERBEE_API_KEY"
+```
+
+成功时返回：
+
+```json
+{ "data": { "id": "com.example.hello", "version": "1.0.0" } }
+```
+
+如果同 ID 的组件已存在，会就地升级（版本号、清单、代码都被替换）。
+
+## 方式 C — `.zip` 集合包
+
+集合包让你**用一次上传**安装多个组件。每个组件仍然遵循方式 B 的规则（独立的 JSDoc 清单、独立的 entry 文件），只是被打包进同一个 `.zip` 里，由根目录的 `collection.json` 列举。
+
+### 包结构
+
+```
+my-pack.zip
+├── collection.json
+├── weather/
+│   ├── index.js          ← 含 @serverbee-widget 清单
+│   └── icon.svg          ← 可选的资源文件
+├── clock/
+│   └── index.js
+└── shared/
+    └── helpers.js        ← 可选；当前不会自动注入，需要 entry 文件自行处理
+```
+
+### `collection.json` 格式
+
+```json
+{
+  "widgets": [
+    { "entry": "weather/index.js" },
+    { "entry": "clock/index.js" }
+  ]
+}
+```
+
+约束：
+
+- `entry` 必须是相对路径（不能以 `/` 开头，不能包含 `..`）；
+- 必须指向 `.js` 或 `.mjs` 文件；
+- 每个 entry 文件都必须包含合法的 `@serverbee-widget` JSDoc 块；
+- 同一个 `.zip` 内**组件 `id` 必须唯一**——重复 `id` 会被拒绝。
+
+### 资源解析
+
+集合包里的资源（图片、JSON、辅助 JS 等）通过 `GET /api/widget-modules/{id}/{相对路径}` 访问。相对路径会自动以 entry 所在文件夹为根目录拼接：
+
+| 请求 URL | 解析到的 zip 内路径 |
+|----------|--------------------|
+| `/api/widget-modules/com.example.weather/index.js` | `weather/index.js` |
+| `/api/widget-modules/com.example.weather/icon.svg` | `weather/icon.svg` |
+| `/api/widget-modules/com.example.clock/index.js` | `clock/index.js` |
+
+组件代码里可以这样引用：
+
+```ts
+const iconUrl = `/api/widget-modules/com.example.weather/icon.svg`
+```
+
+注意：不同 `id` 之间不能跨目录互相访问彼此的资源。
+
+### 打包流程
+
+1. 用你喜欢的打包工具（Vite、tsup、esbuild 等）分别为每个组件构建 `index.js`，外部化 React 和 SDK，保留清单注释；
+2. 把所有产物按上面的目录结构放好；
+3. 在包根目录写 `collection.json`；
+4. 用 `zip` 命令压缩：
+
+```bash
+zip -r my-pack.zip collection.json weather/ clock/
+```
+
+### 安装
+
+UI 操作和方式 B 完全一致——直接上传 `.zip` 即可，后端会通过文件首部的 `PK\x03\x04` 魔数自动识别。
+
+```bash
+curl -X POST "https://your-host/api/widget-modules" \
+  -H "X-API-Key: $SERVERBEE_API_KEY" \
+  -F file=@my-pack.zip
+```
+
+集合包安装成功时返回**一个数组**——每个元素对应包里的一个组件：
+
+```json
+{
+  "data": [
+    { "id": "com.example.weather", "version": "1.0.0" },
+    { "id": "com.example.clock",   "version": "1.0.0" }
+  ]
+}
+```
+
+每个组件会在数据库中独立成行，可以单独启用、停用或卸载；同时它们共享同一份 zip blob 存储。
+
+## 尺寸策略
+
+`sizing.strategy` 决定组件在仪表盘里如何被调整大小：
+
+- `free` — 用户可在 `minW/H` 到 `maxW/H` 之间自由调整宽高；
+- `fixed` — 锁定 `defaultW/H`，不允许调整；
+- `aspect-square` — 始终保持 1:1，会就近吸附到最接近的层级；
+- `content-height` — 宽度可调，高度由内容决定。
+
+更多布局与编辑细节见[仪表盘与组件](/cn/docs/dashboards)。
+
+## SDK 速览
+
+`@serverbee/widget-sdk` 是 ServerBee 暴露给自定义组件的稳定 API 表面，包含：
+
+- `defineWidget` — 声明组件的入口；
+- `z` / `ZodSchema` — 内嵌的 Zod，用于描述配置项 schema；
+- 数据钩子：`useServers`、`useServer`、`useMetric`、`useHistory`、`useTraffic`、`useAlerts`、`useServiceMonitors`、`useUptime`、`useGeoIp`；
+- 宿主钩子：`useTheme`、`useConfigUpdate`、`useCapability`；
+- 通用逃生舱：`useApiQuery` / `useApiMutation` 直接调用后端 REST API；
+- `createActionsHelper` 与 `ActionDefinition` —— 在组件上注册按钮操作。
+
+完整 API 见 SDK 自带的 `packages/widget-sdk/README.md`。
+
+## 卸载
+
+在 **Settings → Widget Modules** 里点击组件右侧的删除按钮，或者：
+
+```bash
+curl -X DELETE "https://your-host/api/widget-modules/com.example.hello" \
+  -H "X-API-Key: $SERVERBEE_API_KEY"
+```
+
+内置组件（如 `com.serverbee.hello-world`）不能被卸载，对其调用 DELETE 会返回 `400`。
+
+## 限制与安全
+
+- **大小上限**：单个文件或 `.zip` 不超过 **1 MiB**；zip 中单个条目最大 **5 MiB**（解压后）。
+- **SSRF 防护**：从 URL 安装时，私网、回环、链路本地地址会被直接拒绝。
+- **Zip-slip 防护**：解压时会拒绝包含 `..` 或绝对路径的条目。
+- **静态解析**：清单必须能用纯正则解析出来；没有任何 `eval` / `Function()` 调用。
+- **管理员限定**：安装、卸载接口都要求管理员权限；普通成员只能读取列表与资源。
+- **同源运行**：组件运行在主 SPA 同源环境，请只安装来源可信的代码。
+
+<Cards>
+  <Card title="仪表盘与组件" href="/cn/docs/dashboards" />
+  <Card title="功能开关" href="/cn/docs/capabilities" />
+  <Card title="API 参考" href="/cn/docs/api-reference" />
+</Cards>
diff --git a/apps/docs/content/docs/cn/index.mdx b/apps/docs/content/docs/cn/index.mdx
index 24a8f172..79c22493 100644
--- a/apps/docs/content/docs/cn/index.mdx
+++ b/apps/docs/content/docs/cn/index.mdx
@@ -78,7 +78,7 @@ Agent 通过 WebSocket 与 Server 保持长连接，实现实时数据推送。
   <Card title="Ping 探测" href="/cn/docs/ping" />
   <Card title="功能开关" href="/cn/docs/capabilities" />
   <Card title="公开状态页" href="/cn/docs/status-page" />
-  <Card title="自定义主题与品牌" href="/cn/docs/custom-themes" />
+  <Card title="自定义组件" href="/cn/docs/custom-widgets" />
   <Card title="iOS 移动端" href="/cn/docs/mobile" />
   <Card title="安全设置" href="/cn/docs/security" />
   <Card title="管理员指南" href="/cn/docs/admin" />
diff --git a/apps/docs/content/docs/cn/meta.json b/apps/docs/content/docs/cn/meta.json
index 7e5ec21f..13f6460a 100644
--- a/apps/docs/content/docs/cn/meta.json
+++ b/apps/docs/content/docs/cn/meta.json
@@ -21,8 +21,7 @@
     "ip-quality",
     "capabilities",
     "status-page",
-    "custom-themes",
-    "custom-frontend",
+    "custom-widgets",
     "mobile",
     "---管理---",
     "security",
diff --git a/apps/docs/content/docs/cn/status-page.mdx b/apps/docs/content/docs/cn/status-page.mdx
index 47b38db0..44f17c09 100644
--- a/apps/docs/content/docs/cn/status-page.mdx
+++ b/apps/docs/content/docs/cn/status-page.mdx
@@ -161,7 +161,7 @@ GET /api/status/{slug}
 更新时可以传入 `theme_ref` 设置自定义主题，例如 `"preset:default"` 或自定义主题引用。传 `null` 表示跟随后台默认主题。
 
 <Cards>
-  <Card title="自定义主题" href="/cn/docs/custom-themes" />
+  <Card title="自定义组件" href="/cn/docs/custom-widgets" />
   <Card title="服务监控" href="/cn/docs/service-monitors" />
   <Card title="告警与通知" href="/cn/docs/alerts" />
 </Cards>
diff --git a/apps/docs/content/docs/en/custom-frontend.mdx b/apps/docs/content/docs/en/custom-frontend.mdx
deleted file mode 100644
index 97e231b7..00000000
--- a/apps/docs/content/docs/en/custom-frontend.mdx
+++ /dev/null
@@ -1,222 +0,0 @@
----
-title: Custom Frontend Themes
-description: Replace the entire ServerBee dashboard with a custom React/Vue/Svelte SPA uploaded as a .sbtheme package.
----
-
-ServerBee lets administrators swap out the built-in dashboard with any SPA they upload as a `.sbtheme` package. The custom frontend runs at the same origin as the server, uses the same REST and WebSocket API, and can be anything — a stripped-down read-only view, a heavily branded white-label product, or a completely custom monitoring experience.
-
-This is a full SPA replacement, not a plugin or color-theme overlay. When a custom frontend is active, it owns every route (login page, dashboards, settings, everything). The existing [Custom themes](/en/docs/custom-themes) color-variable system and brand settings have no effect while a custom frontend is active; the UI shows a notice explaining this.
-
-## What Can and Cannot Be Customized
-
-| What you can do | What you cannot do |
-|-----------------|-------------------|
-| Replace the full HTML/CSS/JS frontend | Add server-side code, migrations, or Rust crates |
-| Implement your own routing, login page, branding | Access any route under `/api/*`, `/swagger-ui/*`, or `/__system/*` — these are always served by the server |
-| Call any existing REST or WebSocket API | Load external scripts, stylesheets, fonts, or make cross-origin fetch/XHR/WebSocket connections (CSP enforces this) |
-| Bundle any JS framework (React, Vue, Svelte, vanilla) | Embed the frontend in an iframe on another origin (CSP `frame-ancestors: none`) |
-| Use your own colors, fonts, icons, and assets | Ship more than 20 MB of uncompressed content or more than 1000 files |
-| Read the current user session via the existing auth API | Per-user themes — one theme is active system-wide for all users |
-
-**Trust model:** Admin-installed themes run same-origin with the server. They have the same data-access authority as the logged-in user — equivalent to an admin replacing the built-in SPA on disk. CSP is defense-in-depth (it raises the bar for opportunistic exfiltration like remote image beacons and cross-origin script loads) but is **not** a containment boundary. Only install themes you trust.
-
-## Quickstart
-
-**Prerequisites:** [bun](https://bun.sh) and a running ServerBee server.
-
-### 1. Scaffold the starter template
-
-```bash
-npx degit ZingerLittleBee/ServerBee/templates/serverbee-theme-starter my-theme
-cd my-theme
-bun install
-```
-
-The starter contains a minimal Vite + TypeScript SPA with a pre-wired API client (`src/lib/serverbee.ts`) that uses same-origin session authentication.
-
-### 2. Edit and build
-
-Customize `src/App.tsx` and the rest of the source. Run `bun run dev` to iterate locally against any running ServerBee server (configure the dev proxy in `vite.config.ts`).
-
-### 3. Pack
-
-```bash
-bun run pack
-```
-
-This runs a Vite production build, validates the output against the same constraints the server enforces (file sizes, extensions, manifest), and produces a deterministic zip with the `.sbtheme` extension in the project root (e.g. `my-theme-1.0.0.sbtheme`).
-
-### 4. Upload
-
-In ServerBee, go to **Settings → Appearance**. The **Custom Frontend** section appears at the top for admin users. Drag the `.sbtheme` file onto the upload card, or click to browse.
-
-After upload, click **Preview** to open the theme in a new tab without activating it system-wide. When you are satisfied, click **Activate**.
-
-<Callout type="warn">
-Activation is immediately global. Every user who reloads any root-level URL will see the new theme. Use **Preview** to verify before activating. If something goes wrong, visit `?theme=default` to recover (see [Recovery and debugging](#recovery-and-debugging)).
-</Callout>
-
-## Manifest Reference
-
-Every `.sbtheme` package must contain a `manifest.json` at the root of the zip:
-
-```json
-{
-  "schema_version": 1,
-  "id": "acme-dashboard",
-  "name": "Acme Corp Dashboard",
-  "version": "1.2.0",
-  "author": "Acme Inc",
-  "homepage": "https://acme.example.com",
-  "description": "Branded dashboard for Acme.",
-  "entry": "index.html",
-  "preview": "preview.png"
-}
-```
-
-| Field | Required | Constraints |
-|-------|----------|-------------|
-| `schema_version` | yes | Integer; only `1` is accepted |
-| `id` | yes | Matches `^[a-z][a-z0-9-]{2,63}$` |
-| `name` | yes | 1–64 chars; HTML tags stripped |
-| `version` | yes | Valid semver (e.g. `1.2.0`) |
-| `author` | no | ≤ 64 chars; HTML tags stripped |
-| `homepage` | no | Valid `http(s)://` URL |
-| `description` | no | ≤ 500 chars; HTML tags stripped |
-| `entry` | no | Defaults to `index.html`; path must exist in the package and end with `.html` |
-| `min_serverbee_version` | no | Semver; upload is rejected if the running server version is lower |
-| `preview` | no | Relative path to a preview image; must exist; ≤ 500 KB; `png`, `jpg`, or `webp` only |
-
-<Callout type="warn">
-**`min_serverbee_version` and pre-releases:** semver treats a release like `1.0.0` as **greater** than a pre-release like `1.0.0-alpha.3`. If your target deployment runs a pre-release build, setting `"min_serverbee_version": "1.0.0"` will cause the upload to be rejected. Leave this field out unless you actually depend on a specific newer server feature.
-</Callout>
-
-The `id` field acts as a theme family identifier. You can upload multiple versions with the same `id`; the server keeps the full history and lets you activate any of them. Uploading a lower version than the newest existing version for the same `id` is rejected with `NO_DOWNGRADE`.
-
-## Size and File Limits
-
-| Limit | Value |
-|-------|-------|
-| Multipart upload hard cap | 25 MB |
-| Total uncompressed content | 20 MB |
-| Single file | 5 MB |
-| File count | 1000 |
-| Per-file path length | 255 chars |
-| Preview image | 500 KB |
-
-**Allowed file extensions** (case-insensitive): `html`, `htm`, `js`, `mjs`, `css`, `png`, `jpg`, `jpeg`, `svg`, `webp`, `gif`, `ico`, `woff`, `woff2`, `ttf`, `otf`, `json`, `txt`, `map`.
-
-The server also enforces a compression-ratio guard: any single zip entry whose decompressed size exceeds its compressed size by more than 100× is rejected (zip bomb defense).
-
-Files rejected outright: directory traversal entries (`../`), absolute paths, Windows drive letters, symlink zip entries, and duplicate entries.
-
-<Callout type="info">
-Keep documentation, README files, and source maps out of the `.sbtheme` package. They inflate the size budget and the server never serves them. Distribute them alongside the theme source repo instead.
-</Callout>
-
-## API and WebSocket Reference
-
-A custom frontend calls the same HTTP REST API and WebSocket endpoints as the built-in dashboard. There is no separate "theme SDK."
-
-- **Full REST API reference:** [`/swagger-ui/`](/swagger-ui/) — live on your running server
-- **OpenAPI document:** [`/api-docs/openapi.json`](/api-docs/openapi.json)
-- **Authentication:** The session cookie is set by `POST /api/auth/login` and is automatically included in all same-origin requests. API key authentication via `X-API-Key` header is also supported.
-- **WebSocket (server updates):** Connect to `GET /api/ws/servers` (browser WebSocket). The server pushes `BrowserMessage` frames (JSON) with `FullSync`, `Update`, `ServerOnline`, `ServerOffline`, and other variants.
-- **Terminal:** Binary WebSocket frames on `/api/ws/terminal/:sessionId`. The first 16 bytes are the session UUID; the rest is raw PTY data.
-
-The `/__system/*` prefix is always served by the default SPA and cannot be overridden by a custom theme. It provides the recovery UI and the `POST /__system/clear-recovery` / `POST /__system/clear-preview` endpoints used by the recovery and preview mechanisms.
-
-## CSP Constraints
-
-All responses that serve custom theme files include the following Content Security Policy:
-
-```
-Content-Security-Policy:
-  default-src 'self';
-  script-src 'self' 'unsafe-inline' 'unsafe-eval';
-  style-src 'self' 'unsafe-inline';
-  img-src 'self' data: blob:;
-  font-src 'self' data:;
-  connect-src 'self';
-  frame-ancestors 'none';
-  base-uri 'self';
-  form-action 'self';
-```
-
-**What `connect-src 'self'` means for theme authors:**
-
-- Fetch, XHR, and WebSocket connections are restricted to the same origin. Your theme can freely call `/api/*` and connect to WebSocket endpoints on the same server.
-- Connections to external URLs (e.g. `https://api.example.com`, `wss://external.host`) are blocked by the browser.
-- If your theme bundles analytics, error-reporting SDKs, or CDN-hosted assets that make external network requests, those requests will be blocked.
-
-**What the CSP does not prevent:**
-
-- Top-level navigation exfiltration (`location.href = 'https://...'`). The CSP3 `navigate-to` directive that would cover this is not supported by browsers in practice.
-- Same-origin API access — the theme runs with the user's session and can read anything the user can read.
-
-`unsafe-eval` is included for compatibility with most React, Vue, Svelte, and wasm-bindgen builds.
-
-The default built-in SPA is not affected by these headers. The CSP above applies only to custom theme responses.
-
-## Recovery and Debugging
-
-### Recover from a broken theme
-
-If a custom theme breaks the UI and you cannot navigate to the management page:
-
-1. Visit `/?theme=default` in your browser. The server immediately returns the built-in default SPA regardless of the active theme and sets a recovery cookie (`sb_force_default`) that keeps the origin on the default SPA for one hour.
-2. You are now on the default SPA. Navigate to **Settings → Appearance** and deactivate or delete the broken theme.
-3. To exit recovery manually and return to the custom theme, click **Exit recovery** on the default SPA, or visit `/?theme=active`. This calls `POST /__system/clear-recovery` and clears the cookie.
-
-<Callout type="info">
-The recovery cookie is browser-wide (origin-scoped) and lasts one hour. Any tab in the same browser that reloads will see the default SPA until recovery is cleared or the cookie expires.
-</Callout>
-
-### Preview before activating
-
-To safely inspect a theme before making it active system-wide:
-
-1. Upload the theme. It is not activated automatically.
-2. Click **Preview** on the theme card. A dialog explains that preview is browser-wide.
-3. Confirm — a new tab opens at `/?theme=preview:<uuid>` and a sticky banner appears inside the theme showing remaining time and an **Exit preview** button.
-4. Review the theme. When done, click **Exit preview** in the banner. The tab returns to the default SPA.
-5. Click **Activate** in the management UI to commit system-wide.
-
-Preview uses a 15-minute cookie (`sb_preview_theme`). It is browser-wide: any tab in the same browser that reloads will see the preview theme. If you need the management UI live during a long review, use a separate browser or incognito window.
-
-### Force the active theme
-
-Visit `/?theme=active` to clear both the recovery and preview cookies and serve the currently active theme (or the default if none is active).
-
-### Debug CSP violations
-
-Open the browser **DevTools → Console**. CSP violations appear as errors with the blocked URL and the violated directive. Common causes:
-
-- External fetch or WebSocket call blocked by `connect-src 'self'` — move the request to your own proxy endpoint or remove the external dependency.
-- External font or image blocked by `font-src`/`img-src` — serve assets from within the `.sbtheme` package or use `data:` URIs.
-- `eval()` call blocked — `unsafe-eval` is already included in the CSP for custom themes, so this should not occur. If you still see this error, check whether your browser extension is overriding the CSP.
-
-## Best Practices
-
-### Asset URLs and SPA history routing
-
-Set `base: '/'` in your Vite config (this is the starter default). The server falls back to serving your `index.html` for any deep path that is not a known asset (e.g. `/servers/abc`). With `base: '/'`, asset URLs are absolute (`/assets/app.js`) and resolve correctly regardless of the current SPA route. With `base: './'`, a reload at `/servers/abc` would request `./assets/app.js` → `/servers/assets/app.js` → 404.
-
-### Internationalization
-
-Use the same locale keys as the built-in SPA where possible. The user's preferred language is available via the `Accept-Language` header (server-side) or `navigator.language` (client-side). Consider shipping translations for at least English and Chinese if your theme is intended for wide use.
-
-### Dark mode
-
-Detect the user's color scheme preference with `prefers-color-scheme` or persist it in `localStorage`. The built-in SPA uses OKLCH variables — if you want your theme to interoperate with the existing color-theme infrastructure, expose a `data-theme` attribute on `<html>` and use the same variable names.
-
-### Accessibility
-
-- Ensure sufficient color contrast (WCAG AA: 4.5:1 for normal text, 3:1 for large text).
-- Use semantic HTML and ARIA roles for interactive components.
-- Keyboard navigation must work for all interactive elements.
-
-### Mobile
-
-Test at 375 px viewport width. Avoid fixed-width layouts. The starter includes a responsive base; do not remove the `<meta name="viewport">` tag.
-
diff --git a/apps/docs/content/docs/en/custom-themes.mdx b/apps/docs/content/docs/en/custom-themes.mdx
deleted file mode 100644
index 3a0e21b2..00000000
--- a/apps/docs/content/docs/en/custom-themes.mdx
+++ /dev/null
@@ -1,101 +0,0 @@
----
-title: Custom themes
-description: Build, share, and apply your own ServerBee theme variables.
----
-
-ServerBee includes preset themes, and administrators can also create full custom themes. A custom theme stores OKLCH CSS variables for light and dark mode in the database, so the dashboard and public status pages can resolve the same theme everywhere.
-
-## Concepts
-
-- Preset themes are immutable and ship with the web app.
-- Custom themes are stored in the server database.
-- The active admin theme controls the dashboard theme for all users.
-- Each public status page can use its own theme or follow the active admin theme.
-
-## Create a theme
-
-1. Open **Settings → Appearance**.
-2. In **My themes**, click **New theme**.
-3. Enter a name and choose a preset to fork from.
-4. Edit the light and dark variables in the theme editor.
-5. Save the theme.
-
-## Apply a theme
-
-- Dashboard: click any preset or custom theme card on **Settings → Appearance**.
-- Status page: edit a status page and choose a theme from the **Theme** selector.
-- To inherit the dashboard theme on a status page, choose **Follow admin default**.
-
-## Import and export
-
-Use **Export** in the editor to download a theme JSON file. Use **Import** on the appearance page to upload one.
-
-The import format is:
-
-```json
-{
-  "version": 1,
-  "name": "Theme name",
-  "description": "Optional description",
-  "based_on": "default",
-  "vars_light": {},
-  "vars_dark": {}
-}
-```
-
-Only `version: 1` is accepted.
-
-## Validation
-
-- Every required variable must exist in both light and dark maps.
-- Values must use `oklch(L C H)` or `oklch(L C H / alpha)` syntax.
-- `L` must be between `0` and `1`.
-- `H` must be between `0` and `360`.
-- Alpha must be between `0` and `1`, or between `0%` and `100%`.
-- Chroma has no hard cap. Browsers may gamut-clip values that cannot be displayed.
-
-## Branding and White Label
-
-The same **Settings → Appearance** page also controls basic product branding. Branding settings are stored in the server database and are read by both the dashboard shell and public pages.
-
-| Field | Description |
-|-------|-------------|
-| `site_title` | Browser/app title shown by the UI |
-| `footer_text` | Footer text shown where the UI renders a product footer |
-| `logo_path` | Public path for the uploaded logo, usually `/api/brand/logo` |
-| `favicon_path` | Public path for the uploaded favicon, usually `/api/brand/favicon` |
-
-Public endpoints:
-
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/api/settings/brand` | Read brand configuration without authentication |
-| GET | `/api/brand/logo` | Serve uploaded logo |
-| GET | `/api/brand/favicon` | Serve uploaded favicon |
-
-Admin endpoints:
-
-| Method | Path | Description |
-|--------|------|-------------|
-| PUT | `/api/settings/brand` | Update `site_title`, `footer_text`, `logo_path`, and `favicon_path` as JSON |
-| POST | `/api/settings/brand/logo` | Upload a logo via multipart field `file` |
-| POST | `/api/settings/brand/favicon` | Upload a favicon via multipart field `file` |
-
-Logo and favicon uploads accept PNG or ICO files only and are limited to 512 KB. Uploading a new asset replaces the previous asset of the same type.
-
-<Callout type="info">
-`PUT /api/settings/brand` expects JSON. Image files are uploaded through the dedicated logo/favicon endpoints, not through the JSON update endpoint.
-</Callout>
-
-## Disable custom themes
-
-Set:
-
-```toml
-[feature]
-custom_themes = false
-```
-
-Or set `SERVERBEE_FEATURE__CUSTOM_THEMES=false`.
-
-When disabled, custom theme mutation endpoints reject writes, and any active `custom:*` reference is resolved as the default preset at read time. Stored themes are preserved.
diff --git a/apps/docs/content/docs/en/custom-widgets.mdx b/apps/docs/content/docs/en/custom-widgets.mdx
new file mode 100644
index 00000000..1ca91e5a
--- /dev/null
+++ b/apps/docs/content/docs/en/custom-widgets.mdx
@@ -0,0 +1,289 @@
+---
+title: Custom Widgets
+description: Author custom dashboard widgets with React + Zod, and install them into ServerBee as a single file or a zip collection.
+icon: Puzzle
+---
+
+ServerBee dashboards natively support custom widget modules. Each widget is a standalone ES module that an admin installs once and then drops onto any dashboard, exactly like a built-in widget. This guide covers the two supported install methods:
+
+- **Method B** — a single `.js` file (one widget per file)
+- **Method C** — a `.zip` collection bundle (multiple widgets in one upload, sharing the same build output)
+
+## Concepts
+
+A widget module has three parts:
+
+1. **Static JSDoc manifest** — a `@serverbee-widget {...}` JSON block at the top of the file declaring the widget's `id`, `version`, `name`, `category`, default sizing, required SDK version, and so on. The manifest is **statically parseable**: the server can index it without ever executing the module, which means offline scanning and permission checks work the same way as runtime loading.
+2. **Default export** — the object returned by `defineWidget({ configSchema, component, actions? })`. `configSchema` is a Zod schema describing the configurable fields; `component` is a React component that receives `{ config, size, isEditing, actions }` props at runtime.
+3. **Runtime dependencies** — imported as `react`, `react/jsx-runtime`, and `@serverbee/widget-sdk`. These are **provided by the host** and must be marked `external` at build time; the browser reuses the main app's instances.
+
+### Trust model
+
+Custom widgets are **admin-only to install** and run **same-origin** in the browser, sharing the session of the logged-in user. That means:
+
+- An approved widget can issue any API request that the current user is authorized for.
+- All widgets share the same React context, so do not introduce global side effects that could break sibling widgets.
+- The platform does not sandbox widget code — **only install code you trust**.
+
+## Method B — single `.widget.js` file
+
+### Anatomy
+
+```js
+/**
+ * @serverbee-widget {
+ *   "id": "com.example.hello",
+ *   "version": "1.0.0",
+ *   "name": "Hello",
+ *   "description": "A minimal example widget.",
+ *   "author": "Your Name",
+ *   "category": "Real-time",
+ *   "sizing": { "defaultW": 3, "defaultH": 2, "minW": 2, "minH": 2, "strategy": "free" },
+ *   "sdkVersion": "^0.1.0"
+ * }
+ */
+import { defineWidget, useServers, useTheme, z } from '@serverbee/widget-sdk'
+
+const ConfigSchema = z.object({
+  greeting: z.string().describe('Greeting text').default('Hello, ServerBee')
+})
+
+export default defineWidget({
+  configSchema: ConfigSchema,
+  component: ({ config }) => {
+    const servers = useServers()
+    const theme = useTheme()
+    const online = servers.filter((s) => s.online).length
+    const { greeting } = config
+    return (
+      <div style={{ padding: 12 }}>
+        <div style={{ fontSize: 16, fontWeight: 600 }}>{greeting}</div>
+        <div style={{ marginTop: 8, color: 'var(--muted-foreground)' }}>
+          {online} / {servers.length} online · {theme.mode} mode
+        </div>
+      </div>
+    )
+  }
+})
+```
+
+### Manifest fields
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `id` | yes | Reverse-DNS-style unique identifier, e.g. `com.example.cpu` |
+| `version` | yes | Semantic version `MAJOR.MINOR.PATCH` |
+| `name` | yes | Display name in the widget picker |
+| `description` | – | Free-form description |
+| `author` | – | Author name or organization |
+| `category` | yes | One of `Real-time`, `Charts`, `Status` |
+| `sizing.defaultW/H` | yes | Default width / height in grid cells |
+| `sizing.minW/H` | yes | Minimum allowed size |
+| `sizing.maxW/H` | – | Optional maximum size |
+| `sizing.strategy` | yes | `free` / `fixed` / `aspect-square` / `content-height` |
+| `sdkVersion` | yes | SDK version range, e.g. `^0.1.0` |
+
+### Build requirements
+
+A custom widget must be built as an **ES module** with the following dependencies marked `external`:
+
+- `react`
+- `react/jsx-runtime`
+- `@serverbee/widget-sdk`
+
+Just as important: the **JSDoc manifest comment must be preserved verbatim at the top of the output**. Most minifiers strip comments by default, so explicitly opt into preserving the manifest comment.
+
+A typical Vite + Terser config:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    lib: {
+      entry: 'src/index.tsx',
+      formats: ['es'],
+      fileName: () => 'index.js'
+    },
+    rollupOptions: {
+      external: ['react', 'react/jsx-runtime', '@serverbee/widget-sdk']
+    },
+    minify: 'terser',
+    terserOptions: {
+      format: {
+        // Keep the @serverbee-widget manifest comment.
+        comments: /@serverbee-widget/
+      }
+    }
+  }
+})
+```
+
+### Install via UI
+
+1. Sign in as an admin.
+2. Open **Settings → Widget Modules**.
+3. Choose **Upload `.js`** to upload a local file, or **Import URL** to fetch over HTTPS.
+4. Once installed, open any dashboard, click **Edit → Add Widget**, and the new widget appears in the picker.
+
+### Install via API
+
+```bash
+# Upload a local file
+curl -X POST "https://your-host/api/widget-modules" \
+  -H "X-API-Key: $SERVERBEE_API_KEY" \
+  -F file=@my.widget.js
+
+# Fetch from URL
+curl -X POST "https://your-host/api/widget-modules?url=https://cdn.example.com/my.widget.js" \
+  -H "X-API-Key: $SERVERBEE_API_KEY"
+```
+
+On success:
+
+```json
+{ "data": { "id": "com.example.hello", "version": "1.0.0" } }
+```
+
+If a widget with the same `id` already exists, it is upgraded in place — the version, manifest, and code are all replaced.
+
+## Method C — `.zip` collection bundle
+
+A collection lets you install **multiple widgets in a single upload**. Each widget still follows the Method B rules (its own JSDoc manifest, its own entry file). They are simply packaged together in one `.zip`, and a root-level `collection.json` enumerates them.
+
+### Package layout
+
+```
+my-pack.zip
+├── collection.json
+├── weather/
+│   ├── index.js          ← contains the @serverbee-widget manifest
+│   └── icon.svg          ← optional asset
+├── clock/
+│   └── index.js
+└── shared/
+    └── helpers.js        ← optional; not auto-injected — entry files must import as needed
+```
+
+### `collection.json` schema
+
+```json
+{
+  "widgets": [
+    { "entry": "weather/index.js" },
+    { "entry": "clock/index.js" }
+  ]
+}
+```
+
+Constraints:
+
+- `entry` must be a relative path (no leading `/`, no `..`).
+- Must point to a `.js` or `.mjs` file.
+- Every entry file must contain a valid `@serverbee-widget` JSDoc block.
+- Widget `id`s must be **unique within the bundle** — duplicates are rejected.
+
+### Asset resolution
+
+Assets inside the bundle (images, JSON, helper scripts, etc.) are served via `GET /api/widget-modules/{id}/{relative-path}`. The relative path is resolved against the **folder of the entry file**:
+
+| Request URL | Resolved zip path |
+|-------------|-------------------|
+| `/api/widget-modules/com.example.weather/index.js` | `weather/index.js` |
+| `/api/widget-modules/com.example.weather/icon.svg` | `weather/icon.svg` |
+| `/api/widget-modules/com.example.clock/index.js` | `clock/index.js` |
+
+Reference assets from widget code like this:
+
+```ts
+const iconUrl = `/api/widget-modules/com.example.weather/icon.svg`
+```
+
+Note: widgets cannot reach into each other's folders — asset resolution is scoped per `id`.
+
+### Build and pack
+
+1. Use your bundler of choice (Vite, tsup, esbuild, ...) to build each widget's `index.js`, externalizing React and the SDK and preserving the manifest comment.
+2. Lay the build outputs out in the directory structure above.
+3. Write `collection.json` at the package root.
+4. Zip it:
+
+```bash
+zip -r my-pack.zip collection.json weather/ clock/
+```
+
+### Install
+
+The UI flow is identical to Method B — just upload the `.zip`. The server sniffs the `PK\x03\x04` magic bytes and dispatches automatically.
+
+```bash
+curl -X POST "https://your-host/api/widget-modules" \
+  -H "X-API-Key: $SERVERBEE_API_KEY" \
+  -F file=@my-pack.zip
+```
+
+A collection install returns an **array** — one entry per widget in the bundle:
+
+```json
+{
+  "data": [
+    { "id": "com.example.weather", "version": "1.0.0" },
+    { "id": "com.example.clock",   "version": "1.0.0" }
+  ]
+}
+```
+
+Each widget gets its own row in the database and can be enabled, disabled, or uninstalled individually. They share a single underlying zip blob for storage.
+
+## Sizing strategies
+
+`sizing.strategy` controls how a widget can be resized on the dashboard:
+
+- `free` — user can resize freely between `minW/H` and `maxW/H`.
+- `fixed` — locked to `defaultW/H`; resizing is disabled.
+- `aspect-square` — always 1:1; snaps to the nearest tier.
+- `content-height` — width is resizable; height is driven by content.
+
+See [Dashboards & Widgets](/en/docs/dashboards) for more on layout and editing.
+
+## SDK surface at a glance
+
+`@serverbee/widget-sdk` is the stable API exposed to custom widgets. It includes:
+
+- `defineWidget` — declares a widget's entry point.
+- `z` / `ZodSchema` — bundled Zod for describing config schemas.
+- Data hooks: `useServers`, `useServer`, `useMetric`, `useHistory`, `useTraffic`, `useAlerts`, `useServiceMonitors`, `useUptime`, `useGeoIp`.
+- Host hooks: `useTheme`, `useConfigUpdate`, `useCapability`.
+- Generic escape hatches: `useApiQuery` / `useApiMutation` for direct REST calls.
+- `createActionsHelper` and `ActionDefinition` for registering action buttons on a widget.
+
+See `packages/widget-sdk/README.md` in the repo for the complete API reference.
+
+## Uninstall
+
+Click the delete button next to a widget in **Settings → Widget Modules**, or:
+
+```bash
+curl -X DELETE "https://your-host/api/widget-modules/com.example.hello" \
+  -H "X-API-Key: $SERVERBEE_API_KEY"
+```
+
+Built-in widgets (for example `com.serverbee.hello-world`) cannot be uninstalled — `DELETE` against them returns `400`.
+
+## Limits and safety
+
+- **Size cap**: a single `.js` file or `.zip` may not exceed **1 MiB**; each entry inside the zip is capped at **5 MiB** uncompressed.
+- **SSRF protection**: URL installs reject private, loopback, and link-local addresses outright.
+- **Zip-slip protection**: extraction rejects entries with `..` or absolute paths.
+- **Static parsing only**: the manifest must be extractable with a plain regex — there is no `eval` / `Function()` involved in installation.
+- **Admin-gated**: install and uninstall endpoints require admin privileges; members can only list and fetch served assets.
+- **Same-origin execution**: widgets run in the same browsing context as the main SPA — only install code from sources you trust.
+
+<Cards>
+  <Card title="Dashboards & Widgets" href="/en/docs/dashboards" />
+  <Card title="Capabilities" href="/en/docs/capabilities" />
+  <Card title="API Reference" href="/en/docs/api-reference" />
+</Cards>
diff --git a/apps/docs/content/docs/en/index.mdx b/apps/docs/content/docs/en/index.mdx
index 342281ce..aff15379 100644
--- a/apps/docs/content/docs/en/index.mdx
+++ b/apps/docs/content/docs/en/index.mdx
@@ -57,7 +57,7 @@ All communication between agents and the server happens over WebSocket with JSON
   <Card title="Ping Monitoring" href="/en/docs/ping" />
   <Card title="Capabilities" href="/en/docs/capabilities" />
   <Card title="Status Pages" href="/en/docs/status-page" />
-  <Card title="Custom Themes & Branding" href="/en/docs/custom-themes" />
+  <Card title="Custom Widgets" href="/en/docs/custom-widgets" />
   <Card title="iOS Mobile" href="/en/docs/mobile" />
   <Card title="Security" href="/en/docs/security" />
   <Card title="Admin Guide" href="/en/docs/admin" />
diff --git a/apps/docs/content/docs/en/meta.json b/apps/docs/content/docs/en/meta.json
index 325c16c5..f82f07cf 100644
--- a/apps/docs/content/docs/en/meta.json
+++ b/apps/docs/content/docs/en/meta.json
@@ -21,8 +21,7 @@
     "ip-quality",
     "capabilities",
     "status-page",
-    "custom-themes",
-    "custom-frontend",
+    "custom-widgets",
     "mobile",
     "---Administration---",
     "security",
diff --git a/apps/docs/content/docs/en/status-page.mdx b/apps/docs/content/docs/en/status-page.mdx
index 0baa1bc8..a366ca10 100644
--- a/apps/docs/content/docs/en/status-page.mdx
+++ b/apps/docs/content/docs/en/status-page.mdx
@@ -161,7 +161,7 @@ Create example:
 To set a custom theme during update, pass `theme_ref`, for example `"preset:default"` or a custom theme reference. Use `null` to follow the admin default.
 
 <Cards>
-  <Card title="Custom Themes" href="/en/docs/custom-themes" />
+  <Card title="Custom Widgets" href="/en/docs/custom-widgets" />
   <Card title="Service Monitors" href="/en/docs/service-monitors" />
   <Card title="Alerts & Notifications" href="/en/docs/alerts" />
 </Cards>

From 5532ecb85a54f5e08bbf7e145ee89ff8ca4ce9e5 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 22:28:48 +0800
Subject: [PATCH 39/64] feat(server): add module_id column to dashboard_widget

Introduce a nullable module_id column so a widget row can reference
an installed widget module. Legacy widgets remain unaffected
(module_id stays NULL).
---
 crates/server/src/entity/dashboard_widget.rs  |  1 +
 ...60528_000070_dashboard_widget_module_id.rs | 22 +++++++++++++++++++
 crates/server/src/migration/mod.rs            |  2 ++
 crates/server/src/service/dashboard.rs        | 19 +++++++++++++++-
 4 files changed, 43 insertions(+), 1 deletion(-)
 create mode 100644 crates/server/src/migration/m20260528_000070_dashboard_widget_module_id.rs

diff --git a/crates/server/src/entity/dashboard_widget.rs b/crates/server/src/entity/dashboard_widget.rs
index 3c02d7d7..ba311ca1 100644
--- a/crates/server/src/entity/dashboard_widget.rs
+++ b/crates/server/src/entity/dashboard_widget.rs
@@ -8,6 +8,7 @@ pub struct Model {
     pub id: String,
     pub dashboard_id: String,
     pub widget_type: String,
+    pub module_id: Option<String>,
     pub title: Option<String>,
     pub config_json: String,
     pub grid_x: i32,
diff --git a/crates/server/src/migration/m20260528_000070_dashboard_widget_module_id.rs b/crates/server/src/migration/m20260528_000070_dashboard_widget_module_id.rs
new file mode 100644
index 00000000..82d33702
--- /dev/null
+++ b/crates/server/src/migration/m20260528_000070_dashboard_widget_module_id.rs
@@ -0,0 +1,22 @@
+use sea_orm_migration::prelude::*;
+
+#[derive(DeriveMigrationName)]
+pub struct Migration;
+
+#[async_trait::async_trait]
+impl MigrationTrait for Migration {
+    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        manager
+            .alter_table(
+                Table::alter()
+                    .table(Alias::new("dashboard_widget"))
+                    .add_column(ColumnDef::new(Alias::new("module_id")).string().null())
+                    .to_owned(),
+            )
+            .await
+    }
+
+    async fn down(&self, _: &SchemaManager) -> Result<(), DbErr> {
+        Ok(())
+    }
+}
diff --git a/crates/server/src/migration/mod.rs b/crates/server/src/migration/mod.rs
index 9fa1c182..87630d3b 100644
--- a/crates/server/src/migration/mod.rs
+++ b/crates/server/src/migration/mod.rs
@@ -38,6 +38,7 @@ mod m20260526_000035_create_spa_themes;
 mod m20260526_000036_simplify_status_page;
 mod m20260528_000037_create_widget_module;
 mod m20260528_000060_drop_legacy_theme_tables;
+mod m20260528_000070_dashboard_widget_module_id;
 
 pub struct Migrator;
 
@@ -82,6 +83,7 @@ impl MigratorTrait for Migrator {
             Box::new(m20260526_000036_simplify_status_page::Migration),
             Box::new(m20260528_000037_create_widget_module::Migration),
             Box::new(m20260528_000060_drop_legacy_theme_tables::Migration),
+            Box::new(m20260528_000070_dashboard_widget_module_id::Migration),
         ]
     }
 }
diff --git a/crates/server/src/service/dashboard.rs b/crates/server/src/service/dashboard.rs
index ad98a1a0..12407f85 100644
--- a/crates/server/src/service/dashboard.rs
+++ b/crates/server/src/service/dashboard.rs
@@ -40,6 +40,8 @@ pub struct UpdateDashboardInput {
 pub struct WidgetInput {
     pub id: Option<String>,
     pub widget_type: String,
+    #[serde(default)]
+    pub module_id: Option<String>,
     pub title: Option<String>,
     pub config_json: serde_json::Value,
     pub grid_x: i32,
@@ -153,7 +155,13 @@ impl DashboardService {
         // Validate widget types
         if let Some(ref widgets) = input.widgets {
             for w in widgets {
-                if !VALID_WIDGET_TYPES.contains(&w.widget_type.as_str()) {
+                if w.widget_type == "module" {
+                    if w.module_id.is_none() {
+                        return Err(AppError::BadRequest(
+                            "widget_type 'module' requires module_id".into(),
+                        ));
+                    }
+                } else if !VALID_WIDGET_TYPES.contains(&w.widget_type.as_str()) {
                     return Err(AppError::BadRequest(format!(
                         "Unknown widget_type: {}",
                         w.widget_type
@@ -206,6 +214,7 @@ impl DashboardService {
                         id: Set(wid),
                         dashboard_id: Set(id.to_string()),
                         widget_type: Set(w.widget_type),
+                        module_id: Set(w.module_id),
                         title: Set(w.title),
                         config_json: Set(config_str),
                         grid_x: Set(w.grid_x),
@@ -223,6 +232,7 @@ impl DashboardService {
                         id: Set(new_id),
                         dashboard_id: Set(id.to_string()),
                         widget_type: Set(w.widget_type),
+                        module_id: Set(w.module_id),
                         title: Set(w.title),
                         config_json: Set(config_str),
                         grid_x: Set(w.grid_x),
@@ -310,6 +320,7 @@ impl DashboardService {
                 id: Set(Uuid::new_v4().to_string()),
                 dashboard_id: Set(dash_id.clone()),
                 widget_type: Set(wtype.to_string()),
+                module_id: Set(None),
                 title: Set(None),
                 config_json: Set(config.to_string()),
                 grid_x: Set(x),
@@ -433,6 +444,7 @@ mod tests {
                     WidgetInput {
                         id: None,
                         widget_type: "gauge".to_string(),
+                        module_id: None,
                         title: Some("CPU".to_string()),
                         config_json: serde_json::json!({"metric": "cpu"}),
                         grid_x: 0,
@@ -444,6 +456,7 @@ mod tests {
                     WidgetInput {
                         id: None,
                         widget_type: "gauge".to_string(),
+                        module_id: None,
                         title: Some("Memory".to_string()),
                         config_json: serde_json::json!({"metric": "memory"}),
                         grid_x: 4,
@@ -474,6 +487,7 @@ mod tests {
                     WidgetInput {
                         id: Some(keep_id.clone()),
                         widget_type: "gauge".to_string(),
+                        module_id: None,
                         title: Some("CPU Updated".to_string()),
                         config_json: serde_json::json!({"metric": "cpu"}),
                         grid_x: 0,
@@ -485,6 +499,7 @@ mod tests {
                     WidgetInput {
                         id: None,
                         widget_type: "markdown".to_string(),
+                        module_id: None,
                         title: Some("Notes".to_string()),
                         config_json: serde_json::json!({"content": "hello"}),
                         grid_x: 6,
@@ -617,6 +632,7 @@ mod tests {
                 widgets: Some(vec![WidgetInput {
                     id: None,
                     widget_type: "nonexistent-widget".to_string(),
+                    module_id: None,
                     title: None,
                     config_json: serde_json::json!({}),
                     grid_x: 0,
@@ -734,6 +750,7 @@ mod tests {
                 widgets: Some(vec![WidgetInput {
                     id: None,
                     widget_type: "gauge".to_string(),
+                    module_id: None,
                     title: Some("CPU".to_string()),
                     config_json: serde_json::json!({}),
                     grid_x: 0,

From d813f550e7c9042d82cfec350e20fa13b97ab726 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 22:28:55 +0800
Subject: [PATCH 40/64] feat(web): widget picker surfaces installed modules

Add a Custom Widgets section in the picker that lists every entry from
the widget registry. Picking a module records widget_type='module' with
module_id on the dashboard editor draft, using the manifest's default
sizing. The picker callback now passes a structured selection
({type:'builtin', widgetType} | {type:'module', moduleId, manifest}) so
the editor can distinguish the two paths cleanly.
---
 .../dashboard/dashboard-editor-view.test.tsx  |  7 ++-
 .../dashboard/dashboard-editor-view.tsx       | 24 +++++++-
 .../components/dashboard/widget-picker.tsx    | 57 ++++++++++++++++++-
 .../src/hooks/use-dashboard-editor.test.tsx   |  1 +
 apps/web/src/hooks/use-dashboard-editor.ts    | 13 +++--
 apps/web/src/hooks/use-dashboard.ts           |  1 +
 apps/web/src/lib/widget-types.ts              |  1 +
 apps/web/src/locales/en/dashboard.json        |  5 ++
 apps/web/src/locales/zh/dashboard.json        |  5 ++
 9 files changed, 103 insertions(+), 11 deletions(-)

diff --git a/apps/web/src/components/dashboard/dashboard-editor-view.test.tsx b/apps/web/src/components/dashboard/dashboard-editor-view.test.tsx
index acb01e54..b796192c 100644
--- a/apps/web/src/components/dashboard/dashboard-editor-view.test.tsx
+++ b/apps/web/src/components/dashboard/dashboard-editor-view.test.tsx
@@ -65,11 +65,11 @@ vi.mock('./widget-picker', () => ({
     open
   }: {
     onOpenChange: (open: boolean) => void
-    onSelect: (widgetType: string) => void
+    onSelect: (selection: { type: 'builtin'; widgetType: string }) => void
     open: boolean
   }) =>
     open ? (
-      <button onClick={() => onSelect('line-chart')} type="button">
+      <button onClick={() => onSelect({ type: 'builtin', widgetType: 'line-chart' })} type="button">
         pick-line-chart
       </button>
     ) : null
@@ -195,6 +195,7 @@ describe('DashboardEditorView', () => {
       {
         id: 'w-1',
         widget_type: 'stat-number',
+        module_id: null,
         title: 'CPU',
         config_json: { metric: 'avg_cpu' },
         grid_x: 4,
@@ -260,6 +261,7 @@ describe('DashboardEditorView', () => {
       {
         id: 'w-1',
         widget_type: 'stat-number',
+        module_id: null,
         title: 'CPU',
         config_json: { metric: 'avg_cpu' },
         grid_x: 0,
@@ -332,6 +334,7 @@ describe('DashboardEditorView', () => {
       {
         id: 'w-1',
         widget_type: 'stat-number',
+        module_id: null,
         title: 'CPU updated',
         config_json: { metric: 'avg_mem' },
         grid_x: 0,
diff --git a/apps/web/src/components/dashboard/dashboard-editor-view.tsx b/apps/web/src/components/dashboard/dashboard-editor-view.tsx
index 9aeda131..af5cb210 100644
--- a/apps/web/src/components/dashboard/dashboard-editor-view.tsx
+++ b/apps/web/src/components/dashboard/dashboard-editor-view.tsx
@@ -10,7 +10,7 @@ import type { Dashboard, DashboardWithWidgets } from '@/lib/widget-types'
 import { DashboardGrid } from './dashboard-grid'
 import { DashboardSwitcher } from './dashboard-switcher'
 import { WidgetConfigDialog } from './widget-config-dialog'
-import { WidgetPicker } from './widget-picker'
+import { WidgetPicker, type WidgetPickerSelection } from './widget-picker'
 
 interface DashboardEditorViewProps {
   activeDashboardId: string
@@ -100,10 +100,28 @@ export function DashboardEditorView({
     handleCancel()
   }
 
-  function handlePickerSelect(widgetType: string) {
+  function handlePickerSelect(selection: WidgetPickerSelection) {
     setPickerOpen(false)
     setEditingWidgetId(null)
-    setConfigWidgetType(widgetType)
+    if (selection.type === 'module') {
+      // Modules currently use their own configSchema; we add directly with an empty
+      // config object instead of opening the legacy config dialog (which is built
+      // around hard-coded form variants per builtin widget type).
+      if (isDashboardReady && dashboard) {
+        const sizing = selection.manifest.sizing
+        editor.addWidget({
+          dashboardId: dashboard.id,
+          widgetType: 'module',
+          moduleId: selection.moduleId,
+          title: selection.manifest.name,
+          configJson: '{}',
+          gridW: sizing.defaultW ?? 4,
+          gridH: sizing.defaultH ?? 3
+        })
+      }
+      return
+    }
+    setConfigWidgetType(selection.widgetType)
     setConfigOpen(true)
   }
 
diff --git a/apps/web/src/components/dashboard/widget-picker.tsx b/apps/web/src/components/dashboard/widget-picker.tsx
index 89ba775e..457630e1 100644
--- a/apps/web/src/components/dashboard/widget-picker.tsx
+++ b/apps/web/src/components/dashboard/widget-picker.tsx
@@ -1,3 +1,4 @@
+import type { WidgetManifest } from '@serverbee/widget-sdk'
 import {
   Activity,
   BarChart3,
@@ -10,6 +11,7 @@ import {
   LineChart,
   List,
   Network,
+  Puzzle,
   Server,
   TrendingUp
 } from 'lucide-react'
@@ -18,10 +20,15 @@ import { useTranslation } from 'react-i18next'
 import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog'
 import { ScrollArea } from '@/components/ui/scroll-area'
 import { WIDGET_TYPES, type WidgetCategory } from '@/lib/widget-types'
+import { useWidgetRegistry } from '@/widgets-runtime/registry'
+
+export type WidgetPickerSelection =
+  | { type: 'builtin'; widgetType: string }
+  | { type: 'module'; moduleId: string; manifest: WidgetManifest }
 
 interface WidgetPickerProps {
   onOpenChange: (open: boolean) => void
-  onSelect: (widgetType: string) => void
+  onSelect: (selection: WidgetPickerSelection) => void
   open: boolean
 }
 
@@ -46,6 +53,7 @@ const CATEGORY_ORDER: WidgetCategory[] = ['Real-time', 'Charts', 'Status']
 
 export function WidgetPicker({ onSelect, open, onOpenChange }: WidgetPickerProps) {
   const { t } = useTranslation('dashboard')
+  const moduleEntries = useWidgetRegistry((s) => s.modules)
 
   const grouped = useMemo(() => {
     const map = new Map<WidgetCategory, (typeof WIDGET_TYPES)[number][]>()
@@ -58,6 +66,8 @@ export function WidgetPicker({ onSelect, open, onOpenChange }: WidgetPickerProps
     return map
   }, [])
 
+  const modules = useMemo(() => Array.from(moduleEntries.values()), [moduleEntries])
+
   return (
     <Dialog onOpenChange={onOpenChange} open={open}>
       <DialogContent className="sm:max-h-[80vh] sm:max-w-lg">
@@ -86,7 +96,7 @@ export function WidgetPicker({ onSelect, open, onOpenChange }: WidgetPickerProps
                           className="flex items-start gap-3 rounded-lg border bg-card p-3 text-left transition-colors hover:bg-muted/50"
                           key={widgetType.id}
                           onClick={() => {
-                            onSelect(widgetType.id)
+                            onSelect({ type: 'builtin', widgetType: widgetType.id })
                             onOpenChange(false)
                           }}
                           type="button"
@@ -105,6 +115,49 @@ export function WidgetPicker({ onSelect, open, onOpenChange }: WidgetPickerProps
                 </div>
               )
             })}
+
+            <div>
+              <h4 className="mb-2 font-medium text-muted-foreground text-xs uppercase tracking-wide">
+                {t('picker_custom_widgets', 'Custom Widgets')}
+              </h4>
+              {modules.length === 0 ? (
+                <p className="rounded-lg border border-dashed bg-card p-3 text-muted-foreground text-xs">
+                  {t('picker_no_custom_widgets', 'No custom widgets installed yet.')}
+                </p>
+              ) : (
+                <div className="grid gap-2 sm:grid-cols-2">
+                  {modules.map((entry) => {
+                    const manifest = entry.manifest
+                    return (
+                      <button
+                        className="flex items-start gap-3 rounded-lg border bg-card p-3 text-left transition-colors hover:bg-muted/50"
+                        key={manifest.id}
+                        onClick={() => {
+                          onSelect({ type: 'module', moduleId: manifest.id, manifest })
+                          onOpenChange(false)
+                        }}
+                        type="button"
+                      >
+                        <div className="rounded-md bg-muted p-1.5">
+                          <Puzzle className="size-4 text-muted-foreground" />
+                        </div>
+                        <div className="min-w-0">
+                          <p className="font-medium text-sm leading-tight">{manifest.name}</p>
+                          {manifest.description && (
+                            <p className="mt-0.5 text-muted-foreground text-xs leading-snug">{manifest.description}</p>
+                          )}
+                          {manifest.author && (
+                            <p className="mt-0.5 text-[10px] text-muted-foreground/70 leading-snug">
+                              {manifest.author}
+                            </p>
+                          )}
+                        </div>
+                      </button>
+                    )
+                  })}
+                </div>
+              )}
+            </div>
           </div>
         </ScrollArea>
       </DialogContent>
diff --git a/apps/web/src/hooks/use-dashboard-editor.test.tsx b/apps/web/src/hooks/use-dashboard-editor.test.tsx
index 86cd275a..d821bb80 100644
--- a/apps/web/src/hooks/use-dashboard-editor.test.tsx
+++ b/apps/web/src/hooks/use-dashboard-editor.test.tsx
@@ -144,6 +144,7 @@ describe('useDashboardEditor', () => {
     expect(result.current.buildSaveInput()[0]).toEqual({
       id: undefined,
       widget_type: 'stat-number',
+      module_id: null,
       title: null,
       config_json: { metric: 'avg_mem', window: 5 },
       grid_x: 0,
diff --git a/apps/web/src/hooks/use-dashboard-editor.ts b/apps/web/src/hooks/use-dashboard-editor.ts
index b8f4bcb1..49b918da 100644
--- a/apps/web/src/hooks/use-dashboard-editor.ts
+++ b/apps/web/src/hooks/use-dashboard-editor.ts
@@ -12,6 +12,9 @@ import type { WidgetInput } from './use-dashboard'
 interface AddWidgetInput {
   configJson: string
   dashboardId: string
+  gridH?: number
+  gridW?: number
+  moduleId?: string | null
   title: string | null
   widgetType: string
 }
@@ -56,18 +59,19 @@ export function useDashboardEditor() {
     setDraftWidgets((current) => mergeLayoutPatch(current, patch))
   }
 
-  function addWidget({ configJson, dashboardId, title, widgetType }: AddWidgetInput) {
+  function addWidget({ configJson, dashboardId, gridH, gridW, moduleId, title, widgetType }: AddWidgetInput) {
     setDraftWidgets((current) => {
-      const { grid_h, grid_w } = getWidgetTypeDefaults(widgetType)
+      const defaults = getWidgetTypeDefaults(widgetType)
       const newWidget: DashboardWidget = {
         config_json: configJson,
         created_at: new Date().toISOString(),
         dashboard_id: dashboardId,
-        grid_h,
-        grid_w,
+        grid_h: gridH ?? defaults.grid_h,
+        grid_w: gridW ?? defaults.grid_w,
         grid_x: 0,
         grid_y: Number.POSITIVE_INFINITY,
         id: `temp-${crypto.randomUUID()}`,
+        module_id: moduleId ?? null,
         sort_order: current.length,
         title,
         widget_type: widgetType
@@ -105,6 +109,7 @@ export function useDashboardEditor() {
     return draftWidgets.map((widget) => ({
       id: widget.id.startsWith('temp-') ? undefined : widget.id,
       widget_type: widget.widget_type,
+      module_id: widget.module_id ?? null,
       title: widget.title,
       config_json: parseConfig(widget.config_json),
       grid_x: widget.grid_x,
diff --git a/apps/web/src/hooks/use-dashboard.ts b/apps/web/src/hooks/use-dashboard.ts
index c0af08de..f398fcef 100644
--- a/apps/web/src/hooks/use-dashboard.ts
+++ b/apps/web/src/hooks/use-dashboard.ts
@@ -15,6 +15,7 @@ export interface WidgetInput {
   grid_x: number
   grid_y: number
   id?: string
+  module_id?: string | null
   sort_order: number
   title?: string | null
   widget_type: string
diff --git a/apps/web/src/lib/widget-types.ts b/apps/web/src/lib/widget-types.ts
index a23c379b..c720df04 100644
--- a/apps/web/src/lib/widget-types.ts
+++ b/apps/web/src/lib/widget-types.ts
@@ -297,6 +297,7 @@ export interface DashboardWidget {
   grid_x: number
   grid_y: number
   id: string
+  module_id?: string | null
   sort_order: number
   title: string | null
   widget_type: string
diff --git a/apps/web/src/locales/en/dashboard.json b/apps/web/src/locales/en/dashboard.json
index 930c6d57..148dea77 100644
--- a/apps/web/src/locales/en/dashboard.json
+++ b/apps/web/src/locales/en/dashboard.json
@@ -32,6 +32,11 @@
   "dashboard_name_placeholder": "Dashboard name",
   "no_widgets_title": "No widgets yet",
   "no_widgets_description": "Click Edit to start adding widgets to your dashboard",
+  "picker_custom_widgets": "Custom Widgets",
+  "picker_no_custom_widgets": "No custom widgets installed yet.",
+  "module_not_installed": "Widget module not installed",
+  "module_not_installed_id": "Widget module \"{{id}}\" not installed",
+  "module_config_invalid": "Widget config invalid: {{message}}",
   "widgetPicker": {
     "categories": {
       "Real-time": "Real-time",
diff --git a/apps/web/src/locales/zh/dashboard.json b/apps/web/src/locales/zh/dashboard.json
index 5417ac42..4b2cf78e 100644
--- a/apps/web/src/locales/zh/dashboard.json
+++ b/apps/web/src/locales/zh/dashboard.json
@@ -32,6 +32,11 @@
   "dashboard_name_placeholder": "仪表盘名称",
   "no_widgets_title": "暂无小组件",
   "no_widgets_description": "点击编辑开始向仪表盘添加小组件",
+  "picker_custom_widgets": "自定义组件",
+  "picker_no_custom_widgets": "尚未安装自定义组件。",
+  "module_not_installed": "组件模块未安装",
+  "module_not_installed_id": "组件模块 \"{{id}}\" 未安装",
+  "module_config_invalid": "组件配置无效：{{message}}",
   "widgetPicker": {
     "categories": {
       "Real-time": "实时",

From 0983710ee1593513de2d829dfdf6d2b2f75ab766 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 22:33:15 +0800
Subject: [PATCH 41/64] feat(web): WidgetRenderer dispatches module widgets to
 registry

When a widget row has widget_type='module', look up its module_id in
the runtime registry and render the registered component with the
parsed config. Render clear placeholders for the not-installed and
invalid-config cases. Includes a renderer test that registers a fake
module and asserts the component output appears.
---
 .../dashboard/module-widget-host.tsx          | 70 +++++++++++++++++++
 .../dashboard/widget-renderer.test.tsx        | 52 +++++++++++++-
 .../components/dashboard/widget-renderer.tsx  |  5 ++
 3 files changed, 125 insertions(+), 2 deletions(-)
 create mode 100644 apps/web/src/components/dashboard/module-widget-host.tsx

diff --git a/apps/web/src/components/dashboard/module-widget-host.tsx b/apps/web/src/components/dashboard/module-widget-host.tsx
new file mode 100644
index 00000000..bf5a0356
--- /dev/null
+++ b/apps/web/src/components/dashboard/module-widget-host.tsx
@@ -0,0 +1,70 @@
+import type { ActionsHelper } from '@serverbee/widget-sdk'
+import { useMemo } from 'react'
+import { useTranslation } from 'react-i18next'
+import type { ServerMetrics } from '@/hooks/use-servers-ws'
+import { parseConfig } from '@/lib/widget-helpers'
+import type { DashboardWidget } from '@/lib/widget-types'
+import { registryActions } from '@/widgets-runtime/registry'
+
+interface ModuleWidgetHostProps {
+  servers: ServerMetrics[]
+  widget: DashboardWidget
+}
+
+const NOOP_ACTIONS: ActionsHelper = {
+  render: () => null
+}
+
+function Placeholder({ message }: { message: string }) {
+  return (
+    <div className="flex h-full items-center justify-center rounded-lg border border-dashed bg-card p-4 text-center text-muted-foreground text-sm">
+      {message}
+    </div>
+  )
+}
+
+export function ModuleWidgetHost({ widget, servers: _servers }: ModuleWidgetHostProps) {
+  const { t } = useTranslation('dashboard')
+  const moduleId = widget.module_id ?? ''
+  const entry = useMemo(() => (moduleId ? registryActions.get(moduleId) : undefined), [moduleId])
+
+  const parsed = useMemo(() => {
+    if (!entry) {
+      return { ok: false as const, error: '' }
+    }
+    const raw = parseConfig<unknown>(widget.config_json)
+    try {
+      const config = entry.module.configSchema.parse(raw)
+      return { ok: true as const, config }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      return { ok: false as const, error: message }
+    }
+  }, [entry, widget.config_json])
+
+  if (!moduleId) {
+    return <Placeholder message={t('module_not_installed', 'Widget module not installed')} />
+  }
+  if (!entry) {
+    return (
+      <Placeholder message={t('module_not_installed_id', 'Widget module "{{id}}" not installed', { id: moduleId })} />
+    )
+  }
+  if (!parsed.ok) {
+    return (
+      <Placeholder
+        message={t('module_config_invalid', 'Widget config invalid: {{message}}', { message: parsed.error })}
+      />
+    )
+  }
+
+  const Component = entry.module.component
+  return (
+    <Component
+      actions={NOOP_ACTIONS}
+      config={parsed.config}
+      isEditing={false}
+      size={{ w: widget.grid_w, h: widget.grid_h }}
+    />
+  )
+}
diff --git a/apps/web/src/components/dashboard/widget-renderer.test.tsx b/apps/web/src/components/dashboard/widget-renderer.test.tsx
index 3321f197..6f05024c 100644
--- a/apps/web/src/components/dashboard/widget-renderer.test.tsx
+++ b/apps/web/src/components/dashboard/widget-renderer.test.tsx
@@ -1,7 +1,9 @@
+import type { WidgetManifest, WidgetModule } from '@serverbee/widget-sdk'
 import { render, screen } from '@testing-library/react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import type { ServerMetrics } from '@/hooks/use-servers-ws'
 import type { DashboardWidget } from '@/lib/widget-types'
+import { registryActions, useWidgetRegistry } from '@/widgets-runtime/registry'
 import { WidgetRenderer } from './widget-renderer'
 
 const { renderCounts } = vi.hoisted(() => ({
@@ -62,7 +64,11 @@ vi.mock('./widgets/uptime-timeline-widget', () => ({
   UptimeTimelineWidget: () => <div data-testid="widget-uptime-timeline">uptime-timeline</div>
 }))
 
-function makeWidget(widgetType: string, config: Record<string, unknown> = {}): DashboardWidget {
+function makeWidget(
+  widgetType: string,
+  config: Record<string, unknown> = {},
+  extra: Partial<DashboardWidget> = {}
+): DashboardWidget {
   return {
     id: 'w-1',
     dashboard_id: 'dash-1',
@@ -74,7 +80,8 @@ function makeWidget(widgetType: string, config: Record<string, unknown> = {}): D
     grid_w: 4,
     grid_h: 3,
     sort_order: 0,
-    created_at: '2026-03-20T00:00:00Z'
+    created_at: '2026-03-20T00:00:00Z',
+    ...extra
   }
 }
 
@@ -131,6 +138,8 @@ const WIDGET_TYPES = [
   'uptime-timeline'
 ] as const
 
+const NOT_INSTALLED_RE = /not installed/i
+
 describe('WidgetRenderer', () => {
   beforeEach(() => {
     renderCounts.gauge = 0
@@ -202,4 +211,43 @@ describe('WidgetRenderer', () => {
 
     expect(renderCounts.gauge).toBe(2)
   })
+
+  describe('module widgets', () => {
+    beforeEach(() => {
+      useWidgetRegistry.setState({ modules: new Map(), failures: new Map() })
+    })
+
+    const fakeManifest: WidgetManifest = {
+      id: 'com.test.fake',
+      version: '1.0.0',
+      name: 'Fake',
+      category: 'Real-time',
+      sizing: { defaultW: 2, defaultH: 2, minW: 1, minH: 1, strategy: 'free' },
+      sdkVersion: '^0.1.0'
+    }
+
+    function makeFakeModule(component: WidgetModule['component']): WidgetModule {
+      return {
+        __brand: 'WidgetModule',
+        configSchema: { parse: (v: unknown) => v } as unknown as WidgetModule['configSchema'],
+        component,
+        actions: []
+      }
+    }
+
+    it('renders the registered module component', () => {
+      registryActions.register(
+        'com.test.fake',
+        makeFakeModule(() => <div data-testid="fake-module">hello from module</div>),
+        fakeManifest
+      )
+      render(<WidgetRenderer servers={[]} widget={makeWidget('module', {}, { module_id: 'com.test.fake' })} />)
+      expect(screen.getByTestId('fake-module')).toBeInTheDocument()
+    })
+
+    it('shows a placeholder when the referenced module is not installed', () => {
+      render(<WidgetRenderer servers={[]} widget={makeWidget('module', {}, { module_id: 'com.test.missing' })} />)
+      expect(screen.getByText(NOT_INSTALLED_RE)).toBeInTheDocument()
+    })
+  })
 })
diff --git a/apps/web/src/components/dashboard/widget-renderer.tsx b/apps/web/src/components/dashboard/widget-renderer.tsx
index 087c9192..7909f084 100644
--- a/apps/web/src/components/dashboard/widget-renderer.tsx
+++ b/apps/web/src/components/dashboard/widget-renderer.tsx
@@ -18,6 +18,7 @@ import type {
   TrafficBarConfig,
   UptimeTimelineConfig
 } from '@/lib/widget-types'
+import { ModuleWidgetHost } from './module-widget-host'
 import { areWidgetServerDependenciesEqual } from './widget-render-dependencies'
 import { AlertListWidget } from './widgets/alert-list'
 import { DiskIoWidget } from './widgets/disk-io'
@@ -85,6 +86,10 @@ function ErrorFallback() {
 function WidgetContent({ widget, servers }: WidgetRendererProps) {
   const config = useMemo(() => parseConfig<Record<string, unknown>>(widget.config_json), [widget.config_json])
 
+  if (widget.widget_type === 'module') {
+    return <ModuleWidgetHost servers={servers} widget={widget} />
+  }
+
   switch (widget.widget_type) {
     case 'stat-number':
       return <StatNumberWidget config={config as unknown as StatNumberConfig} servers={servers} />

From 72457e219fdd96165ac6df4a8163ee4162f4afac Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 22:40:54 +0800
Subject: [PATCH 42/64] build(server): ensure builtin-widgets dist dir exists
 pre-embed

---
 crates/server/build.rs | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 crates/server/build.rs

diff --git a/crates/server/build.rs b/crates/server/build.rs
new file mode 100644
index 00000000..31fbc603
--- /dev/null
+++ b/crates/server/build.rs
@@ -0,0 +1,11 @@
+//! Ensure the directory `rust-embed` reads from at compile time exists, even
+//! when the frontend has never been built in this checkout. Without this, a
+//! cold `cargo build` of `serverbee-server` from a fresh clone fails because
+//! `#[folder = "../../apps/web/dist/builtin-widgets"]` expects the path to
+//! resolve. The empty dir is enough: the runtime registrar logs a friendly
+//! warning when `manifest.json` is missing.
+fn main() {
+    let dir = std::path::Path::new("../../apps/web/dist/builtin-widgets");
+    let _ = std::fs::create_dir_all(dir);
+    println!("cargo:rerun-if-changed=../../apps/web/dist/builtin-widgets");
+}

From f1a007ccc6df72a4b98a4f65d88c51b61a63a5b6 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 22:41:14 +0800
Subject: [PATCH 43/64] fix(server): cap source size for widget manifest regex
 extraction

---
 crates/server/src/service/widget_module/extractor.rs | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/crates/server/src/service/widget_module/extractor.rs b/crates/server/src/service/widget_module/extractor.rs
index f37554f5..97488993 100644
--- a/crates/server/src/service/widget_module/extractor.rs
+++ b/crates/server/src/service/widget_module/extractor.rs
@@ -46,8 +46,19 @@ static SEMVER_RE: Lazy<Regex> = Lazy::new(|| Regex::new(r"^\d+\.\d+\.\d+(-[\w.]+
 static SEMVER_RANGE_RE: Lazy<Regex> =
     Lazy::new(|| Regex::new(r"^[\^~]?\d+\.\d+\.\d+").unwrap());
 
+/// Hard cap on input length we'll regex-scan for a `@serverbee-widget` JSDoc
+/// block. The regex is already bounded by JSDoc start/end markers but feeding
+/// a multi-megabyte string to `Regex::captures` is a cheap DoS vector; reject
+/// up front. 1 MiB is well above any realistic single JS file we accept.
+pub const MAX_SOURCE_BYTES_FOR_REGEX: usize = 1_048_576;
+
 pub fn extract_manifest(source: &str) -> Result<WidgetManifest, super::WidgetModuleError> {
     use super::WidgetModuleError as E;
+    if source.len() > MAX_SOURCE_BYTES_FOR_REGEX {
+        return Err(E::ManifestValidation(
+            "source too large for manifest extraction".into(),
+        ));
+    }
     let captures = JSDOC_RE
         .captures(source)
         .ok_or_else(|| E::ManifestExtraction("no @serverbee-widget JSDoc block found".into()))?;

From 95718350dab1eaa5f3b6f6bc8c2ee3e24456e872 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 22:44:23 +0800
Subject: [PATCH 44/64] fix(server): cap widget zip total uncompressed bytes
 and entry count

---
 .../src/service/widget_module/package.rs       | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/crates/server/src/service/widget_module/package.rs b/crates/server/src/service/widget_module/package.rs
index d5a38e5e..c206b2da 100644
--- a/crates/server/src/service/widget_module/package.rs
+++ b/crates/server/src/service/widget_module/package.rs
@@ -16,13 +16,23 @@ impl UnpackedPackage {
         Self { entries }
     }
 
-    /// Unpack a zip blob (defends against zip-slip and oversize entries).
+    /// Unpack a zip blob (defends against zip-slip, oversize entries, and
+    /// zip-bomb style total uncompressed size or excessive entry counts).
     pub fn from_zip(blob: &[u8]) -> Result<Self, WidgetModuleError> {
         const MAX_ENTRY_BYTES: u64 = 5 * 1024 * 1024;
+        const MAX_ZIP_ENTRIES: usize = 64;
+        const MAX_TOTAL_UNCOMPRESSED: u64 = 32 * 1024 * 1024;
+
         let reader = Cursor::new(blob);
         let mut zip = zip::ZipArchive::new(reader)
             .map_err(|e| WidgetModuleError::ManifestExtraction(format!("invalid zip: {e}")))?;
+        if zip.len() > MAX_ZIP_ENTRIES {
+            return Err(WidgetModuleError::ManifestExtraction(
+                "too many entries".into(),
+            ));
+        }
         let mut entries = HashMap::new();
+        let mut total: u64 = 0;
         for i in 0..zip.len() {
             let mut entry = zip
                 .by_index(i)
@@ -40,6 +50,12 @@ impl UnpackedPackage {
                     "entry too large: {name}"
                 )));
             }
+            total = total.saturating_add(entry.size());
+            if total > MAX_TOTAL_UNCOMPRESSED {
+                return Err(WidgetModuleError::ManifestExtraction(
+                    "zip too large".into(),
+                ));
+            }
             let mut buf = Vec::with_capacity(entry.size() as usize);
             entry
                 .read_to_end(&mut buf)

From 1d078d3c1a91a5261e086c315970afbdb86d4ac0 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 22:44:51 +0800
Subject: [PATCH 45/64] fix(server): widget module install + asset hardening
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Reject install when id collides with an existing module of a different
  source_type (spec §3.5: Builtin must not be silently overwritten by an
  Upload/Url upsert). Returns 409 Conflict.
- Introduce WidgetModuleError::AssetNotFound mapped to HTTP 404; reserve
  InvalidAssetPath for actual traversal attempts (still 400).
- serve_asset now returns a ServedAsset { bytes, mime, version,
  code_sha256 } so the route can build ETag + Cache-Control headers
  without a second DB read.
- Extend mime_for with .wasm, .html, .txt, .md so module bundles can
  ship companion docs/assets without falling back to octet-stream.
---
 .../server/src/service/widget_module/error.rs |  6 +-
 .../src/service/widget_module/service.rs      | 78 ++++++++++++++++---
 2 files changed, 72 insertions(+), 12 deletions(-)

diff --git a/crates/server/src/service/widget_module/error.rs b/crates/server/src/service/widget_module/error.rs
index e74fbbb2..1238af56 100644
--- a/crates/server/src/service/widget_module/error.rs
+++ b/crates/server/src/service/widget_module/error.rs
@@ -10,6 +10,8 @@ pub enum WidgetModuleError {
     IdConflict(String),
     #[error("module not found: {0}")]
     NotFound(String),
+    #[error("asset not found: {0}")]
+    AssetNotFound(String),
     #[error("invalid asset path")]
     InvalidAssetPath,
     #[error("database: {0}")]
@@ -19,7 +21,9 @@ pub enum WidgetModuleError {
 impl From<WidgetModuleError> for AppError {
     fn from(err: WidgetModuleError) -> Self {
         match err {
-            WidgetModuleError::NotFound(msg) => AppError::NotFound(msg),
+            WidgetModuleError::NotFound(msg) | WidgetModuleError::AssetNotFound(msg) => {
+                AppError::NotFound(msg)
+            }
             WidgetModuleError::IdConflict(msg) => AppError::Conflict(msg),
             WidgetModuleError::InvalidAssetPath
             | WidgetModuleError::ManifestExtraction(_)
diff --git a/crates/server/src/service/widget_module/service.rs b/crates/server/src/service/widget_module/service.rs
index 95560d42..b4767ed0 100644
--- a/crates/server/src/service/widget_module/service.rs
+++ b/crates/server/src/service/widget_module/service.rs
@@ -3,7 +3,16 @@ use serde::Serialize;
 use utoipa::ToSchema;
 
 use super::{WidgetModuleError, package::UnpackedPackage};
-use crate::entity::widget_module::{self, Entity as WidgetModuleEntity};
+use crate::entity::widget_module::{self, Entity as WidgetModuleEntity, SourceType};
+
+/// Asset bytes plus the per-row metadata callers need to set caching headers
+/// without re-querying the database.
+pub struct ServedAsset {
+    pub bytes: Vec<u8>,
+    pub mime: String,
+    pub version: String,
+    pub code_sha256: String,
+}
 
 #[derive(Debug, Clone)]
 pub enum InstalledFrom {
@@ -65,22 +74,24 @@ impl WidgetModuleService {
             .ok_or_else(|| WidgetModuleError::NotFound(id.to_string()))
     }
 
-    /// Loads the package and returns bytes + mime for a requested asset path.
+    /// Loads the package and returns bytes + mime + ETag inputs for a requested
+    /// asset path. The route layer wraps these into HTTP cache headers without
+    /// needing a second database round-trip.
     pub async fn serve_asset(
         db: &DatabaseConnection,
         id: &str,
         requested: &str,
-    ) -> Result<(Vec<u8>, String), WidgetModuleError> {
+    ) -> Result<ServedAsset, WidgetModuleError> {
         let row = Self::get(db, id).await?;
 
         if requested.contains("..") {
             return Err(WidgetModuleError::InvalidAssetPath);
         }
 
-        if matches!(
-            row.source_type,
-            crate::entity::widget_module::SourceType::Builtin
-        ) {
+        let version = row.version.clone();
+        let code_sha256 = row.code_sha256.clone();
+
+        if matches!(row.source_type, SourceType::Builtin) {
             // Builtin: the URL `/api/widget-modules/<id>/<requested>` resolves to a path
             // within the embedded directory. `row.entry_path` is the module's main file
             // (e.g. "hello-world/index.js"); we resolve `requested` relative to its folder.
@@ -95,8 +106,13 @@ impl WidgetModuleService {
                 format!("{folder}/{requested}")
             };
             let bytes = crate::service::widget_module::builtin::builtin_asset_bytes(&full)
-                .ok_or(WidgetModuleError::InvalidAssetPath)?;
-            return Ok((bytes, mime_for(&full)));
+                .ok_or_else(|| WidgetModuleError::AssetNotFound(requested.to_string()))?;
+            return Ok(ServedAsset {
+                bytes,
+                mime: mime_for(&full),
+                version,
+                code_sha256,
+            });
         }
 
         let blob = row
@@ -130,10 +146,15 @@ impl WidgetModuleService {
 
         let bytes = package
             .get(&lookup_path)
-            .ok_or(WidgetModuleError::InvalidAssetPath)?
+            .ok_or_else(|| WidgetModuleError::AssetNotFound(requested.to_string()))?
             .to_vec();
         let mime = mime_for(&lookup_path);
-        Ok((bytes, mime))
+        Ok(ServedAsset {
+            bytes,
+            mime,
+            version,
+            code_sha256,
+        })
     }
 
     /// Install (or upgrade) a single-file JS widget module by extracting the
@@ -167,6 +188,19 @@ impl WidgetModuleService {
             InstalledFrom::Upload(name) => (SourceType::Upload, Some(name)),
         };
 
+        // Reject if an existing row owns this id under a different source_type.
+        // Spec §3.5: a user-uploaded module must never silently overwrite a
+        // builtin (or vice versa) — those are separate trust domains.
+        if let Some(existing) =
+            widget_module::Entity::find_by_id(manifest.id.clone()).one(db).await?
+            && existing.source_type != source_type
+        {
+            return Err(WidgetModuleError::IdConflict(format!(
+                "id {} already installed as {:?}",
+                manifest.id, existing.source_type
+            )));
+        }
+
         let manifest_json = serde_json::to_string(&manifest).map_err(|e| {
             WidgetModuleError::ManifestValidation(format!("serialize manifest: {e}"))
         })?;
@@ -316,6 +350,20 @@ impl WidgetModuleService {
             InstalledFrom::Upload(name) => (SourceType::Upload, Some(name)),
         };
 
+        // Reject the whole collection up front if any id collides with an
+        // existing row owned by a different source_type (e.g. Builtin).
+        for (manifest, _, _) in prepared.iter() {
+            if let Some(existing) =
+                widget_module::Entity::find_by_id(manifest.id.clone()).one(db).await?
+                && existing.source_type != source_type
+            {
+                return Err(WidgetModuleError::IdConflict(format!(
+                    "id {} already installed as {:?}",
+                    manifest.id, existing.source_type
+                )));
+            }
+        }
+
         let now = Utc::now();
         let mut installed: Vec<widget_module::Model> = Vec::with_capacity(prepared.len());
 
@@ -401,6 +449,14 @@ fn mime_for(path: &str) -> String {
         "image/jpeg"
     } else if lower.ends_with(".webp") {
         "image/webp"
+    } else if lower.ends_with(".wasm") {
+        "application/wasm"
+    } else if lower.ends_with(".html") || lower.ends_with(".htm") {
+        "text/html; charset=utf-8"
+    } else if lower.ends_with(".txt") {
+        "text/plain; charset=utf-8"
+    } else if lower.ends_with(".md") {
+        "text/markdown; charset=utf-8"
     } else {
         "application/octet-stream"
     }

From 12efae6e56de1d84609cee64add3280073e6dc4f Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 22:54:36 +0800
Subject: [PATCH 46/64] fix(server): SSRF guard + body cap + audit on widget
 module install

- Replace string-based is_private_host with full IP-resolution SSRF
  guard. The URL's host is resolved via tokio::net::lookup_host and
  every returned address must pass is_public_ip, which rejects
  loopback, private, CGNAT (100.64/10), link-local (incl. cloud
  metadata 169.254.169.254), benchmarking, documentation, multicast,
  and reserved-for-future-use ranges for both IPv4 and IPv6 (incl.
  ULA fc00::/7, fe80::/10, ::ffff:0:0/96 v4-mapped, 2001:db8::/32).
- Disable HTTP redirects on the fetch client and explicitly reject
  3xx responses so a public-IP DNS check cannot be bypassed by a
  Location pointing into the intranet.
- Stream the URL body with a running total instead of buffering the
  full response, aborting early once MAX_MODULE_BYTES is exceeded.
- Apply a tower DefaultBodyLimit::max(MAX_MODULE_BYTES + 64 KiB) to
  the write router so multipart uploads cannot exhaust memory before
  our own checks run.
- Audit log every install (per widget for collection installs) and
  every uninstall via AuditService::log; failures are swallowed so
  audit never blocks the user-visible response.
- Add unit tests covering is_public_ip across v4/v6 reserved ranges.

Adds reqwest stream feature; futures_util was already in the tree.
---
 Cargo.lock                                    |  15 +
 crates/server/Cargo.toml                      |   2 +-
 crates/server/src/router/api/widget_module.rs | 328 +++++++++++++++---
 3 files changed, 299 insertions(+), 46 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index e36af316..3f422ea7 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3302,12 +3302,14 @@ dependencies = [
  "sync_wrapper 1.0.2",
  "tokio",
  "tokio-rustls 0.26.4",
+ "tokio-util",
  "tower",
  "tower-http",
  "tower-service",
  "url",
  "wasm-bindgen",
  "wasm-bindgen-futures",
+ "wasm-streams",
  "web-sys",
  "webpki-roots 1.0.6",
 ]
@@ -5512,6 +5514,19 @@ dependencies = [
  "wasmparser",
 ]
 
+[[package]]
+name = "wasm-streams"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15053d8d85c7eccdbefef60f06769760a563c7f0a9d6902a13d35c7800b0ad65"
+dependencies = [
+ "futures-util",
+ "js-sys",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+]
+
 [[package]]
 name = "wasmparser"
 version = "0.244.0"
diff --git a/crates/server/Cargo.toml b/crates/server/Cargo.toml
index 996f8919..14166f74 100644
--- a/crates/server/Cargo.toml
+++ b/crates/server/Cargo.toml
@@ -39,7 +39,7 @@ once_cell = "1"
 regex = "1"
 rust-embed = { version = "8", features = ["mime-guess"] }
 mime_guess = "2"
-reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "json"] }
+reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "json", "stream"] }
 flate2 = "1"
 html-escape = "0.2"
 maxminddb = "0.27"
diff --git a/crates/server/src/router/api/widget_module.rs b/crates/server/src/router/api/widget_module.rs
index 57d19917..f99ded15 100644
--- a/crates/server/src/router/api/widget_module.rs
+++ b/crates/server/src/router/api/widget_module.rs
@@ -1,20 +1,26 @@
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
 use std::sync::Arc;
 
 use axum::{
     Json, Router,
-    extract::{Extension, Multipart, Path, Query, State},
+    extract::{ConnectInfo, DefaultBodyLimit, Extension, Multipart, Path, Query, State},
     http::{HeaderMap, HeaderValue, StatusCode, header},
     response::IntoResponse,
     routing::{delete, get, post},
 };
+use futures_util::StreamExt;
 use serde::Deserialize;
 
 use crate::{
     error::{ApiResponse, AppError, ok},
     middleware::auth::CurrentUser,
-    service::widget_module::{
-        WidgetModuleService,
-        service::{InstalledFrom, WidgetModuleListEntry},
+    router::utils::extract_client_ip,
+    service::{
+        audit::AuditService,
+        widget_module::{
+            WidgetModuleService,
+            service::{InstalledFrom, WidgetModuleListEntry},
+        },
     },
     state::AppState,
 };
@@ -26,9 +32,13 @@ pub fn read_router() -> Router<Arc<AppState>> {
 }
 
 pub fn write_router() -> Router<Arc<AppState>> {
+    // Apply a per-route body cap so this endpoint cannot be used as a memory
+    // amplifier even before our MAX_MODULE_BYTES check runs. We add a small
+    // headroom over MAX_MODULE_BYTES for multipart envelope overhead.
     Router::new()
         .route("/widget-modules", post(install_widget_module))
         .route("/widget-modules/{id}", delete(uninstall_module))
+        .layer(DefaultBodyLimit::max(MAX_MODULE_BYTES + 65_536))
 }
 
 #[utoipa::path(
@@ -65,15 +75,18 @@ pub async fn serve_asset(
     State(state): State<Arc<AppState>>,
     Path((id, asset_path)): Path<(String, String)>,
 ) -> Result<impl IntoResponse, AppError> {
-    let (bytes, mime) = WidgetModuleService::serve_asset(&state.db, &id, &asset_path).await?;
-    let row = WidgetModuleService::get(&state.db, &id).await?;
-    let etag_suffix_len = 8.min(row.code_sha256.len());
-    let etag = format!("\"{}-{}\"", row.version, &row.code_sha256[..etag_suffix_len]);
+    let served = WidgetModuleService::serve_asset(&state.db, &id, &asset_path).await?;
+    let etag_suffix_len = 8.min(served.code_sha256.len());
+    let etag = format!(
+        "\"{}-{}\"",
+        served.version,
+        &served.code_sha256[..etag_suffix_len]
+    );
 
     let mut headers = HeaderMap::new();
     headers.insert(
         header::CONTENT_TYPE,
-        HeaderValue::from_str(&mime).map_err(|e| AppError::Internal(e.to_string()))?,
+        HeaderValue::from_str(&served.mime).map_err(|e| AppError::Internal(e.to_string()))?,
     );
     headers.insert(
         header::ETAG,
@@ -83,7 +96,7 @@ pub async fn serve_asset(
         header::CACHE_CONTROL,
         HeaderValue::from_static("public, max-age=86400, immutable"),
     );
-    Ok((StatusCode::OK, headers, bytes))
+    Ok((StatusCode::OK, headers, served.bytes))
 }
 
 #[derive(Debug, Deserialize)]
@@ -94,22 +107,129 @@ pub struct InstallQuery {
 /// Max accepted module size (1 MiB) — applies to both URL fetch and multipart upload.
 const MAX_MODULE_BYTES: usize = 1_048_576;
 
-fn is_private_host(host: &str) -> bool {
-    if host == "localhost" || host == "127.0.0.1" || host == "::1" {
-        return true;
-    }
-    if host.starts_with("10.") || host.starts_with("192.168.") {
-        return true;
+/// SSRF guard: rejects an IP that falls into any reserved / private / loopback /
+/// link-local / multicast / documentation range. Cloud metadata (169.254.169.254),
+/// CGNAT (100.64.0.0/10), and IPv6 ULA/link-local/v4-mapped are explicitly covered.
+/// Returns `true` only for addresses that we consider safe to dial from the server.
+pub(crate) fn is_public_ip(ip: IpAddr) -> bool {
+    match ip {
+        IpAddr::V4(v4) => is_public_ipv4(v4),
+        IpAddr::V6(v6) => is_public_ipv6(v6),
     }
-    // 172.16.0.0 – 172.31.255.255
-    if let Some(rest) = host.strip_prefix("172.")
-        && let Some((second, _)) = rest.split_once('.')
-        && let Ok(n) = second.parse::<u8>()
-        && (16..=31).contains(&n)
+}
+
+fn is_public_ipv4(ip: Ipv4Addr) -> bool {
+    if ip.is_unspecified()
+        || ip.is_loopback()
+        || ip.is_private()
+        || ip.is_link_local()
+        || ip.is_broadcast()
+        || ip.is_multicast()
+        || ip.is_documentation()
     {
-        return true;
+        return false;
+    }
+    let [a, b, c, _] = ip.octets();
+    // 100.64.0.0/10 CGNAT
+    if a == 100 && (b & 0b1100_0000) == 0b0100_0000 {
+        return false;
+    }
+    // 192.0.0.0/24 IETF (and 192.0.2.0/24 documentation already filtered by is_documentation)
+    if a == 192 && b == 0 && c == 0 {
+        return false;
+    }
+    // 192.88.99.0/24 (6to4 anycast, deprecated)
+    if a == 192 && b == 88 && c == 99 {
+        return false;
+    }
+    // 198.18.0.0/15 benchmarking
+    if a == 198 && (b == 18 || b == 19) {
+        return false;
+    }
+    // 240.0.0.0/4 reserved for future use (covers 255.255.255.255 too)
+    if a >= 240 {
+        return false;
+    }
+    true
+}
+
+fn is_public_ipv6(ip: Ipv6Addr) -> bool {
+    if ip.is_unspecified() || ip.is_loopback() || ip.is_multicast() {
+        return false;
+    }
+    let segments = ip.segments();
+    // fc00::/7 unique-local
+    if (segments[0] & 0xfe00) == 0xfc00 {
+        return false;
+    }
+    // fe80::/10 link-local
+    if (segments[0] & 0xffc0) == 0xfe80 {
+        return false;
+    }
+    // ::ffff:0:0/96 IPv4-mapped — check octets 0..=9 are zero and 10..=11 are 0xff
+    let octets = ip.octets();
+    if octets[..10] == [0u8; 10] && octets[10] == 0xff && octets[11] == 0xff {
+        // Recurse on the embedded v4 address.
+        let v4 = Ipv4Addr::new(octets[12], octets[13], octets[14], octets[15]);
+        return is_public_ipv4(v4);
+    }
+    // 2001:db8::/32 documentation
+    if segments[0] == 0x2001 && segments[1] == 0x0db8 {
+        return false;
+    }
+    // 100::/64 discard prefix
+    if segments[0] == 0x0100 && segments[1] == 0 && segments[2] == 0 && segments[3] == 0 {
+        return false;
+    }
+    true
+}
+
+/// Resolves the URL's host to its IP addresses and rejects if ANY resolved
+/// address lives in a reserved range. We bias toward false-negatives (refuse
+/// the fetch) because the cost of a wrong allow is "talked to internal box";
+/// the cost of a wrong reject is "user must self-host the module".
+async fn enforce_url_safety(url: &str) -> Result<(), AppError> {
+    let parsed =
+        url::Url::parse(url).map_err(|e| AppError::BadRequest(format!("bad url: {e}")))?;
+    let scheme = parsed.scheme();
+    if scheme != "http" && scheme != "https" {
+        return Err(AppError::BadRequest("url must be http(s)".into()));
+    }
+    let host = parsed
+        .host_str()
+        .ok_or_else(|| AppError::BadRequest("url missing host".into()))?;
+    let port = parsed
+        .port_or_known_default()
+        .ok_or_else(|| AppError::BadRequest("url missing port".into()))?;
+
+    // If the host is a literal IP, check it directly without DNS.
+    if let Ok(ip) = host.parse::<IpAddr>() {
+        if !is_public_ip(ip) {
+            return Err(AppError::BadRequest(
+                "private/loopback/reserved address rejected".into(),
+            ));
+        }
+        return Ok(());
+    }
+
+    let addrs = tokio::net::lookup_host((host, port))
+        .await
+        .map_err(|e| AppError::BadRequest(format!("dns lookup failed: {e}")))?;
+    let mut any = false;
+    for sa in addrs {
+        any = true;
+        if !is_public_ip(sa.ip()) {
+            return Err(AppError::BadRequest(
+                "host resolves to private/reserved address".into(),
+            ));
+        }
     }
-    false
+    if !any {
+        return Err(AppError::BadRequest(
+            "host resolved to no addresses".into(),
+        ));
+    }
+    Ok(())
 }
 
 #[utoipa::path(
@@ -129,35 +249,43 @@ fn is_private_host(host: &str) -> bool {
             description = "Installed (or upgraded) widget module(s). For a single `.js` file the response is `{ data: { id, version } }`. For a `.zip` collection it is `{ data: [{ id, version }, ...] }` — one entry per widget in the collection.",
         ),
         (status = 400, description = "Bad URL, unsupported source, or invalid manifest"),
+        (status = 409, description = "Module id conflicts with an existing install of a different source type"),
     ),
     security(("session_cookie" = []), ("api_key" = []))
 )]
 pub async fn install_widget_module(
     State(state): State<Arc<AppState>>,
+    ConnectInfo(addr): ConnectInfo<std::net::SocketAddr>,
     Extension(user): Extension<CurrentUser>,
     Query(q): Query<InstallQuery>,
+    headers: HeaderMap,
     multipart: Option<Multipart>,
 ) -> Result<Json<ApiResponse<serde_json::Value>>, AppError> {
     let user_id = user.user_id.parse::<i64>().ok();
+    let client_ip = extract_client_ip(
+        &ConnectInfo(addr),
+        &headers,
+        &state.config.server.trusted_proxies,
+    )
+    .to_string();
 
     let (bytes, from) = if let Some(url) = q.url {
-        if !(url.starts_with("https://") || url.starts_with("http://")) {
-            return Err(AppError::BadRequest("url must be http(s)".into()));
-        }
-        let parsed = url::Url::parse(&url)
-            .map_err(|e| AppError::BadRequest(format!("bad url: {e}")))?;
-        if let Some(host) = parsed.host_str()
-            && is_private_host(host)
-        {
-            return Err(AppError::BadRequest(
-                "private/loopback urls rejected".into(),
-            ));
-        }
-        let resp = reqwest::Client::new()
+        enforce_url_safety(&url).await?;
+
+        // Disable redirects: a 3xx Location could re-enter a private address
+        // after the initial public-IP check passed.
+        let client = reqwest::Client::builder()
+            .redirect(reqwest::redirect::Policy::none())
+            .build()
+            .map_err(|e| AppError::Internal(format!("http client: {e}")))?;
+        let resp = client
             .get(&url)
             .send()
             .await
             .map_err(|e| AppError::BadRequest(format!("fetch: {e}")))?;
+        if resp.status().is_redirection() {
+            return Err(AppError::BadRequest("redirects not allowed".into()));
+        }
         if !resp.status().is_success() {
             return Err(AppError::BadRequest(format!(
                 "fetch {}: {}",
@@ -165,15 +293,21 @@ pub async fn install_widget_module(
                 resp.status()
             )));
         }
-        let bytes = resp
-            .bytes()
-            .await
-            .map_err(|e| AppError::Internal(format!("read body: {e}")))?
-            .to_vec();
-        if bytes.len() > MAX_MODULE_BYTES {
-            return Err(AppError::BadRequest("module too large (>1MB)".into()));
+
+        // Stream the body with a running total so we abort early on oversize
+        // responses instead of buffering an unbounded payload.
+        let mut total = 0usize;
+        let mut buf = Vec::with_capacity(64 * 1024);
+        let mut stream = resp.bytes_stream();
+        while let Some(chunk) = stream.next().await {
+            let chunk = chunk.map_err(|e| AppError::Internal(format!("read body: {e}")))?;
+            total += chunk.len();
+            if total > MAX_MODULE_BYTES {
+                return Err(AppError::BadRequest("module too large (>1MB)".into()));
+            }
+            buf.extend_from_slice(&chunk);
         }
-        (bytes, InstalledFrom::Url(url))
+        (buf, InstalledFrom::Url(url))
     } else if let Some(mut mp) = multipart {
         let mut bytes_opt: Option<Vec<u8>> = None;
         let mut name_opt: Option<String> = None;
@@ -213,13 +347,49 @@ pub async fn install_widget_module(
         )
         .await?;
         let payload: Vec<serde_json::Value> = rows
-            .into_iter()
+            .iter()
             .map(|r| serde_json::json!({ "id": r.id, "version": r.version }))
             .collect();
+        // Best-effort audit log per installed widget — failures here must
+        // never poison the install response.
+        for row in rows.iter() {
+            let detail = serde_json::json!({
+                "id": row.id,
+                "version": row.version,
+                "source_type": format!("{:?}", row.source_type),
+                "source_url": row.source_url,
+                "code_sha256": row.code_sha256,
+            })
+            .to_string();
+            let _ = AuditService::log(
+                &state.db,
+                &user.user_id,
+                "widget_module.install",
+                Some(&detail),
+                &client_ip,
+            )
+            .await;
+        }
         ok(serde_json::Value::Array(payload))
     } else {
         let row =
             WidgetModuleService::install_single_file(&state.db, bytes, from, user_id).await?;
+        let detail = serde_json::json!({
+            "id": row.id,
+            "version": row.version,
+            "source_type": format!("{:?}", row.source_type),
+            "source_url": row.source_url,
+            "code_sha256": row.code_sha256,
+        })
+        .to_string();
+        let _ = AuditService::log(
+            &state.db,
+            &user.user_id,
+            "widget_module.install",
+            Some(&detail),
+            &client_ip,
+        )
+        .await;
         ok(serde_json::json!({ "id": row.id, "version": row.version }))
     }
 }
@@ -238,8 +408,76 @@ pub async fn install_widget_module(
 )]
 pub async fn uninstall_module(
     State(state): State<Arc<AppState>>,
+    ConnectInfo(addr): ConnectInfo<std::net::SocketAddr>,
+    Extension(user): Extension<CurrentUser>,
+    headers: HeaderMap,
     Path(id): Path<String>,
 ) -> Result<StatusCode, AppError> {
+    let client_ip = extract_client_ip(
+        &ConnectInfo(addr),
+        &headers,
+        &state.config.server.trusted_proxies,
+    )
+    .to_string();
     WidgetModuleService::uninstall(&state.db, &id).await?;
+    let detail = serde_json::json!({ "id": id }).to_string();
+    let _ = AuditService::log(
+        &state.db,
+        &user.user_id,
+        "widget_module.uninstall",
+        Some(&detail),
+        &client_ip,
+    )
+    .await;
     Ok(StatusCode::NO_CONTENT)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn ipv4_loopback_and_private_rejected() {
+        assert!(!is_public_ip("127.0.0.1".parse().unwrap()));
+        assert!(!is_public_ip("10.1.2.3".parse().unwrap()));
+        assert!(!is_public_ip("172.16.0.1".parse().unwrap()));
+        assert!(!is_public_ip("192.168.1.1".parse().unwrap()));
+        assert!(!is_public_ip("169.254.169.254".parse().unwrap()));
+        assert!(!is_public_ip("100.64.0.1".parse().unwrap()));
+        assert!(!is_public_ip("224.0.0.1".parse().unwrap()));
+        assert!(!is_public_ip("240.0.0.1".parse().unwrap()));
+        assert!(!is_public_ip("255.255.255.255".parse().unwrap()));
+        assert!(!is_public_ip("198.18.0.1".parse().unwrap()));
+        assert!(!is_public_ip("198.51.100.1".parse().unwrap()));
+        assert!(!is_public_ip("203.0.113.1".parse().unwrap()));
+        assert!(!is_public_ip("192.0.2.1".parse().unwrap()));
+        assert!(!is_public_ip("0.0.0.0".parse().unwrap()));
+    }
+
+    #[test]
+    fn ipv4_public_accepted() {
+        assert!(is_public_ip("8.8.8.8".parse().unwrap()));
+        assert!(is_public_ip("1.1.1.1".parse().unwrap()));
+        assert!(is_public_ip("203.0.114.1".parse().unwrap()));
+    }
+
+    #[test]
+    fn ipv6_reserved_rejected() {
+        assert!(!is_public_ip("::1".parse().unwrap()));
+        assert!(!is_public_ip("::".parse().unwrap()));
+        assert!(!is_public_ip("fc00::1".parse().unwrap()));
+        assert!(!is_public_ip("fd12:3456::1".parse().unwrap()));
+        assert!(!is_public_ip("fe80::1".parse().unwrap()));
+        assert!(!is_public_ip("ff02::1".parse().unwrap())); // multicast
+        assert!(!is_public_ip("2001:db8::1".parse().unwrap()));
+        assert!(!is_public_ip("::ffff:127.0.0.1".parse().unwrap()));
+        assert!(!is_public_ip("::ffff:169.254.169.254".parse().unwrap()));
+        assert!(!is_public_ip("0100::1".parse().unwrap()));
+    }
+
+    #[test]
+    fn ipv6_public_accepted() {
+        assert!(is_public_ip("2606:4700:4700::1111".parse().unwrap()));
+        assert!(is_public_ip("::ffff:8.8.8.8".parse().unwrap()));
+    }
+}

From 412ffc23067dd374b98bdc2615a1978c0765890a Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 22:57:27 +0800
Subject: [PATCH 47/64] test(server): widget module SSRF, role, and source-type
 conflict
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Loopback / cloud-metadata / private-CIDR install URLs are rejected.
- Non-admin (member) cannot POST or DELETE on /api/widget-modules.
- Uploading a single-file widget whose id matches a Builtin returns
  409 Conflict (B3 spec §3.5 enforcement).
- An Upload-source row can be upgraded by re-uploading with a higher
  version under the same source_type.

Seeds a member user in start_test_server_with_db so role tests can
log in without bespoke setup.
---
 .../server/tests/widget_module_integration.rs | 237 ++++++++++++++++++
 1 file changed, 237 insertions(+)

diff --git a/crates/server/tests/widget_module_integration.rs b/crates/server/tests/widget_module_integration.rs
index 137b548c..c8eb0165 100644
--- a/crates/server/tests/widget_module_integration.rs
+++ b/crates/server/tests/widget_module_integration.rs
@@ -73,6 +73,10 @@ async fn start_test_server_with_db() -> TestServerContext {
         .await
         .expect("Failed to seed admin");
 
+    AuthService::create_user(&db, "member", "memberpass", "member")
+        .await
+        .expect("Failed to seed member");
+
     let state_db = db.clone();
     let state = AppState::new(state_db, config)
         .await
@@ -719,6 +723,239 @@ async fn install_zip_entry_with_dotdot_is_400() {
     assert_eq!(res.status(), 400);
 }
 
+async fn login_member(client: &Client, base_url: &str) {
+    let resp = client
+        .post(format!("{base_url}/api/auth/login"))
+        .json(&json!({ "username": "member", "password": "memberpass" }))
+        .send()
+        .await
+        .expect("Login request failed");
+    assert_eq!(resp.status(), 200, "member login should succeed");
+}
+
+// ---------- B3: id collision across source_types ----------
+
+#[tokio::test]
+async fn install_rejects_collision_with_builtin_source_type() {
+    let ctx = start_test_server_with_db().await;
+    serverbee_server::service::widget_module::builtin::register_all(&ctx.db)
+        .await
+        .expect("register builtin widgets");
+
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    // Upload a single-file widget whose id matches the Builtin hello-world.
+    let code = r#"/**
+ * @serverbee-widget {
+ *   "id": "com.serverbee.hello-world",
+ *   "version": "9.9.9",
+ *   "name": "Hijacked",
+ *   "category": "Real-time",
+ *   "sizing": { "defaultW": 2, "defaultH": 2, "minW": 1, "minH": 1, "strategy": "free" },
+ *   "sdkVersion": "^0.1.0"
+ * }
+ */
+export default {};"#;
+    let form = reqwest::multipart::Form::new().part(
+        "file",
+        reqwest::multipart::Part::bytes(code.as_bytes().to_vec())
+            .file_name("hijack.js"),
+    );
+
+    let res = client
+        .post(format!("{}/api/widget-modules", ctx.base_url))
+        .multipart(form)
+        .send()
+        .await
+        .expect("install request failed");
+    assert_eq!(
+        res.status(),
+        409,
+        "upload colliding with Builtin id must return 409 Conflict"
+    );
+}
+
+#[tokio::test]
+async fn install_allows_upgrade_of_same_source_type() {
+    let ctx = start_test_server_with_db().await;
+
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    let body_v1 = r#"/**
+ * @serverbee-widget {
+ *   "id": "com.test.upgradeable",
+ *   "version": "1.0.0",
+ *   "name": "Up",
+ *   "category": "Real-time",
+ *   "sizing": { "defaultW": 2, "defaultH": 2, "minW": 1, "minH": 1, "strategy": "free" },
+ *   "sdkVersion": "^0.1.0"
+ * }
+ */
+export default {};"#;
+    let form = reqwest::multipart::Form::new().part(
+        "file",
+        reqwest::multipart::Part::bytes(body_v1.as_bytes().to_vec()).file_name("up.js"),
+    );
+    let res = client
+        .post(format!("{}/api/widget-modules", ctx.base_url))
+        .multipart(form)
+        .send()
+        .await
+        .expect("first install failed");
+    assert_eq!(res.status(), 200);
+
+    let body_v2 = r#"/**
+ * @serverbee-widget {
+ *   "id": "com.test.upgradeable",
+ *   "version": "1.1.0",
+ *   "name": "Up",
+ *   "category": "Real-time",
+ *   "sizing": { "defaultW": 2, "defaultH": 2, "minW": 1, "minH": 1, "strategy": "free" },
+ *   "sdkVersion": "^0.1.0"
+ * }
+ */
+export default {};"#;
+    let form2 = reqwest::multipart::Form::new().part(
+        "file",
+        reqwest::multipart::Part::bytes(body_v2.as_bytes().to_vec()).file_name("up.js"),
+    );
+    let res2 = client
+        .post(format!("{}/api/widget-modules", ctx.base_url))
+        .multipart(form2)
+        .send()
+        .await
+        .expect("upgrade install failed");
+    assert_eq!(
+        res2.status(),
+        200,
+        "upgrading an existing Upload-source row should succeed"
+    );
+    let body: serde_json::Value = res2.json().await.expect("invalid JSON");
+    assert_eq!(body["data"]["version"], "1.1.0");
+}
+
+// ---------- B4: SSRF guard ----------
+
+#[tokio::test]
+async fn install_rejects_loopback_url() {
+    let ctx = start_test_server_with_db().await;
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    let res = client
+        .post(format!(
+            "{}/api/widget-modules?url=http://127.0.0.1:9527/widget.js",
+            ctx.base_url
+        ))
+        .send()
+        .await
+        .expect("install request failed");
+    assert_eq!(
+        res.status(),
+        400,
+        "loopback url must be rejected by SSRF guard"
+    );
+}
+
+#[tokio::test]
+async fn install_rejects_link_local_metadata_url() {
+    let ctx = start_test_server_with_db().await;
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    let res = client
+        .post(format!(
+            "{}/api/widget-modules?url=http://169.254.169.254/latest/meta-data/",
+            ctx.base_url
+        ))
+        .send()
+        .await
+        .expect("install request failed");
+    assert_eq!(
+        res.status(),
+        400,
+        "cloud metadata url must be rejected by SSRF guard"
+    );
+}
+
+#[tokio::test]
+async fn install_rejects_private_cidr_url() {
+    let ctx = start_test_server_with_db().await;
+    let client = http_client();
+    login_admin(&client, &ctx.base_url).await;
+
+    let res = client
+        .post(format!(
+            "{}/api/widget-modules?url=http://10.0.0.1/widget.js",
+            ctx.base_url
+        ))
+        .send()
+        .await
+        .expect("install request failed");
+    assert_eq!(res.status(), 400);
+}
+
+// ---------- I14: member role denied ----------
+
+#[tokio::test]
+async fn install_rejects_member_role() {
+    let ctx = start_test_server_with_db().await;
+    let client = http_client();
+    login_member(&client, &ctx.base_url).await;
+
+    let code = r#"/**
+ * @serverbee-widget {
+ *   "id": "com.test.member-attempt",
+ *   "version": "1.0.0",
+ *   "name": "X",
+ *   "category": "Real-time",
+ *   "sizing": { "defaultW": 2, "defaultH": 2, "minW": 1, "minH": 1, "strategy": "free" },
+ *   "sdkVersion": "^0.1.0"
+ * }
+ */
+export default {};"#;
+    let form = reqwest::multipart::Form::new().part(
+        "file",
+        reqwest::multipart::Part::bytes(code.as_bytes().to_vec()).file_name("x.js"),
+    );
+    let res = client
+        .post(format!("{}/api/widget-modules", ctx.base_url))
+        .multipart(form)
+        .send()
+        .await
+        .expect("install request failed");
+    assert_eq!(
+        res.status(),
+        403,
+        "member must not be able to POST widget-modules"
+    );
+}
+
+#[tokio::test]
+async fn uninstall_rejects_member_role() {
+    let ctx = start_test_server_with_db().await;
+    seed_module(&ctx.db, "com.test.foo").await;
+
+    let client = http_client();
+    login_member(&client, &ctx.base_url).await;
+
+    let res = client
+        .delete(format!(
+            "{}/api/widget-modules/com.test.foo",
+            ctx.base_url
+        ))
+        .send()
+        .await
+        .expect("delete request failed");
+    assert_eq!(
+        res.status(),
+        403,
+        "member must not be able to DELETE widget-modules"
+    );
+}
+
 #[tokio::test]
 async fn install_zip_entry_missing_jsdoc_is_400() {
     let ctx = start_test_server_with_db().await;

From 98f2992257e3fe407d5e99ece0fbf4f64b219621 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:04:47 +0800
Subject: [PATCH 48/64] feat(widget-sdk): introspect API + drop as any in form
 rendering

Add a public ZodSchema.introspect() that exposes kind/label/default/optional
plus shape (for object) and values (for enum), so renderers no longer reach
into private fields via 'as any'. Form's top-level renderer now consumes
introspect() and tests cover all schema kinds.
---
 packages/widget-sdk/src/form/index.tsx  |  8 +++---
 packages/widget-sdk/src/z/primitives.ts | 30 ++++++++++++++++++++++
 packages/widget-sdk/tests/z.test.ts     | 33 +++++++++++++++++++++++++
 3 files changed, 68 insertions(+), 3 deletions(-)

diff --git a/packages/widget-sdk/src/form/index.tsx b/packages/widget-sdk/src/form/index.tsx
index 6de110d2..0f5f388d 100644
--- a/packages/widget-sdk/src/form/index.tsx
+++ b/packages/widget-sdk/src/form/index.tsx
@@ -7,14 +7,16 @@ export function renderConfigForm(
   value: Record<string, unknown>,
   onChange: (v: Record<string, unknown>) => void
 ): ReactNode {
-  if ((schema as any)._kind !== 'object') {
+  const info = schema.introspect()
+  if (info.kind !== 'object' || !info.shape) {
     return <em>Top-level schema must be z.object()</em>
   }
-  const shape = (schema as any).shape as Record<string, ZodTypeAny>
+  const shape = info.shape
   return (
     <div>
       {Object.entries(shape).map(([key, fieldSchema]) => {
-        const label = (fieldSchema as any)._label ?? key
+        const fieldInfo = fieldSchema.introspect()
+        const label = fieldInfo.label ?? key
         const id = `cfg-${key}`
         return (
           <div key={key} style={{ marginBottom: 8 }}>
diff --git a/packages/widget-sdk/src/z/primitives.ts b/packages/widget-sdk/src/z/primitives.ts
index 96e81eae..186a2d3c 100644
--- a/packages/widget-sdk/src/z/primitives.ts
+++ b/packages/widget-sdk/src/z/primitives.ts
@@ -3,6 +3,15 @@ import { ZError } from './validate'
 export type Infer<T> = T extends ZodSchema<infer U> ? U : never
 export type ZodTypeAny = ZodSchema<any>
 
+export interface SchemaIntrospection<T = unknown> {
+  default?: T
+  kind: string
+  label?: string
+  optional: boolean
+  shape?: Record<string, ZodTypeAny>
+  values?: readonly string[]
+}
+
 export abstract class ZodSchema<T> {
   abstract _kind: string
   _label?: string
@@ -37,6 +46,27 @@ export abstract class ZodSchema<T> {
     this._optional = true
     return this
   }
+
+  /**
+   * Public, type-safe introspection of schema metadata for form renderers and
+   * other tooling. Avoids reaching into private `_kind` / `shape` / `values`
+   * via `as any`. Subclasses may expose `shape` (for object) or `values`
+   * (for enum) — they are surfaced here in a tagged shape.
+   */
+  introspect(): SchemaIntrospection<T> {
+    const self = this as unknown as {
+      shape?: Record<string, ZodTypeAny>
+      values?: readonly string[]
+    }
+    return {
+      kind: this._kind,
+      label: this._label,
+      default: this._default,
+      optional: this._optional,
+      shape: self.shape,
+      values: self.values
+    }
+  }
 }
 
 class ZString extends ZodSchema<string> {
diff --git a/packages/widget-sdk/tests/z.test.ts b/packages/widget-sdk/tests/z.test.ts
index 95cc36ac..3a2374ad 100644
--- a/packages/widget-sdk/tests/z.test.ts
+++ b/packages/widget-sdk/tests/z.test.ts
@@ -80,3 +80,36 @@ describe('z extensions', () => {
     expect(() => s.parse('bogus')).toThrow()
   })
 })
+
+describe('ZodSchema.introspect', () => {
+  it('reports kind/label/default/optional', () => {
+    const s = z.string().describe('Name').default('anon').optional()
+    const info = s.introspect()
+    expect(info.kind).toBe('string')
+    expect(info.label).toBe('Name')
+    expect(info.default).toBe('anon')
+    expect(info.optional).toBe(true)
+  })
+
+  it('exposes shape for z.object()', () => {
+    const s = z.object({ a: z.string(), b: z.number() })
+    const info = s.introspect()
+    expect(info.kind).toBe('object')
+    expect(info.shape).toBeDefined()
+    expect(Object.keys(info.shape ?? {})).toEqual(['a', 'b'])
+  })
+
+  it('exposes values for z.enum()', () => {
+    const s = z.enum(['x', 'y', 'z'] as const)
+    const info = s.introspect()
+    expect(info.kind).toBe('enum')
+    expect(info.values).toEqual(['x', 'y', 'z'])
+  })
+
+  it('reports extension kinds', () => {
+    expect(z.metricPath().introspect().kind).toBe('metricPath')
+    expect(z.color().introspect().kind).toBe('color')
+    expect(z.duration().introspect().kind).toBe('duration')
+    expect(z.serverId().introspect().kind).toBe('serverId')
+  })
+})

From 148fb58954453afa4e8c9ef6d4018153c162c303 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:10:38 +0800
Subject: [PATCH 49/64] feat(widget-sdk): real form renderers for metricPath /
 color / duration

Replace the generic text-input fallback with purpose-built widgets:
- metricPath: text input + datalist seeded from runtime.getMetricPaths()
  (optional host hook) with a baseline of well-known paths
- color: native <input type=color>
- duration: text input with pattern + placeholder + title hint

All three drop through cleanly when the schema kind doesn't match and are
covered by new vitest cases.
---
 .../widget-sdk/src/form/field-renderers.tsx   | 81 ++++++++++++++++++-
 packages/widget-sdk/tests/form.test.tsx       | 27 +++++++
 2 files changed, 104 insertions(+), 4 deletions(-)

diff --git a/packages/widget-sdk/src/form/field-renderers.tsx b/packages/widget-sdk/src/form/field-renderers.tsx
index 3cd46305..058b3bc9 100644
--- a/packages/widget-sdk/src/form/field-renderers.tsx
+++ b/packages/widget-sdk/src/form/field-renderers.tsx
@@ -9,9 +9,41 @@ interface FieldProps {
   value: unknown
 }
 
+const METRIC_PATH_SUGGESTIONS = [
+  'cpu.total',
+  'cpu_cores',
+  'memory.used_pct',
+  'mem_used',
+  'mem_total',
+  'load1',
+  'load5',
+  'load15',
+  'net_in_speed',
+  'net_out_speed',
+  'disk_used',
+  'disk_total'
+]
+
+function getMetricPathSuggestions(): string[] {
+  try {
+    const rt = getRuntime() as ReturnType<typeof getRuntime> & {
+      getMetricPaths?: () => string[]
+    }
+    if (typeof rt.getMetricPaths === 'function') {
+      const fromHost = rt.getMetricPaths()
+      if (Array.isArray(fromHost) && fromHost.length > 0) {
+        return fromHost
+      }
+    }
+  } catch {
+    // runtime not installed — fall back to defaults
+  }
+  return METRIC_PATH_SUGGESTIONS
+}
+
 export function renderField(props: FieldProps) {
-  const kind = (props.schema as any)._kind
-  switch (kind) {
+  const info = props.schema.introspect()
+  switch (info.kind) {
     case 'string':
       return (
         <input
@@ -40,7 +72,7 @@ export function renderField(props: FieldProps) {
         />
       )
     case 'enum': {
-      const opts = (props.schema as any).values as string[]
+      const opts = (info.values ?? []) as readonly string[]
       return (
         <select id={props.id} onChange={(e) => props.onChange(e.target.value)} value={(props.value as string) ?? ''}>
           {opts.map((o) => (
@@ -64,8 +96,49 @@ export function renderField(props: FieldProps) {
         </select>
       )
     }
+    case 'metricPath': {
+      const suggestions = getMetricPathSuggestions()
+      const listId = `${props.id}-paths`
+      return (
+        <>
+          <input
+            id={props.id}
+            list={listId}
+            onChange={(e) => props.onChange(e.target.value)}
+            placeholder="cpu.total"
+            type="text"
+            value={(props.value as string) ?? ''}
+          />
+          <datalist id={listId}>
+            {suggestions.map((path) => (
+              <option key={path} value={path} />
+            ))}
+          </datalist>
+        </>
+      )
+    }
+    case 'color':
+      return (
+        <input
+          id={props.id}
+          onChange={(e) => props.onChange(e.target.value)}
+          type="color"
+          value={(props.value as string) ?? '#000000'}
+        />
+      )
+    case 'duration':
+      return (
+        <input
+          id={props.id}
+          onChange={(e) => props.onChange(e.target.value)}
+          pattern="^\d+(s|m|h|d)$"
+          placeholder="30s"
+          title="Examples: 30s, 5m, 1h, 7d"
+          type="text"
+          value={(props.value as string) ?? ''}
+        />
+      )
     default:
-      // metricPath / color / duration → text input
       return (
         <input
           id={props.id}
diff --git a/packages/widget-sdk/tests/form.test.tsx b/packages/widget-sdk/tests/form.test.tsx
index 21eda989..6e7ea8ca 100644
--- a/packages/widget-sdk/tests/form.test.tsx
+++ b/packages/widget-sdk/tests/form.test.tsx
@@ -48,4 +48,31 @@ describe('renderConfigForm', () => {
     render(<Wrapper initial={{ srv: 's1' }} schema={schema} />)
     expect(screen.getByLabelText('Server')).toBeTruthy()
   })
+
+  it('renders a metric path text+datalist for z.metricPath()', () => {
+    const schema = z.object({ path: z.metricPath().describe('Metric path') })
+    render(<Wrapper initial={{ path: 'cpu.total' }} schema={schema} />)
+    const input = screen.getByLabelText('Metric path') as HTMLInputElement
+    expect(input.tagName).toBe('INPUT')
+    expect(input.type).toBe('text')
+    expect(input.getAttribute('list')).toBeTruthy()
+    expect(input.value).toBe('cpu.total')
+  })
+
+  it('renders a color picker for z.color()', () => {
+    const schema = z.object({ tint: z.color().describe('Tint') })
+    render(<Wrapper initial={{ tint: '#ff8800' }} schema={schema} />)
+    const input = screen.getByLabelText('Tint') as HTMLInputElement
+    expect(input.type).toBe('color')
+    expect(input.value).toBe('#ff8800')
+  })
+
+  it('renders a duration input with pattern for z.duration()', () => {
+    const schema = z.object({ every: z.duration().describe('Every') })
+    render(<Wrapper initial={{ every: '30s' }} schema={schema} />)
+    const input = screen.getByLabelText('Every') as HTMLInputElement
+    expect(input.type).toBe('text')
+    expect(input.getAttribute('pattern')).toBe('^\\d+(s|m|h|d)$')
+    expect(input.value).toBe('30s')
+  })
 })

From 531145b007f10d5df7d59fa0349d3b56015e4019 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:11:30 +0800
Subject: [PATCH 50/64] feat(widget-sdk): reject duplicate action ids + drop
 component as-any cast

defineWidget now throws on duplicate action ids (caught at registration
time instead of producing confusing runtime behavior where actions.find()
silently picks the first match). Also remove the redundant 'as any' cast on
component now that the generic propagates correctly through WidgetModule.
---
 packages/widget-sdk/src/define-widget.ts        | 12 ++++++++++--
 packages/widget-sdk/tests/define-widget.test.ts | 13 +++++++++++++
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/packages/widget-sdk/src/define-widget.ts b/packages/widget-sdk/src/define-widget.ts
index ed60d999..3876683c 100644
--- a/packages/widget-sdk/src/define-widget.ts
+++ b/packages/widget-sdk/src/define-widget.ts
@@ -43,10 +43,18 @@ export function defineWidget<TSchema extends ZodTypeAny>(
   if (!input || typeof input.component !== 'function') {
     throw new Error('defineWidget: component is required')
   }
+  const actions = input.actions ?? []
+  const seen = new Set<string>()
+  for (const a of actions) {
+    if (seen.has(a.id)) {
+      throw new Error(`defineWidget: duplicate action id "${a.id}"`)
+    }
+    seen.add(a.id)
+  }
   return {
     __brand: 'WidgetModule',
     configSchema: input.configSchema,
-    component: input.component as any,
-    actions: input.actions ?? []
+    component: input.component,
+    actions
   }
 }
diff --git a/packages/widget-sdk/tests/define-widget.test.ts b/packages/widget-sdk/tests/define-widget.test.ts
index ebf58393..b14a4d74 100644
--- a/packages/widget-sdk/tests/define-widget.test.ts
+++ b/packages/widget-sdk/tests/define-widget.test.ts
@@ -25,4 +25,17 @@ describe('defineWidget', () => {
   it('throws when component is missing', () => {
     expect(() => defineWidget({ configSchema: {} as any } as any)).toThrow(/component/)
   })
+
+  it('throws on duplicate action ids', () => {
+    expect(() =>
+      defineWidget({
+        configSchema: { _kind: 'object', shape: {} } as any,
+        component: () => null,
+        actions: [
+          { id: 'restart', label: 'Restart', run: async () => {} },
+          { id: 'restart', label: 'Restart again', run: async () => {} }
+        ]
+      })
+    ).toThrow(/duplicate action id "restart"/)
+  })
 })

From 2b60962e90cbe670757bb89044cb55b5e941b11c Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:15:31 +0800
Subject: [PATCH 51/64] feat(widget-sdk): sort useApiQuery params for stable
 URL + cache key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Object iteration order isn't a contract — without sorting, callers passing
the same params in different orders produced different URLs and therefore
different cache keys. Sort entries by key before building URLSearchParams.
---
 packages/widget-sdk/src/hooks/escape-hatch.ts | 18 +++++++++---------
 packages/widget-sdk/tests/hooks-api.test.tsx  | 17 +++++++++++++++++
 2 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/packages/widget-sdk/src/hooks/escape-hatch.ts b/packages/widget-sdk/src/hooks/escape-hatch.ts
index 7ac9bdd9..958a8cc0 100644
--- a/packages/widget-sdk/src/hooks/escape-hatch.ts
+++ b/packages/widget-sdk/src/hooks/escape-hatch.ts
@@ -22,15 +22,15 @@ export function useApiQuery<T>(
   }
 ): UseQueryResult<T> {
   const params = opts?.params
-  const url = params
-    ? `${path}?${new URLSearchParams(
-        Object.fromEntries(
-          Object.entries(params)
-            .filter(([, v]) => v !== undefined)
-            .map(([k, v]) => [k, String(v)])
-        )
-      ).toString()}`
-    : path
+  // Sort entries by key so the resulting URL — and therefore the React Query
+  // cache key — is stable regardless of the order callers pass params in.
+  const sortedEntries = params
+    ? Object.entries(params)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => [k, String(v)] as [string, string])
+        .sort(([a], [b]) => a.localeCompare(b))
+    : []
+  const url = sortedEntries.length > 0 ? `${path}?${new URLSearchParams(sortedEntries).toString()}` : path
   return useQuery<T>({
     queryKey: ['widget-api', url],
     queryFn: () => request<T>('GET', url),
diff --git a/packages/widget-sdk/tests/hooks-api.test.tsx b/packages/widget-sdk/tests/hooks-api.test.tsx
index f8e86f02..cecab498 100644
--- a/packages/widget-sdk/tests/hooks-api.test.tsx
+++ b/packages/widget-sdk/tests/hooks-api.test.tsx
@@ -39,4 +39,21 @@ describe('api hooks', () => {
       expect.objectContaining({ method: 'POST', credentials: 'include' })
     )
   })
+
+  it('useApiQuery sorts params for stable URL + cache key', async () => {
+    const { result: out1 } = renderHook(() => useApiQuery<{ hello: string }>('/api/test', { params: { b: 2, a: 1 } }), {
+      wrapper
+    })
+    await waitFor(() => expect(out1.current.data).toEqual({ hello: 'world' }))
+    const { result: out2 } = renderHook(() => useApiQuery<{ hello: string }>('/api/test', { params: { a: 1, b: 2 } }), {
+      wrapper
+    })
+    await waitFor(() => expect(out2.current.data).toEqual({ hello: 'world' }))
+
+    // Both should hit the same URL: a before b.
+    const calledUrls = (global.fetch as unknown as { mock: { calls: unknown[][] } }).mock.calls.map(
+      (call) => call[0] as string
+    )
+    expect(calledUrls.every((u) => u === '/api/test?a=1&b=2')).toBe(true)
+  })
 })

From fbf4f8299b7c3eac1a731cf54af103f78a783f87 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:19:15 +0800
Subject: [PATCH 52/64] feat(widget-sdk): sdkVersion compat check at module
 load time
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a minimal semver-range matcher supporting exact, caret (^), and tilde (~)
ranges. The loader now compares the host SDK_VERSION against each manifest's
sdkVersion before importing the module — incompatible modules are recorded
as load failures instead of being imported with potentially missing exports.
Also assert SDK_VERSION stays in sync with package.json.
---
 apps/web/src/widgets-runtime/loader.test.ts | 32 +++++++++++
 apps/web/src/widgets-runtime/loader.ts      | 10 +++-
 packages/widget-sdk/src/index.ts            | 10 +++-
 packages/widget-sdk/src/manifest.ts         | 61 ++++++++++++++++++++-
 packages/widget-sdk/tests/manifest.test.ts  | 44 ++++++++++++++-
 5 files changed, 152 insertions(+), 5 deletions(-)

diff --git a/apps/web/src/widgets-runtime/loader.test.ts b/apps/web/src/widgets-runtime/loader.test.ts
index 2a94e64b..48d63aba 100644
--- a/apps/web/src/widgets-runtime/loader.test.ts
+++ b/apps/web/src/widgets-runtime/loader.test.ts
@@ -2,6 +2,8 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { bootstrapLoader } from './loader'
 import { useWidgetRegistry } from './registry'
 
+const SDK_VERSION_MISMATCH_RE = /sdk version mismatch/
+
 describe('bootstrapLoader', () => {
   beforeEach(() => {
     useWidgetRegistry.setState({ modules: new Map(), failures: new Map() })
@@ -40,6 +42,36 @@ describe('bootstrapLoader', () => {
     expect(useWidgetRegistry.getState().modules.get('com.test.foo')?.manifest.name).toBe('Foo')
   })
 
+  it('rejects modules with incompatible sdkVersion range', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        data: [
+          {
+            id: 'com.test.future',
+            version: '1.0.0',
+            entry_path: 'index.js',
+            manifest: {
+              id: 'com.test.future',
+              version: '1.0.0',
+              name: 'Future',
+              category: 'Real-time',
+              sizing: { defaultW: 2, defaultH: 2, minW: 1, minH: 1, strategy: 'free' },
+              // Host is 0.1.0; ^2.0.0 cannot be satisfied.
+              sdkVersion: '^2.0.0'
+            }
+          }
+        ]
+      })
+    }) as any
+    const importer = vi.fn()
+    await bootstrapLoader({ importer, hostSdkVersion: '0.1.0' })
+    expect(importer).not.toHaveBeenCalled()
+    expect(useWidgetRegistry.getState().modules.has('com.test.future')).toBe(false)
+    const failure = useWidgetRegistry.getState().failures.get('com.test.future')
+    expect(failure?.message).toMatch(SDK_VERSION_MISMATCH_RE)
+  })
+
   it('isolates one module failure', async () => {
     global.fetch = vi.fn().mockResolvedValue({
       ok: true,
diff --git a/apps/web/src/widgets-runtime/loader.ts b/apps/web/src/widgets-runtime/loader.ts
index 18296fd0..bef4e89d 100644
--- a/apps/web/src/widgets-runtime/loader.ts
+++ b/apps/web/src/widgets-runtime/loader.ts
@@ -1,4 +1,4 @@
-import type { WidgetManifest, WidgetModule } from '@serverbee/widget-sdk'
+import { isCompatible, SDK_VERSION, type WidgetManifest, type WidgetModule } from '@serverbee/widget-sdk'
 import { registryActions } from './registry'
 
 interface ListEntry {
@@ -10,6 +10,8 @@ interface ListEntry {
 
 export interface BootstrapOptions {
   baseUrl?: string
+  /** Override the host SDK version (used in tests). */
+  hostSdkVersion?: string
   /** Override the import function (used in tests). */
   importer?: (url: string) => Promise<{ default: WidgetModule }>
 }
@@ -17,6 +19,7 @@ export interface BootstrapOptions {
 export async function bootstrapLoader(opts: BootstrapOptions = {}): Promise<void> {
   const base = opts.baseUrl ?? '/api/widget-modules'
   const importer = opts.importer ?? ((url: string) => import(/* @vite-ignore */ url))
+  const hostVersion = opts.hostSdkVersion ?? SDK_VERSION
 
   const res = await fetch(base, { credentials: 'include' })
   if (!res.ok) {
@@ -28,6 +31,11 @@ export async function bootstrapLoader(opts: BootstrapOptions = {}): Promise<void
   await Promise.allSettled(
     modules.map(async (entry) => {
       try {
+        if (!isCompatible(hostVersion, entry.manifest.sdkVersion)) {
+          throw new Error(
+            `sdk version mismatch: host ${hostVersion} does not satisfy manifest range ${entry.manifest.sdkVersion}`
+          )
+        }
         const url = `${base}/${entry.id}/${entry.entry_path}`
         const mod = await importer(url)
         if (!mod.default || mod.default.__brand !== 'WidgetModule') {
diff --git a/packages/widget-sdk/src/index.ts b/packages/widget-sdk/src/index.ts
index 3d85b3f2..26dc3e6e 100644
--- a/packages/widget-sdk/src/index.ts
+++ b/packages/widget-sdk/src/index.ts
@@ -11,7 +11,13 @@ export { defineWidget } from './define-widget'
 export { renderConfigForm } from './form'
 export * from './hooks'
 export type { SizingStrategy, WidgetCategory, WidgetManifest, WidgetSizing } from './manifest'
-export { validateManifest } from './manifest'
-export type { ServerSummary, WidgetRuntime } from './runtime-context'
+export { isCompatible, validateManifest } from './manifest'
+export type {
+  ConfirmOptions,
+  NotifyOptions,
+  ServerSummary,
+  ThemeSnapshot,
+  WidgetRuntime
+} from './runtime-context'
 export { createWidgetRuntime, getRuntime, resetRuntime } from './runtime-context'
 export { type Infer, ZError, ZodSchema, type ZodTypeAny, z } from './z'
diff --git a/packages/widget-sdk/src/manifest.ts b/packages/widget-sdk/src/manifest.ts
index 9cbb34e8..3e3636bc 100644
--- a/packages/widget-sdk/src/manifest.ts
+++ b/packages/widget-sdk/src/manifest.ts
@@ -24,7 +24,7 @@ export interface WidgetManifest {
   version: string
 }
 
-const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.]+)?$/
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(-[\w.]+)?$/
 const SEMVER_RANGE_RE = /^[\^~]?\d+\.\d+\.\d+/
 const VALID_CATEGORIES = new Set<WidgetCategory>(['Real-time', 'Charts', 'Status'])
 const VALID_STRATEGIES = new Set<SizingStrategy>(['fixed', 'free', 'aspect-square', 'content-height'])
@@ -71,3 +71,62 @@ export function validateManifest(input: unknown): WidgetManifest {
 
   return m as WidgetManifest
 }
+
+interface ParsedVersion {
+  major: number
+  minor: number
+  patch: number
+}
+
+function parseVersion(v: string): ParsedVersion | null {
+  const m = SEMVER_RE.exec(v)
+  if (!m) {
+    return null
+  }
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) }
+}
+
+/**
+ * Minimal semver-range compatibility check. Supports:
+ *   - exact:   "1.2.3"          → host must be exactly 1.2.3
+ *   - caret:   "^1.2.3"         → host >= 1.2.3 and host.major === range.major
+ *                                (when major === 0: host.minor must equal range.minor too)
+ *   - tilde:   "~1.2.3"         → host >= 1.2.3 and host.major.minor === range.major.minor
+ *
+ * Pre-release tags on either side are ignored for compatibility comparison.
+ */
+export function isCompatible(hostVersion: string, range: string): boolean {
+  const host = parseVersion(hostVersion)
+  if (!host) {
+    return false
+  }
+  const op = range[0]
+  const versionPart = op === '^' || op === '~' ? range.slice(1) : range
+  const target = parseVersion(versionPart)
+  if (!target) {
+    return false
+  }
+  const hostGTE =
+    host.major > target.major ||
+    (host.major === target.major && host.minor > target.minor) ||
+    (host.major === target.major && host.minor === target.minor && host.patch >= target.patch)
+  if (op === '^') {
+    if (!hostGTE) {
+      return false
+    }
+    if (target.major !== 0) {
+      return host.major === target.major
+    }
+    // ^0.x.y is pinned to 0.x — minor bump is treated as breaking
+    if (target.minor !== 0) {
+      return host.major === 0 && host.minor === target.minor
+    }
+    // ^0.0.z is pinned to exact patch
+    return host.major === 0 && host.minor === 0 && host.patch === target.patch
+  }
+  if (op === '~') {
+    return hostGTE && host.major === target.major && host.minor === target.minor
+  }
+  // exact match
+  return host.major === target.major && host.minor === target.minor && host.patch === target.patch
+}
diff --git a/packages/widget-sdk/tests/manifest.test.ts b/packages/widget-sdk/tests/manifest.test.ts
index 07cc0be3..f34a4fdf 100644
--- a/packages/widget-sdk/tests/manifest.test.ts
+++ b/packages/widget-sdk/tests/manifest.test.ts
@@ -1,5 +1,7 @@
 import { describe, expect, it } from 'vitest'
-import { validateManifest } from '../src/manifest'
+import packageJson from '../package.json'
+import { SDK_VERSION } from '../src'
+import { isCompatible, validateManifest } from '../src/manifest'
 
 describe('validateManifest', () => {
   const base = {
@@ -29,3 +31,43 @@ describe('validateManifest', () => {
     expect(() => validateManifest({ ...base, version: 'not-semver' })).toThrow(/version/)
   })
 })
+
+describe('SDK_VERSION matches package.json', () => {
+  it('SDK_VERSION constant is in sync with package.json version', () => {
+    expect(SDK_VERSION).toBe(packageJson.version)
+  })
+})
+
+describe('isCompatible (semver range check)', () => {
+  it('caret: ^0.1.0 accepts host 0.1.0 + patch bumps but rejects 0.2.0', () => {
+    expect(isCompatible('0.1.0', '^0.1.0')).toBe(true)
+    expect(isCompatible('0.1.5', '^0.1.0')).toBe(true)
+    expect(isCompatible('0.0.9', '^0.1.0')).toBe(false)
+    expect(isCompatible('0.2.0', '^0.1.0')).toBe(false)
+  })
+
+  it('caret: ^1.2.3 accepts any 1.x.y >= 1.2.3 but rejects 2.0.0 and 1.2.2', () => {
+    expect(isCompatible('1.2.3', '^1.2.3')).toBe(true)
+    expect(isCompatible('1.9.0', '^1.2.3')).toBe(true)
+    expect(isCompatible('1.2.2', '^1.2.3')).toBe(false)
+    expect(isCompatible('2.0.0', '^1.2.3')).toBe(false)
+  })
+
+  it('tilde: ~1.2.3 accepts 1.2.x >= 1.2.3 but rejects 1.3.0', () => {
+    expect(isCompatible('1.2.3', '~1.2.3')).toBe(true)
+    expect(isCompatible('1.2.9', '~1.2.3')).toBe(true)
+    expect(isCompatible('1.2.2', '~1.2.3')).toBe(false)
+    expect(isCompatible('1.3.0', '~1.2.3')).toBe(false)
+  })
+
+  it('exact: 1.2.3 only matches 1.2.3', () => {
+    expect(isCompatible('1.2.3', '1.2.3')).toBe(true)
+    expect(isCompatible('1.2.4', '1.2.3')).toBe(false)
+    expect(isCompatible('1.3.0', '1.2.3')).toBe(false)
+  })
+
+  it('returns false for unparseable host or range', () => {
+    expect(isCompatible('bogus', '^1.0.0')).toBe(false)
+    expect(isCompatible('1.0.0', 'bogus')).toBe(false)
+  })
+})

From bab01a4eafd724596ece8e6dbde15530e3b2a247 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:21:06 +0800
Subject: [PATCH 53/64] feat(widget-sdk): live hooks via useSyncExternalStore

Add subscribeServers / subscribeTheme to WidgetRuntime so widgets can
re-render on host data changes. Rewrite useServers / useServer / useMetric /
useCapability / useTheme using useSyncExternalStore with memoized
snapshot getters. Add NotifyOptions / ConfirmOptions / ThemeSnapshot types
and optional notify / requestConfirm runtime slots so the host can wire
toast and confirm dialog primitives later.
---
 packages/widget-sdk/src/hooks/host.ts         |  8 +-
 packages/widget-sdk/src/hooks/live.ts         | 83 ++++++++++++-------
 packages/widget-sdk/src/runtime-context.ts    | 45 ++++++++--
 packages/widget-sdk/tests/hooks-live.test.tsx | 57 ++++++++++++-
 4 files changed, 149 insertions(+), 44 deletions(-)

diff --git a/packages/widget-sdk/src/hooks/host.ts b/packages/widget-sdk/src/hooks/host.ts
index fdff632b..bd5e0ec7 100644
--- a/packages/widget-sdk/src/hooks/host.ts
+++ b/packages/widget-sdk/src/hooks/host.ts
@@ -1,7 +1,9 @@
-import { getRuntime } from '../runtime-context'
+import { useSyncExternalStore } from 'react'
+import { getRuntime, type ThemeSnapshot } from '../runtime-context'
 
-export function useTheme() {
-  return getRuntime().themeStore()
+export function useTheme(): ThemeSnapshot {
+  const rt = getRuntime()
+  return useSyncExternalStore(rt.subscribeTheme, rt.themeStore, rt.themeStore)
 }
 
 export function useConfigUpdate<TConfig = Record<string, unknown>>(instanceId: string) {
diff --git a/packages/widget-sdk/src/hooks/live.ts b/packages/widget-sdk/src/hooks/live.ts
index e13a61b0..ed90060e 100644
--- a/packages/widget-sdk/src/hooks/live.ts
+++ b/packages/widget-sdk/src/hooks/live.ts
@@ -1,3 +1,4 @@
+import { useCallback, useMemo, useSyncExternalStore } from 'react'
 import { getRuntime, type ServerSummary } from '../runtime-context'
 
 const CAPS: Record<string, number> = {
@@ -15,47 +16,65 @@ const CAPS: Record<string, number> = {
 }
 
 export function useServers(): ServerSummary[] {
-  return getRuntime().serversStore()
+  const rt = getRuntime()
+  return useSyncExternalStore(rt.subscribeServers, rt.serversStore, rt.serversStore)
 }
 
+const PATH_TOKEN_RE = /[a-zA-Z_][a-zA-Z0-9_]*|\[\d+\]/g
+
 export function useServer(id: string | null): unknown {
-  if (id === null) {
-    return undefined
-  }
-  return getRuntime().serverByIdStore(id)
+  const rt = getRuntime()
+  const subscribe = rt.subscribeServers
+  const getSnapshot = useCallback((): unknown => {
+    if (id === null) {
+      return undefined
+    }
+    return rt.serverByIdStore(id)
+  }, [rt, id])
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
 }
 
-const PATH_TOKEN_RE = /[a-zA-Z_][a-zA-Z0-9_]*|\[\d+\]/g
-
 export function useMetric(id: string | null, path: string): number | string | undefined {
-  if (id === null) {
-    return undefined
-  }
-  const server = getRuntime().serverByIdStore(id) as Record<string, any> | undefined
-  if (!server) {
-    return undefined
-  }
-  const tokens = path.match(PATH_TOKEN_RE) ?? []
-  let cur: any = server
-  for (const tok of tokens) {
-    if (cur == null) {
+  const rt = getRuntime()
+  const subscribe = rt.subscribeServers
+  const tokens = useMemo(() => path.match(PATH_TOKEN_RE) ?? [], [path])
+  const getSnapshot = useCallback((): number | string | undefined => {
+    if (id === null) {
+      return undefined
+    }
+    const server = rt.serverByIdStore(id) as Record<string, unknown> | undefined
+    if (!server) {
       return undefined
     }
-    cur = tok.startsWith('[') ? cur[Number(tok.slice(1, -1))] : cur[tok]
-  }
-  return cur
+    let cur: unknown = server
+    for (const tok of tokens) {
+      if (cur == null || typeof cur !== 'object') {
+        return undefined
+      }
+      const obj = cur as Record<string, unknown> | unknown[]
+      cur = tok.startsWith('[') ? (obj as unknown[])[Number(tok.slice(1, -1))] : (obj as Record<string, unknown>)[tok]
+    }
+    if (typeof cur === 'number' || typeof cur === 'string') {
+      return cur
+    }
+    return undefined
+  }, [rt, id, tokens])
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
 }
 
 export function useCapability(id: string | null, cap: string): boolean {
-  if (id === null) {
-    return false
-  }
-  const bit = CAPS[cap]
-  if (!bit) {
-    return false
-  }
-  const server = getRuntime()
-    .serversStore()
-    .find((s) => s.id === id)
-  return server ? (server.capabilities & bit) !== 0 : false
+  const rt = getRuntime()
+  const subscribe = rt.subscribeServers
+  const getSnapshot = useCallback((): boolean => {
+    if (id === null) {
+      return false
+    }
+    const bit = CAPS[cap]
+    if (!bit) {
+      return false
+    }
+    const server = rt.serversStore().find((s) => s.id === id)
+    return server ? (server.capabilities & bit) !== 0 : false
+  }, [rt, id, cap])
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
 }
diff --git a/packages/widget-sdk/src/runtime-context.ts b/packages/widget-sdk/src/runtime-context.ts
index a91dc5c9..c670ff15 100644
--- a/packages/widget-sdk/src/runtime-context.ts
+++ b/packages/widget-sdk/src/runtime-context.ts
@@ -8,24 +8,59 @@ export interface ServerSummary {
   online: boolean
 }
 
+export interface NotifyOptions {
+  message: string
+  type: 'success' | 'error' | 'info'
+}
+
+export interface ConfirmOptions {
+  body?: string
+  title: string
+}
+
+export interface ThemeSnapshot {
+  cssVar: (name: string) => string
+  mode: 'light' | 'dark'
+}
+
 export interface WidgetRuntime {
   apiBaseUrl: string
+  /** Optional: hint list of well-known metric paths for the metricPath picker. */
+  getMetricPaths?: () => string[]
+  /** Optional: host-provided toast hook. SDK falls back to console.* */
+  notify?: (opts: NotifyOptions) => void
   onConfigUpdate: (instanceId: string, patch: Record<string, unknown>) => void
   queryClient: QueryClient
+  /** Optional: host-provided confirm dialog. SDK falls back to window.confirm. */
+  requestConfirm?: (opts: ConfirmOptions) => Promise<boolean>
   serverByIdStore: (id: string) => unknown
   serversStore: () => ServerSummary[]
-  themeStore: () => { mode: 'light' | 'dark'; cssVar: (name: string) => string }
+  /** Subscribe to server-list changes. Returns an unsubscribe fn. */
+  subscribeServers: (cb: () => void) => () => void
+  /** Subscribe to theme changes. Returns an unsubscribe fn. */
+  subscribeTheme: (cb: () => void) => () => void
+  themeStore: () => ThemeSnapshot
 }
 
 let _runtime: WidgetRuntime | null = null
 
-export function createWidgetRuntime(
-  rt: Omit<WidgetRuntime, 'serverByIdStore'> & {
-    serverByIdStore?: WidgetRuntime['serverByIdStore']
+type RuntimeInput = Omit<WidgetRuntime, 'serverByIdStore' | 'subscribeServers' | 'subscribeTheme'> & {
+  serverByIdStore?: WidgetRuntime['serverByIdStore']
+  subscribeServers?: WidgetRuntime['subscribeServers']
+  subscribeTheme?: WidgetRuntime['subscribeTheme']
+}
+
+const noopSubscribe = (_cb: () => void): (() => void) => {
+  return () => {
+    /* no-op */
   }
-): WidgetRuntime {
+}
+
+export function createWidgetRuntime(rt: RuntimeInput): WidgetRuntime {
   _runtime = {
     serverByIdStore: () => undefined,
+    subscribeServers: noopSubscribe,
+    subscribeTheme: noopSubscribe,
     ...rt
   }
   return _runtime
diff --git a/packages/widget-sdk/tests/hooks-live.test.tsx b/packages/widget-sdk/tests/hooks-live.test.tsx
index db7c340b..369b29b3 100644
--- a/packages/widget-sdk/tests/hooks-live.test.tsx
+++ b/packages/widget-sdk/tests/hooks-live.test.tsx
@@ -1,16 +1,23 @@
-import { renderHook } from '@testing-library/react'
+import { act, render, renderHook, screen } from '@testing-library/react'
 import { beforeEach, describe, expect, it } from 'vitest'
 import { useCapability, useMetric, useServers } from '../src/hooks/live'
-import { createWidgetRuntime, resetRuntime } from '../src/runtime-context'
+import { createWidgetRuntime, resetRuntime, type ServerSummary } from '../src/runtime-context'
 
 describe('live hooks', () => {
   beforeEach(() => {
     resetRuntime()
+    // Cached references — useSyncExternalStore requires snapshots to be stable
+    // across calls when nothing changed; the production runtime backs both
+    // stores by React Query, which already memoizes its returns.
+    const cachedServers: ServerSummary[] = [
+      { id: 's1', name: 'one', online: true, lastSeen: null, capabilities: 1 | 8 }
+    ]
+    const cachedDetail = { id: 's1', cpu: { usage: 42 }, disks: [{ used: 100 }] }
     createWidgetRuntime({
       apiBaseUrl: '/api',
       queryClient: {} as any,
-      serversStore: () => [{ id: 's1', name: 'one', online: true, lastSeen: null, capabilities: 1 | 8 }],
-      serverByIdStore: (id) => (id === 's1' ? { id: 's1', cpu: { usage: 42 }, disks: [{ used: 100 }] } : undefined),
+      serversStore: () => cachedServers,
+      serverByIdStore: (id) => (id === 's1' ? cachedDetail : undefined),
       themeStore: () => ({ mode: 'light', cssVar: () => '' }),
       onConfigUpdate: () => {}
     })
@@ -46,3 +53,45 @@ describe('live hooks', () => {
     expect(docker.current).toBe(false)
   })
 })
+
+describe('useServers re-renders on subscription', () => {
+  it('rerenders when subscribe callback fires after store mutation', () => {
+    resetRuntime()
+    let servers: ServerSummary[] = []
+    const listeners = new Set<() => void>()
+    createWidgetRuntime({
+      apiBaseUrl: '/api',
+      queryClient: {} as any,
+      serversStore: () => servers,
+      serverByIdStore: (id) => servers.find((s) => s.id === id),
+      subscribeServers: (cb) => {
+        listeners.add(cb)
+        return () => {
+          listeners.delete(cb)
+        }
+      },
+      themeStore: () => ({ mode: 'light', cssVar: () => '' }),
+      onConfigUpdate: () => {}
+    })
+
+    function Probe() {
+      const list = useServers()
+      return <div data-testid="count">{list.length}</div>
+    }
+
+    render(<Probe />)
+    expect(screen.getByTestId('count').textContent).toBe('0')
+
+    act(() => {
+      servers = [
+        { id: 's1', name: 'one', online: true, lastSeen: null, capabilities: 0 },
+        { id: 's2', name: 'two', online: true, lastSeen: null, capabilities: 0 }
+      ]
+      for (const cb of listeners) {
+        cb()
+      }
+    })
+
+    expect(screen.getByTestId('count').textContent).toBe('2')
+  })
+})

From e4ff35ce14ccb8dc6b69cfa76ab1361fcb1c3efe Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:22:15 +0800
Subject: [PATCH 54/64] feat(widget-sdk): ActionButton with confirm dialog,
 toast, and audit hook
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wire ActionButton through the runtime's optional requestConfirm / notify
slots so the host can plug in shadcn AlertDialog and sonner toast. Falls
back to window.confirm and console.* when no host hook is registered.
Errors are caught and surfaced as 'error' notifications instead of
bubbling. Server-side audit log emission is deferred — recorded in a
TODO comment until POST /api/widget-actions/audit lands.
---
 .../widget-sdk/src/actions/action-button.tsx  | 63 ++++++++++++++--
 packages/widget-sdk/tests/actions.test.tsx    | 71 ++++++++++++++++++-
 2 files changed, 125 insertions(+), 9 deletions(-)

diff --git a/packages/widget-sdk/src/actions/action-button.tsx b/packages/widget-sdk/src/actions/action-button.tsx
index abe3d9be..08165d3c 100644
--- a/packages/widget-sdk/src/actions/action-button.tsx
+++ b/packages/widget-sdk/src/actions/action-button.tsx
@@ -1,31 +1,80 @@
 import { useState } from 'react'
 import type { ActionDefinition } from '../define-widget'
+import { getRuntime } from '../runtime-context'
 
 interface Props {
   action: ActionDefinition
   onRun: () => Promise<void>
 }
 
+async function askConfirm(action: ActionDefinition): Promise<boolean> {
+  if (!action.confirm) {
+    return true
+  }
+  try {
+    const rt = getRuntime()
+    if (rt.requestConfirm) {
+      return await rt.requestConfirm(action.confirm)
+    }
+  } catch {
+    // runtime not installed — fall back to window.confirm
+  }
+  if (typeof window !== 'undefined' && typeof window.confirm === 'function') {
+    const body = action.confirm.body ? `\n\n${action.confirm.body}` : ''
+    return window.confirm(`${action.confirm.title}${body}`)
+  }
+  return true
+}
+
+function notify(type: 'success' | 'error', message: string): void {
+  try {
+    const rt = getRuntime()
+    if (rt.notify) {
+      rt.notify({ type, message })
+      return
+    }
+  } catch {
+    // runtime not installed
+  }
+  if (type === 'error') {
+    console.error(`[widget-action] ${message}`)
+  } else {
+    console.info(`[widget-action] ${message}`)
+  }
+}
+
+// NOTE: server-side widget-action audit log is intentionally deferred. The
+// backend endpoint (POST /api/widget-actions/audit) does not exist yet; once
+// it lands, we'll fire a best-effort POST from here on success. Until then we
+// log via console.info with the `[widget-action]` prefix.
 export function ActionButton({ action, onRun }: Props) {
   const [pending, setPending] = useState(false)
-  const [confirming, setConfirming] = useState(false)
+
   const trigger = async () => {
-    if (action.confirm && !confirming) {
-      setConfirming(true)
+    const ok = await askConfirm(action)
+    if (!ok) {
       return
     }
-    setConfirming(false)
     setPending(true)
     try {
       await onRun()
+      notify('success', `${action.label}: done`)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      notify('error', `${action.label}: ${msg}`)
     } finally {
       setPending(false)
     }
   }
+
   return (
-    <button disabled={pending} onClick={trigger} type="button">
-      {confirming ? `Confirm: ${action.label}` : action.label}
-      {pending ? '…' : ''}
+    <button
+      className="rounded-md border px-3 py-1 text-sm hover:bg-accent disabled:cursor-not-allowed disabled:opacity-60"
+      disabled={pending}
+      onClick={trigger}
+      type="button"
+    >
+      {pending ? `${action.label}…` : action.label}
     </button>
   )
 }
diff --git a/packages/widget-sdk/tests/actions.test.tsx b/packages/widget-sdk/tests/actions.test.tsx
index c6f707e7..c817df05 100644
--- a/packages/widget-sdk/tests/actions.test.tsx
+++ b/packages/widget-sdk/tests/actions.test.tsx
@@ -1,16 +1,34 @@
-import { fireEvent, render, screen, waitFor } from '@testing-library/react'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { createActionsHelper } from '../src/actions'
 import type { ActionDefinition } from '../src/define-widget'
+import { createWidgetRuntime, resetRuntime } from '../src/runtime-context'
+
+function installRuntime(overrides: Partial<Parameters<typeof createWidgetRuntime>[0]> = {}) {
+  resetRuntime()
+  createWidgetRuntime({
+    apiBaseUrl: '/api',
+    queryClient: {} as any,
+    serversStore: () => [],
+    themeStore: () => ({ mode: 'light', cssVar: () => '' }),
+    onConfigUpdate: () => {},
+    ...overrides
+  })
+}
 
 describe('actions helper', () => {
   beforeEach(() => {
+    installRuntime()
     global.fetch = vi.fn().mockResolvedValue({
       ok: true,
       json: async () => ({ data: { ok: true } })
     }) as any
   })
 
+  afterEach(() => {
+    cleanup()
+  })
+
   it('renders a button that triggers run() and shows loading state', async () => {
     const run = vi.fn().mockResolvedValue(undefined)
     const actions: ActionDefinition[] = [{ id: 'a1', label: 'Do it', run }]
@@ -25,4 +43,53 @@ describe('actions helper', () => {
     const { container } = render(<>{helper.render('missing')}</>)
     expect(container.textContent).toBe('')
   })
+
+  it('calls runtime.requestConfirm when action has confirm and aborts on false', async () => {
+    const run = vi.fn().mockResolvedValue(undefined)
+    const requestConfirm = vi.fn().mockResolvedValue(false)
+    installRuntime({ requestConfirm })
+    const actions: ActionDefinition[] = [
+      {
+        id: 'a1',
+        label: 'Restart',
+        run,
+        confirm: { title: 'Restart server?', body: 'Are you sure?' }
+      }
+    ]
+    const helper = createActionsHelper(actions)
+    render(<>{helper.render('a1')}</>)
+    fireEvent.click(screen.getByRole('button', { name: 'Restart' }))
+    await waitFor(() =>
+      expect(requestConfirm).toHaveBeenCalledWith({ title: 'Restart server?', body: 'Are you sure?' })
+    )
+    expect(run).not.toHaveBeenCalled()
+  })
+
+  it('proceeds with action when confirm returns true and emits success notify', async () => {
+    const run = vi.fn().mockResolvedValue(undefined)
+    const requestConfirm = vi.fn().mockResolvedValue(true)
+    const notify = vi.fn()
+    installRuntime({ requestConfirm, notify })
+    const actions: ActionDefinition[] = [{ id: 'a1', label: 'Restart', run, confirm: { title: 'Restart?' } }]
+    const helper = createActionsHelper(actions)
+    render(<>{helper.render('a1')}</>)
+    fireEvent.click(screen.getByRole('button', { name: 'Restart' }))
+    await waitFor(() => expect(run).toHaveBeenCalledOnce())
+    await waitFor(() => expect(notify).toHaveBeenCalledWith(expect.objectContaining({ type: 'success' })))
+  })
+
+  it('catches errors and emits error notify (does not re-throw)', async () => {
+    const run = vi.fn().mockRejectedValue(new Error('boom'))
+    const notify = vi.fn()
+    installRuntime({ notify })
+    const actions: ActionDefinition[] = [{ id: 'a1', label: 'Risky', run }]
+    const helper = createActionsHelper(actions)
+    render(<>{helper.render('a1')}</>)
+    fireEvent.click(screen.getByRole('button', { name: 'Risky' }))
+    await waitFor(() =>
+      expect(notify).toHaveBeenCalledWith(
+        expect.objectContaining({ type: 'error', message: expect.stringContaining('boom') })
+      )
+    )
+  })
 })

From 068df62ea5d0a60515735e5d452b8d8124f6d1c5 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:22:29 +0800
Subject: [PATCH 55/64] feat(web): wire widget runtime bridge to React Query +
 theme + sonner
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

mountRuntimeBridge now derives serversStore / serverByIdStore from the
['servers'] React Query cache (memoized so useSyncExternalStore sees a
stable reference), filters QueryCache events to the servers key for
subscribeServers, mirrors the <html> dark-class theme through a
MutationObserver-backed watcher, and routes notify() to sonner toasts.
Also adds a runtime-bridge.test.ts that exercises cache→summary mapping,
subscription dispatch, theme lookup, notify routing, plus a shim-drift
test that parses public/runtime/widget-sdk.js and asserts every named
export still resolves on the real SDK namespace.
---
 apps/web/src/main.tsx                         |  11 +-
 .../widgets-runtime/runtime-bridge.test.ts    | 133 ++++++++++
 .../web/src/widgets-runtime/runtime-bridge.ts | 228 +++++++++++++++++-
 3 files changed, 349 insertions(+), 23 deletions(-)
 create mode 100644 apps/web/src/widgets-runtime/runtime-bridge.test.ts

diff --git a/apps/web/src/main.tsx b/apps/web/src/main.tsx
index c688f823..c0295bd1 100644
--- a/apps/web/src/main.tsx
+++ b/apps/web/src/main.tsx
@@ -15,16 +15,7 @@ const queryClient = new QueryClient({
   }
 })
 
-mountRuntimeBridge({
-  queryClient,
-  serversStore: () => [],
-  serverByIdStore: () => undefined,
-  themeStore: () => ({
-    mode: document.documentElement.classList.contains('dark') ? 'dark' : 'light',
-    cssVar: (n) => getComputedStyle(document.documentElement).getPropertyValue(n).trim()
-  }),
-  onConfigUpdate: () => {}
-})
+mountRuntimeBridge({ queryClient })
 
 // Best-effort: don't block rendering. Endpoint may return empty in Plan 1.
 bootstrapLoader().catch((e) => console.warn('widget bootstrap failed', e))
diff --git a/apps/web/src/widgets-runtime/runtime-bridge.test.ts b/apps/web/src/widgets-runtime/runtime-bridge.test.ts
new file mode 100644
index 00000000..8d49cc86
--- /dev/null
+++ b/apps/web/src/widgets-runtime/runtime-bridge.test.ts
@@ -0,0 +1,133 @@
+// biome-ignore lint/performance/noNamespaceImport: shim-drift test enumerates every named export.
+import * as Sdk from '@serverbee/widget-sdk'
+import { QueryClient } from '@tanstack/react-query'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { ServerMetrics } from '@/hooks/use-servers-ws'
+import { mountRuntimeBridge } from './runtime-bridge'
+
+function makeServer(id: string): ServerMetrics {
+  return {
+    id,
+    name: id,
+    cpu: 0,
+    cpu_cores: null,
+    cpu_name: null,
+    mem_total: 0,
+    mem_used: 0,
+    swap_total: 0,
+    swap_used: 0,
+    disk_total: 0,
+    disk_used: 0,
+    disk_read_bytes_per_sec: 0,
+    disk_write_bytes_per_sec: 0,
+    net_in_speed: 0,
+    net_in_transfer: 0,
+    net_out_speed: 0,
+    net_out_transfer: 0,
+    load1: 0,
+    load5: 0,
+    load15: 0,
+    process_count: 0,
+    tcp_conn: 0,
+    udp_conn: 0,
+    uptime: 0,
+    last_active: 0,
+    online: true,
+    country_code: null,
+    group_id: null,
+    os: null,
+    region: null,
+    capabilities: 0
+  }
+}
+
+describe('runtime-bridge: React Query store wiring', () => {
+  let qc: QueryClient
+
+  beforeEach(() => {
+    Sdk.resetRuntime()
+    qc = new QueryClient()
+    mountRuntimeBridge({ queryClient: qc })
+  })
+
+  afterEach(() => {
+    Sdk.resetRuntime()
+  })
+
+  it('serversStore is empty until the cache is seeded', () => {
+    expect(Sdk.getRuntime().serversStore()).toEqual([])
+  })
+
+  it('serversStore reflects current cache after setQueryData', () => {
+    qc.setQueryData<ServerMetrics[]>(['servers'], [makeServer('s1'), makeServer('s2')])
+    const list = Sdk.getRuntime().serversStore()
+    expect(list.map((s) => s.id)).toEqual(['s1', 's2'])
+  })
+
+  it('serversStore returns the same array reference when cache is unchanged', () => {
+    qc.setQueryData<ServerMetrics[]>(['servers'], [makeServer('s1')])
+    const a = Sdk.getRuntime().serversStore()
+    const b = Sdk.getRuntime().serversStore()
+    expect(a).toBe(b)
+  })
+
+  it('subscribeServers fires on ["servers"] cache updates', () => {
+    const cb = vi.fn()
+    const unsub = Sdk.getRuntime().subscribeServers(cb)
+    qc.setQueryData<ServerMetrics[]>(['servers'], [makeServer('s1')])
+    expect(cb).toHaveBeenCalled()
+    unsub()
+  })
+
+  it('subscribeServers ignores updates to other query keys', () => {
+    const cb = vi.fn()
+    const unsub = Sdk.getRuntime().subscribeServers(cb)
+    qc.setQueryData<ServerMetrics[]>(['something-else'], [makeServer('s1')])
+    expect(cb).not.toHaveBeenCalled()
+    unsub()
+  })
+
+  it('serverByIdStore looks up by id from cache', () => {
+    qc.setQueryData<ServerMetrics[]>(['servers'], [makeServer('s1'), makeServer('s2')])
+    const lookup = Sdk.getRuntime().serverByIdStore('s2')
+    expect((lookup as ServerMetrics).id).toBe('s2')
+    expect(Sdk.getRuntime().serverByIdStore('missing')).toBeUndefined()
+  })
+
+  it('notify routes through sonner without throwing', () => {
+    // sonner is mocked-friendly: just confirm the call path runs.
+    expect(() => Sdk.getRuntime().notify?.({ type: 'success', message: 'ok' })).not.toThrow()
+    expect(() => Sdk.getRuntime().notify?.({ type: 'error', message: 'bad' })).not.toThrow()
+  })
+
+  it('themeStore reports light/dark from <html> class', () => {
+    document.documentElement.classList.remove('dark')
+    expect(Sdk.getRuntime().themeStore().mode).toBe('light')
+    document.documentElement.classList.add('dark')
+    expect(Sdk.getRuntime().themeStore().mode).toBe('dark')
+    document.documentElement.classList.remove('dark')
+  })
+})
+
+describe('runtime-bridge: shim export drift', () => {
+  it('every named export listed in /runtime/widget-sdk.js resolves to a live SDK export', async () => {
+    const fs = await import('node:fs/promises')
+    const path = await import('node:path')
+    const shimPath = path.resolve(import.meta.dirname, '../../public/runtime/widget-sdk.js')
+    const shimSrc = await fs.readFile(shimPath, 'utf8')
+    // Grep `export const <name> = ns.<rhsName>` pairs.
+    const re = /export\s+const\s+(\w+)\s*=\s*ns\.(\w+)/g
+    const pairs: Array<{ exportName: string; rhsName: string }> = []
+    let match: RegExpExecArray | null = re.exec(shimSrc)
+    while (match !== null) {
+      pairs.push({ exportName: match[1], rhsName: match[2] })
+      match = re.exec(shimSrc)
+    }
+    expect(pairs.length).toBeGreaterThan(0)
+    const sdkAsRecord = Sdk as unknown as Record<string, unknown>
+    for (const { exportName, rhsName } of pairs) {
+      expect(rhsName, `shim exports ${exportName} from ns.${rhsName}`).toBe(exportName)
+      expect(sdkAsRecord[rhsName], `SDK is missing export '${rhsName}' referenced by shim`).not.toBeUndefined()
+    }
+  })
+})
diff --git a/apps/web/src/widgets-runtime/runtime-bridge.ts b/apps/web/src/widgets-runtime/runtime-bridge.ts
index 38b4fe23..e4d420c0 100644
--- a/apps/web/src/widgets-runtime/runtime-bridge.ts
+++ b/apps/web/src/widgets-runtime/runtime-bridge.ts
@@ -1,30 +1,232 @@
-import type { ServerSummary } from '@serverbee/widget-sdk'
+// Widget modules dynamically `import *` from these packages via the import-map
+// shim, so the host must expose the full namespace objects on `globalThis`.
+// Named imports won't work here — these `*` imports are intentional.
+import type { ConfirmOptions, NotifyOptions, ServerSummary, ThemeSnapshot } from '@serverbee/widget-sdk'
+// biome-ignore lint/performance/noNamespaceImport: shim requires full namespace
 import * as Sdk from '@serverbee/widget-sdk'
 import type { QueryClient } from '@tanstack/react-query'
+// biome-ignore lint/performance/noNamespaceImport: shim requires full namespace
 import * as React from 'react'
+// biome-ignore lint/performance/noNamespaceImport: shim requires full namespace
 import * as JsxRuntime from 'react/jsx-runtime'
+// biome-ignore lint/performance/noNamespaceImport: shim requires full namespace
 import * as ReactDOM from 'react-dom'
+import { toast } from 'sonner'
+import type { ServerMetrics } from '@/hooks/use-servers-ws'
+
+const SERVERS_QUERY_KEY = ['servers'] as const
 
 export interface BridgeInputs {
-  onConfigUpdate: (instanceId: string, patch: Record<string, unknown>) => void
+  onConfigUpdate?: (instanceId: string, patch: Record<string, unknown>) => void
   queryClient: QueryClient
-  serverByIdStore: (id: string) => unknown
-  serversStore: () => ServerSummary[]
-  themeStore: () => { mode: 'light' | 'dark'; cssVar: (n: string) => string }
+  /** Optional: host confirm hook. If omitted, the SDK falls back to window.confirm. */
+  requestConfirm?: (opts: ConfirmOptions) => Promise<boolean>
+}
+
+function metricsToSummary(metrics: ServerMetrics): ServerSummary {
+  return {
+    id: metrics.id,
+    name: metrics.name,
+    online: metrics.online,
+    lastSeen: typeof metrics.last_active === 'number' ? metrics.last_active : null,
+    capabilities:
+      typeof metrics.effective_capabilities === 'number' ? metrics.effective_capabilities : (metrics.capabilities ?? 0)
+  }
+}
+
+interface ServerSummariesCache {
+  raw: ServerMetrics[] | undefined
+  summaries: ServerSummary[]
+}
+
+/**
+ * Memoized projection of the `['servers']` cache → `ServerSummary[]`. We cache
+ * by the raw array reference so `useSyncExternalStore` sees a stable snapshot
+ * (otherwise React loops forever).
+ */
+function makeServerSummariesGetter(queryClient: QueryClient): () => ServerSummary[] {
+  let cache: ServerSummariesCache = { raw: undefined, summaries: [] }
+  return () => {
+    const raw = queryClient.getQueryData<ServerMetrics[]>(SERVERS_QUERY_KEY)
+    if (raw === cache.raw) {
+      return cache.summaries
+    }
+    const summaries = raw ? raw.map(metricsToSummary) : []
+    cache = { raw, summaries }
+    return summaries
+  }
+}
+
+function makeServerByIdGetter(queryClient: QueryClient): (id: string) => unknown {
+  return (id: string) => {
+    const raw = queryClient.getQueryData<ServerMetrics[]>(SERVERS_QUERY_KEY)
+    return raw?.find((s) => s.id === id)
+  }
+}
+
+function makeSubscribeServers(queryClient: QueryClient): (cb: () => void) => () => void {
+  return (cb: () => void) => {
+    const unsub = queryClient.getQueryCache().subscribe((event) => {
+      // We only care about updates to the ['servers'] cache. The cache emits
+      // a flurry of events (added/removed/updated/observers); filter to those
+      // that mutate the data for our queryKey.
+      const key = event.query.queryKey
+      if (Array.isArray(key) && key.length >= 1 && key[0] === SERVERS_QUERY_KEY[0]) {
+        cb()
+      }
+    })
+    return unsub
+  }
+}
+
+interface ThemeWatcher {
+  getSnapshot: () => ThemeSnapshot
+  subscribe: (cb: () => void) => () => void
+}
+
+/**
+ * The host app uses a manual `light`/`dark` class toggle on `<html>` driven by
+ * `ThemeProvider`. We mirror that into a `ThemeSnapshot` and re-emit on
+ * `MutationObserver` `class` changes — same source of truth, no extra coupling.
+ */
+function makeThemeWatcher(): ThemeWatcher {
+  const listeners = new Set<() => void>()
+  let observer: MutationObserver | null = null
+  let storageHandler: ((e: StorageEvent) => void) | null = null
+  let mediaQuery: MediaQueryList | null = null
+  let mediaHandler: (() => void) | null = null
+
+  function readMode(): 'light' | 'dark' {
+    return typeof document !== 'undefined' && document.documentElement.classList.contains('dark') ? 'dark' : 'light'
+  }
+
+  // We memoize the snapshot **object** by current mode so getSnapshot returns
+  // a stable reference across calls when the underlying mode is unchanged.
+  // `cssVar` is a pure read of the live document; capturing it inside the
+  // snapshot object is fine.
+  let lastMode: 'light' | 'dark' = readMode()
+  let cached: ThemeSnapshot = makeSnapshot(lastMode)
+
+  function makeSnapshot(mode: 'light' | 'dark'): ThemeSnapshot {
+    return {
+      mode,
+      cssVar: (name: string) =>
+        typeof getComputedStyle !== 'undefined'
+          ? getComputedStyle(document.documentElement).getPropertyValue(name).trim()
+          : ''
+    }
+  }
+
+  function getSnapshot(): ThemeSnapshot {
+    const mode = readMode()
+    if (mode !== lastMode) {
+      lastMode = mode
+      cached = makeSnapshot(mode)
+    }
+    return cached
+  }
+
+  function notify() {
+    const mode = readMode()
+    if (mode !== lastMode) {
+      lastMode = mode
+      cached = makeSnapshot(mode)
+      for (const cb of listeners) {
+        cb()
+      }
+    }
+  }
+
+  function ensureObservers() {
+    if (typeof document === 'undefined') {
+      return
+    }
+    if (!observer) {
+      observer = new MutationObserver(() => notify())
+      observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] })
+    }
+    if (!storageHandler) {
+      storageHandler = (e: StorageEvent) => {
+        if (e.key === 'theme') {
+          notify()
+        }
+      }
+      window.addEventListener('storage', storageHandler)
+    }
+    if (!mediaQuery) {
+      mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
+      mediaHandler = () => notify()
+      mediaQuery.addEventListener('change', mediaHandler)
+    }
+  }
+
+  function teardownIfUnused() {
+    if (listeners.size > 0) {
+      return
+    }
+    if (observer) {
+      observer.disconnect()
+      observer = null
+    }
+    if (storageHandler) {
+      window.removeEventListener('storage', storageHandler)
+      storageHandler = null
+    }
+    if (mediaQuery && mediaHandler) {
+      mediaQuery.removeEventListener('change', mediaHandler)
+      mediaQuery = null
+      mediaHandler = null
+    }
+  }
+
+  return {
+    getSnapshot,
+    subscribe: (cb: () => void) => {
+      listeners.add(cb)
+      ensureObservers()
+      return () => {
+        listeners.delete(cb)
+        teardownIfUnused()
+      }
+    }
+  }
+}
+
+function notifyViaToast(opts: NotifyOptions): void {
+  switch (opts.type) {
+    case 'success':
+      toast.success(opts.message)
+      break
+    case 'error':
+      toast.error(opts.message)
+      break
+    default:
+      toast(opts.message)
+      break
+  }
 }
 
 export function mountRuntimeBridge(inputs: BridgeInputs): void {
-  ;(globalThis as any).__SERVERBEE_REACT__ = React
-  ;(globalThis as any).__SERVERBEE_REACT_DOM__ = ReactDOM
-  ;(globalThis as any).__SERVERBEE_JSX_RUNTIME__ = JsxRuntime
-  ;(globalThis as any).__SERVERBEE_SDK__ = Sdk
+  ;(globalThis as Record<string, unknown>).__SERVERBEE_REACT__ = React
+  ;(globalThis as Record<string, unknown>).__SERVERBEE_REACT_DOM__ = ReactDOM
+  ;(globalThis as Record<string, unknown>).__SERVERBEE_JSX_RUNTIME__ = JsxRuntime
+  ;(globalThis as Record<string, unknown>).__SERVERBEE_SDK__ = Sdk
+
+  const serversStore = makeServerSummariesGetter(inputs.queryClient)
+  const serverByIdStore = makeServerByIdGetter(inputs.queryClient)
+  const subscribeServers = makeSubscribeServers(inputs.queryClient)
+  const themeWatcher = makeThemeWatcher()
 
   Sdk.createWidgetRuntime({
     apiBaseUrl: '/api',
     queryClient: inputs.queryClient,
-    serversStore: inputs.serversStore,
-    serverByIdStore: inputs.serverByIdStore,
-    themeStore: inputs.themeStore,
-    onConfigUpdate: inputs.onConfigUpdate
+    serversStore,
+    serverByIdStore,
+    subscribeServers,
+    themeStore: themeWatcher.getSnapshot,
+    subscribeTheme: themeWatcher.subscribe,
+    notify: notifyViaToast,
+    requestConfirm: inputs.requestConfirm,
+    onConfigUpdate: inputs.onConfigUpdate ?? (() => undefined)
   })
 }

From 5106b45c18839406d83e44f0a624737316bb3b40 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:27:12 +0800
Subject: [PATCH 56/64] fix(server): serve /runtime/* shims with no-cache
 headers

The widget-sdk / react / react-dom / jsx-runtime shim files referenced by
the SPA import-map are unhashed and re-emitted on every server upgrade.
Without explicit no-cache, browsers held onto stale shims after upgrades,
breaking dynamically-imported widget modules. Detect the /runtime/ prefix
in static_files and emit Cache-Control: no-cache, no-store, must-revalidate.
---
 crates/server/src/router/static_files.rs | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/crates/server/src/router/static_files.rs b/crates/server/src/router/static_files.rs
index 451af43e..9f435eff 100644
--- a/crates/server/src/router/static_files.rs
+++ b/crates/server/src/router/static_files.rs
@@ -29,6 +29,11 @@ fn embedded_file_response(path: &str, file: &rust_embed::EmbeddedFile) -> Respon
     let mut builder = Response::builder().header(header::CONTENT_TYPE, mime.as_ref());
     if path.starts_with("assets/") {
         builder = builder.header(header::CACHE_CONTROL, "public, max-age=31536000, immutable");
+    } else if path.starts_with("runtime/") {
+        // The runtime shim files are unhashed and re-emitted on every SPA
+        // upgrade; a stale browser cache here breaks the import-map and the
+        // dynamically-imported widget modules. Disable all caching.
+        builder = builder.header(header::CACHE_CONTROL, "no-cache, no-store, must-revalidate");
     } else {
         builder = builder.header(header::CACHE_CONTROL, "public, max-age=60");
     }

From 486f7ff2bd1d9efc6896ea7571af53533f423eca Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:28:29 +0800
Subject: [PATCH 57/64] feat(server): validate module_id references installed
 widget module

---
 crates/server/src/service/dashboard.rs | 135 ++++++++++++++++++++++++-
 1 file changed, 132 insertions(+), 3 deletions(-)

diff --git a/crates/server/src/service/dashboard.rs b/crates/server/src/service/dashboard.rs
index 12407f85..286b5061 100644
--- a/crates/server/src/service/dashboard.rs
+++ b/crates/server/src/service/dashboard.rs
@@ -4,7 +4,7 @@ use sea_orm::*;
 use serde::{Deserialize, Serialize};
 use uuid::Uuid;
 
-use crate::entity::{dashboard, dashboard_widget};
+use crate::entity::{dashboard, dashboard_widget, widget_module};
 use crate::error::AppError;
 
 const VALID_WIDGET_TYPES: &[&str] = &[
@@ -152,14 +152,29 @@ impl DashboardService {
             ));
         }
 
-        // Validate widget types
+        // Validate widget types and module references.
+        //
+        // Module lookups happen pre-transaction for simplicity. The race window
+        // (module uninstalled between this check and the txn) is tiny and the
+        // consequence is the same as referencing a missing module at render
+        // time: the UI shows a placeholder. Defense in depth lives in the
+        // widget renderer.
         if let Some(ref widgets) = input.widgets {
             for w in widgets {
                 if w.widget_type == "module" {
-                    if w.module_id.is_none() {
+                    let Some(module_id) = w.module_id.as_ref() else {
                         return Err(AppError::BadRequest(
                             "widget_type 'module' requires module_id".into(),
                         ));
+                    };
+                    let exists = widget_module::Entity::find_by_id(module_id)
+                        .one(db)
+                        .await?
+                        .is_some();
+                    if !exists {
+                        return Err(AppError::BadRequest(format!(
+                            "module_id '{module_id}' is not installed"
+                        )));
                     }
                 } else if !VALID_WIDGET_TYPES.contains(&w.widget_type.as_str()) {
                     return Err(AppError::BadRequest(format!(
@@ -654,6 +669,120 @@ mod tests {
         }
     }
 
+    #[tokio::test]
+    async fn test_update_unknown_module_id_rejected() {
+        let (db, _tmp) = setup_db_with_fk().await;
+
+        let dash = DashboardService::create(
+            &db,
+            CreateDashboardInput {
+                name: "Test".to_string(),
+            },
+        )
+        .await
+        .unwrap();
+
+        let result = DashboardService::update(
+            &db,
+            &dash.id,
+            UpdateDashboardInput {
+                name: None,
+                is_default: None,
+                sort_order: None,
+                widgets: Some(vec![WidgetInput {
+                    id: None,
+                    widget_type: "module".to_string(),
+                    module_id: Some("com.does.not.exist".to_string()),
+                    title: None,
+                    config_json: serde_json::json!({}),
+                    grid_x: 0,
+                    grid_y: 0,
+                    grid_w: 4,
+                    grid_h: 3,
+                    sort_order: 0,
+                }]),
+            },
+        )
+        .await;
+
+        assert!(result.is_err());
+        match result.unwrap_err() {
+            AppError::BadRequest(msg) => {
+                assert!(
+                    msg.contains("is not installed"),
+                    "unexpected error message: {msg}"
+                );
+                assert!(msg.contains("com.does.not.exist"));
+            }
+            other => panic!("Expected BadRequest, got {:?}", other),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_update_installed_module_id_accepted() {
+        use chrono::Utc;
+        use sea_orm::Set;
+
+        let (db, _tmp) = setup_db_with_fk().await;
+
+        // Seed a fake installed module
+        let module = widget_module::ActiveModel {
+            id: Set("com.test.widget".to_string()),
+            version: Set("1.0.0".to_string()),
+            source_type: Set(widget_module::SourceType::Upload),
+            source_url: Set(None),
+            bundled_by_theme_id: Set(None),
+            manifest_json: Set("{}".to_string()),
+            code_sha256: Set("abc".to_string()),
+            entry_path: Set("index.js".to_string()),
+            package_blob: Set(None),
+            installed_by: Set(None),
+            installed_at: Set(Utc::now()),
+            enabled: Set(true),
+        };
+        module.insert(&db).await.unwrap();
+
+        let dash = DashboardService::create(
+            &db,
+            CreateDashboardInput {
+                name: "Test".to_string(),
+            },
+        )
+        .await
+        .unwrap();
+
+        let result = DashboardService::update(
+            &db,
+            &dash.id,
+            UpdateDashboardInput {
+                name: None,
+                is_default: None,
+                sort_order: None,
+                widgets: Some(vec![WidgetInput {
+                    id: None,
+                    widget_type: "module".to_string(),
+                    module_id: Some("com.test.widget".to_string()),
+                    title: Some("Custom".to_string()),
+                    config_json: serde_json::json!({}),
+                    grid_x: 0,
+                    grid_y: 0,
+                    grid_w: 4,
+                    grid_h: 3,
+                    sort_order: 0,
+                }]),
+            },
+        )
+        .await
+        .unwrap();
+
+        assert_eq!(result.widgets.len(), 1);
+        assert_eq!(result.widgets[0].widget_type, "module");
+        assert_eq!(
+            result.widgets[0].module_id,
+            Some("com.test.widget".to_string())
+        );
+    }
+
     #[tokio::test]
     async fn test_delete_last_dashboard_rejected() {
         let (db, _tmp) = setup_db_with_fk().await;

From 3e0b05a0e4ccfb3d92b59a18bc36cd9c26ea4fbe Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:40:02 +0800
Subject: [PATCH 58/64] feat(web): file install accepts .zip + branches toast
 for collection

---
 apps/web/src/api/widget-modules.ts            | 21 ++++++++++++++++---
 apps/web/src/locales/en/settings.json         |  9 +++++---
 apps/web/src/locales/zh/settings.json         |  9 +++++---
 .../src/routes/_authed/settings/widgets.tsx   | 14 ++++++++++---
 4 files changed, 41 insertions(+), 12 deletions(-)

diff --git a/apps/web/src/api/widget-modules.ts b/apps/web/src/api/widget-modules.ts
index 7aa9cac1..b881d38a 100644
--- a/apps/web/src/api/widget-modules.ts
+++ b/apps/web/src/api/widget-modules.ts
@@ -11,11 +11,26 @@ export interface ModuleSummary {
   version: string
 }
 
-export interface ModuleInstallResult {
+export interface ModuleInstallEntry {
   id: string
   version: string
 }
 
+export type ModuleInstallResult =
+  | { kind: 'single'; id: string; version: string }
+  | { kind: 'collection'; widgets: ModuleInstallEntry[] }
+
+function asInstallResult(data: unknown): ModuleInstallResult {
+  if (Array.isArray(data)) {
+    return {
+      kind: 'collection',
+      widgets: data as ModuleInstallEntry[]
+    }
+  }
+  const entry = data as ModuleInstallEntry
+  return { kind: 'single', id: entry.id, version: entry.version }
+}
+
 const LIST_KEY = ['widget-modules'] as const
 
 export function useWidgetModules() {
@@ -56,7 +71,7 @@ export function useInstallFromUrl() {
         throw new Error(await readError(res))
       }
       const json = await res.json()
-      return json.data as ModuleInstallResult
+      return asInstallResult(json.data)
     },
     onSuccess: () => {
       qc.invalidateQueries({ queryKey: LIST_KEY }).catch(() => undefined)
@@ -79,7 +94,7 @@ export function useInstallFromFile() {
         throw new Error(await readError(res))
       }
       const json = await res.json()
-      return json.data as ModuleInstallResult
+      return asInstallResult(json.data)
     },
     onSuccess: () => {
       qc.invalidateQueries({ queryKey: LIST_KEY }).catch(() => undefined)
diff --git a/apps/web/src/locales/en/settings.json b/apps/web/src/locales/en/settings.json
index 1d77d05a..257e2869 100644
--- a/apps/web/src/locales/en/settings.json
+++ b/apps/web/src/locales/en/settings.json
@@ -525,8 +525,8 @@
   "widgets.install_from_url_desc": "Fetch a widget module from an HTTPS URL. The server validates and stores it locally.",
   "widgets.url_label": "Module URL",
   "widgets.install": "Install",
-  "widgets.upload_file": "Upload .js file",
-  "widgets.upload_file_desc": "Pick a single-file widget bundle (.js or .mjs) from your computer.",
+  "widgets.upload_file": "Upload widget bundle",
+  "widgets.upload_file_desc": "Pick a single .js/.mjs widget bundle or a .zip collection bundle from your computer.",
   "widgets.uploading": "Uploading…",
   "widgets.installed_modules": "Installed modules",
   "widgets.no_modules": "No widget modules installed yet.",
@@ -534,5 +534,8 @@
   "widgets.builtin_locked": "Built-in (cannot uninstall)",
   "widgets.confirm_uninstall": "Uninstall \"{{name}}\"? Any dashboard widgets using this module will stop rendering.",
   "widgets.toast_installed": "Installed {{id}} v{{version}}",
-  "widgets.toast_uninstalled": "Uninstalled {{id}}"
+  "widgets.toast_installed_collection": "Installed {{count}} widgets from collection",
+  "widgets.toast_uninstalled": "Uninstalled {{id}}",
+  "widgets.widget_config_module_not_installed": "Widget module is not installed",
+  "widgets.widget_config_module_no_fields": "This module exposes no configurable fields."
 }
diff --git a/apps/web/src/locales/zh/settings.json b/apps/web/src/locales/zh/settings.json
index ef450c5e..11b733d5 100644
--- a/apps/web/src/locales/zh/settings.json
+++ b/apps/web/src/locales/zh/settings.json
@@ -506,8 +506,8 @@
   "widgets.install_from_url_desc": "从 HTTPS URL 拉取 Widget 模块，服务端会校验并本地存储。",
   "widgets.url_label": "模块 URL",
   "widgets.install": "安装",
-  "widgets.upload_file": "上传 .js 文件",
-  "widgets.upload_file_desc": "从本地选择一个单文件 Widget 包（.js 或 .mjs）。",
+  "widgets.upload_file": "上传 Widget 包",
+  "widgets.upload_file_desc": "从本地选择单文件 Widget 包（.js / .mjs），或选择 .zip 集合包。",
   "widgets.uploading": "上传中…",
   "widgets.installed_modules": "已安装的模块",
   "widgets.no_modules": "尚未安装任何 Widget 模块。",
@@ -515,5 +515,8 @@
   "widgets.builtin_locked": "内置（不可卸载）",
   "widgets.confirm_uninstall": "确定卸载 “{{name}}” 吗？任何仪表盘上使用该模块的小组件都将无法渲染。",
   "widgets.toast_installed": "已安装 {{id}} v{{version}}",
-  "widgets.toast_uninstalled": "已卸载 {{id}}"
+  "widgets.toast_installed_collection": "安装了 {{count}} 个 widget",
+  "widgets.toast_uninstalled": "已卸载 {{id}}",
+  "widgets.widget_config_module_not_installed": "Widget 模块未安装",
+  "widgets.widget_config_module_no_fields": "该模块没有可配置字段。"
 }
diff --git a/apps/web/src/routes/_authed/settings/widgets.tsx b/apps/web/src/routes/_authed/settings/widgets.tsx
index c3df133e..2fe08e37 100644
--- a/apps/web/src/routes/_authed/settings/widgets.tsx
+++ b/apps/web/src/routes/_authed/settings/widgets.tsx
@@ -57,7 +57,11 @@ function WidgetsPage() {
     installUrl.mutate(trimmed, {
       onSuccess: (data) => {
         setUrl('')
-        toast.success(t('widgets.toast_installed', { id: data.id, version: data.version }))
+        if (data.kind === 'collection') {
+          toast.success(t('widgets.toast_installed_collection', { count: data.widgets.length }))
+        } else {
+          toast.success(t('widgets.toast_installed', { id: data.id, version: data.version }))
+        }
       },
       onError: (err) => {
         toast.error(err.message)
@@ -72,7 +76,11 @@ function WidgetsPage() {
     }
     installFile.mutate(file, {
       onSuccess: (data) => {
-        toast.success(t('widgets.toast_installed', { id: data.id, version: data.version }))
+        if (data.kind === 'collection') {
+          toast.success(t('widgets.toast_installed_collection', { count: data.widgets.length }))
+        } else {
+          toast.success(t('widgets.toast_installed', { id: data.id, version: data.version }))
+        }
       },
       onError: (err) => {
         toast.error(err.message)
@@ -131,7 +139,7 @@ function WidgetsPage() {
           <p className="text-muted-foreground text-sm">{t('widgets.upload_file_desc')}</p>
           <div className="flex items-center gap-2">
             <Input
-              accept=".js,.mjs"
+              accept=".js,.mjs,.zip"
               aria-label={t('widgets.upload_file')}
               className="flex-1"
               disabled={installFile.isPending}

From 853958ed12d0c012a25c95573f1eb60f36182b45 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:40:23 +0800
Subject: [PATCH 59/64] feat(web): module-aware widget config dialog via SDK
 renderConfigForm

When widget_type is "module", look up the registered module and use
the SDK's renderConfigForm to render fields for its configSchema.
Handles missing modules (disable save, show id-aware placeholder)
and modules with empty schemas (show a "no configurable fields"
notice). Adds tests for all three branches.
---
 .../dashboard/widget-config-dialog.test.tsx   | 143 +++++++++++++++++-
 .../dashboard/widget-config-dialog.tsx        |  39 ++++-
 apps/web/src/locales/en/dashboard.json        |   1 +
 apps/web/src/locales/zh/dashboard.json        |   1 +
 4 files changed, 180 insertions(+), 4 deletions(-)

diff --git a/apps/web/src/components/dashboard/widget-config-dialog.test.tsx b/apps/web/src/components/dashboard/widget-config-dialog.test.tsx
index 0a94f200..da4dc86e 100644
--- a/apps/web/src/components/dashboard/widget-config-dialog.test.tsx
+++ b/apps/web/src/components/dashboard/widget-config-dialog.test.tsx
@@ -1,6 +1,8 @@
-import { render, screen } from '@testing-library/react'
+import { defineWidget, type WidgetManifest, z } from '@serverbee/widget-sdk'
+import { fireEvent, render, screen } from '@testing-library/react'
 import type { ReactNode } from 'react'
-import { describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { registryActions } from '@/widgets-runtime/registry'
 import { WidgetConfigDialog } from './widget-config-dialog'
 
 const translations: Record<string, string> = {
@@ -26,7 +28,12 @@ const translations: Record<string, string> = {
   'common.timeRange.24hours': '24 hours',
   'common.timeRange.30days': '30 days',
   'common.timeRange.60days': '60 days',
-  'common.timeRange.90days': '90 days'
+  'common.timeRange.90days': '90 days',
+  module_not_installed: 'Widget module not installed',
+  module_not_installed_id: 'Widget module "{{id}}" not installed',
+  module_config_no_fields: 'This module exposes no configurable fields.',
+  save: 'Save',
+  add_widget: 'Add'
 }
 
 vi.mock('react-i18next', () => ({
@@ -126,6 +133,7 @@ const mockServers = [
 ]
 
 const noop = vi.fn()
+const NOT_INSTALLED_RE = /not installed/i
 
 describe('WidgetConfigDialog', () => {
   it('renders metric select for stat-number widget', () => {
@@ -282,4 +290,133 @@ describe('WidgetConfigDialog', () => {
     expect(screen.getByText('60 days')).toBeInTheDocument()
     expect(screen.getByText('90 days')).toBeInTheDocument()
   })
+
+  describe('module widgets', () => {
+    const moduleId = 'com.test.cfg-dialog'
+    const fakeManifest: WidgetManifest = {
+      id: moduleId,
+      version: '1.0.0',
+      name: 'Test',
+      category: 'Real-time',
+      sizing: { defaultW: 2, defaultH: 2, minW: 1, minH: 1, strategy: 'free' },
+      sdkVersion: '^0.1.0'
+    }
+
+    afterEach(() => {
+      registryActions.unregister(moduleId)
+    })
+
+    it('renders the SDK config form fields for a registered module widget', () => {
+      const module = defineWidget({
+        configSchema: z.object({
+          label: z.string().describe('Label')
+        }),
+        component: () => <div />
+      })
+      registryActions.register(moduleId, module, fakeManifest)
+
+      const onSubmit = vi.fn()
+      render(
+        <WidgetConfigDialog
+          onOpenChange={noop}
+          onSubmit={onSubmit}
+          open
+          servers={mockServers as never}
+          widget={{
+            id: 'w-mod',
+            dashboard_id: 'd-1',
+            widget_type: 'module',
+            module_id: moduleId,
+            title: null,
+            config_json: '{"label":"hi"}',
+            grid_x: 0,
+            grid_y: 0,
+            grid_w: 2,
+            grid_h: 2,
+            sort_order: 0,
+            created_at: '2026-03-20T00:00:00Z'
+          }}
+          widgetType="module"
+        />
+      )
+
+      // The renderer surfaces the field label
+      expect(screen.getByText('Label')).toBeInTheDocument()
+      // Existing value is loaded into the input
+      const labelInput = screen.getByDisplayValue('hi') as HTMLInputElement
+      expect(labelInput).toBeInTheDocument()
+
+      // Type a new value and save
+      fireEvent.change(labelInput, { target: { value: 'world' } })
+      fireEvent.click(screen.getByText('Save'))
+      expect(onSubmit).toHaveBeenCalledTimes(1)
+      const [, configJson] = onSubmit.mock.calls[0]
+      expect(JSON.parse(configJson)).toMatchObject({ label: 'world' })
+    })
+
+    it('shows a placeholder when the module is not installed and disables save', () => {
+      const onSubmit = vi.fn()
+      render(
+        <WidgetConfigDialog
+          onOpenChange={noop}
+          onSubmit={onSubmit}
+          open
+          servers={mockServers as never}
+          widget={{
+            id: 'w-mod',
+            dashboard_id: 'd-1',
+            widget_type: 'module',
+            module_id: 'com.does.not.exist',
+            title: null,
+            config_json: '{}',
+            grid_x: 0,
+            grid_y: 0,
+            grid_w: 2,
+            grid_h: 2,
+            sort_order: 0,
+            created_at: '2026-03-20T00:00:00Z'
+          }}
+          widgetType="module"
+        />
+      )
+
+      expect(screen.getByText(NOT_INSTALLED_RE)).toBeInTheDocument()
+      const saveButton = screen.getByText('Save') as HTMLButtonElement
+      expect(saveButton).toBeDisabled()
+    })
+
+    it('shows a "no configurable fields" message for modules with empty configSchema', () => {
+      const module = defineWidget({
+        configSchema: z.object({}),
+        component: () => <div />
+      })
+      registryActions.register(moduleId, module, fakeManifest)
+
+      render(
+        <WidgetConfigDialog
+          onOpenChange={noop}
+          onSubmit={noop}
+          open
+          servers={mockServers as never}
+          widget={{
+            id: 'w-mod',
+            dashboard_id: 'd-1',
+            widget_type: 'module',
+            module_id: moduleId,
+            title: null,
+            config_json: '{}',
+            grid_x: 0,
+            grid_y: 0,
+            grid_w: 2,
+            grid_h: 2,
+            sort_order: 0,
+            created_at: '2026-03-20T00:00:00Z'
+          }}
+          widgetType="module"
+        />
+      )
+
+      expect(screen.getByText('This module exposes no configurable fields.')).toBeInTheDocument()
+    })
+  })
 })
diff --git a/apps/web/src/components/dashboard/widget-config-dialog.tsx b/apps/web/src/components/dashboard/widget-config-dialog.tsx
index bc436f57..0123113a 100644
--- a/apps/web/src/components/dashboard/widget-config-dialog.tsx
+++ b/apps/web/src/components/dashboard/widget-config-dialog.tsx
@@ -1,3 +1,4 @@
+import { renderConfigForm } from '@serverbee/widget-sdk'
 import { useEffect, useMemo, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import { Button } from '@/components/ui/button'
@@ -26,6 +27,7 @@ import type {
   UptimeTimelineConfig,
   WidgetConfig
 } from '@/lib/widget-types'
+import { type RegistryEntry, registryActions } from '@/widgets-runtime/registry'
 
 interface WidgetConfigDialogProps {
   onOpenChange: (open: boolean) => void
@@ -644,6 +646,25 @@ function useUptimeDaysOptions(t: (key: string) => string): { label: string; valu
   ]
 }
 
+function ModuleForm({
+  entry,
+  config,
+  onChange,
+  t
+}: {
+  config: Record<string, unknown>
+  entry: RegistryEntry
+  onChange: (c: Record<string, unknown>) => void
+  t: (key: string) => string
+}) {
+  const schema = entry.module.configSchema
+  const info = useMemo(() => schema.introspect(), [schema])
+  if (info.kind !== 'object' || !info.shape || Object.keys(info.shape).length === 0) {
+    return <p className="text-muted-foreground text-sm">{t('module_config_no_fields')}</p>
+  }
+  return <div data-testid="module-config-form">{renderConfigForm(schema, config, onChange)}</div>
+}
+
 function UptimeTimelineForm({
   config,
   servers,
@@ -688,6 +709,7 @@ function UptimeTimelineForm({
   )
 }
 
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: dispatcher renders one form per widget_type; refactoring to a table is more work than the value
 export function WidgetConfigDialog({
   open,
   onOpenChange,
@@ -709,6 +731,13 @@ export function WidgetConfigDialog({
   }, [widget])
 
   const needsNoConfig = widgetType === 'service-status' || widgetType === 'server-map'
+  const isModule = widgetType === 'module'
+  const moduleId = widget?.module_id ?? null
+  const moduleEntry = useMemo(
+    () => (isModule && moduleId ? registryActions.get(moduleId) : undefined),
+    [isModule, moduleId]
+  )
+  const moduleMissing = isModule && !moduleEntry
 
   const handleSubmit = () => {
     // Seed per-widget defaults that the form only shows but doesn't write,
@@ -784,12 +813,20 @@ export function WidgetConfigDialog({
               t={t}
             />
           )}
+          {isModule && moduleEntry && <ModuleForm config={config} entry={moduleEntry} onChange={setConfig} t={t} />}
+          {moduleMissing && (
+            <p className="text-destructive text-sm">
+              {moduleId ? t('module_not_installed_id').replace('{{id}}', moduleId) : t('module_not_installed')}
+            </p>
+          )}
           {needsNoConfig && (
             <p className="text-muted-foreground text-sm">{t('dialogs.widgetConfig.messages.noConfigNeeded')}</p>
           )}
         </div>
         <DialogFooter>
-          <Button onClick={handleSubmit}>{widget ? t('save') : t('add_widget')}</Button>
+          <Button disabled={moduleMissing} onClick={handleSubmit}>
+            {widget ? t('save') : t('add_widget')}
+          </Button>
         </DialogFooter>
       </DialogContent>
     </Dialog>
diff --git a/apps/web/src/locales/en/dashboard.json b/apps/web/src/locales/en/dashboard.json
index 148dea77..f43f5ae4 100644
--- a/apps/web/src/locales/en/dashboard.json
+++ b/apps/web/src/locales/en/dashboard.json
@@ -37,6 +37,7 @@
   "module_not_installed": "Widget module not installed",
   "module_not_installed_id": "Widget module \"{{id}}\" not installed",
   "module_config_invalid": "Widget config invalid: {{message}}",
+  "module_config_no_fields": "This module exposes no configurable fields.",
   "widgetPicker": {
     "categories": {
       "Real-time": "Real-time",
diff --git a/apps/web/src/locales/zh/dashboard.json b/apps/web/src/locales/zh/dashboard.json
index 4b2cf78e..d8cf3b51 100644
--- a/apps/web/src/locales/zh/dashboard.json
+++ b/apps/web/src/locales/zh/dashboard.json
@@ -37,6 +37,7 @@
   "module_not_installed": "组件模块未安装",
   "module_not_installed_id": "组件模块 \"{{id}}\" 未安装",
   "module_config_invalid": "组件配置无效：{{message}}",
+  "module_config_no_fields": "该模块没有可配置字段。",
   "widgetPicker": {
     "categories": {
       "Real-time": "实时",

From 674bf839bd35a37a186412dd9f6a91b3322e9572 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:41:01 +0800
Subject: [PATCH 60/64] docs: spec dual-column reality + hook category fixes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Spec §5 originally claimed widget_type would be renamed to module_id
in a single migration. The actual implementation keeps both columns
to let legacy V1 widgets and module-backed V2 widgets coexist on the
same dashboard during the rewrite period. Document the dual-column
state and the eventual cutover.

custom-widgets.mdx: move useCapability to the live-hook section
(it subscribes to the WS store via useSyncExternalStore, not REST).
Split data hooks into "live" (server snapshot) vs "domain" (REST).
---
 apps/docs/content/docs/cn/custom-widgets.mdx             | 5 +++--
 apps/docs/content/docs/en/custom-widgets.mdx             | 5 +++--
 .../specs/2026-05-28-custom-widget-system-design.md      | 9 ++++++++-
 3 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/apps/docs/content/docs/cn/custom-widgets.mdx b/apps/docs/content/docs/cn/custom-widgets.mdx
index dd712208..3e0a34a4 100644
--- a/apps/docs/content/docs/cn/custom-widgets.mdx
+++ b/apps/docs/content/docs/cn/custom-widgets.mdx
@@ -255,8 +255,9 @@ curl -X POST "https://your-host/api/widget-modules" \
 
 - `defineWidget` — 声明组件的入口；
 - `z` / `ZodSchema` — 内嵌的 Zod，用于描述配置项 schema；
-- 数据钩子：`useServers`、`useServer`、`useMetric`、`useHistory`、`useTraffic`、`useAlerts`、`useServiceMonitors`、`useUptime`、`useGeoIp`；
-- 宿主钩子：`useTheme`、`useConfigUpdate`、`useCapability`；
+- 实时钩子：`useServers`、`useServer`、`useMetric`、`useCapability`（通过 `useSyncExternalStore` 订阅 WebSocket 实时数据）；
+- 业务钩子：`useHistory`、`useTraffic`、`useAlerts`、`useServiceMonitors`、`useUptime`、`useGeoIp`；
+- 宿主钩子：`useTheme`、`useConfigUpdate`；
 - 通用逃生舱：`useApiQuery` / `useApiMutation` 直接调用后端 REST API；
 - `createActionsHelper` 与 `ActionDefinition` —— 在组件上注册按钮操作。
 
diff --git a/apps/docs/content/docs/en/custom-widgets.mdx b/apps/docs/content/docs/en/custom-widgets.mdx
index 1ca91e5a..c84b62a7 100644
--- a/apps/docs/content/docs/en/custom-widgets.mdx
+++ b/apps/docs/content/docs/en/custom-widgets.mdx
@@ -255,8 +255,9 @@ See [Dashboards & Widgets](/en/docs/dashboards) for more on layout and editing.
 
 - `defineWidget` — declares a widget's entry point.
 - `z` / `ZodSchema` — bundled Zod for describing config schemas.
-- Data hooks: `useServers`, `useServer`, `useMetric`, `useHistory`, `useTraffic`, `useAlerts`, `useServiceMonitors`, `useUptime`, `useGeoIp`.
-- Host hooks: `useTheme`, `useConfigUpdate`, `useCapability`.
+- Live hooks: `useServers`, `useServer`, `useMetric`, `useCapability` (subscribe to the live WebSocket store via `useSyncExternalStore`).
+- Domain hooks: `useHistory`, `useTraffic`, `useAlerts`, `useServiceMonitors`, `useUptime`, `useGeoIp`.
+- Host hooks: `useTheme`, `useConfigUpdate`.
 - Generic escape hatches: `useApiQuery` / `useApiMutation` for direct REST calls.
 - `createActionsHelper` and `ActionDefinition` for registering action buttons on a widget.
 
diff --git a/docs/superpowers/specs/2026-05-28-custom-widget-system-design.md b/docs/superpowers/specs/2026-05-28-custom-widget-system-design.md
index 27c5edd5..d4a58521 100644
--- a/docs/superpowers/specs/2026-05-28-custom-widget-system-design.md
+++ b/docs/superpowers/specs/2026-05-28-custom-widget-system-design.md
@@ -509,7 +509,14 @@ The rewrite is chunked to surface SDK gaps early:
 
 After Chunk C lands, the old `WidgetRenderer` + `widget-types.ts` + per-type config dialog code is deleted in a single cleanup commit.
 
-Per project convention, `dashboard_widget.widget_type` is renamed to `module_id` in a schema-only migration; no data conversion (dev period).
+### Schema reality (implementation note)
+
+The first cut keeps `widget_type` alongside a new nullable `module_id` column rather than renaming:
+
+- Legacy widgets continue to use `widget_type='gauge' | 'markdown' | ...` with `module_id=NULL`.
+- Module-backed widgets use `widget_type='module'` with `module_id` pointing at `widget_module.id`.
+
+This lets the 14 legacy widgets keep their V1 switch-based renderer while V2 module dispatch runs in parallel. When Chunks A–C land and the legacy renderer is deleted, the `widget_type` column is dropped in a follow-up migration and `module_id` becomes mandatory.
 
 ---
 

From 70c7b3adcf1a1005264ab4528fa24e9b928f3816 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:47:23 +0800
Subject: [PATCH 61/64] docs: update widget safety surface + drop stale theme
 references
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

custom-widgets.mdx now documents the post-review hardening: 32 MiB
zip total cap + 64-entry cap, broadened SSRF reserved ranges with
explicit redirect rejection, id-collision 409, sdkVersion semver
gating, audit logging, and the built-in ActionButton confirm/toast
behaviour.

Drop SERVERBEE_FEATURE__CUSTOM_THEMES env var and [feature].custom_themes
config table from configuration.mdx — the legacy custom-theme feature
was deleted in f2a1cb72 and the corresponding config field no longer
exists.

Drop theme_ref and "resolved theme variables" mentions from
status-page.mdx — the column was dropped in m20260526_000036 and the
public response no longer carries a theme block.
---
 apps/docs/content/docs/cn/configuration.mdx  |  8 --------
 apps/docs/content/docs/cn/custom-widgets.mdx | 10 +++++++---
 apps/docs/content/docs/cn/status-page.mdx    |  6 +-----
 apps/docs/content/docs/en/configuration.mdx  |  7 -------
 apps/docs/content/docs/en/custom-widgets.mdx | 10 +++++++---
 apps/docs/content/docs/en/status-page.mdx    |  6 +-----
 6 files changed, 16 insertions(+), 31 deletions(-)

diff --git a/apps/docs/content/docs/cn/configuration.mdx b/apps/docs/content/docs/cn/configuration.mdx
index da4e89c4..473bc41d 100644
--- a/apps/docs/content/docs/cn/configuration.mdx
+++ b/apps/docs/content/docs/cn/configuration.mdx
@@ -57,7 +57,6 @@ ServerBee 使用 [figment](https://github.com/SergioBenitez/Figment) 库加载
 | `SERVERBEE_AUTH__MAX_SERVERS` | `0` | 通过注册码接入的最大服务器数（0 = 不限制），尽力软限制 |
 | `SERVERBEE_SERVER__TRUSTED_PROXIES` | 私有/回环 CIDR | 受信任的反向代理 CIDR 列表，默认信任 RFC 1918 + 回环地址。设为 `[]` 禁用 |
 | `SERVERBEE_SCHEDULER__TIMEZONE` | `UTC` | 流量日聚合时区（如 `Asia/Shanghai`） |
-| `SERVERBEE_FEATURE__CUSTOM_THEMES` | `true` | 将 `feature.custom_themes` 设为 false 可禁用用户自定义主题。自定义引用会在读取时强制转换为 `preset:default` |
 | `SERVERBEE_LOG__LEVEL` | `info` | 日志级别：`trace`/`debug`/`info`/`warn`/`error` |
 | `SERVERBEE_LOG__FILE` | `""` | 日志文件路径，留空输出到 stdout |
 
@@ -353,13 +352,6 @@ ip_quality_event_days = 90
 # 默认: "UTC"
 timezone = "UTC"
 
-# --- 功能开关 ---
-[feature]
-# 是否启用用户自定义主题
-# 设为 false 时，自定义主题引用会在读取时强制转换为 preset:default
-# 默认: true
-custom_themes = true
-
 # --- GeoIP 地理位置 ---
 [geoip]
 # MaxMind 兼容 MMDB 数据库文件路径，路径非空时使用自定义 GeoIP；为空时可在设置页下载 DB-IP Lite
diff --git a/apps/docs/content/docs/cn/custom-widgets.mdx b/apps/docs/content/docs/cn/custom-widgets.mdx
index 3e0a34a4..d8929392 100644
--- a/apps/docs/content/docs/cn/custom-widgets.mdx
+++ b/apps/docs/content/docs/cn/custom-widgets.mdx
@@ -276,12 +276,16 @@ curl -X DELETE "https://your-host/api/widget-modules/com.example.hello" \
 
 ## 限制与安全
 
-- **大小上限**：单个文件或 `.zip` 不超过 **1 MiB**；zip 中单个条目最大 **5 MiB**（解压后）。
-- **SSRF 防护**：从 URL 安装时，私网、回环、链路本地地址会被直接拒绝。
+- **大小上限**：上传单个 `.js` 文件或 `.zip` 不超过 **1 MiB**；zip 中单个条目最大 **5 MiB**（解压后）；整个 zip 的解压总大小不超过 **32 MiB**，条目数不超过 **64**。
+- **SSRF 防护**：从 URL 安装会先做 DNS 解析，任何落在保留/私有段的 IP 都会被拒绝——回环（`127.0.0.0/8`、`::1`）、私网（`10/8`、`172.16/12`、`192.168/16`）、CGNAT（`100.64/10`）、链路本地（`169.254/16`，含云元数据接口）、IPv6 ULA（`fc00::/7`）和链路本地（`fe80::/10`）、benchmarking、文档、组播、保留段。HTTP 跳转被禁用——3xx 响应直接拒绝，避免公网 URL 通过重定向绕回内网。
 - **Zip-slip 防护**：解压时会拒绝包含 `..` 或绝对路径的条目。
-- **静态解析**：清单必须能用纯正则解析出来；没有任何 `eval` / `Function()` 调用。
+- **静态解析**：清单必须能用纯正则解析出来；没有任何 `eval` / `Function()` 调用。解析器在源码 > 1 MiB 时直接拒绝。
+- **ID 冲突拒绝**：若上传的 `id` 已属于其他来源的模块（例如试图覆盖内置组件），返回 `409 Conflict`。
+- **SDK 版本校验**：每个清单声明 `sdkVersion` 兼容范围；不在范围内的模块不会被加载。
 - **管理员限定**：安装、卸载接口都要求管理员权限；普通成员只能读取列表与资源。
+- **审计日志**：每次安装/卸载都会写入 audit log，记录操作者、来源、id、版本、code SHA-256。
 - **同源运行**：组件运行在主 SPA 同源环境，请只安装来源可信的代码。
+- **Action 按钮**：通过 `defineWidget({ actions })` 声明的按钮自带确认对话框（`confirm` 配置生效时）、加载状态和成功/失败 toast 提示。
 
 <Cards>
   <Card title="仪表盘与组件" href="/cn/docs/dashboards" />
diff --git a/apps/docs/content/docs/cn/status-page.mdx b/apps/docs/content/docs/cn/status-page.mdx
index 44f17c09..133ed842 100644
--- a/apps/docs/content/docs/cn/status-page.mdx
+++ b/apps/docs/content/docs/cn/status-page.mdx
@@ -1,6 +1,6 @@
 ---
 title: 公开状态页
-description: 发布包含事件公告、维护窗口、可用性历史和自定义主题的公开健康状态页。
+description: 发布包含事件公告、维护窗口和可用性历史的公开健康状态页。
 icon: Globe
 ---
 
@@ -48,7 +48,6 @@ GET /api/status
 | 启用 | `enabled` | 禁用后页面返回 404 |
 | 黄色可用性阈值 | `uptime_yellow_threshold` | 低于该百分比的日期显示为降级 |
 | 红色可用性阈值 | `uptime_red_threshold` | 低于该百分比的日期显示为严重故障 |
-| 主题 | `theme_ref` | 预设/自定义主题引用，或 `null` 跟随后台默认主题 |
 
 <Callout type="info">
 当前 API 请求字段使用 `server_ids_json` 和 `status_page_ids_json` 表示选择的 ID。这些字段在请求体中接受 JSON 数组。
@@ -63,7 +62,6 @@ GET /api/status/{slug}
 响应包含：
 
 - `page` -- 页面元数据和显示选项
-- `theme` -- 解析后的主题变量
 - `servers` -- 选中服务器状态、可用性百分比和 90 天每日可用性数据
 - `active_incidents` -- 关联到页面且尚未解决的事件
 - `planned_maintenances` -- 关联到页面的活动/计划维护窗口
@@ -158,8 +156,6 @@ GET /api/status/{slug}
 }
 ```
 
-更新时可以传入 `theme_ref` 设置自定义主题，例如 `"preset:default"` 或自定义主题引用。传 `null` 表示跟随后台默认主题。
-
 <Cards>
   <Card title="自定义组件" href="/cn/docs/custom-widgets" />
   <Card title="服务监控" href="/cn/docs/service-monitors" />
diff --git a/apps/docs/content/docs/en/configuration.mdx b/apps/docs/content/docs/en/configuration.mdx
index 514ca045..7a4a7081 100644
--- a/apps/docs/content/docs/en/configuration.mdx
+++ b/apps/docs/content/docs/en/configuration.mdx
@@ -51,7 +51,6 @@ There is no admin username/password environment variable. On first start (when n
 | `SERVERBEE_AUTH__MAX_SERVERS` | `0` | Maximum servers allowed via enrollment (0 = no limit). Best-effort soft cap |
 | `SERVERBEE_SERVER__TRUSTED_PROXIES` | private/loopback CIDRs | CIDR list of trusted reverse proxies. Defaults to RFC 1918 + loopback. Set to `[]` to disable |
 | `SERVERBEE_SCHEDULER__TIMEZONE` | `UTC` | Timezone for daily traffic aggregation (e.g. `Asia/Shanghai`) |
-| `SERVERBEE_FEATURE__CUSTOM_THEMES` | `true` | Set `feature.custom_themes` to false to disable user-defined themes. Custom refs are read-coerced to `preset:default` |
 | `SERVERBEE_LOG__LEVEL` | `info` | Log level: `trace`, `debug`, `info`, `warn`, `error` |
 | `SERVERBEE_LOG__FILE` | `""` | Log file path. Empty means stdout only |
 
@@ -280,12 +279,6 @@ Raw metric records are collected every 60 seconds and retained for 7 days by def
 |-----|------|---------|-------------|
 | `timezone` | string | `"UTC"` | Timezone for daily traffic aggregation and billing cycle computation. Use IANA timezone names (e.g. `Asia/Shanghai`, `US/Eastern`) |
 
-### `[feature]` -- Feature Flags
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `custom_themes` | bool | `true` | Disable user-defined themes when false. Custom refs are read-coerced to `preset:default` |
-
 ### `[rate_limit]` -- Rate Limiting
 
 | Key | Type | Default | Description |
diff --git a/apps/docs/content/docs/en/custom-widgets.mdx b/apps/docs/content/docs/en/custom-widgets.mdx
index c84b62a7..700a2b00 100644
--- a/apps/docs/content/docs/en/custom-widgets.mdx
+++ b/apps/docs/content/docs/en/custom-widgets.mdx
@@ -276,12 +276,16 @@ Built-in widgets (for example `com.serverbee.hello-world`) cannot be uninstalled
 
 ## Limits and safety
 
-- **Size cap**: a single `.js` file or `.zip` may not exceed **1 MiB**; each entry inside the zip is capped at **5 MiB** uncompressed.
-- **SSRF protection**: URL installs reject private, loopback, and link-local addresses outright.
+- **Size caps**: a single `.js` file or `.zip` may not exceed **1 MiB** on upload; each entry inside a zip is capped at **5 MiB** uncompressed; the whole zip is capped at **32 MiB** total uncompressed across at most **64 entries**.
+- **SSRF protection**: URL installs resolve DNS and reject any host whose IP falls in a reserved/private range — loopback (`127.0.0.0/8`, `::1`), private networks (`10/8`, `172.16/12`, `192.168/16`), CGNAT (`100.64/10`), link-local (`169.254/16` — includes cloud metadata endpoints), IPv6 ULA (`fc00::/7`) and link-local (`fe80::/10`), benchmarking, documentation, multicast, and reserved ranges. HTTP redirects are disabled — 3xx responses are rejected outright so a public URL cannot pivot into the private network.
 - **Zip-slip protection**: extraction rejects entries with `..` or absolute paths.
-- **Static parsing only**: the manifest must be extractable with a plain regex — there is no `eval` / `Function()` involved in installation.
+- **Static parsing only**: the manifest must be extractable with a plain regex — there is no `eval` / `Function()` involved in installation. The extractor itself rejects sources > 1 MiB up front.
+- **ID conflict rejection**: an upload whose `id` already belongs to a module from a different source (e.g. trying to overwrite a built-in with an upload) is refused with `409 Conflict`.
+- **SDK version gating**: each manifest declares `sdkVersion` as a semver range; the loader refuses to register a module whose required range does not match the host SDK.
 - **Admin-gated**: install and uninstall endpoints require admin privileges; members can only list and fetch served assets.
+- **Audit logged**: every install and uninstall is recorded in the audit log with the actor, source, id, version, and code SHA-256.
 - **Same-origin execution**: widgets run in the same browsing context as the main SPA — only install code from sources you trust.
+- **Action buttons** declared via `defineWidget({ actions })` get a built-in confirm dialog (when `confirm` is set), pending state, and toast notifications on success/failure.
 
 <Cards>
   <Card title="Dashboards & Widgets" href="/en/docs/dashboards" />
diff --git a/apps/docs/content/docs/en/status-page.mdx b/apps/docs/content/docs/en/status-page.mdx
index a366ca10..589f811d 100644
--- a/apps/docs/content/docs/en/status-page.mdx
+++ b/apps/docs/content/docs/en/status-page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Status Pages
-description: Publish public server health pages with incidents, maintenance windows, uptime history, and custom themes.
+description: Publish public server health pages with incidents, maintenance windows, and uptime history.
 icon: Globe
 ---
 
@@ -48,7 +48,6 @@ Create and manage pages in **Settings → Status Pages**. Each page has its own
 | Enabled | `enabled` | Disabled pages return 404 |
 | Yellow uptime threshold | `uptime_yellow_threshold` | Days below this percentage show as degraded |
 | Red uptime threshold | `uptime_red_threshold` | Days below this percentage show as major outage |
-| Theme | `theme_ref` | Preset/custom theme reference, or `null` to follow admin default |
 
 <Callout type="info">
 The current API request fields use `server_ids_json` and `status_page_ids_json` for selected IDs. These fields accept JSON arrays in request bodies.
@@ -63,7 +62,6 @@ GET /api/status/{slug}
 The response includes:
 
 - `page` -- page metadata and display options
-- `theme` -- resolved theme variables
 - `servers` -- selected server statuses, uptime percentages, and 90-day daily uptime data
 - `active_incidents` -- unresolved incidents linked to the page
 - `planned_maintenances` -- active/upcoming maintenance windows linked to the page
@@ -158,8 +156,6 @@ Create example:
 }
 ```
 
-To set a custom theme during update, pass `theme_ref`, for example `"preset:default"` or a custom theme reference. Use `null` to follow the admin default.
-
 <Cards>
   <Card title="Custom Widgets" href="/en/docs/custom-widgets" />
   <Card title="Service Monitors" href="/en/docs/service-monitors" />

From 3755f9c3e760d680088b6fb801d15e985500e6e3 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:49:11 +0800
Subject: [PATCH 62/64] chore(web): drop unused widget-config i18n keys from
 settings namespace

The dialog placeholders for "module not installed" and "no
configurable fields" were finalised under the dashboard namespace
(dashboard.json) in 68249ab6 / 853958ed. Leave only the settings-page
toast strings here.
---
 apps/web/src/locales/en/settings.json | 4 +---
 apps/web/src/locales/zh/settings.json | 4 +---
 2 files changed, 2 insertions(+), 6 deletions(-)

diff --git a/apps/web/src/locales/en/settings.json b/apps/web/src/locales/en/settings.json
index 257e2869..4d8c697a 100644
--- a/apps/web/src/locales/en/settings.json
+++ b/apps/web/src/locales/en/settings.json
@@ -535,7 +535,5 @@
   "widgets.confirm_uninstall": "Uninstall \"{{name}}\"? Any dashboard widgets using this module will stop rendering.",
   "widgets.toast_installed": "Installed {{id}} v{{version}}",
   "widgets.toast_installed_collection": "Installed {{count}} widgets from collection",
-  "widgets.toast_uninstalled": "Uninstalled {{id}}",
-  "widgets.widget_config_module_not_installed": "Widget module is not installed",
-  "widgets.widget_config_module_no_fields": "This module exposes no configurable fields."
+  "widgets.toast_uninstalled": "Uninstalled {{id}}"
 }
diff --git a/apps/web/src/locales/zh/settings.json b/apps/web/src/locales/zh/settings.json
index 11b733d5..80d8409c 100644
--- a/apps/web/src/locales/zh/settings.json
+++ b/apps/web/src/locales/zh/settings.json
@@ -516,7 +516,5 @@
   "widgets.confirm_uninstall": "确定卸载 “{{name}}” 吗？任何仪表盘上使用该模块的小组件都将无法渲染。",
   "widgets.toast_installed": "已安装 {{id}} v{{version}}",
   "widgets.toast_installed_collection": "安装了 {{count}} 个 widget",
-  "widgets.toast_uninstalled": "已卸载 {{id}}",
-  "widgets.widget_config_module_not_installed": "Widget 模块未安装",
-  "widgets.widget_config_module_no_fields": "该模块没有可配置字段。"
+  "widgets.toast_uninstalled": "已卸载 {{id}}"
 }

From b17196a114d8d328f7d2711a5861a77d1f3f1170 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:49:58 +0800
Subject: [PATCH 63/64] chore: bump version to v1.0.0-alpha.5

---
 CHANGELOG.md          | 17 +++++++++++++++++
 Cargo.lock            |  6 +++---
 Cargo.toml            |  2 +-
 apps/web/package.json |  2 +-
 4 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 45c731b8..ec7ac3ab 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0-alpha.5] - 2026-05-28
+
+### Added
+
+- **Custom widget system (B/C method)** -- New `@serverbee/widget-sdk` workspace package exposes `defineWidget`, a bundled `z` schema validator, and a typed hook surface (live: `useServers/useServer/useMetric/useCapability` via `useSyncExternalStore`; domain: `useHistory/useTraffic/useAlerts/useServiceMonitors/useUptime/useGeoIp`; host: `useTheme/useConfigUpdate`; escape hatches: `useApiQuery/useApiMutation`). Widgets are authored as a single ESM file with a top-of-file `@serverbee-widget` JSDoc manifest, statically extractable, no `eval`. Admins install via `POST /api/widget-modules` (URL or multipart upload) for single `.js`/`.mjs` files or `.zip` collection bundles with a `collection.json` index. Built-in widgets are emitted by a new Vite nested-build plugin to `apps/web/dist/builtin-widgets/`, embedded into the server binary via rust-embed, and registered at boot
+- **Dashboard module rendering** -- `dashboard_widget` gained a `module_id` column; `widget_type='module'` widgets dispatch through the widget registry and render via the SDK component contract. The picker surfaces installed modules under a "Custom Widgets" section; the config dialog renders the module's `configSchema` via the SDK form renderer (real renderers for `z.metricPath`/`z.color`/`z.duration`) with friendly placeholders for missing modules or empty schemas. `ActionButton` from the SDK ships with confirm dialog, pending state, and success/error toast wiring
+- **Bilingual widget docs** -- `apps/docs/content/docs/{en,cn}/custom-widgets.mdx` covers method B (single file) and method C (zip bundle) end-to-end: manifest fields, build pipeline with React/SDK externals, install flows, asset resolution rules, SDK surface summary, and the full safety/limits table
+
+### Changed
+
+- **Widget install hardening** -- SSRF guard now resolves DNS and rejects any host whose IP falls in a reserved/private range (loopback, RFC 1918, CGNAT, link-local incl. cloud metadata, IPv6 ULA/link-local, benchmarking, documentation, multicast, reserved); HTTP redirects are disabled; uploads enforce a per-route 1 MiB body limit with streaming size accounting; zip extraction caps total uncompressed size at 32 MiB across at most 64 entries; manifest extractor rejects sources > 1 MiB up front; id conflicts across `source_type` (e.g. upload trying to overwrite a builtin) return `409 Conflict`; `dashboard_widget.module_id` is validated against installed modules; SDK declarations carry a `sdkVersion` semver range checked at load time. Install and uninstall events emit audit log entries
+- **Runtime bridge** -- `mountRuntimeBridge` now wires the SDK runtime to the live React Query servers cache and the host theme provider via `useSyncExternalStore`, surfaces sonner toasts, and exposes a confirm-dialog request channel. `/runtime/*` import-map shims are served with `Cache-Control: no-cache` to avoid stale shim drift across SPA upgrades. `defineWidget` rejects duplicate action ids
+
+### Removed
+
+- **Legacy SPA theme + custom CSS theme system** -- The `spa_theme` package upload feature, `custom_theme` CSS variable system, and seven preset themes are deleted in their entirety (backend service/router/entity, migrations dropping `spa_themes` and `custom_theme`, the appearance settings UI, preset CSS files, `theme_ref` from public status pages, and the `SERVERBEE_FEATURE__CUSTOM_THEMES` config field). The theme provider is collapsed to light/dark/system. The old `custom-themes.mdx` and `custom-frontend.mdx` doc pages are replaced by `custom-widgets.mdx`
+
 ## [1.0.0-alpha.4] - 2026-05-27
 
 ### Added
diff --git a/Cargo.lock b/Cargo.lock
index 3f422ea7..159789c0 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3972,7 +3972,7 @@ dependencies = [
 
 [[package]]
 name = "serverbee-agent"
-version = "1.0.0-alpha.4"
+version = "1.0.0-alpha.5"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -4015,7 +4015,7 @@ dependencies = [
 
 [[package]]
 name = "serverbee-common"
-version = "1.0.0-alpha.4"
+version = "1.0.0-alpha.5"
 dependencies = [
  "chrono",
  "serde",
@@ -4026,7 +4026,7 @@ dependencies = [
 
 [[package]]
 name = "serverbee-server"
-version = "1.0.0-alpha.4"
+version = "1.0.0-alpha.5"
 dependencies = [
  "a2",
  "anyhow",
diff --git a/Cargo.toml b/Cargo.toml
index ae2104ca..3fabe49e 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -7,7 +7,7 @@ members = [
 ]
 
 [workspace.package]
-version = "1.0.0-alpha.4"
+version = "1.0.0-alpha.5"
 edition = "2024"
 license = "AGPL-3.0-or-later"
 repository = "https://github.com/ZingerLittleBee/ServerBee"
diff --git a/apps/web/package.json b/apps/web/package.json
index 78427334..8de6bc96 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@serverbee/web",
   "private": true,
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.5",
   "type": "module",
   "scripts": {
     "dev": "vite",

From 16633c5e07e1bc330686391ff859312bec19f987 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 23:49:59 +0800
Subject: [PATCH 64/64] chore: silence ultracite errors in widget-sdk package

CI runs ultracite from the repo root and lints packages/widget-sdk/,
which the local apps/web invocation skips. Add biome overrides for the
SDK's barrel files, runtime introspection sites, and tests so the test
suite can keep using inline regex / no-op stubs / shared bitmask
helpers. Inline-suppress the two legitimate src cases (window.confirm
fallback in ActionButton, capability bitmask check in useCapability).

Picks up the unsafe biome auto-fixes: useless React fragments around a
ReactNode render, template literal for ZError prefix, and the JSDoc
closing-asterisk on WidgetRuntime.notify.
---
 biome.json                                    | 38 ++++++++++++++++++-
 .../widget-sdk/src/actions/action-button.tsx  |  1 +
 packages/widget-sdk/src/hooks/live.ts         |  1 +
 packages/widget-sdk/src/runtime-context.ts    |  2 +-
 packages/widget-sdk/src/z/validate.ts         |  2 +-
 packages/widget-sdk/tests/actions.test.tsx    | 10 ++---
 6 files changed, 46 insertions(+), 8 deletions(-)

diff --git a/biome.json b/biome.json
index 8ea9e76a..cd01747f 100644
--- a/biome.json
+++ b/biome.json
@@ -117,12 +117,48 @@
     {
       "includes": [
         "apps/docs/src/lib/cn.ts",
-        "packages/db/src/schema/index.ts"
+        "packages/db/src/schema/index.ts",
+        "packages/widget-sdk/src/index.ts",
+        "packages/widget-sdk/src/hooks/index.ts",
+        "packages/widget-sdk/src/z/index.ts"
       ],
       "linter": {
         "rules": {
           "performance": {
             "noBarrelFile": "off"
+          },
+          "style": {
+            "noExportedImports": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": [
+        "packages/widget-sdk/src/z/primitives.ts",
+        "packages/widget-sdk/src/manifest.ts"
+      ],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noExplicitAny": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["packages/widget-sdk/tests/**"],
+      "linter": {
+        "rules": {
+          "performance": {
+            "useTopLevelRegex": "off"
+          },
+          "suspicious": {
+            "noEmptyBlockStatements": "off",
+            "noBitwiseOperators": "off"
+          },
+          "complexity": {
+            "noUselessFragments": "off"
           }
         }
       }
diff --git a/packages/widget-sdk/src/actions/action-button.tsx b/packages/widget-sdk/src/actions/action-button.tsx
index 08165d3c..9133fe3b 100644
--- a/packages/widget-sdk/src/actions/action-button.tsx
+++ b/packages/widget-sdk/src/actions/action-button.tsx
@@ -21,6 +21,7 @@ async function askConfirm(action: ActionDefinition): Promise<boolean> {
   }
   if (typeof window !== 'undefined' && typeof window.confirm === 'function') {
     const body = action.confirm.body ? `\n\n${action.confirm.body}` : ''
+    // biome-ignore lint/suspicious/noAlert: deliberate fallback when host runtime has not wired requestConfirm
     return window.confirm(`${action.confirm.title}${body}`)
   }
   return true
diff --git a/packages/widget-sdk/src/hooks/live.ts b/packages/widget-sdk/src/hooks/live.ts
index ed90060e..03d2c139 100644
--- a/packages/widget-sdk/src/hooks/live.ts
+++ b/packages/widget-sdk/src/hooks/live.ts
@@ -74,6 +74,7 @@ export function useCapability(id: string | null, cap: string): boolean {
       return false
     }
     const server = rt.serversStore().find((s) => s.id === id)
+    // biome-ignore lint/suspicious/noBitwiseOperators: capabilities is a bitmask, AND is the intended operation
     return server ? (server.capabilities & bit) !== 0 : false
   }, [rt, id, cap])
   return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
diff --git a/packages/widget-sdk/src/runtime-context.ts b/packages/widget-sdk/src/runtime-context.ts
index c670ff15..71155032 100644
--- a/packages/widget-sdk/src/runtime-context.ts
+++ b/packages/widget-sdk/src/runtime-context.ts
@@ -27,7 +27,7 @@ export interface WidgetRuntime {
   apiBaseUrl: string
   /** Optional: hint list of well-known metric paths for the metricPath picker. */
   getMetricPaths?: () => string[]
-  /** Optional: host-provided toast hook. SDK falls back to console.* */
+  /** Optional: host-provided toast hook. SDK falls back to console.*/
   notify?: (opts: NotifyOptions) => void
   onConfigUpdate: (instanceId: string, patch: Record<string, unknown>) => void
   queryClient: QueryClient
diff --git a/packages/widget-sdk/src/z/validate.ts b/packages/widget-sdk/src/z/validate.ts
index cf7c8db7..137aaa7a 100644
--- a/packages/widget-sdk/src/z/validate.ts
+++ b/packages/widget-sdk/src/z/validate.ts
@@ -2,7 +2,7 @@ export class ZError extends Error {
   path: string[]
 
   constructor(path: string[], message: string) {
-    super(`${path.length ? path.join('.') + ': ' : ''}${message}`)
+    super(`${path.length ? `${path.join('.')}: ` : ''}${message}`)
     this.path = path
   }
 }
diff --git a/packages/widget-sdk/tests/actions.test.tsx b/packages/widget-sdk/tests/actions.test.tsx
index c817df05..cf182d19 100644
--- a/packages/widget-sdk/tests/actions.test.tsx
+++ b/packages/widget-sdk/tests/actions.test.tsx
@@ -33,14 +33,14 @@ describe('actions helper', () => {
     const run = vi.fn().mockResolvedValue(undefined)
     const actions: ActionDefinition[] = [{ id: 'a1', label: 'Do it', run }]
     const helper = createActionsHelper(actions)
-    render(<>{helper.render('a1')}</>)
+    render(helper.render('a1'))
     fireEvent.click(screen.getByRole('button', { name: 'Do it' }))
     await waitFor(() => expect(run).toHaveBeenCalledOnce())
   })
 
   it('returns null for unknown id', () => {
     const helper = createActionsHelper([])
-    const { container } = render(<>{helper.render('missing')}</>)
+    const { container } = render(helper.render('missing'))
     expect(container.textContent).toBe('')
   })
 
@@ -57,7 +57,7 @@ describe('actions helper', () => {
       }
     ]
     const helper = createActionsHelper(actions)
-    render(<>{helper.render('a1')}</>)
+    render(helper.render('a1'))
     fireEvent.click(screen.getByRole('button', { name: 'Restart' }))
     await waitFor(() =>
       expect(requestConfirm).toHaveBeenCalledWith({ title: 'Restart server?', body: 'Are you sure?' })
@@ -72,7 +72,7 @@ describe('actions helper', () => {
     installRuntime({ requestConfirm, notify })
     const actions: ActionDefinition[] = [{ id: 'a1', label: 'Restart', run, confirm: { title: 'Restart?' } }]
     const helper = createActionsHelper(actions)
-    render(<>{helper.render('a1')}</>)
+    render(helper.render('a1'))
     fireEvent.click(screen.getByRole('button', { name: 'Restart' }))
     await waitFor(() => expect(run).toHaveBeenCalledOnce())
     await waitFor(() => expect(notify).toHaveBeenCalledWith(expect.objectContaining({ type: 'success' })))
@@ -84,7 +84,7 @@ describe('actions helper', () => {
     installRuntime({ notify })
     const actions: ActionDefinition[] = [{ id: 'a1', label: 'Risky', run }]
     const helper = createActionsHelper(actions)
-    render(<>{helper.render('a1')}</>)
+    render(helper.render('a1'))
     fireEvent.click(screen.getByRole('button', { name: 'Risky' }))
     await waitFor(() =>
       expect(notify).toHaveBeenCalledWith(