@sero-ai/ui 0.1.0 → 0.2.1

package/src/components/ui/tree.tsx

@@ -20,7 +20,7 @@ const TreeContext = React.createContext<TreeContextValue>({
 });
 
 function useTreeContext<T = any>() {
-  return React.useContext(TreeContext) as TreeContextValue<T>;
+  return React.use(TreeContext) as TreeContextValue<T>;
 }
 
 interface TreeProps extends React.HTMLAttributes<HTMLDivElement> {
@@ -61,7 +61,7 @@ interface TreeItemProps<T = any>
 }
 
 /**
- * TreeItem — full-width row button.
+ * TreeItem, full-width row button.
  *
  * The row carries hover / selected / drag-target backgrounds so the
  * highlight spans edge-to-edge (VSCode-style). Indentation is applied
@@ -140,7 +140,7 @@ interface TreeItemLabelProps<T = any>
 }
 
 /**
- * TreeItemLabel — content wrapper inside a TreeItem.
+ * TreeItemLabel, content wrapper inside a TreeItem.
  *
  * Layout-only (chevron + children). Background lives on the parent
  * TreeItem so it spans the full row width.

package/src/index.ts

@@ -1,16 +1,137 @@
 // @sero-ai/ui — Shared UI components, AI elements, and utilities
 //
-// Consumers can import from subpaths for tree-shakeable access:
-//   import { Button } from "@sero-ai/ui/components/ui/button"
-//   import { Message } from "@sero-ai/ui/components/ai-elements/message"
-//   import { cn } from "@sero-ai/ui/lib/utils"
-//   import { useIsMobile } from "@sero-ai/ui/hooks/use-mobile"
+// Prefer importing common primitives from the barrel export:
+//   import { Button, Card, Input, cn, useIsMobile } from "@sero-ai/ui"
 //
-// Or import the barrel export:
-//   import { cn, useIsMobile } from "@sero-ai/ui"
+// Deep subpath imports are still supported when needed. Because this package is
+// native ESM, consumers should use runtime .js extensions for deep imports:
+//   import { Button } from "@sero-ai/ui/components/ui/button.js"
+//   import { cn } from "@sero-ai/ui/lib/utils.js"
 
 // ── Utilities ──
 export { cn } from "./lib/utils";
 
 // ── Hooks ──
 export { useIsMobile } from "./hooks/use-mobile";
+
+// ── Theme ──
+export * from "./theme";
+
+// ── UI Components ──
+export * from "./components/ui/accordion";
+export * from "./components/ui/alert-dialog";
+export * from "./components/ui/alert";
+export * from "./components/ui/aspect-ratio";
+export * from "./components/ui/avatar";
+export * from "./components/ui/badge";
+export * from "./components/ui/breadcrumb";
+export * from "./components/ui/button-group";
+export * from "./components/ui/button";
+export * from "./components/ui/calendar";
+export * from "./components/ui/card";
+export * from "./components/ui/carousel";
+export * from "./components/ui/chart";
+export * from "./components/ui/checkbox";
+export * from "./components/ui/collapsible";
+export * from "./components/ui/combobox";
+export * from "./components/ui/command";
+export * from "./components/ui/context-menu";
+export * from "./components/ui/dialog";
+export * from "./components/ui/direction";
+export * from "./components/ui/drawer";
+export * from "./components/ui/dropdown-menu";
+export * from "./components/ui/empty";
+export * from "./components/ui/field";
+export * from "./components/ui/form";
+export * from "./components/ui/hover-card";
+export * from "./components/ui/input-group";
+export * from "./components/ui/input-otp";
+export * from "./components/ui/input";
+export * from "./components/ui/item";
+export * from "./components/ui/kbd";
+export * from "./components/ui/label";
+export * from "./components/ui/menubar";
+export * from "./components/ui/native-select";
+export * from "./components/ui/navigation-menu";
+export * from "./components/ui/pagination";
+export * from "./components/ui/plugin-safety-disclaimer";
+export * from "./components/ui/popover";
+export * from "./components/ui/progress";
+export * from "./components/ui/radio-group";
+export * from "./components/ui/resizable";
+export * from "./components/ui/scroll-area";
+export * from "./components/ui/search-input";
+export * from "./components/ui/select";
+export * from "./components/ui/separator";
+export * from "./components/ui/sheet";
+export * from "./components/ui/sidebar";
+export * from "./components/ui/skeleton";
+export * from "./components/ui/slider";
+export * from "./components/ui/sonner";
+export * from "./components/ui/spinner";
+export * from "./components/ui/switch";
+export * from "./components/ui/table";
+export * from "./components/ui/tabs";
+export * from "./components/ui/textarea";
+export * from "./components/ui/toggle-group";
+export * from "./components/ui/toggle";
+export * from "./components/ui/tooltip";
+export * from "./components/ui/tree";
+// ── AI Elements ──
+export * from "./components/ai-elements/agent";
+export * from "./components/ai-elements/artifact";
+export * from "./components/ai-elements/attachments";
+export * from "./components/ai-elements/audio-player";
+export * from "./components/ai-elements/canvas";
+export * from "./components/ai-elements/chain-of-thought";
+export * from "./components/ai-elements/checkpoint";
+export * from "./components/ai-elements/code-block";
+export * from "./components/ai-elements/commit";
+export * from "./components/ai-elements/confirmation";
+export * from "./components/ai-elements/connection";
+export * from "./components/ai-elements/context";
+export * from "./components/ai-elements/controls";
+export * from "./components/ai-elements/conversation";
+export * from "./components/ai-elements/edge";
+export * from "./components/ai-elements/environment-variables";
+export * from "./components/ai-elements/file-tree";
+export * from "./components/ai-elements/image";
+export * from "./components/ai-elements/inline-citation";
+export * from "./components/ai-elements/jsx-preview";
+export * from "./components/ai-elements/message";
+export * from "./components/ai-elements/mic-selector";
+export * from "./components/ai-elements/model-selector";
+export * from "./components/ai-elements/node";
+export * from "./components/ai-elements/open-in-chat";
+export * from "./components/ai-elements/package-info";
+export * from "./components/ai-elements/panel";
+export * from "./components/ai-elements/persona";
+export * from "./components/ai-elements/plan";
+export * from "./components/ai-elements/prompt-input-context";
+export * from "./components/ai-elements/prompt-input-elements";
+export * from "./components/ai-elements/prompt-input-textarea";
+export * from "./components/ai-elements/prompt-input";
+export * from "./components/ai-elements/queue";
+export * from "./components/ai-elements/reasoning";
+export * from "./components/ai-elements/sandbox";
+export * from "./components/ai-elements/schema-display";
+export * from "./components/ai-elements/shimmer";
+export * from "./components/ai-elements/snippet";
+export * from "./components/ai-elements/sources";
+export * from "./components/ai-elements/speech-input";
+export * from "./components/ai-elements/stack-trace";
+export * from "./components/ai-elements/suggestion";
+export * from "./components/ai-elements/task";
+export * from "./components/ai-elements/terminal";
+export * from "./components/ai-elements/test-results";
+export * from "./components/ai-elements/tool";
+export * from "./components/ai-elements/toolbar";
+export * from "./components/ai-elements/transcription";
+export * from "./components/ai-elements/voice-selector-accent";
+export * from "./components/ai-elements/voice-selector";
+export * from "./components/ai-elements/web-preview";
+
+// ── Model Selection Components ──
+export * from "./components/model-selection/available-model-picker";
+export * from "./components/model-selection/model-warning-list";
+export * from "./components/model-selection/thinking-level-picker";

package/src/styles/globals.css

@@ -22,7 +22,7 @@
   /* Border (light) */
   --border-subtle: #d4d8e0;
   --border-default: #bcc1cc;
-  --border-focus: #6366f1;
+  --border-focus: #059669;
 
   /* Text (light) */
   --text-primary: #0f1117;
@@ -30,10 +30,26 @@
   --text-muted: #6b7280;
   --text-inverse: #fafafa;
 
-  /* Accent (indigo) — brand accent colour used by Sero components */
-  --accent-primary: #6366f1;
-  --accent-hover: #818cf8;
-  --accent-muted: #6366f11a;
+  /* Brand colours — product identity, actions, active UI */
+  --brand-primary: #059669;
+  --brand-primary-hover: #047857;
+  --brand-primary-foreground: #ffffff;
+  --brand-primary-muted: color-mix(in srgb, var(--brand-primary) 10%, transparent);
+  --brand-primary-subtle: color-mix(in srgb, var(--brand-primary) 15%, transparent);
+  --brand-primary-faint: color-mix(in srgb, var(--brand-primary) 3%, transparent);
+  --brand-primary-border: color-mix(in srgb, var(--brand-primary) 20%, transparent);
+  --brand-secondary: #7c3aed;
+  --brand-secondary-hover: #6d28d9;
+  --brand-secondary-foreground: #ffffff;
+  --brand-secondary-muted: color-mix(in srgb, var(--brand-secondary) 10%, transparent);
+  --brand-secondary-subtle: color-mix(in srgb, var(--brand-secondary) 15%, transparent);
+  --brand-secondary-faint: color-mix(in srgb, var(--brand-secondary) 3%, transparent);
+  --brand-secondary-border: color-mix(in srgb, var(--brand-secondary) 20%, transparent);
+
+  /* Legacy accent / syntax accent */
+  --accent-primary: var(--brand-secondary);
+  --accent-hover: var(--brand-secondary-hover);
+  --accent-muted: var(--brand-secondary-muted);
   --accent-code: #7c3aed;
 
   /* Status — solid */
@@ -79,10 +95,10 @@
   --voice-processing-muted: rgba(6, 182, 212, 0.15);
 
   /* Semantic colours — indigo accent for notifications/banners */
-  --banner-primary: #6366f1;
-  --banner-primary-muted: rgba(99, 102, 241, 0.10);
-  --banner-primary-subtle: rgba(99, 102, 241, 0.15);
-  --banner-primary-border: rgba(99, 102, 241, 0.20);
+  --banner-primary: var(--brand-secondary);
+  --banner-primary-muted: color-mix(in srgb, var(--banner-primary) 10%, transparent);
+  --banner-primary-subtle: color-mix(in srgb, var(--banner-primary) 15%, transparent);
+  --banner-primary-border: color-mix(in srgb, var(--banner-primary) 20%, transparent);
 
   /* Thinking / reasoning gradients */
   --gradient-thinking-high: linear-gradient(135deg, rgba(245, 158, 11, 0.20), rgba(239, 68, 68, 0.20));
@@ -131,15 +147,15 @@
      shadcn component (Dialog, Command, Dropdown, Tooltip, …)
      automatically follows theme changes.
      NOTE: --accent here is the shadcn "hover/selection bg",
-     NOT the brand accent colour (that's --accent-primary). */
+     NOT a brand colour (use --brand-primary/secondary). */
   --background: var(--bg-base);
   --foreground: var(--text-primary);
   --card: var(--bg-surface);
   --card-foreground: var(--text-primary);
   --popover: var(--bg-elevated);
   --popover-foreground: var(--text-primary);
-  --primary: var(--text-primary);
-  --primary-foreground: var(--text-inverse);
+  --primary: var(--brand-primary);
+  --primary-foreground: var(--brand-primary-foreground);
   --secondary: var(--bg-surface);
   --secondary-foreground: var(--text-primary);
   --muted: var(--bg-muted);
@@ -157,8 +173,8 @@
   --chart-5: oklch(0.769 0.188 70.08);
   --sidebar: var(--bg-surface);
   --sidebar-foreground: var(--text-primary);
-  --sidebar-primary: var(--accent-primary);
-  --sidebar-primary-foreground: var(--text-inverse);
+  --sidebar-primary: var(--brand-primary);
+  --sidebar-primary-foreground: var(--brand-primary-foreground);
   --sidebar-accent: var(--bg-elevated);
   --sidebar-accent-foreground: var(--text-primary);
   --sidebar-border: var(--border-subtle);
@@ -208,6 +224,38 @@
   --radius-4xl: calc(var(--radius) + 16px);
   --color-background: var(--background);
   --color-foreground: var(--foreground);
+  --color-brand-primary: var(--brand-primary);
+  --color-brand-primary-foreground: var(--brand-primary-foreground);
+  --color-brand-primary-muted: var(--brand-primary-muted);
+  --color-brand-primary-subtle: var(--brand-primary-subtle);
+  --color-brand-primary-faint: var(--brand-primary-faint);
+  --color-brand-primary-border: var(--brand-primary-border);
+  --color-brand-secondary: var(--brand-secondary);
+  --color-brand-secondary-foreground: var(--brand-secondary-foreground);
+  --color-brand-secondary-muted: var(--brand-secondary-muted);
+  --color-brand-secondary-subtle: var(--brand-secondary-subtle);
+  --color-brand-secondary-faint: var(--brand-secondary-faint);
+  --color-brand-secondary-border: var(--brand-secondary-border);
+  --color-status-success: var(--status-success);
+  --color-status-success-muted: var(--status-success-muted);
+  --color-status-success-subtle: var(--status-success-subtle);
+  --color-status-success-faint: var(--status-success-faint);
+  --color-status-success-border: var(--status-success-border);
+  --color-status-warning: var(--status-warning);
+  --color-status-warning-muted: var(--status-warning-muted);
+  --color-status-warning-subtle: var(--status-warning-subtle);
+  --color-status-warning-faint: var(--status-warning-faint);
+  --color-status-warning-border: var(--status-warning-border);
+  --color-status-error: var(--status-error);
+  --color-status-error-muted: var(--status-error-muted);
+  --color-status-error-subtle: var(--status-error-subtle);
+  --color-status-error-faint: var(--status-error-faint);
+  --color-status-error-border: var(--status-error-border);
+  --color-status-info: var(--status-info);
+  --color-status-info-muted: var(--status-info-muted);
+  --color-status-info-subtle: var(--status-info-subtle);
+  --color-status-info-faint: var(--status-info-faint);
+  --color-status-info-border: var(--status-info-border);
   --color-card: var(--card);
   --color-card-foreground: var(--card-foreground);
   --color-popover: var(--popover);
@@ -250,6 +298,7 @@
   /* Border (dark) */
   --border-subtle: #27272a;
   --border-default: #3f3f46;
+  --border-focus: #34d399;
 
   /* Text (dark) */
   --text-primary: #fafafa;
@@ -257,10 +306,26 @@
   --text-muted: #71717a;
   --text-inverse: #09090b;
 
-  /* Accent (dark) */
-  --accent-primary: #818cf8;
-  --accent-hover: #a5b4fc;
-  --accent-muted: #6366f133;
+  /* Brand colours (dark) */
+  --brand-primary: #34d399;
+  --brand-primary-hover: #6ee7b7;
+  --brand-primary-foreground: #052e1c;
+  --brand-primary-muted: color-mix(in srgb, var(--brand-primary) 10%, transparent);
+  --brand-primary-subtle: color-mix(in srgb, var(--brand-primary) 15%, transparent);
+  --brand-primary-faint: color-mix(in srgb, var(--brand-primary) 3%, transparent);
+  --brand-primary-border: color-mix(in srgb, var(--brand-primary) 20%, transparent);
+  --brand-secondary: #c4b5fd;
+  --brand-secondary-hover: #ddd6fe;
+  --brand-secondary-foreground: #1e1038;
+  --brand-secondary-muted: color-mix(in srgb, var(--brand-secondary) 10%, transparent);
+  --brand-secondary-subtle: color-mix(in srgb, var(--brand-secondary) 15%, transparent);
+  --brand-secondary-faint: color-mix(in srgb, var(--brand-secondary) 3%, transparent);
+  --brand-secondary-border: color-mix(in srgb, var(--brand-secondary) 20%, transparent);
+
+  /* Legacy accent / syntax accent (dark) */
+  --accent-primary: var(--brand-secondary);
+  --accent-hover: var(--brand-secondary-hover);
+  --accent-muted: var(--brand-secondary-muted);
   --accent-code: #c4b5fd;
 
   /* Status — solid (dark) */
@@ -306,10 +371,10 @@
   --voice-processing-muted: rgba(34, 211, 238, 0.15);
 
   /* Banner / notifications (dark) */
-  --banner-primary: #818cf8;
-  --banner-primary-muted: rgba(129, 140, 248, 0.10);
-  --banner-primary-subtle: rgba(129, 140, 248, 0.15);
-  --banner-primary-border: rgba(129, 140, 248, 0.20);
+  --banner-primary: var(--brand-secondary);
+  --banner-primary-muted: color-mix(in srgb, var(--banner-primary) 10%, transparent);
+  --banner-primary-subtle: color-mix(in srgb, var(--banner-primary) 15%, transparent);
+  --banner-primary-border: color-mix(in srgb, var(--banner-primary) 20%, transparent);
 
   /* Thinking gradients (dark) */
   --gradient-thinking-high: linear-gradient(135deg, rgba(245, 158, 11, 0.20), rgba(239, 68, 68, 0.20));
@@ -331,8 +396,8 @@
   --card-foreground: var(--text-primary);
   --popover: var(--bg-elevated);
   --popover-foreground: var(--text-primary);
-  --primary: var(--text-primary);
-  --primary-foreground: var(--text-inverse);
+  --primary: var(--brand-primary);
+  --primary-foreground: var(--brand-primary-foreground);
   --secondary: var(--bg-surface);
   --secondary-foreground: var(--text-primary);
   --muted: var(--bg-muted);
@@ -350,8 +415,8 @@
   --chart-5: oklch(0.645 0.246 16.439);
   --sidebar: var(--bg-surface);
   --sidebar-foreground: var(--text-primary);
-  --sidebar-primary: var(--accent-primary);
-  --sidebar-primary-foreground: var(--text-inverse);
+  --sidebar-primary: var(--brand-primary);
+  --sidebar-primary-foreground: var(--brand-primary-foreground);
   --sidebar-accent: var(--bg-elevated);
   --sidebar-accent-foreground: var(--text-primary);
   --sidebar-border: var(--border-subtle);

package/src/styles/plugin.css

@@ -0,0 +1,4 @@
+@import "./globals.css";
+
+/* Federated Sero plugins should import this file, then add plugin-local
+   @source directives. It keeps Tailwind 4 token names aligned with the shell. */

package/src/theme/apply-theme.ts

@@ -0,0 +1,250 @@
+import type {
+  ColorTokens,
+  ThemePreset,
+} from './types';
+
+// ── Token → CSS Variable Mapping ─────────────────────────────
+
+/** Maps ColorTokens keys to their CSS custom property names. */
+const COLOR_TOKEN_TO_CSS: Record<keyof ColorTokens, string> = {
+  bgBase: '--bg-base',
+  bgSurface: '--bg-surface',
+  bgElevated: '--bg-elevated',
+  bgOverlay: '--bg-overlay',
+  bgMuted: '--bg-muted',
+  borderSubtle: '--border-subtle',
+  borderDefault: '--border-default',
+  borderFocus: '--border-focus',
+  textPrimary: '--text-primary',
+  textSecondary: '--text-secondary',
+  textMuted: '--text-muted',
+  textInverse: '--text-inverse',
+  brandPrimary: '--brand-primary',
+  brandPrimaryHover: '--brand-primary-hover',
+  brandPrimaryForeground: '--brand-primary-foreground',
+  brandSecondary: '--brand-secondary',
+  brandSecondaryHover: '--brand-secondary-hover',
+  brandSecondaryForeground: '--brand-secondary-foreground',
+  accentPrimary: '--accent-primary',
+  accentHover: '--accent-hover',
+  accentMuted: '--accent-muted',
+  accentCode: '--accent-code',
+  statusSuccess: '--status-success',
+  statusWarning: '--status-warning',
+  statusError: '--status-error',
+  statusInfo: '--status-info',
+  collabPrimary: '--collab-primary',
+  voiceRecording: '--voice-recording',
+  voiceProcessing: '--voice-processing',
+  bannerPrimary: '--banner-primary',
+};
+
+/**
+ * Derived opacity variants generated from base semantic colours.
+ * Each entry is [css-var-name, base-token-key, percentage].
+ */
+const DERIVED_OPACITY_VARS: Array<[string, keyof ColorTokens, number]> = [
+  ['--brand-primary-muted', 'brandPrimary', 10],
+  ['--brand-primary-subtle', 'brandPrimary', 15],
+  ['--brand-primary-faint', 'brandPrimary', 3],
+  ['--brand-primary-border', 'brandPrimary', 20],
+  ['--brand-secondary-muted', 'brandSecondary', 10],
+  ['--brand-secondary-subtle', 'brandSecondary', 15],
+  ['--brand-secondary-faint', 'brandSecondary', 3],
+  ['--brand-secondary-border', 'brandSecondary', 20],
+  ['--status-success-muted', 'statusSuccess', 10],
+  ['--status-success-subtle', 'statusSuccess', 15],
+  ['--status-success-faint', 'statusSuccess', 3],
+  ['--status-success-border', 'statusSuccess', 20],
+  ['--status-warning-muted', 'statusWarning', 10],
+  ['--status-warning-subtle', 'statusWarning', 15],
+  ['--status-warning-faint', 'statusWarning', 3],
+  ['--status-warning-border', 'statusWarning', 20],
+  ['--status-error-muted', 'statusError', 10],
+  ['--status-error-subtle', 'statusError', 15],
+  ['--status-error-faint', 'statusError', 3],
+  ['--status-error-border', 'statusError', 20],
+  ['--status-info-muted', 'statusInfo', 10],
+  ['--status-info-subtle', 'statusInfo', 15],
+  ['--status-info-faint', 'statusInfo', 3],
+  ['--status-info-border', 'statusInfo', 20],
+  ['--collab-primary-muted', 'collabPrimary', 10],
+  ['--collab-primary-subtle', 'collabPrimary', 15],
+  ['--collab-primary-border', 'collabPrimary', 20],
+  ['--voice-recording-muted', 'voiceRecording', 20],
+  ['--voice-processing-muted', 'voiceProcessing', 15],
+  ['--banner-primary-muted', 'bannerPrimary', 10],
+  ['--banner-primary-subtle', 'bannerPrimary', 15],
+  ['--banner-primary-border', 'bannerPrimary', 20],
+];
+
+export interface ApplyThemeOptions {
+  loadFont?: (fontStack: string) => void;
+}
+
+function tint(color: string, percentage: number): string {
+  return `color-mix(in srgb, ${color} ${percentage}%, transparent)`;
+}
+
+// ── Apply / Reset ────────────────────────────────────────────
+
+/** Apply a theme preset for the given mode. */
+export function applyThemePreset(
+  preset: ThemePreset,
+  mode: 'light' | 'dark',
+  options: ApplyThemeOptions = {},
+): void {
+  const root = document.documentElement;
+  const colors = mode === 'dark' ? preset.colors.dark : preset.colors.light;
+
+  for (const [key, cssVar] of Object.entries(COLOR_TOKEN_TO_CSS)) {
+    const value = colors[key as keyof ColorTokens];
+    if (value) root.style.setProperty(cssVar, value);
+  }
+
+  for (const [cssVar, baseKey, percentage] of DERIVED_OPACITY_VARS) {
+    const baseColor = colors[baseKey];
+    if (baseColor) root.style.setProperty(cssVar, tint(baseColor, percentage));
+  }
+
+  if (preset.typography?.fontSans) {
+    options.loadFont?.(preset.typography.fontSans);
+    root.style.setProperty('--font-sans', preset.typography.fontSans);
+  }
+  if (preset.typography?.fontMono) {
+    options.loadFont?.(preset.typography.fontMono);
+    root.style.setProperty('--font-mono', preset.typography.fontMono);
+  }
+  if (preset.typography?.fontSizeBase) {
+    root.style.setProperty('--font-size-base', preset.typography.fontSizeBase);
+  }
+
+  if (preset.spacing?.md) {
+    const mdPx = parseFloat(preset.spacing.md);
+    if (Number.isFinite(mdPx) && mdPx > 0) {
+      root.style.setProperty('--spacing', `${(mdPx / 3).toFixed(3)}px`);
+    }
+  }
+
+  if (preset.radius?.md) {
+    root.style.setProperty('--radius', preset.radius.md);
+  }
+
+  root.classList.toggle('dark', mode === 'dark');
+}
+
+/** All CSS custom properties managed by the theme engine. */
+const ALL_MANAGED_VARS = [
+  ...Object.values(COLOR_TOKEN_TO_CSS),
+  ...DERIVED_OPACITY_VARS.map(([v]) => v),
+  '--font-sans',
+  '--font-mono',
+  '--font-size-base',
+  '--spacing',
+  '--radius',
+];
+
+/** Remove all inline theme overrides, reverting to CSS defaults. */
+export function resetTheme(): void {
+  const root = document.documentElement;
+  for (const cssVar of ALL_MANAGED_VARS) {
+    root.style.removeProperty(cssVar);
+  }
+}
+
+// ── Validation ───────────────────────────────────────────────
+
+const LEGACY_REQUIRED_COLOR_KEYS: Array<keyof ColorTokens> = [
+  'bgBase', 'bgSurface', 'bgElevated', 'bgOverlay', 'bgMuted',
+  'borderSubtle', 'borderDefault', 'borderFocus',
+  'textPrimary', 'textSecondary', 'textMuted', 'textInverse',
+  'accentPrimary', 'accentHover', 'accentMuted', 'accentCode',
+  'statusSuccess', 'statusWarning', 'statusError', 'statusInfo',
+  'collabPrimary', 'voiceRecording', 'voiceProcessing', 'bannerPrimary',
+];
+
+/** Validate that a value looks like a CSS colour. */
+function isColorValue(v: unknown): v is string {
+  if (typeof v !== 'string') return false;
+  return /^(#[0-9a-fA-F]{3,8}|rgba?\(|oklch\(|hsla?\(|color-mix\()/.test(v.trim());
+}
+
+function optionalColor(o: Record<string, unknown>, key: keyof ColorTokens): string | undefined {
+  const value = o[key];
+  return isColorValue(value) ? value : undefined;
+}
+
+function normaliseColorTokens(obj: unknown): ColorTokens | null {
+  if (!obj || typeof obj !== 'object') return null;
+  const o = obj as Record<string, unknown>;
+  if (!LEGACY_REQUIRED_COLOR_KEYS.every((k) => isColorValue(o[k]))) return null;
+
+  const legacy = o as Record<keyof ColorTokens, string>;
+  return {
+    ...legacy,
+    brandPrimary: optionalColor(o, 'brandPrimary') ?? legacy.statusSuccess,
+    brandPrimaryHover: optionalColor(o, 'brandPrimaryHover') ?? legacy.statusSuccess,
+    brandPrimaryForeground: optionalColor(o, 'brandPrimaryForeground') ?? legacy.textInverse,
+    brandSecondary: optionalColor(o, 'brandSecondary') ?? legacy.accentCode,
+    brandSecondaryHover: optionalColor(o, 'brandSecondaryHover') ?? legacy.accentHover,
+    brandSecondaryForeground: optionalColor(o, 'brandSecondaryForeground') ?? legacy.textInverse,
+  };
+}
+
+function sanitiseTypography(raw: unknown): ThemePreset['typography'] | undefined {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const o = raw as Record<string, unknown>;
+  const result: Record<string, string> = {};
+  for (const key of ['fontSans', 'fontMono', 'fontSizeBase'] as const) {
+    if (typeof o[key] === 'string') result[key] = o[key];
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function sanitiseSpacing(raw: unknown): ThemePreset['spacing'] | undefined {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const o = raw as Record<string, unknown>;
+  const result: Record<string, string> = {};
+  for (const key of ['xs', 'sm', 'md', 'lg', 'xl'] as const) {
+    if (typeof o[key] === 'string') result[key] = o[key];
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function sanitiseRadius(raw: unknown): ThemePreset['radius'] | undefined {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const o = raw as Record<string, unknown>;
+  const result: Record<string, string> = {};
+  for (const key of ['sm', 'md', 'lg'] as const) {
+    if (typeof o[key] === 'string') result[key] = o[key];
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+/** Validate and normalise an unknown value into a ThemePreset. */
+export function validateThemePreset(data: unknown): ThemePreset | null {
+  if (!data || typeof data !== 'object') return null;
+  const d = data as Record<string, unknown>;
+
+  if (typeof d.id !== 'string' || !d.id) return null;
+  if (typeof d.name !== 'string' || !d.name) return null;
+  if (d.version !== 1) return null;
+
+  const colors = d.colors as Record<string, unknown> | undefined;
+  const light = normaliseColorTokens(colors?.light);
+  const dark = normaliseColorTokens(colors?.dark);
+  if (!light || !dark) return null;
+
+  return {
+    id: d.id,
+    name: d.name,
+    description: typeof d.description === 'string' ? d.description : undefined,
+    author: typeof d.author === 'string' ? d.author : undefined,
+    version: 1,
+    builtin: d.builtin === true,
+    colors: { light, dark },
+    typography: sanitiseTypography(d.typography),
+    spacing: sanitiseSpacing(d.spacing),
+    radius: sanitiseRadius(d.radius),
+  };
+}

package/src/theme/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './apply-theme';