@nastechai/agent 0.16.0 → 0.17.0

package/src/themes/presets.ts

@@ -0,0 +1,477 @@
+import type { DashboardTheme, ThemeTypography, ThemeLayout } from "./types";
+
+/**
+ * Built-in dashboard themes.
+ *
+ * Each theme defines its own palette, typography, and layout so switching
+ * themes produces visible changes beyond just color — fonts, density, and
+ * corner-radius all shift to match the theme's personality.
+ *
+ * Theme names must stay in sync with the backend's
+ * `_BUILTIN_DASHBOARD_THEMES` list in `nastech_cli/web_server.py`.
+ */
+
+// ---------------------------------------------------------------------------
+// Shared typography / layout presets
+// ---------------------------------------------------------------------------
+
+/** Default system stack — neutral, safe fallback for every platform. */
+const SYSTEM_SANS =
+  'system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif';
+const SYSTEM_MONO =
+  'ui-monospace, "SF Mono", "Cascadia Mono", Menlo, Consolas, monospace';
+
+const DEFAULT_TYPOGRAPHY: ThemeTypography = {
+  fontSans: SYSTEM_SANS,
+  fontMono: SYSTEM_MONO,
+  baseSize: "15px",
+  lineHeight: "1.55",
+  letterSpacing: "0",
+};
+
+const DEFAULT_LAYOUT: ThemeLayout = {
+  radius: "0.5rem",
+  density: "comfortable",
+};
+
+/** Rounded layout — softer, more playful corners everywhere. */
+export const ROUNDED_LAYOUT: ThemeLayout = {
+  radius: "1.25rem",
+  density: "comfortable",
+};
+
+// ---------------------------------------------------------------------------
+// Themes
+// ---------------------------------------------------------------------------
+
+export const defaultTheme: DashboardTheme = {
+  name: "default",
+  label: "NasTech Teal",
+  description: "Classic dark teal — the canonical NasTech look",
+  palette: {
+    background: { hex: "#041c1c", alpha: 1 },
+    midground: { hex: "#ffe6cb", alpha: 1 },
+    foreground: { hex: "#ffffff", alpha: 0 },
+    warmGlow: "rgba(255, 189, 56, 0.35)",
+    noiseOpacity: 1,
+  },
+  typography: DEFAULT_TYPOGRAPHY,
+  layout: DEFAULT_LAYOUT,
+};
+
+export const midnightTheme: DashboardTheme = {
+  name: "midnight",
+  label: "Midnight",
+  description: "Deep blue-violet with cool accents",
+  palette: {
+    background: { hex: "#0a0a1f", alpha: 1 },
+    midground: { hex: "#d4c8ff", alpha: 1 },
+    foreground: { hex: "#ffffff", alpha: 0 },
+    warmGlow: "rgba(167, 139, 250, 0.32)",
+    noiseOpacity: 0.8,
+  },
+  typography: {
+    ...DEFAULT_TYPOGRAPHY,
+    fontSans: `"Inter", ${SYSTEM_SANS}`,
+    fontMono: `"JetBrains Mono", ${SYSTEM_MONO}`,
+    fontUrl:
+      "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap",
+    letterSpacing: "-0.005em",
+  },
+  layout: {
+    ...DEFAULT_LAYOUT,
+    radius: "0.75rem",
+  },
+};
+
+export const emberTheme: DashboardTheme = {
+  name: "ember",
+  label: "Ember",
+  description: "Warm crimson and bronze — forge vibes",
+  palette: {
+    background: { hex: "#1a0a06", alpha: 1 },
+    midground: { hex: "#ffd8b0", alpha: 1 },
+    foreground: { hex: "#ffffff", alpha: 0 },
+    warmGlow: "rgba(249, 115, 22, 0.38)",
+    noiseOpacity: 1,
+  },
+  typography: {
+    ...DEFAULT_TYPOGRAPHY,
+    fontSans: `"Spectral", Georgia, "Times New Roman", serif`,
+    fontMono: `"IBM Plex Mono", ${SYSTEM_MONO}`,
+    fontUrl:
+      "https://fonts.googleapis.com/css2?family=Spectral:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;700&display=swap",
+  },
+  layout: {
+    ...DEFAULT_LAYOUT,
+    radius: "0.25rem",
+  },
+  colorOverrides: {
+    destructive: "#c92d0f",
+    warning: "#f97316",
+  },
+};
+
+export const monoTheme: DashboardTheme = {
+  name: "mono",
+  label: "Mono",
+  description: "Clean grayscale — minimal and focused",
+  palette: {
+    background: { hex: "#0e0e0e", alpha: 1 },
+    midground: { hex: "#eaeaea", alpha: 1 },
+    foreground: { hex: "#ffffff", alpha: 0 },
+    warmGlow: "rgba(255, 255, 255, 0.1)",
+    noiseOpacity: 0.6,
+  },
+  typography: {
+    ...DEFAULT_TYPOGRAPHY,
+    fontSans: `"IBM Plex Sans", ${SYSTEM_SANS}`,
+    fontMono: `"IBM Plex Mono", ${SYSTEM_MONO}`,
+    fontUrl:
+      "https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap",
+  },
+  layout: {
+    ...DEFAULT_LAYOUT,
+    radius: "0",
+  },
+};
+
+export const cyberpunkTheme: DashboardTheme = {
+  name: "cyberpunk",
+  label: "Cyberpunk",
+  description: "Neon green on black — matrix terminal",
+  palette: {
+    background: { hex: "#040608", alpha: 1 },
+    midground: { hex: "#9bffcf", alpha: 1 },
+    foreground: { hex: "#ffffff", alpha: 0 },
+    warmGlow: "rgba(0, 255, 136, 0.22)",
+    noiseOpacity: 1.2,
+  },
+  typography: {
+    ...DEFAULT_TYPOGRAPHY,
+    fontSans: `"Share Tech Mono", "JetBrains Mono", ${SYSTEM_MONO}`,
+    fontMono: `"Share Tech Mono", "JetBrains Mono", ${SYSTEM_MONO}`,
+    fontUrl:
+      "https://fonts.googleapis.com/css2?family=Share+Tech+Mono&family=JetBrains+Mono:wght@400;700&display=swap",
+  },
+  layout: {
+    ...DEFAULT_LAYOUT,
+    radius: "0",
+  },
+  colorOverrides: {
+    success: "#00ff88",
+    warning: "#ffd700",
+    destructive: "#ff0055",
+  },
+};
+
+export const roseTheme: DashboardTheme = {
+  name: "rose",
+  label: "Rosé",
+  description: "Soft pink and warm ivory — easy on the eyes",
+  palette: {
+    background: { hex: "#1a0f15", alpha: 1 },
+    midground: { hex: "#ffd4e1", alpha: 1 },
+    foreground: { hex: "#ffffff", alpha: 0 },
+    warmGlow: "rgba(249, 168, 212, 0.3)",
+    noiseOpacity: 0.9,
+  },
+  typography: {
+    ...DEFAULT_TYPOGRAPHY,
+    fontSans: `"Fraunces", Georgia, serif`,
+    fontMono: `"DM Mono", ${SYSTEM_MONO}`,
+    fontUrl:
+      "https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400;9..144,500;9..144,600&family=DM+Mono:wght@400;500&display=swap",
+  },
+  layout: {
+    ...DEFAULT_LAYOUT,
+    radius: "1rem",
+  },
+};
+
+/**
+ * AMOLED Black — pure #000000 background for OLED screens.
+ * Full iOS-style glassmorphism: every surface is frosted glass with
+ * backdrop-filter blur, semi-transparent backgrounds, cyan glow accents,
+ * pill-shaped nav items, and thin cyan scrollbars.
+ */
+export const amoledTheme: DashboardTheme = {
+  name: "amoled",
+  label: "AMOLED Black",
+  description: "Pure black OLED glass — iOS frosted panels, cyan accents, zero grain",
+  palette: {
+    background: { hex: "#000000", alpha: 1 },
+    midground: { hex: "#00e5ff", alpha: 1 },
+    foreground: { hex: "#ffffff", alpha: 0.04 },
+    warmGlow: "rgba(0, 229, 255, 0.14)",
+    noiseOpacity: 0,
+  },
+  typography: {
+    ...DEFAULT_TYPOGRAPHY,
+    fontSans: `"Inter", ${SYSTEM_SANS}`,
+    fontMono: `"JetBrains Mono", ${SYSTEM_MONO}`,
+    fontUrl:
+      "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap",
+    letterSpacing: "-0.01em",
+  },
+  layout: {
+    radius: "1.25rem",
+    density: "comfortable",
+  },
+  componentStyles: {
+    sidebar: {
+      background: "rgba(0, 0, 0, 0.72)",
+    },
+    header: {
+      background: "rgba(0, 0, 0, 0.80)",
+    },
+    card: {
+      background: "rgba(6, 6, 6, 0.70)",
+    },
+  },
+  colorOverrides: {
+    primary: "#00e5ff",
+    primaryForeground: "#000000",
+    accent: "#00e5ff",
+    accentForeground: "#000000",
+    border: "rgba(0, 229, 255, 0.08)",
+    input: "rgba(255, 255, 255, 0.05)",
+    muted: "rgba(0, 0, 0, 0.50)",
+    mutedForeground: "#6b7280",
+    card: "rgba(6, 6, 6, 0.70)",
+    popover: "rgba(4, 4, 4, 0.88)",
+    success: "#00ff88",
+    warning: "#ffcc00",
+    destructive: "#ff3b5c",
+    ring: "#00e5ff",
+  },
+  customCSS: `
+/* ═══════════════════════════════════════════════════════════════════
+   iOS-AMOLED Glass — frosted glass on every surface
+   ═══════════════════════════════════════════════════════════════════ */
+
+/* ── Sidebar: deep frosted glass panel ─────────────────────────────── */
+#app-sidebar {
+  backdrop-filter: blur(32px) saturate(200%) brightness(0.88) !important;
+  -webkit-backdrop-filter: blur(32px) saturate(200%) brightness(0.88) !important;
+  border-right: 1px solid rgba(0, 229, 255, 0.07) !important;
+  box-shadow: 4px 0 48px rgba(0,0,0,0.65), inset -1px 0 0 rgba(0,229,255,0.04) !important;
+}
+
+/* ── Mobile top bar: glass bar ──────────────────────────────────────── */
+header {
+  backdrop-filter: blur(24px) saturate(180%) !important;
+  -webkit-backdrop-filter: blur(24px) saturate(180%) !important;
+  border-bottom: 1px solid rgba(0, 229, 255, 0.07) !important;
+}
+
+/* ── Sidebar nav items: iOS pill shape ──────────────────────────────── */
+#app-sidebar nav a,
+#app-sidebar nav li > button:not([size="icon"]) {
+  border-radius: 0.875rem !important;
+  margin: 1px 8px !important;
+  padding-left: 12px !important;
+  padding-right: 12px !important;
+  transition: background 150ms ease, box-shadow 150ms ease !important;
+}
+#app-sidebar nav a[aria-current="page"] {
+  background: rgba(0, 229, 255, 0.10) !important;
+  box-shadow: inset 0 0 0 1px rgba(0, 229, 255, 0.22), 0 0 16px rgba(0,229,255,0.05) !important;
+}
+#app-sidebar nav a:not([aria-current="page"]):hover {
+  background: rgba(255, 255, 255, 0.04) !important;
+}
+
+/* ── Modals / dialogs / popovers: deepest glass ─────────────────────── */
+[role="dialog"],
+[data-radix-popper-content-wrapper] > *,
+[data-state][data-side] {
+  backdrop-filter: blur(40px) saturate(200%) !important;
+  -webkit-backdrop-filter: blur(40px) saturate(200%) !important;
+  background: rgba(4, 4, 4, 0.88) !important;
+  border: 1px solid rgba(0, 229, 255, 0.09) !important;
+  border-radius: var(--theme-radius) !important;
+  box-shadow: 0 32px 80px rgba(0,0,0,0.88), 0 0 0 1px rgba(255,255,255,0.025) !important;
+}
+
+/* ── Inputs: glass with cyan focus glow ─────────────────────────────── */
+input:not([type="checkbox"]):not([type="radio"]):not([type="range"]):not([type="color"]),
+textarea,
+select {
+  background: rgba(255, 255, 255, 0.04) !important;
+  border-color: rgba(0, 229, 255, 0.14) !important;
+  border-radius: var(--theme-radius) !important;
+  transition: border-color 120ms ease, box-shadow 120ms ease, background 120ms ease !important;
+}
+input:not([type="checkbox"]):not([type="radio"]):focus-visible,
+textarea:focus-visible,
+select:focus {
+  border-color: rgba(0, 229, 255, 0.55) !important;
+  box-shadow: 0 0 0 3px rgba(0, 229, 255, 0.10), 0 0 20px rgba(0,229,255,0.06) !important;
+  outline: none !important;
+  background: rgba(0, 229, 255, 0.03) !important;
+}
+
+/* ── Search inputs: full pill ────────────────────────────────────────── */
+input[type="search"],
+input[placeholder*="Search"],
+input[placeholder*="search"],
+input[placeholder*="Filter"],
+input[placeholder*="filter"] {
+  border-radius: 9999px !important;
+}
+
+/* ── Buttons: rounded everywhere ─────────────────────────────────────── */
+button:not([role="switch"]):not([class*="rounded-full"]),
+[role="button"]:not([role="switch"]) {
+  border-radius: calc(var(--theme-radius) * 0.75) !important;
+}
+
+/* ── Cards: subtle glass depth ───────────────────────────────────────── */
+.card,
+[class*="rounded-lg"],
+[class*="rounded-xl"],
+[class*="rounded-2xl"] {
+  backdrop-filter: blur(8px) !important;
+  -webkit-backdrop-filter: blur(8px) !important;
+}
+
+/* ── Thin cyan scrollbars ─────────────────────────────────────────────── */
+* {
+  scrollbar-width: thin;
+  scrollbar-color: rgba(0, 229, 255, 0.16) transparent;
+}
+::-webkit-scrollbar { width: 3px; height: 3px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb {
+  background: rgba(0, 229, 255, 0.16);
+  border-radius: 99px;
+}
+::-webkit-scrollbar-thumb:hover { background: rgba(0, 229, 255, 0.35); }
+
+/* ── Text selection: cyan highlight ──────────────────────────────────── */
+::selection {
+  background: rgba(0, 229, 255, 0.22);
+  color: #ffffff;
+}
+
+/* ── Kill grain completely ───────────────────────────────────────────── */
+.grain::after { display: none !important; }
+  `,
+};
+
+/**
+ * Cloud — maximum rounding, soft lavender-white palette.
+ * The "bubbly" feel: every element has pill-shaped corners.
+ */
+export const cloudTheme: DashboardTheme = {
+  name: "cloud",
+  label: "Cloud",
+  description: "Soft, rounded, airy — lavender haze with pillowy corners",
+  palette: {
+    background: { hex: "#0f0d1a", alpha: 1 },
+    midground: { hex: "#e8e0ff", alpha: 1 },
+    foreground: { hex: "#ffffff", alpha: 0.02 },
+    warmGlow: "rgba(180, 160, 255, 0.28)",
+    noiseOpacity: 0.5,
+  },
+  typography: {
+    ...DEFAULT_TYPOGRAPHY,
+    fontSans: `"Nunito", "Outfit", ${SYSTEM_SANS}`,
+    fontMono: `"Fira Code", ${SYSTEM_MONO}`,
+    fontUrl:
+      "https://fonts.googleapis.com/css2?family=Nunito:wght@400;500;600;700;800&family=Fira+Code:wght@400;500&display=swap",
+    lineHeight: "1.65",
+    letterSpacing: "0.01em",
+  },
+  layout: {
+    radius: "1.5rem",
+    density: "spacious",
+  },
+  colorOverrides: {
+    primary: "#a78bfa",
+    primaryForeground: "#0f0d1a",
+    accent: "#c4b5fd",
+    accentForeground: "#0f0d1a",
+    border: "#2a2040",
+    card: "#16112a",
+    success: "#86efac",
+    warning: "#fde68a",
+    destructive: "#f87171",
+    ring: "#a78bfa",
+  },
+};
+
+/**
+ * Nord — the classic Arctic color palette. Rounded, calm, professional.
+ */
+export const nordTheme: DashboardTheme = {
+  name: "nord",
+  label: "Nord",
+  description: "Arctic blue — calm, clean, Scandinavian minimalism",
+  palette: {
+    background: { hex: "#2e3440", alpha: 1 },
+    midground: { hex: "#d8dee9", alpha: 1 },
+    foreground: { hex: "#eceff4", alpha: 0.03 },
+    warmGlow: "rgba(136, 192, 208, 0.2)",
+    noiseOpacity: 0.4,
+  },
+  typography: {
+    ...DEFAULT_TYPOGRAPHY,
+    fontSans: `"Inter", ${SYSTEM_SANS}`,
+    fontMono: `"JetBrains Mono", ${SYSTEM_MONO}`,
+    fontUrl:
+      "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap",
+    letterSpacing: "-0.005em",
+  },
+  layout: {
+    radius: "0.75rem",
+    density: "comfortable",
+  },
+  colorOverrides: {
+    primary: "#88c0d0",
+    primaryForeground: "#2e3440",
+    accent: "#81a1c1",
+    accentForeground: "#eceff4",
+    border: "#3b4252",
+    card: "#3b4252",
+    success: "#a3be8c",
+    warning: "#ebcb8b",
+    destructive: "#bf616a",
+    ring: "#88c0d0",
+  },
+};
+
+/**
+ * Same look as ``defaultTheme`` but with a larger root font size, looser
+ * line-height, and ``spacious`` density so every rem-based size in the
+ * dashboard scales up. For users who find the default 15px UI too dense.
+ */
+export const defaultLargeTheme: DashboardTheme = {
+  name: "default-large",
+  label: "NasTech Teal (Large)",
+  description: "NasTech Teal with bigger fonts and roomier spacing",
+  palette: defaultTheme.palette,
+  typography: {
+    ...DEFAULT_TYPOGRAPHY,
+    baseSize: "18px",
+    lineHeight: "1.65",
+  },
+  layout: {
+    ...DEFAULT_LAYOUT,
+    density: "spacious",
+  },
+};
+
+export const BUILTIN_THEMES: Record<string, DashboardTheme> = {
+  default: defaultTheme,
+  "default-large": defaultLargeTheme,
+  midnight: midnightTheme,
+  ember: emberTheme,
+  mono: monoTheme,
+  cyberpunk: cyberpunkTheme,
+  rose: roseTheme,
+  amoled: amoledTheme,
+  cloud: cloudTheme,
+  nord: nordTheme,
+};

package/src/themes/types.ts

@@ -0,0 +1,187 @@
+/**
+ * Dashboard theme model.
+ *
+ * Themes customise three orthogonal layers:
+ *
+ *   1. `palette`       — the 3-layer color triplet (background/midground/
+ *                         foreground) + warm-glow + noise opacity. The
+ *                         design-system cascade in `src/index.css` derives
+ *                         every shadcn-compat token (card, muted, border,
+ *                         primary, etc.) from this triplet via `color-mix()`.
+ *   2. `typography`    — font families, base font size, line height,
+ *                         letter spacing. An optional `fontUrl` is injected
+ *                         as `<link rel="stylesheet">` so self-hosted and
+ *                         Google/Bunny/etc-hosted fonts both work.
+ *   3. `layout`        — corner radius and density (spacing multiplier).
+ *
+ * Plus an optional `colorOverrides` escape hatch for themes that want to
+ * pin specific shadcn tokens to exact values (e.g. a pastel theme that
+ * needs a softer `destructive` red than the derived default).
+ */
+
+/** A color layer: hex base + alpha (0–1). */
+export interface ThemeLayer {
+  alpha: number;
+  hex: string;
+}
+
+export interface ThemePalette {
+  /** Deepest canvas color (typically near-black). */
+  background: ThemeLayer;
+  /** Primary text + accent. Most UI chrome reads this. */
+  midground: ThemeLayer;
+  /** Top-layer highlight. In LENS_0 this is white @ alpha 0 — invisible by
+   *  default but still drives `--color-ring`-style accents. */
+  foreground: ThemeLayer;
+  /** Warm vignette color for <Backdrop />, as an rgba() string. */
+  warmGlow: string;
+  /** Scalar multiplier (0–1.2) on the noise overlay. Lower for softer themes
+   *  like Mono and Rosé, higher for grittier themes like Cyberpunk. */
+  noiseOpacity: number;
+}
+
+export interface ThemeTypography {
+  /** CSS font-family stack for sans-serif body copy. */
+  fontSans: string;
+  /** CSS font-family stack for monospace / code blocks. */
+  fontMono: string;
+  /** Optional display/heading font stack. Falls back to `fontSans`. */
+  fontDisplay?: string;
+  /** Optional external stylesheet URL (e.g. Google Fonts, Bunny Fonts,
+   *  self-hosted .woff2 @font-face sheet). Injected as a <link> in <head>
+   *  on theme switch. Same URL is never injected twice. */
+  fontUrl?: string;
+  /** Root font size (controls rem scale). Example: `"14px"`, `"16px"`. */
+  baseSize: string;
+  /** Default line-height. Example: `"1.5"`, `"1.65"`. */
+  lineHeight: string;
+  /** Default letter-spacing. Example: `"0"`, `"0.01em"`, `"-0.01em"`. */
+  letterSpacing: string;
+}
+
+export type ThemeDensity = "compact" | "comfortable" | "spacious";
+
+export interface ThemeLayout {
+  /** Corner-radius token. Example: `"0"`, `"0.25rem"`, `"0.5rem"`,
+   *  `"1rem"`. Maps to `--radius` and cascades into every component. */
+  radius: string;
+  /** Spacing multiplier. `compact` = 0.85, `comfortable` = 1.0 (default),
+   *  `spacious` = 1.2. Applied via the `--spacing-mul` CSS var. */
+  density: ThemeDensity;
+}
+
+/** Overall layout variant the shell renders. `standard` = default single-
+ *  column page layout. `cockpit` = reserves a left sidebar rail for a
+ *  plugin slot (intended for HUD-style themes with persistent status panels).
+ *  `tiled` = relaxes the main content max-width so pages can use the full
+ *  viewport width. Themes set this; plugins react via CSS vars /
+ *  `[data-layout-variant="..."]` selectors. */
+export type ThemeLayoutVariant = "standard" | "cockpit" | "tiled";
+
+/** Named hero/background assets a theme can populate. Each value is
+ *  emitted as a CSS var (`--theme-asset-<name>`). The default shell
+ *  consumes `bg` in `<Backdrop />` when present; other slots are
+ *  plugin-facing — a cockpit sidebar plugin reads `--theme-asset-hero`
+ *  to render its hero render without coupling to the theme name. */
+export interface ThemeAssets {
+  /** Full-viewport background image URL, injected under the noise layer. */
+  bg?: string;
+  /** Hero render (Gundam, mascot, wallpaper) — for plugin sidebars/overlays. */
+  hero?: string;
+  /** Logo mark — header slot consumers use this. */
+  logo?: string;
+  /** Faction/brand crest — header-left decoration. */
+  crest?: string;
+  /** Secondary sidebar illustration. */
+  sidebar?: string;
+  /** Alternate header artwork. */
+  header?: string;
+  /** User-defined named assets. Keyed by [a-zA-Z0-9_-] only.
+   *  Emitted as `--theme-asset-custom-<key>`. */
+  custom?: Record<string, string>;
+}
+
+/** Component-style override buckets. Each bucket's entries become CSS
+ *  vars (`--component-<bucket>-<kebab-property>`) that shell components
+ *  (Card, Backdrop, App header/footer, etc.) read. Values are plain CSS
+ *  strings — we don't parse them, so themes can use `clip-path`,
+ *  `border-image`, `background`, `box-shadow`, and anything else CSS
+ *  accepts. */
+export interface ThemeComponentStyles {
+  card?: Record<string, string>;
+  header?: Record<string, string>;
+  footer?: Record<string, string>;
+  sidebar?: Record<string, string>;
+  tab?: Record<string, string>;
+  progress?: Record<string, string>;
+  badge?: Record<string, string>;
+  backdrop?: Record<string, string>;
+  page?: Record<string, string>;
+}
+
+/** Optional hex overrides keyed by shadcn-compat token name (without the
+ *  `--color-` prefix). Any key set here wins over the DS cascade. */
+export interface ThemeColorOverrides {
+  card?: string;
+  cardForeground?: string;
+  popover?: string;
+  popoverForeground?: string;
+  primary?: string;
+  primaryForeground?: string;
+  secondary?: string;
+  secondaryForeground?: string;
+  muted?: string;
+  mutedForeground?: string;
+  accent?: string;
+  accentForeground?: string;
+  destructive?: string;
+  destructiveForeground?: string;
+  success?: string;
+  warning?: string;
+  border?: string;
+  input?: string;
+  ring?: string;
+}
+
+export interface DashboardTheme {
+  description: string;
+  label: string;
+  name: string;
+  palette: ThemePalette;
+  typography: ThemeTypography;
+  layout: ThemeLayout;
+  /** Overall shell layout. Defaults to `"standard"` when absent. */
+  layoutVariant?: ThemeLayoutVariant;
+  /** Named + custom asset URLs exposed as CSS vars on theme apply. */
+  assets?: ThemeAssets;
+  /** Raw CSS injected as a scoped `<style>` tag on theme apply, cleaned up
+   *  on theme switch. Intended for selector-level chrome that's too
+   *  expressive for componentStyles alone (e.g. `::before` pseudo-elements,
+   *  complex animations, media queries). */
+  customCSS?: string;
+  /** Per-component CSS-var overrides. See `ThemeComponentStyles`. */
+  componentStyles?: ThemeComponentStyles;
+  colorOverrides?: ThemeColorOverrides;
+}
+
+/**
+ * Wire response shape for `GET /api/dashboard/themes`.
+ *
+ * The `themes` list is intentionally partial — built-in themes are fully
+ * defined in `presets.ts`; user themes carry their full definition so the
+ * client can apply them without a second round-trip.
+ */
+export interface ThemeListEntry {
+  description: string;
+  label: string;
+  name: string;
+  /** Full theme definition. Present for user-defined themes loaded from
+   *  `~/.nastech/dashboard-themes/*.yaml`; undefined for built-ins (the
+   *  client already has those in `BUILTIN_THEMES`). */
+  definition?: DashboardTheme;
+}
+
+export interface ThemeListResponse {
+  active: string;
+  themes: ThemeListEntry[];
+}

package/tsconfig.app.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2023",
+    "useDefineForClassFields": true,
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Path aliases */
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}