@monster-orange/den 0.2.8 → 0.3.0

package/src/ui/server/theme-routes.ts

@@ -0,0 +1,292 @@
+/**
+ * Theme routes (GET only):
+ *
+ *   /theme.css            the active theme as CSS custom properties, both
+ *                         modes (see theme-runtime.ts renderThemeCss)
+ *   /theme/<id>/<file>    a file the theme's validated manifest names (its
+ *                         mark .svg, its .woff2 fonts), nothing else
+ *   /theme-favicon/<id>?mode=light|dark&v=<version>-<hash>
+ *                         theme <id>'s browser-tab icon in that mode (its
+ *                         `favicon`, else its mark's file, the dark variant
+ *                         in dark mode, else Den's own icon); `v` only makes
+ *                         the URL change with the file. /theme-favicon with
+ *                         no id is the active theme's, never cached.
+ *   /api/themes           the installed themes, the active one (with its
+ *                         favicon URLs per mode) and the org default (what
+ *                         appearance.theme null draws)
+ *
+ * Collaborators are injectable for tests.
+ */
+import { createHash } from "crypto";
+import * as fs from "fs";
+import * as http from "http";
+import * as path from "path";
+import { send404, sendJson } from "./http-helpers.js";
+import type { AppearancePrefs } from "./appearance-prefs.js";
+import type { ThemeManifest, ThemeMode } from "../../shared/theme/contract.js";
+import {
+  faviconFile,
+  findTheme,
+  listThemes,
+  renderThemeCss,
+  resolveActiveTheme,
+  themeAsset,
+  themeAssetUrl,
+  type ActiveTheme,
+  type ThemeRoots,
+} from "./theme-runtime.js";
+
+export interface ThemeRouteDeps {
+  roots: () => ThemeRoots;
+  /** The user's appearance prefs (user.yml). */
+  prefs: () => AppearancePrefs;
+  /** The org config's `theme:`. */
+  distributionTheme: () => string | null | undefined;
+  warn: (line: string) => void;
+  /** Den's own tab icon (public/favicon.ico), for a theme with a text mark. */
+  denFavicon?: string;
+}
+
+function denFaviconPath(deps: ThemeRouteDeps): string {
+  return (
+    deps.denFavicon ??
+    path.join(
+      deps.roots().engineRoot,
+      "src",
+      "ui",
+      "server",
+      "public",
+      "favicon.ico",
+    )
+  );
+}
+
+/**
+ * The file and type theme `id` shows in the browser tab in `mode`: a file
+ * its manifest names (themeAsset's rule), else Den's own icon.
+ */
+function faviconAsset(
+  deps: ThemeRouteDeps,
+  id: string,
+  theme: ThemeManifest,
+  mode: ThemeMode,
+): { file: string; type: string } | null {
+  const rel = faviconFile(theme, mode);
+  if (rel) return themeAsset(deps.roots(), id, rel);
+  const file = denFaviconPath(deps);
+  return fs.existsSync(file) ? { file, type: "image/x-icon" } : null;
+}
+
+/** /theme-favicon/<id>?mode=<mode>&v=<version>-<content hash>. */
+function faviconUrl(
+  deps: ThemeRouteDeps,
+  a: ActiveTheme,
+  mode: ThemeMode,
+): string | null {
+  const asset = faviconAsset(deps, a.id, a.theme, mode);
+  if (!asset) return null;
+  const hash = createHash("sha256")
+    .update(fs.readFileSync(asset.file))
+    .digest("hex")
+    .slice(0, 10);
+  return `/theme-favicon/${a.id}?mode=${mode}&v=${encodeURIComponent(`${a.theme.version}-${hash}`)}`;
+}
+
+/** The active theme for these deps (the user's, the distribution's, den). */
+export function activeTheme(deps: ThemeRouteDeps): ActiveTheme | null {
+  let prefs: AppearancePrefs = { theme: null, mode: "system" };
+  let dist: string | null | undefined = null;
+  try {
+    prefs = deps.prefs();
+  } catch (e) {
+    deps.warn(`[theme] user config unreadable: ${(e as Error).message}`);
+  }
+  try {
+    dist = deps.distributionTheme();
+  } catch (e) {
+    deps.warn(`[theme] org config unreadable: ${(e as Error).message}`);
+  }
+  return resolveActiveTheme(
+    deps.roots(),
+    { user: prefs.theme, distribution: typeof dist === "string" ? dist : null },
+    deps.warn,
+  );
+}
+
+/**
+ * The org default: the theme drawn when you have chosen none (the org
+ * config's `brand.theme` if it is installed and valid, else den).
+ */
+export function orgDefaultTheme(deps: ThemeRouteDeps): ActiveTheme | null {
+  let dist: string | null | undefined = null;
+  try {
+    dist = deps.distributionTheme();
+  } catch {
+    /* warned by activeTheme */
+  }
+  return resolveActiveTheme(
+    deps.roots(),
+    { user: null, distribution: typeof dist === "string" ? dist : null },
+    deps.warn,
+  );
+}
+
+function markOf(a: ActiveTheme) {
+  const m = a.theme.mark ?? {};
+  return {
+    svg: m.svg ? themeAssetUrl(a.id, m.svg) : null,
+    svg_dark: m.svg_dark ? themeAssetUrl(a.id, m.svg_dark) : null,
+    png: m.png ? themeAssetUrl(a.id, m.png) : null,
+    png_dark: m.png_dark ? themeAssetUrl(a.id, m.png_dark) : null,
+    webp: m.webp ? themeAssetUrl(a.id, m.webp) : null,
+    webp_dark: m.webp_dark ? themeAssetUrl(a.id, m.webp_dark) : null,
+    text: m.text ?? null,
+    shape: m.shape ?? null,
+  };
+}
+
+/** Handles the routes above; false when `pathname` is not one of them. */
+export function handleThemeRoutes(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  pathname: string,
+  deps: ThemeRouteDeps,
+): boolean {
+  const isAsset = pathname.startsWith("/theme/");
+  const isFavicon =
+    pathname === "/theme-favicon" || pathname.startsWith("/theme-favicon/");
+  if (
+    pathname !== "/theme.css" &&
+    pathname !== "/api/themes" &&
+    !isAsset &&
+    !isFavicon
+  )
+    return false;
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    res.writeHead(405, { Allow: "GET" });
+    res.end("read-only");
+    return true;
+  }
+
+  if (isFavicon) {
+    const id = pathname.slice("/theme-favicon/".length);
+    const q = new URL(req.url ?? "/", "http://localhost").searchParams;
+    const mode: ThemeMode = q.get("mode") === "dark" ? "dark" : "light";
+    let t: { id: string; theme: ThemeManifest } | null = null;
+    if (pathname === "/theme-favicon") t = activeTheme(deps);
+    else {
+      const found = /^[a-z][a-z0-9-]{1,39}$/.test(id)
+        ? findTheme(deps.roots(), id)
+        : null;
+      if (found?.ok && found.theme) t = { id: found.id, theme: found.theme };
+    }
+    const asset = t && faviconAsset(deps, t.id, t.theme, mode);
+    if (!asset) {
+      send404(res);
+      return true;
+    }
+    const headers: Record<string, string> = {
+      "Content-Type": asset.type,
+      "X-Content-Type-Options": "nosniff",
+      // The versioned URL names the file; the bare one follows your choice.
+      "Cache-Control": pathname === "/theme-favicon" ? "no-store" : "no-cache",
+    };
+    if (asset.type === "image/svg+xml")
+      headers["Content-Security-Policy"] =
+        "default-src 'none'; style-src 'unsafe-inline'";
+    res.writeHead(200, headers);
+    res.end(req.method === "HEAD" ? undefined : fs.readFileSync(asset.file));
+    return true;
+  }
+
+  if (pathname === "/theme.css") {
+    const a = activeTheme(deps);
+    res.writeHead(200, {
+      "Content-Type": "text/css; charset=utf-8",
+      // The theme follows the user's choice: never serve yesterday's.
+      "Cache-Control": "no-store",
+    });
+    res.end(a ? renderThemeCss(a.id, a.theme) : "/* no valid theme */\n");
+    return true;
+  }
+
+  if (pathname === "/api/themes") {
+    const a = activeTheme(deps);
+    let prefs: AppearancePrefs = { theme: null, mode: "system" };
+    try {
+      prefs = deps.prefs();
+    } catch {
+      /* warned by activeTheme */
+    }
+    const org = orgDefaultTheme(deps);
+    sendJson(res, {
+      // What "Org default" in the Theme menu means: appearance.theme null.
+      org_default: org ? { id: org.id, name: org.theme.name } : null,
+      active: a
+        ? {
+            id: a.id,
+            name: a.theme.name,
+            version: a.theme.version,
+            source: a.source,
+            chosen_by: a.chosenBy,
+            default_mode: a.theme.default_mode ?? "dark",
+            mark: markOf(a),
+            // The tab icon per mode: the shell sets the one for the mode
+            // it draws in (appearance.js).
+            favicon: {
+              light: faviconUrl(deps, a, "light"),
+              dark: faviconUrl(deps, a, "dark"),
+            },
+          }
+        : null,
+      prefs,
+      themes: listThemes(deps.roots()).map((t) => ({
+        id: t.id,
+        name: t.name,
+        version: t.version,
+        source: t.source,
+        ok: t.ok,
+        ...(t.problem ? { problem: t.problem } : {}),
+      })),
+    });
+    return true;
+  }
+
+  // /theme/<id>/<file…>. Each segment is decoded and must be a plain name:
+  // an encoded slash, dot segment or NUL never reaches the lookup, which in
+  // turn only matches the exact paths the manifest names.
+  const [id, ...segs] = pathname.slice("/theme/".length).split("/");
+  let rel: string;
+  try {
+    const parts = segs.map((s) => decodeURIComponent(s));
+    if (
+      !id ||
+      parts.length === 0 ||
+      parts.some((p) => !p || p === "." || p === ".." || /[\\/\0]/.test(p))
+    ) {
+      send404(res);
+      return true;
+    }
+    rel = parts.join("/");
+  } catch {
+    send404(res);
+    return true;
+  }
+  const asset = themeAsset(deps.roots(), id, rel);
+  if (!asset) {
+    send404(res);
+    return true;
+  }
+  const headers: Record<string, string> = {
+    "Content-Type": asset.type,
+    "X-Content-Type-Options": "nosniff",
+    "Cache-Control": "no-cache",
+  };
+  // Opened directly, an SVG is a document: let it run nothing, fetch nothing.
+  if (asset.type === "image/svg+xml")
+    headers["Content-Security-Policy"] =
+      "default-src 'none'; style-src 'unsafe-inline'";
+  res.writeHead(200, headers);
+  res.end(req.method === "HEAD" ? undefined : fs.readFileSync(asset.file));
+  return true;
+}

package/src/ui/server/theme-runtime.ts

@@ -0,0 +1,407 @@
+/**
+ * The theme runtime: which theme the web UI draws with, and that theme as CSS.
+ *
+ * Themes come from three places (see src/ui/cli/theme-command.ts):
+ *   built-in  <engineRoot>/themes/den/          Den's own, always present
+ *   locked    <distRoot>/plugins/<id>/ + lock   vendored by `theme add`
+ *   local     <distRoot>/plugins/<id>/, no lock the distribution's own
+ *
+ * The active theme is the user's choice (user.yml `appearance.theme`), else
+ * the distribution's (org config `brand.theme`), else den. A choice that is not
+ * installed or fails validation falls through to the next, ending at den,
+ * with one warning in the server log per bad choice. Only a validated
+ * manifest is ever rendered: its values passed the schema's CSS-value rule
+ * (no ; { } < > \ url() @import), so writing them into custom properties
+ * cannot break out of the declaration.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import {
+  installedThemeIds,
+  readLock,
+  themeDirFor,
+  validationSummary,
+} from "../cli/theme-command.js";
+import {
+  themeDirIn,
+  validatePluginDir,
+} from "../../shared/plugins/manifest.js";
+import {
+  markImage,
+  themeFiles,
+  validateThemeDir,
+  type ColorToken,
+  type ThemeManifest,
+  type ThemeMode,
+} from "../../shared/theme/contract.js";
+
+export const BUILTIN_THEME = "den";
+
+export type ThemeOrigin = "built-in" | "locked" | "local";
+
+export interface ThemeRoots {
+  distRoot: string;
+  engineRoot: string;
+}
+
+export interface InstalledTheme {
+  id: string;
+  name: string;
+  version: string;
+  source: ThemeOrigin;
+  /** Validates under this Den: only then is it rendered or served. */
+  ok: boolean;
+  /** Why it is not ok. */
+  problem?: string;
+  dir: string;
+  theme?: ThemeManifest;
+}
+
+export const COLOR_TOKENS: readonly ColorToken[] = [
+  "bg",
+  "surface",
+  "raised",
+  "sunken",
+  "text",
+  "muted",
+  "faint",
+  "border",
+  "border-strong",
+  "accent",
+  "accent-text",
+  "accent-fill",
+  "on-accent",
+  "ok",
+  "warn",
+  "bad",
+  "remote",
+];
+
+export function builtinThemeDir(engineRoot: string): string {
+  return path.join(engineRoot, "themes", BUILTIN_THEME);
+}
+
+function inspect(
+  id: string,
+  dir: string,
+  source: ThemeOrigin,
+  expectId?: string,
+  pluginDir?: string,
+): InstalledTheme {
+  // The theme itself, to render; the verdict is `validate`'s for the whole
+  // plugin (author/maintainer, `den` range, README, capabilities), so what
+  // fails validate never loads and is never offered (PL-SPEC d4).
+  const v = validateThemeDir(dir, expectId ? { expectId } : {});
+  const verdict = validatePluginDir(
+    pluginDir ?? dir,
+    expectId ? { expectId } : {},
+  );
+  const ok = v.ok && verdict.ok;
+  return {
+    id,
+    name: v.theme?.name ?? id,
+    version: v.theme?.version ?? "?",
+    source,
+    ok,
+    ...(ok ? {} : { problem: validationSummary(verdict.ok ? v : verdict) }),
+    dir,
+    ...(v.theme ? { theme: v.theme } : {}),
+  };
+}
+
+/**
+ * Where plugin `id`'s theme is: plugins/<id>/ for a den-theme.json plugin,
+ * else the directory its den-plugin.json theme entry names.
+ */
+function pluginThemeDir(distRoot: string, id: string): string {
+  const dir = themeDirFor(distRoot, id);
+  return themeDirIn(dir) ?? dir;
+}
+
+/** Every theme this distribution can use: den first, then plugins/<id>/ sorted. */
+export function listThemes(roots: ThemeRoots): InstalledTheme[] {
+  let lock: ReturnType<typeof readLock> = {};
+  try {
+    lock = readLock(roots.distRoot);
+  } catch {
+    /* an unreadable lock: every theme is then local; `theme list` reports it */
+  }
+  const out = [
+    inspect(BUILTIN_THEME, builtinThemeDir(roots.engineRoot), "built-in"),
+  ];
+  for (const id of installedThemeIds(roots.distRoot)) {
+    if (id === BUILTIN_THEME) continue; // the built-in one is never shadowed
+    out.push(
+      inspect(
+        id,
+        pluginThemeDir(roots.distRoot, id),
+        lock[id]?.kinds?.includes("theme") ? "locked" : "local",
+        id,
+        themeDirFor(roots.distRoot, id),
+      ),
+    );
+  }
+  return out;
+}
+
+/** One theme by id, or null when no such theme is installed. */
+export function findTheme(
+  roots: ThemeRoots,
+  id: string,
+): InstalledTheme | null {
+  if (id === BUILTIN_THEME)
+    return inspect(id, builtinThemeDir(roots.engineRoot), "built-in");
+  if (!/^[a-z][a-z0-9-]{1,39}$/.test(id)) return null;
+  if (!installedThemeIds(roots.distRoot).includes(id)) return null;
+  let locked = false;
+  try {
+    locked = !!readLock(roots.distRoot)[id]?.kinds?.includes("theme");
+  } catch {
+    /* see listThemes */
+  }
+  return inspect(
+    id,
+    pluginThemeDir(roots.distRoot, id),
+    locked ? "locked" : "local",
+    id,
+    themeDirFor(roots.distRoot, id),
+  );
+}
+
+export interface ThemeChoice {
+  /** user.yml `appearance.theme`. */
+  user?: string | null;
+  /** The org config's `brand.theme`. */
+  distribution?: string | null;
+}
+
+export interface ActiveTheme {
+  id: string;
+  theme: ThemeManifest;
+  dir: string;
+  source: ThemeOrigin;
+  /** Which choice won. */
+  chosenBy: "user" | "distribution" | "default";
+}
+
+const warned = new Set<string>();
+
+/** Forget which warnings were logged (tests). */
+export function resetThemeWarnings(): void {
+  warned.clear();
+}
+
+/**
+ * The theme to draw with. Never throws: a bad choice is warned about once
+ * and skipped. Null only if Den's own theme is unusable (a broken install).
+ */
+export function resolveActiveTheme(
+  roots: ThemeRoots,
+  choice: ThemeChoice,
+  warn: (line: string) => void = (l) => console.warn(l),
+): ActiveTheme | null {
+  const candidates: [string, ActiveTheme["chosenBy"], string][] = [];
+  if (choice.user) candidates.push([choice.user, "user", "your appearance"]);
+  if (choice.distribution)
+    candidates.push([
+      choice.distribution,
+      "distribution",
+      "the distribution's `brand.theme`",
+    ]);
+  candidates.push([BUILTIN_THEME, "default", "the default"]);
+  for (const [id, chosenBy, label] of candidates) {
+    let t: InstalledTheme | null = null;
+    try {
+      t = findTheme(roots, String(id));
+    } catch (e) {
+      t = null;
+      warnOnce(
+        warn,
+        `${id}:error`,
+        () =>
+          `theme "${id}" (${label}) could not be read: ${(e as Error).message}`,
+      );
+    }
+    if (t?.ok && t.theme)
+      return {
+        id: t.id,
+        theme: t.theme,
+        dir: t.dir,
+        source: t.source,
+        chosenBy,
+      };
+    if (id === BUILTIN_THEME && chosenBy === "default") {
+      warnOnce(
+        warn,
+        "den:broken",
+        () =>
+          `the built-in theme is not valid (${t?.problem ?? "missing"}); the UI has no theme`,
+      );
+      return null;
+    }
+    warnOnce(warn, `${id}:${t ? "invalid" : "missing"}`, () =>
+      t
+        ? `theme "${id}" (${label}) is not valid under this Den: ${t.problem}; using the next choice`
+        : `theme "${id}" (${label}) is not installed; using the next choice`,
+    );
+  }
+  return null;
+}
+
+function warnOnce(
+  warn: (line: string) => void,
+  key: string,
+  line: () => string,
+): void {
+  if (warned.has(key)) return;
+  warned.add(key);
+  warn(`[theme] ${line()}`);
+}
+
+/** URL of a file in a theme, as /theme/<id>/<file> serves it. */
+export function themeAssetUrl(id: string, rel: string): string {
+  return `/theme/${id}/${rel.split("/").map(encodeURIComponent).join("/")}`;
+}
+
+const DEFAULT_TYPE = {
+  sans: '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif',
+  mono: 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace',
+  ja: '"Hiragino Sans", "Noto Sans JP", "Yu Gothic", Meiryo, sans-serif',
+};
+
+/** A generic family ends a stack that can always resolve. */
+const GENERIC_FAMILY =
+  /(?:^|,)\s*(?:sans-serif|serif|monospace|cursive|fantasy|system-ui|ui-sans-serif|ui-serif|ui-monospace|ui-rounded|math|emoji)\s*$/i;
+
+/**
+ * A theme's font stack, made safe to use alone: one that does not end in a
+ * generic family gets Den's stack after it, so a missing font never drops
+ * the UI to the browser's default serif. The pages use only var(--sans),
+ * var(--mono), var(--display); the fallbacks live here, nowhere else.
+ */
+export function fontStack(stack: string | undefined, fallback: string): string {
+  if (!stack?.trim()) return fallback;
+  return GENERIC_FAMILY.test(stack) ? stack : `${stack}, ${fallback}`;
+}
+
+/**
+ * Den's base rules, the same under every theme. A link in body content is
+ * underlined (subtly, in a tint of its own color), so it never reads by
+ * color alone: a theme whose accent text is red would otherwise make links
+ * look like errors next to --bad. Nav links, buttons and pills are not
+ * body content. :where() keeps the rule at zero specificity, so any page
+ * style that draws a link differently wins.
+ */
+const BASE_CSS = [
+  "/* Den base (every theme) */",
+  ':where(a[href]:not(nav a, header a, .topbar a, [role="button"], [class*="btn"], [class*="pill"], [class*="tab"])) {',
+  "  text-decoration-line: underline;",
+  "  text-decoration-thickness: 1px;",
+  "  text-underline-offset: 0.2em;",
+  "  text-decoration-color: color-mix(in srgb, currentColor 40%, transparent);",
+  "}",
+  ':where(a[href]:not(nav a, header a, .topbar a, [role="button"], [class*="btn"], [class*="pill"], [class*="tab"])):hover {',
+  "  text-decoration-color: currentColor;",
+  "}",
+];
+
+/**
+ * The theme as CSS: @font-face for its fonts, type and shape on :root, and
+ * one block of color tokens per mode, selected by <html data-mode>. The
+ * theme's default mode also applies when data-mode is unset. Then Den's
+ * base rules (BASE_CSS).
+ */
+export function renderThemeCss(id: string, theme: ThemeManifest): string {
+  const lines: string[] = [
+    `/* ${theme.name} ${theme.version} (${id}, den.theme/v1). Generated by Den from den-theme.json. */`,
+  ];
+  for (const f of theme.fonts ?? [])
+    for (const file of f.files) {
+      const [lo, hi] = (file.weight ?? "400").split(" ");
+      lines.push(
+        `@font-face { font-family: "${f.family}"; src: url("${themeAssetUrl(id, file.path)}") format("woff2"); font-weight: ${hi ? `${lo} ${hi}` : lo}; font-style: ${file.style ?? "normal"}; font-display: swap; }`,
+      );
+    }
+  const type = theme.type ?? {};
+  const shape = theme.shape ?? {};
+  const sans = fontStack(type.sans, DEFAULT_TYPE.sans);
+  lines.push(
+    ":root {",
+    `  --sans: ${sans};`,
+    `  --mono: ${fontStack(type.mono, DEFAULT_TYPE.mono)};`,
+    `  --display: ${fontStack(type.display, sans)};`,
+    `  --ja: ${fontStack(type.ja, DEFAULT_TYPE.ja)};`,
+    `  --radius: ${shape.radius ?? "8px"};`,
+    `  --radius-button: ${shape["radius-button"] ?? "6px"};`,
+    `  --density: ${shape.density === "compact" ? "0.85" : "1"};`,
+    "}",
+  );
+  const def: ThemeMode = theme.default_mode ?? "dark";
+  for (const mode of [def, def === "dark" ? "light" : "dark"] as ThemeMode[]) {
+    const c = theme.modes[mode];
+    const sel =
+      mode === def
+        ? `:root,\n:root[data-mode="${mode}"]`
+        : `:root[data-mode="${mode}"]`;
+    lines.push(`${sel} {`, `  color-scheme: ${mode};`);
+    for (const t of COLOR_TOKENS) lines.push(`  --${t}: ${c[t]};`);
+    lines.push(
+      `  --shadow: ${c.shadow ?? (mode === "dark" ? "0 12px 30px rgb(0 0 0 / 0.5)" : "0 8px 24px rgb(0 0 0 / 0.14)")};`,
+      `  --bar: ${c.bar ?? "none"};`,
+      "}",
+    );
+  }
+  lines.push(...BASE_CSS);
+  return `${lines.join("\n")}\n`;
+}
+
+const ASSET_TYPES: Record<string, string> = {
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
+};
+
+/**
+ * The theme's browser-tab icon in a mode, relative to its directory: its
+ * `favicon` (both modes), else its mark's image (the dark variant in dark
+ * mode, if it has one), else null (a text mark: Den's own icon).
+ */
+export function faviconFile(
+  theme: ThemeManifest,
+  mode: ThemeMode,
+): string | null {
+  return theme.favicon ?? markImage(theme.mark, mode)?.file ?? null;
+}
+
+/**
+ * The file /theme/<id>/<rel> may serve, or null: only a file the validated
+ * manifest names (its mark, its favicon, its fonts), only .svg, .png,
+ * .webp, .ico or .woff2, only inside the theme's directory. `rel` is the
+ * decoded remainder of the URL path.
+ */
+export function themeAsset(
+  roots: ThemeRoots,
+  id: string,
+  rel: string,
+): { file: string; type: string } | null {
+  const type = ASSET_TYPES[path.extname(rel).toLowerCase()];
+  if (!type) return null;
+  const t = findTheme(roots, id);
+  if (!t?.ok || !t.theme) return null;
+  if (!themeFiles(t.theme).includes(rel)) return null;
+  const root = path.resolve(t.dir);
+  const file = path.resolve(root, rel);
+  if (!file.startsWith(root + path.sep)) return null;
+  try {
+    // Resolve links too: the real file must still be inside the theme.
+    const real = fs.realpathSync(file);
+    const realRoot = fs.realpathSync(root);
+    if (!real.startsWith(realRoot + path.sep) || !fs.statSync(real).isFile())
+      return null;
+    return { file: real, type };
+  } catch {
+    return null;
+  }
+}