dsh-tiddlywiki 0.1.0

package/src/client/styles.ts

@@ -0,0 +1,235 @@
+/**
+ * Client stylesheet injection (design doc D5 — pure DOM, no React).
+ * All rules are `dsh-tw-*` scoped; the tag is stable per plugin so the HMR
+ * driver can identify it on rebuild.
+ *
+ * Theme: uses the live `--dsw-alias-*` design tokens (same family as the
+ * shutdown launcher) with fallbacks, so it follows light/dark automatically.
+ *
+ * @module dsh-tiddlywiki/client/styles
+ */
+
+export const STYLE_ID = 'dsh-tiddlywiki-styles'
+
+const CSS_TEXT = `
+/* ── sidebar entry ───────────────────────────────────────────── */
+.dsh-tw-entry {
+  display: flex; align-items: center; gap: 8px; position: relative;
+  width: calc(100% - 8px); margin: 2px 4px; padding: 6px 10px;
+  border: none; border-radius: 8px; background: transparent;
+  color: var(--dsw-alias-label-secondary, inherit); font: inherit; font-size: 13px;
+  cursor: pointer; text-align: left;
+}
+.dsh-tw-entry:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.12)); color: var(--dsw-alias-label-primary, inherit); }
+.dsh-tw-entry[data-active="true"] { background: var(--dsw-alias-interactive-bg-active, rgba(128,128,128,.18)); color: var(--dsw-alias-label-primary, inherit); font-weight: 500; }
+.dsh-tw-entry svg { flex: none; }
+.dsh-tw-entry .dsh-tw-entry-label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
+/* ── center-column panel (fixed overlay, JS-pinned to the column rect) ── */
+.dsh-tw-view {
+  display: none; flex-direction: column; min-height: 0; box-sizing: border-box;
+  background: var(--dsw-alias-bg-layer-1, var(--dsw-bg, #fff));
+}
+html[data-dsh-tw-active] .dsh-tw-view { display: flex; }
+/* Hide the conversation content the panel overlays (all three column gens). */
+html[data-dsh-tw-active] [data-pane="conversation"] > :not([data-dsh-tw-view]),
+html[data-dsh-tw-active] [class*="centerCol"] > :not([data-dsh-tw-view]),
+html[data-dsh-tw-active] .dshDesktopConversationSurface > :not([data-dsh-tw-view]) { display: none !important; }
+
+.dsh-tw-panel-bar {
+  display: flex; align-items: center; gap: 8px; padding: 6px 10px;
+  border-bottom: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,.18));
+  background: var(--dsw-alias-bg-layer-1, transparent);
+  font-size: 12px; color: var(--dsw-alias-label-secondary, inherit);
+  flex: none;
+}
+.dsh-tw-panel-bar button {
+  border: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,.25));
+  background: transparent; color: inherit; font: inherit; font-size: 12px;
+  padding: 2px 8px; border-radius: 6px; cursor: pointer;
+}
+.dsh-tw-panel-bar button:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.12)); }
+.dsh-tw-panel-title { font-weight: 600; margin-right: auto; }
+.dsh-tw-status-chip { font-variant-numeric: tabular-nums; }
+.dsh-tw-status-chip[data-state="running"] { color: var(--dsw-alias-state-success-primary, #3eaa5f); }
+.dsh-tw-status-chip[data-state="starting"] { color: var(--dsw-alias-state-warning-primary, #d9822b); }
+.dsh-tw-status-chip[data-state="failed"], .dsh-tw-status-chip[data-state="stopped"] { color: var(--dsw-alias-state-error-primary, #d13b3b); }
+
+.dsh-tw-panel-frame { flex: 1; min-height: 0; border: 0; width: 100%; display: block; background: #fff; }
+/* [hidden] must beat the author display rules above (UA hidden is overridden). */
+.dsh-tw-panel-frame[hidden],
+.dsh-tw-panel-error[hidden] { display: none !important; }
+
+.dsh-tw-panel-error {
+  flex: 1; display: flex; flex-direction: column; align-items: center; justify-content: center;
+  gap: 10px; color: var(--dsw-alias-label-secondary, #666); font-size: 13px; text-align: center; padding: 20px;
+}
+.dsh-tw-panel-error button {
+  border: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,.25)); background: transparent;
+  color: inherit; font: inherit; padding: 6px 14px; border-radius: 8px; cursor: pointer;
+}
+.dsh-tw-panel-error button:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.12)); }
+.dsh-tw-panel-error code { font-size: 11px; opacity: .8; max-width: 80%; overflow-wrap: anywhere; }
+
+/* ── floating quick-note widget ────────────────────────────────
+   Positioned ABOVE the shutdown launcher FAB (fixed right:24 bottom:24,
+   z-index 900, 46px) and BELOW its confirm overlay (z-index 1000). */
+.dsh-tw-note {
+  position: fixed; right: 24px; bottom: 88px; z-index: 950;
+  display: flex; flex-direction: column; align-items: flex-end; gap: 10px;
+  font-family: inherit;
+}
+.dsh-tw-note-card {
+  width: 340px; max-width: calc(100vw - 40px);
+  background: var(--dsw-alias-bg-layer-2, #fff); color: var(--dsw-alias-label-primary, #222);
+  border: 1px solid var(--dsw-alias-border-l2, rgba(0,0,0,.15));
+  border-radius: 14px; box-shadow: var(--dsw-shadow-lv3, 0 8px 30px rgba(0,0,0,.22));
+  padding: 12px; display: flex; flex-direction: column; gap: 10px;
+  font-size: 13px;
+}
+.dsh-tw-note-card[hidden] { display: none; }
+.dsh-tw-note-head {
+  display: flex; align-items: center; gap: 8px;
+  font-size: 12px; font-weight: 600; color: var(--dsw-alias-label-primary, #222);
+}
+.dsh-tw-note-head .dsh-tw-note-label { margin-right: auto; display: flex; align-items: center; gap: 6px; }
+.dsh-tw-note-close {
+  border: none; background: transparent; color: var(--dsw-alias-label-secondary, #888);
+  font: inherit; font-size: 15px; line-height: 1; padding: 2px 6px; border-radius: 6px; cursor: pointer;
+}
+.dsh-tw-note-close:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.12)); color: var(--dsw-alias-label-primary, #222); }
+.dsh-tw-note-fields { display: flex; gap: 8px; }
+.dsh-tw-note-fields input {
+  flex: 1; min-width: 0; border: 1px solid var(--dsw-alias-border-l2, rgba(0,0,0,.18));
+  border-radius: 8px; padding: 6px 9px; font: inherit; font-size: 12px;
+  background: var(--dsw-alias-bg-layer-1, #fff); color: var(--dsw-alias-label-primary, inherit);
+  transition: border-color 120ms ease, box-shadow 120ms ease;
+}
+.dsh-tw-note-fields input:focus, .dsh-tw-note-text:focus {
+  outline: none; border-color: var(--dsw-alias-brand-primary, #3e63dd);
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--dsw-alias-brand-primary, #3e63dd) 25%, transparent);
+}
+.dsh-tw-note-text {
+  border: 1px solid var(--dsw-alias-border-l2, rgba(0,0,0,.18)); border-radius: 8px;
+  padding: 8px 9px; font: inherit; font-size: 13px; min-height: 120px; resize: vertical;
+  background: var(--dsw-alias-bg-layer-1, #fff); color: var(--dsw-alias-label-primary, inherit);
+  transition: border-color 120ms ease, box-shadow 120ms ease;
+}
+.dsh-tw-note-foot { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
+.dsh-tw-note-hint { font-size: 11px; color: var(--dsw-alias-label-dimmed, #999); }
+.dsh-tw-note-save {
+  border: 1px solid transparent; background: var(--dsw-alias-brand-primary, #3e63dd); color: #fff;
+  font: inherit; font-size: 12px; padding: 6px 16px; border-radius: 8px; cursor: pointer;
+  transition: filter 120ms ease;
+}
+.dsh-tw-note-save:hover:not(:disabled) { filter: brightness(1.08); }
+.dsh-tw-note-save:disabled { opacity: .55; cursor: default; }
+.dsh-tw-note-edit {
+  border: 1px solid var(--dsw-alias-border-l2, rgba(0,0,0,.18));
+  background: var(--dsw-alias-bg-layer-2, #fff); color: var(--dsw-alias-label-primary, #222);
+  font: inherit; font-size: 12px; padding: 6px 10px; border-radius: 8px; cursor: pointer;
+  transition: filter 120ms ease;
+}
+.dsh-tw-note-edit:hover:not(:disabled) { filter: brightness(.96); }
+.dsh-tw-note-edit:disabled { opacity: .55; cursor: default; }
+/* ── Native-editor popup iframe (quick-note "在 TW 中编辑") ──────────────── */
+.dsh-tw-editor-popup {
+  position: fixed; left: 0; right: 0; top: 0; bottom: 0; margin: auto;
+  width: min(880px, 92vw); height: min(640px, 86vh);
+  display: flex; flex-direction: column; overflow: hidden;
+  background: var(--dsw-alias-bg-layer-2, #fff); color: var(--dsw-alias-label-primary, #222);
+  border: 1px solid var(--dsw-alias-border-l2, rgba(0,0,0,.2));
+  border-radius: 12px; box-shadow: 0 14px 44px rgba(0,0,0,.3);
+  z-index: 980; font-family: inherit; font-size: 13px;
+}
+.dsh-tw-editor-bar {
+  display: flex; align-items: center; gap: 8px; flex: 0 0 auto;
+  padding: 7px 8px 7px 14px; cursor: move; user-select: none;
+  background: var(--dsw-alias-bg-layer-1, #f4f5f7);
+  border-bottom: 1px solid var(--dsw-alias-border-l1, rgba(0,0,0,.1));
+}
+.dsh-tw-editor-title { flex: 1; min-width: 0; font-weight: 600; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.dsh-tw-editor-close {
+  border: none; background: transparent; cursor: pointer; font-size: 14px; line-height: 1;
+  color: var(--dsw-alias-label-dimmed, #888); padding: 5px 8px; border-radius: 6px;
+}
+.dsh-tw-editor-close:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.12)); color: var(--dsw-alias-label-primary, #222); }
+.dsh-tw-editor-frame { flex: 1; min-height: 0; width: 100%; border: 0; background: #fff; }
+.dsh-tw-editor-resize { position: absolute; right: 0; bottom: 0; width: 16px; height: 16px; cursor: nwse-resize; }
+.dsh-tw-note-toggle {
+  border: 1px solid var(--dsw-alias-border-l2, rgba(0,0,0,.18));
+  background: var(--dsw-alias-bg-layer-2, #fff); color: var(--dsw-alias-label-primary, #222);
+  font: inherit; font-size: 13px; padding: 9px 16px; border-radius: 999px;
+  box-shadow: var(--dsw-shadow-lv3, 0 4px 16px rgba(0,0,0,.16)); cursor: pointer;
+  display: inline-flex; align-items: center; gap: 6px;
+  transition: background-color 120ms ease;
+}
+.dsh-tw-note-toggle:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.1)); }
+
+/* ── toast ──────────────────────────────────────────────────── */
+.dsh-tw-toast {
+  position: fixed; left: 50%; bottom: 96px; transform: translateX(-50%);
+  background: var(--dsw-alias-bg-inverse, rgba(30,30,30,.92)); color: var(--dsw-alias-label-inverse, #fff);
+  font-size: 13px; padding: 8px 16px; border-radius: 999px; z-index: 10001;
+  opacity: 0; transition: opacity .2s ease; pointer-events: none;
+  max-width: 80vw; overflow-wrap: anywhere;
+}
+.dsh-tw-toast.dsh-tw-toast-show { opacity: 1; }
+
+/* ── settings page (config panel §13) ────────────────────────── */
+.dsh-tw-settings { display: flex; flex-direction: column; gap: 10px; padding: 12px 16px; min-width: 0; }
+.dsh-tw-settings-row { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
+.dsh-tw-settings-chip {
+  font-size: 12px; padding: 2px 10px; border-radius: 999px;
+  border: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,.25));
+}
+.dsh-tw-settings-chip[data-state="running"] { color: var(--dsw-alias-state-success-primary, #3eaa5f); }
+.dsh-tw-settings-chip[data-state="starting"] { color: var(--dsw-alias-state-warning-primary, #d9822b); }
+.dsh-tw-settings-chip[data-state="failed"], .dsh-tw-settings-chip[data-state="stopped"] { color: var(--dsw-alias-state-error-primary, #d13b3b); }
+.dsh-tw-settings-section { display: flex; flex-direction: column; gap: 8px; padding: 10px 12px; border-radius: 10px; border: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,.18)); }
+.dsh-tw-settings-h { margin: 0; font-size: 13px; font-weight: 600; color: var(--dsw-alias-label-primary, #222); }
+.dsh-tw-settings-field { display: flex; align-items: center; gap: 8px; font-size: 12px; color: var(--dsw-alias-label-secondary, inherit); }
+.dsh-tw-settings-field-check { cursor: pointer; }
+.dsh-tw-settings-label { flex: 0 0 170px; }
+.dsh-tw-settings-input {
+  flex: 1; min-width: 0; font: inherit; font-size: 12px; padding: 4px 8px; border-radius: 6px;
+  border: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,.28));
+  background: var(--dsw-alias-bg-input, transparent); color: var(--dsw-alias-label-primary, #222);
+}
+.dsh-tw-settings-input:focus {
+  outline: none; border-color: var(--dsw-alias-brand-primary, #3e63dd);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--dsw-alias-brand-primary, #3e63dd) 22%, transparent);
+}
+.dsh-tw-settings-list { display: flex; flex-direction: column; gap: 2px; max-height: 240px; overflow: auto; }
+.dsh-tw-settings-plugin { display: flex; align-items: center; gap: 8px; padding: 3px 4px; border-radius: 6px; font-size: 12px; }
+.dsh-tw-settings-plugin:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.08)); }
+.dsh-tw-settings-name { font-weight: 500; flex: 0 0 130px; color: var(--dsw-alias-label-primary, #222); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.dsh-tw-settings-head { padding: 2px 4px 4px; font-size: 11px; }
+.dsh-tw-settings-col { flex: 0 0 14px; text-align: center; color: var(--dsw-alias-label-dimmed, #999); }
+.dsh-tw-settings-row.dsh-tw-settings-plugin input { flex: 0 0 auto; margin: 0; }
+.dsh-tw-settings-muted { color: var(--dsw-alias-label-dimmed, #999); font-size: 12px; }
+.dsh-tw-settings-btn {
+  align-self: flex-start; border: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,.28));
+  background: transparent; color: var(--dsw-alias-label-primary, #222);
+  font: inherit; font-size: 12px; padding: 4px 12px; border-radius: 7px; cursor: pointer;
+}
+.dsh-tw-settings-btn:hover:not(:disabled) { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.1)); }
+.dsh-tw-settings-btn:disabled { opacity: .55; cursor: default; }
+.dsh-tw-settings-btn.dsh-tw-settings-primary {
+  background: var(--dsw-alias-brand-primary, #3e63dd); border-color: transparent; color: #fff;
+}
+.dsh-tw-settings-error { color: var(--dsw-alias-state-error-primary, #d13b3b); font-size: 12px; }
+.dsh-tw-settings-search { flex: 0 0 auto; max-width: 220px; }
+.dsh-tw-settings-check { accent-color: var(--dsw-alias-brand-primary, #3e63dd); }
+`
+
+export function injectStyles(): void {
+  if (typeof document === 'undefined') return
+  let el = document.getElementById(STYLE_ID)
+  if (el !== null) return
+  el = document.createElement('style')
+  el.id = STYLE_ID
+  el.dataset.plugin = 'dsh-tiddlywiki'
+  el.textContent = CSS_TEXT
+  document.head.append(el)
+}

package/src/client/toast.ts

@@ -0,0 +1,22 @@
+/**
+ * One-shot transient toast, shared by the quick-note widget and the settings
+ * page. Reuses a single body-level element (`.dsh-tw-toast`) with a show
+ * class; the element is created lazily and styled by styles.ts.
+ *
+ * @module dsh-tiddlywiki/client/toast
+ */
+
+export function toast(message: string): void {
+  let el = document.querySelector<HTMLElement>('.dsh-tw-toast')
+  if (el === null) {
+    el = document.createElement('div')
+    el.className = 'dsh-tw-toast'
+    document.body.append(el)
+  }
+  el.textContent = message
+  el.classList.add('dsh-tw-toast-show')
+  clearTimeout((el as HTMLElement & { __twToastTimer?: number }).__twToastTimer)
+  ;(el as HTMLElement & { __twToastTimer?: number }).__twToastTimer = window.setTimeout(() => {
+    el?.classList.remove('dsh-tw-toast-show')
+  }, 2_500)
+}

package/src/host/admin.ts

@@ -0,0 +1,408 @@
+/**
+ * Admin surface for the plugin settings page (design doc §13, config panel).
+ *
+ * - dynamic plugin/theme management: enumerate the bundled catalog from the
+ *   installed tiddlywiki package, read/write the wiki's `tiddlywiki.info`
+ *   plugins/themes arrays, then restart the TW child so the change applies;
+ * - extensible config: the settings page reads/writes a config tiddler
+ *   ($:/plugins/dsh-tiddlywiki/config, a JSON string) that overlays the
+ *   cordis `config:` block — future config fields just extend the shape.
+ *
+ * Routes (all under ROUTE_PREFIX/admin, JSON):
+ *   GET  /admin/state   current info + catalog + effective config + status
+ *   POST /admin/info    { plugins?, themes? } → write info → restart TW
+ *   POST /admin/config  { ...patch }          → write config tiddler
+ *   POST /admin/restart restart the TW child
+ *
+ * @module dsh-tiddlywiki/host/admin
+ */
+import { createRequire } from 'node:module'
+import { readFile, writeFile, readdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { TiddlyWebClient } from './tw-api.ts'
+import type { WikiServer } from './wiki.ts'
+import { ROUTE_PREFIX, type WebServerFace } from './routes.ts'
+import { CONFIG_TIDDLER, type ConfigStore, type PluginConfigShape } from './config.ts'
+
+/** One bundled plugin/theme from the catalog. */
+export interface CatalogEntry {
+  /** Short name as used in tiddlywiki.info, e.g. "tiddlywiki/katex". */
+  name: string
+  /** Full tiddler title, e.g. "$:/plugins/tiddlywiki/katex". */
+  title: string
+  label: string
+  description: string
+  /** Dependent theme NAMES (converted from plugin.info `dependents`), e.g. heavier → ["tiddlywiki/snowwhite"]. */
+  dependents?: string[]
+}
+
+export interface Catalog {
+  plugins: CatalogEntry[]
+  themes: CatalogEntry[]
+  /** Bundled language plugins (tiddlywiki package `languages/` dir). */
+  languages: CatalogEntry[]
+}
+
+/** Shape of tiddlywiki.info (plugins/themes/languages + build/description). */
+export interface WikiInfo {
+  description?: string
+  plugins: string[]
+  themes: string[]
+  languages?: string[]
+  build?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+/** Resolve the installed tiddlywiki package root (for the catalog). */
+export function resolveTwRoot(): string {
+  const require = createRequire(import.meta.url)
+  return dirname(require.resolve('tiddlywiki/package.json'))
+}
+
+/** Read the wiki's tiddlywiki.info. */
+export async function readWikiInfo(wikiPath: string): Promise<WikiInfo> {
+  let raw: string
+  try {
+    raw = await readFile(join(wikiPath, 'tiddlywiki.info'), 'utf8')
+  } catch {
+    return { plugins: [], themes: [], languages: [] }
+  }
+  const parsed = JSON.parse(raw) as Partial<WikiInfo>
+  return {
+    description: parsed.description,
+    plugins: parsed.plugins ?? [],
+    themes: parsed.themes ?? [],
+    languages: parsed.languages ?? [],
+    ...parsed,
+  }
+}
+
+/** Write the wiki's tiddlywiki.info (pretty-printed, ordering preserved). */
+export async function writeWikiInfo(wikiPath: string, info: WikiInfo): Promise<void> {
+  await writeFile(join(wikiPath, 'tiddlywiki.info'), `${JSON.stringify(info, null, 4)}\n`, 'utf8')
+}
+
+/** Enumerate bundled official plugins + themes + languages of tiddlywiki. */
+export async function bundledCatalog(twRoot: string): Promise<Catalog> {
+  // TW themes are SKINS layered on the vanilla base (which carries the full
+  // 70KB base stylesheet). A theme whose stylesheet body is empty is a broken
+  // stub (e.g. tight-heavier in some releases) — skip it so the settings list
+  // never offers a no-op theme. vanilla itself is always kept.
+  const themeHasCss = async (dir: string): Promise<boolean> => {
+    for (const name of ['base.tid', 'styles.tid']) {
+      try {
+        const raw = await readFile(join(twRoot, 'themes', 'tiddlywiki', dir, name), 'utf8')
+        const body = raw
+          .replace(/^[\s\S]*?\r?\n\r?\n/, '')
+          .split('\n')
+          .filter((line) => !/^\\rules\b/.test(line.trim()))
+          .join('\n')
+          .trim()
+        if (body.length > 0) return true
+      } catch {
+        /* file absent */
+      }
+    }
+    return false
+  }
+  const scan = async (sub: 'plugins' | 'themes'): Promise<CatalogEntry[]> => {
+    const root = join(twRoot, sub, 'tiddlywiki')
+    let dirs: string[]
+    try {
+      dirs = await readdir(root)
+    } catch {
+      return []
+    }
+    const out: CatalogEntry[] = []
+    for (const dir of dirs) {
+      let info: { name?: string; description?: string; dependents?: string[] } = {}
+      try {
+        info = JSON.parse(await readFile(join(root, dir, 'plugin.info'), 'utf8')) as typeof info
+      } catch {
+        info = {}
+      }
+      if (sub === 'themes' && dir !== 'vanilla' && !(await themeHasCss(dir))) continue
+      out.push({
+        name: `tiddlywiki/${dir}`,
+        title: sub === 'plugins' ? `$:/plugins/tiddlywiki/${dir}` : `$:/themes/tiddlywiki/${dir}`,
+        label: info.name ?? dir,
+        description: info.description ?? '',
+        // plugin.info `dependents` are full plugin titles → convert to names.
+        dependents: Array.isArray(info.dependents)
+          ? info.dependents.map((dep) => dep.replace(/^\$:\/themes\/tiddlywiki\//, 'tiddlywiki/'))
+          : undefined,
+      })
+    }
+    out.sort((a, b) => a.name.localeCompare(b.name))
+    return out
+  }
+  // Language plugins live in the package ROOT `languages/` dir (not plugins/),
+  // and are enabled via the tiddlywiki.info `languages` array (boot resolves
+  // them through $tw.config.languagesPath). Fully offline — official builds.
+  const scanLanguages = async (): Promise<CatalogEntry[]> => {
+    const root = join(twRoot, 'languages')
+    let dirs: string[]
+    try {
+      dirs = await readdir(root)
+    } catch {
+      return []
+    }
+    const out: CatalogEntry[] = []
+    for (const dir of dirs) {
+      let info: { name?: string; description?: string } = {}
+      try {
+        info = JSON.parse(await readFile(join(root, dir, 'plugin.info'), 'utf8')) as typeof info
+      } catch {
+        info = {}
+      }
+      out.push({
+        name: dir,
+        title: `$:/languages/${dir}`,
+        label: info.name ?? dir,
+        description: info.description ?? '',
+      })
+    }
+    out.sort((a, b) => a.name.localeCompare(b.name))
+    return out
+  }
+  const [plugins, themes, languages] = await Promise.all([scan('plugins'), scan('themes'), scanLanguages()])
+  return { plugins, themes, languages }
+}
+
+/**
+ * Normalize a theme selection into the tiddlywiki.info `themes` array.
+ *
+ * TW themes are SKINS with a dependency chain (plugin.info `dependents`):
+ *   vanilla ← snowwhite ← heavier / centralised / readonly / starlight
+ *   vanilla ← tight / seamless
+ * The ACTIVE theme is `$:/theme`, and switching to it registers the theme PLUS
+ * its transitive dependents (boot.js accumulatePlugin) — if a dependent isn't
+ * loaded, the vanilla base stylesheet is lost and the UI breaks. So we always
+ * emit the transitive closure, dependency-first (base first, active overlay
+ * last), and force vanilla in as the base. Empty selection → vanilla.
+ */
+export function normalizeThemes(selected: string[], deps: Record<string, string[]> = {}): string[] {
+  const sel = selected.filter((name) => typeof name === 'string' && name.length > 0)
+  if (sel.length === 0) sel.push('tiddlywiki/vanilla')
+  const out: string[] = []
+  const seen = new Set<string>()
+  const visit = (name: string): void => {
+    if (seen.has(name)) return
+    seen.add(name)
+    for (const dep of deps[name] ?? []) {
+      if (dep !== name) visit(dep)
+    }
+    out.push(name)
+  }
+  for (const name of sel) visit(name)
+  if (!out.includes('tiddlywiki/vanilla')) out.unshift('tiddlywiki/vanilla')
+  return out
+}
+
+/**
+ * Ensure a language code (e.g. "zh-Hans") is in tiddlywiki.info `languages`.
+ * Returns whether tiddlywiki.info changed (caller decides whether to restart).
+ */
+export async function ensureLanguage(wikiPath: string, twRoot: string, lang: string): Promise<boolean> {
+  if (typeof lang !== 'string' || lang.trim().length === 0) return false
+  const code = lang.trim()
+  const catalog = await bundledCatalog(twRoot)
+  if (!catalog.languages.some((l) => l.name === code)) {
+    throw new Error(`unknown language plugin: ${code}`)
+  }
+  const info = await readWikiInfo(wikiPath)
+  const current = info.languages ?? []
+  if (current.includes(code)) return false
+  info.languages = [...current, code]
+  await writeWikiInfo(wikiPath, info)
+  return true
+}
+
+function json(res: ServerResponse, payload: unknown, status = 200): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(JSON.stringify(payload))
+}
+
+async function readBody(req: IncomingMessage, limit = 1024 * 1024): Promise<string> {
+  return new Promise((resolveP, rejectP) => {
+    let size = 0
+    const chunks: Buffer[] = []
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length
+      if (size > limit) {
+        rejectP(new Error('body too large'))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => resolveP(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', rejectP)
+  })
+}
+
+export interface AdminDeps {
+  server: WikiServer
+  getClient: () => TiddlyWebClient | undefined
+  getWikiPath: () => string
+  twRoot: () => string
+  config: ConfigStore
+}
+
+export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: AdminDeps): () => void {
+  const handleState = async (_req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    try {
+      const wikiPath = deps.getWikiPath()
+      const [info, catalog] = await Promise.all([readWikiInfo(wikiPath), bundledCatalog(deps.twRoot())])
+      let git: unknown = null
+      try {
+        const { GitFace } = await import('./git.ts')
+        git = await new GitFace().status(wikiPath)
+      } catch {
+        git = null
+      }
+      json(res, {
+        ok: true,
+        server: deps.server.status(),
+        info: { plugins: info.plugins, themes: info.themes, languages: info.languages ?? [] },
+        catalog,
+        config: deps.config.get(),
+        git,
+      })
+    } catch (err) {
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+    }
+  }
+
+  const handleInfo = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    try {
+      const body = JSON.parse(await readBody(req)) as { plugins?: unknown; themes?: unknown; themeActive?: unknown; languages?: unknown }
+      const wikiPath = deps.getWikiPath()
+      const info = await readWikiInfo(wikiPath)
+      const catalog = await bundledCatalog(deps.twRoot())
+      const known = new Set([...catalog.plugins, ...catalog.themes].map((c) => c.name))
+      const knownLangs = new Set(catalog.languages.map((c) => c.name))
+      const applyList = (field: 'plugins' | 'themes', raw: unknown): string[] => {
+        if (!Array.isArray(raw)) return info[field]
+        const next: string[] = []
+        for (const name of raw) {
+          if (typeof name !== 'string') continue
+          if (!known.has(name) && !info[field].includes(name)) {
+            throw new Error(`unknown plugin/theme: ${name}`)
+          }
+          if (!next.includes(name)) next.push(name)
+        }
+        return next
+      }
+      const applyLanguages = (raw: unknown): string[] => {
+        if (!Array.isArray(raw)) return info.languages ?? []
+        const next: string[] = []
+        for (const code of raw) {
+          if (typeof code !== 'string') continue
+          if (!knownLangs.has(code) && !(info.languages ?? []).includes(code)) {
+            throw new Error(`unknown language plugin: ${code}`)
+          }
+          if (!next.includes(code)) next.push(code)
+        }
+        return next
+      }
+      info.plugins = applyList('plugins', body.plugins)
+      // Activate the chosen theme: load its full dependency chain AND set
+      // `$:/theme` so the browser's themeManager actually applies it (the
+      // `themes` array alone only makes the plugin available).
+      let activatedTheme: string | undefined
+      if (Array.isArray(body.themes)) {
+        const themeDeps: Record<string, string[]> = {}
+        for (const theme of catalog.themes) {
+          if (theme.dependents && theme.dependents.length > 0) themeDeps[theme.name] = theme.dependents
+        }
+        let selected = applyList('themes', body.themes)
+        // Explicit active-theme pick (new two-layer UI): validate and auto-add
+        // it to the loaded set so its dependency closure is loaded. Without an
+        // explicit pick, activate the deepest loaded overlay (old single-radio).
+        const explicitActive = typeof body.themeActive === 'string' && body.themeActive.length > 0
+        if (explicitActive) {
+          const activeName = body.themeActive as string
+          if (known.has(activeName) || info.themes.includes(activeName)) {
+            if (!selected.includes(activeName)) selected.push(activeName)
+            activatedTheme = activeName
+          }
+        }
+        info.themes = normalizeThemes(selected, themeDeps)
+        if (activatedTheme === undefined && info.themes.length > 0) {
+          activatedTheme = info.themes[info.themes.length - 1]
+        }
+      } else {
+        info.themes = applyList('themes', body.themes)
+      }
+      if (Array.isArray(body.languages)) info.languages = applyLanguages(body.languages)
+      await writeWikiInfo(wikiPath, info)
+      await deps.server.restart()
+      // Activate the chosen theme tiddler (mirrors TW's own Control Panel).
+      if (activatedTheme !== undefined) {
+        const client = deps.getClient()
+        if (client !== undefined) {
+          await client
+            .put({ title: '$:/theme', text: `$:/themes/${activatedTheme}`, type: 'text/vnd.tiddlywiki', tags: [] })
+            .catch(() => undefined)
+        }
+      }
+      // After a languages change, pin the active language tiddler: first
+      // enabled language, or en-GB when none is enabled. Only when the request
+      // actually carried a languages array (plugins/themes restarts skip this).
+      if (Array.isArray(body.languages)) {
+        const client = deps.getClient()
+        if (client !== undefined) {
+          const langs = info.languages ?? []
+          const active = langs.length > 0 ? `$:/languages/${langs[0]}` : '$:/languages/en-GB'
+          await client.put({ title: '$:/language', text: active, type: 'text/plain', tags: [] }).catch(() => undefined)
+          // Keep the startup auto-apply hint (config uiLanguage) consistent with
+          // the active language, so a later dsh-web restart doesn't re-enable
+          // a language the user just disabled here.
+          const hint = langs.length > 0 ? langs[0] : ''
+          if ((deps.config.get().uiLanguage ?? '') !== hint) {
+            await deps.config.set(client, { uiLanguage: hint }).catch(() => undefined)
+          }
+        }
+      }
+      json(res, { ok: true, info: { plugins: info.plugins, themes: info.themes, languages: info.languages ?? [] } })
+    } catch (err) {
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 400)
+    }
+  }
+
+  const handleConfig = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    try {
+      const body = JSON.parse(await readBody(req)) as PluginConfigShape
+      const client = deps.getClient()
+      if (client === undefined) {
+        json(res, { ok: false, error: 'wiki service is not running' }, 503)
+        return
+      }
+      await deps.config.set(client, body)
+      json(res, { ok: true, config: deps.config.get() })
+    } catch (err) {
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 400)
+    }
+  }
+
+  const handleRestart = async (_req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    try {
+      await deps.server.restart()
+      json(res, { ok: true, status: deps.server.status().status })
+    } catch (err) {
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+    }
+  }
+
+  const disposers = [
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/state`, handler: (req, res) => { void handleState(req, res) } }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/info`, handler: (req, res) => { void handleInfo(req, res) } }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/config`, handler: (req, res) => { void handleConfig(req, res) } }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/restart`, handler: (req, res) => { void handleRestart(req, res) } }),
+  ]
+  return () => {
+    for (const dispose of disposers) dispose()
+  }
+}