@ramme-io/create-app 2.0.0 → 2.0.1

package/template/src/features/theme/utils/ThemeGenerator.logic.ts

@@ -0,0 +1,587 @@
+/**
+ * ThemeGenerator.logic.ts — The Core Engine for Ramme 2.0 Theme Lab
+ *
+ * HSL-based token generation with:
+ * - Aesthetic Profiles (Cyberpunk, Nordic, Earthy, Corporate, Minimalist, Sunset, Ocean)
+ * - Smart Light→Dark harmony (preserve Chroma, shift Luminance)
+ * - Keyword-to-palette mapper for zero-API "AI" generation
+ */
+
+// ─── HSL TYPES ───────────────────────────────────────────────────────────────
+
+export interface HSL {
+  h: number; // 0-360
+  s: number; // 0-100
+  l: number; // 0-100
+}
+
+export interface ThemePalette {
+  background: HSL;
+  foreground: HSL;
+  primary: HSL;
+  secondary: HSL;
+  accent: HSL;
+  muted: HSL;
+  border: HSL;
+  card: HSL;
+  input: HSL;
+}
+
+export interface FontPair {
+  heading: string;
+  body: string;
+}
+
+export interface GeneratedTheme {
+  name: string;
+  description: string;
+  profileId: string;
+  fonts: FontPair;
+  light: ThemePalette;
+  dark: ThemePalette;
+}
+
+// ─── HSL ↔ RGB CONVERSION ────────────────────────────────────────────────────
+
+export function hslToRgb(h: number, s: number, l: number): [number, number, number] {
+  s /= 100;
+  l /= 100;
+  const k = (n: number) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n: number) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  return [
+    Math.round(f(0) * 255),
+    Math.round(f(8) * 255),
+    Math.round(f(4) * 255),
+  ];
+}
+
+export function hslToRgbString(hsl: HSL): string {
+  const [r, g, b] = hslToRgb(hsl.h, hsl.s, hsl.l);
+  return `${r} ${g} ${b}`;
+}
+
+export function hslToCssString(hsl: HSL): string {
+  return `hsl(${hsl.h}, ${hsl.s}%, ${hsl.l}%)`;
+}
+
+// ─── UTILITY ─────────────────────────────────────────────────────────────────
+
+function clamp(val: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, val));
+}
+
+function rand(min: number, max: number): number {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+// ─── LIGHT → DARK HARMONY ────────────────────────────────────────────────────
+// Maintains Chroma (Saturation) while shifting Luminance for readability
+
+function lightToDark(palette: ThemePalette): ThemePalette {
+  return {
+    background: { h: palette.background.h, s: clamp(palette.background.s + 5, 0, 30), l: clamp(rand(6, 14), 0, 100) },
+    foreground: { h: palette.foreground.h, s: clamp(palette.foreground.s, 0, 15), l: clamp(rand(88, 96), 0, 100) },
+    primary:    { h: palette.primary.h, s: palette.primary.s, l: clamp(palette.primary.l + rand(5, 15), 30, 75) },
+    secondary:  { h: palette.secondary.h, s: palette.secondary.s, l: clamp(palette.secondary.l + rand(5, 10), 30, 70) },
+    accent:     { h: palette.accent.h, s: palette.accent.s, l: clamp(palette.accent.l + rand(5, 15), 35, 75) },
+    muted:      { h: palette.background.h, s: clamp(palette.background.s + 3, 0, 20), l: clamp(rand(14, 22), 0, 100) },
+    border:     { h: palette.background.h, s: clamp(palette.background.s, 0, 20), l: clamp(rand(20, 30), 0, 100) },
+    card:       { h: palette.background.h, s: clamp(palette.background.s + 3, 0, 25), l: clamp(rand(10, 18), 0, 100) },
+    input:      { h: palette.background.h, s: clamp(palette.background.s + 2, 0, 20), l: clamp(rand(12, 20), 0, 100) },
+  };
+}
+
+// ─── AESTHETIC PROFILES ──────────────────────────────────────────────────────
+
+export interface AestheticProfile {
+  id: string;
+  name: string;
+  description: string;
+  fonts: FontPair;
+  generate: () => ThemePalette;
+}
+
+const profileCyberpunk: AestheticProfile = {
+  id: 'cyberpunk',
+  name: 'Cyberpunk',
+  description: 'Neon-soaked digital dystopia with electric accents.',
+  fonts: { heading: 'Orbitron', body: 'Rajdhani' },
+  generate: () => {
+    const hue = rand(270, 320); // magenta-purple range
+    return {
+      background: { h: 260, s: 15, l: 96 },
+      foreground: { h: 260, s: 30, l: 10 },
+      primary:    { h: hue, s: rand(85, 100), l: rand(50, 60) },
+      secondary:  { h: (hue + 120) % 360, s: rand(80, 95), l: rand(50, 60) },
+      accent:     { h: rand(160, 190), s: rand(90, 100), l: rand(45, 55) },
+      muted:      { h: 260, s: 10, l: 92 },
+      border:     { h: 260, s: 12, l: 85 },
+      card:       { h: 260, s: 12, l: 98 },
+      input:      { h: 260, s: 10, l: 97 },
+    };
+  },
+};
+
+const profileNordic: AestheticProfile = {
+  id: 'nordic',
+  name: 'Nordic',
+  description: 'Cool, airy Scandinavian minimalism with subtle blues.',
+  fonts: { heading: 'Sora', body: 'Inter' },
+  generate: () => {
+    const hue = rand(200, 220);
+    return {
+      background: { h: hue, s: 15, l: 97 },
+      foreground: { h: hue, s: 20, l: 15 },
+      primary:    { h: hue, s: rand(45, 65), l: rand(45, 55) },
+      secondary:  { h: (hue + 30) % 360, s: rand(30, 45), l: rand(50, 60) },
+      accent:     { h: rand(340, 360), s: rand(50, 65), l: rand(55, 65) },
+      muted:      { h: hue, s: 10, l: 93 },
+      border:     { h: hue, s: 12, l: 87 },
+      card:       { h: hue, s: 8, l: 99 },
+      input:      { h: hue, s: 8, l: 98 },
+    };
+  },
+};
+
+const profileEarthy: AestheticProfile = {
+  id: 'earthy',
+  name: 'Earthy',
+  description: 'Warm terracotta, forest greens, and natural tones.',
+  fonts: { heading: 'Fraunces', body: 'Outfit' },
+  generate: () => {
+    const hue = rand(20, 40); // warm orange-brown
+    return {
+      background: { h: hue, s: 20, l: 96 },
+      foreground: { h: hue, s: 25, l: 12 },
+      primary:    { h: rand(130, 160), s: rand(35, 55), l: rand(35, 50) },
+      secondary:  { h: hue, s: rand(50, 70), l: rand(45, 55) },
+      accent:     { h: rand(35, 55), s: rand(65, 85), l: rand(50, 60) },
+      muted:      { h: hue, s: 15, l: 92 },
+      border:     { h: hue, s: 18, l: 85 },
+      card:       { h: hue, s: 12, l: 98 },
+      input:      { h: hue, s: 10, l: 97 },
+    };
+  },
+};
+
+const profileCorporate: AestheticProfile = {
+  id: 'corporate',
+  name: 'Corporate High-Tech',
+  description: 'Sleek, professional blues and crisp neutrals.',
+  fonts: { heading: 'Plus Jakarta Sans', body: 'Inter' },
+  generate: () => {
+    const hue = rand(210, 230);
+    return {
+      background: { h: 220, s: 10, l: 97 },
+      foreground: { h: 220, s: 15, l: 12 },
+      primary:    { h: hue, s: rand(70, 90), l: rand(45, 55) },
+      secondary:  { h: (hue + 160) % 360, s: rand(55, 75), l: rand(45, 55) },
+      accent:     { h: rand(40, 60), s: rand(75, 90), l: rand(48, 58) },
+      muted:      { h: 220, s: 8, l: 93 },
+      border:     { h: 220, s: 10, l: 87 },
+      card:       { h: 220, s: 6, l: 99 },
+      input:      { h: 220, s: 6, l: 98 },
+    };
+  },
+};
+
+const profileMinimalist: AestheticProfile = {
+  id: 'minimalist',
+  name: 'Minimalist',
+  description: 'Monochrome elegance with a single accent pop.',
+  fonts: { heading: 'Manrope', body: 'Manrope' },
+  generate: () => {
+    const accentHue = rand(0, 360);
+    return {
+      background: { h: 0, s: 0, l: 98 },
+      foreground: { h: 0, s: 0, l: 8 },
+      primary:    { h: accentHue, s: rand(60, 80), l: rand(48, 58) },
+      secondary:  { h: 0, s: 0, l: rand(40, 50) },
+      accent:     { h: (accentHue + 180) % 360, s: rand(55, 75), l: rand(50, 60) },
+      muted:      { h: 0, s: 0, l: 94 },
+      border:     { h: 0, s: 0, l: 88 },
+      card:       { h: 0, s: 0, l: 100 },
+      input:      { h: 0, s: 0, l: 99 },
+    };
+  },
+};
+
+const profileSunset: AestheticProfile = {
+  id: 'sunset',
+  name: 'Sunset',
+  description: 'Warm gradients from golden amber to dusky rose.',
+  fonts: { heading: 'Playfair Display', body: 'Lora' },
+  generate: () => {
+    const hue = rand(15, 35);
+    return {
+      background: { h: hue, s: 25, l: 97 },
+      foreground: { h: hue, s: 20, l: 10 },
+      primary:    { h: rand(340, 360), s: rand(65, 85), l: rand(50, 60) },
+      secondary:  { h: rand(25, 45), s: rand(75, 90), l: rand(50, 60) },
+      accent:     { h: rand(275, 310), s: rand(55, 75), l: rand(55, 65) },
+      muted:      { h: hue, s: 18, l: 93 },
+      border:     { h: hue, s: 15, l: 87 },
+      card:       { h: hue, s: 15, l: 99 },
+      input:      { h: hue, s: 12, l: 98 },
+    };
+  },
+};
+
+const profileOcean: AestheticProfile = {
+  id: 'ocean',
+  name: 'Ocean Depth',
+  description: 'Deep teals, coral highlights, and aquatic mystery.',
+  fonts: { heading: 'Space Grotesk', body: 'Outfit' },
+  generate: () => {
+    const hue = rand(175, 200);
+    return {
+      background: { h: hue, s: 18, l: 96 },
+      foreground: { h: hue, s: 25, l: 10 },
+      primary:    { h: hue, s: rand(60, 80), l: rand(40, 50) },
+      secondary:  { h: rand(10, 30), s: rand(65, 85), l: rand(55, 65) },
+      accent:     { h: rand(45, 65), s: rand(70, 90), l: rand(50, 60) },
+      muted:      { h: hue, s: 12, l: 92 },
+      border:     { h: hue, s: 14, l: 85 },
+      card:       { h: hue, s: 10, l: 98 },
+      input:      { h: hue, s: 8, l: 97 },
+    };
+  },
+};
+
+export const AESTHETIC_PROFILES: AestheticProfile[] = [
+  profileCyberpunk,
+  profileNordic,
+  profileEarthy,
+  profileCorporate,
+  profileMinimalist,
+  profileSunset,
+  profileOcean,
+];
+
+// ─── DESCRIPTIVE PALETTE SYNTHESIZER ─────────────────────────────────────────
+// Generates truly custom palettes from arbitrary text descriptions by analyzing
+// mood, temperature, intensity, color words, and theme of the prompt.
+
+const COLOR_HINTS: Record<string, { h: number; s: number }> = {
+  red: { h: 0, s: 80 }, crimson: { h: 348, s: 85 }, scarlet: { h: 10, s: 85 },
+  orange: { h: 30, s: 85 }, amber: { h: 45, s: 90 }, gold: { h: 50, s: 85 },
+  yellow: { h: 55, s: 80 }, lime: { h: 90, s: 75 },
+  green: { h: 140, s: 60 }, emerald: { h: 155, s: 70 }, sage: { h: 140, s: 30 },
+  olive: { h: 80, s: 40 }, mint: { h: 160, s: 55 }, forest: { h: 145, s: 50 },
+  teal: { h: 175, s: 65 }, cyan: { h: 185, s: 75 }, turquoise: { h: 170, s: 60 },
+  blue: { h: 220, s: 75 }, navy: { h: 230, s: 60 }, cobalt: { h: 215, s: 80 },
+  sky: { h: 200, s: 70 }, azure: { h: 210, s: 75 }, steel: { h: 210, s: 25 },
+  indigo: { h: 260, s: 70 }, violet: { h: 270, s: 70 },
+  purple: { h: 280, s: 70 }, magenta: { h: 300, s: 80 }, fuchsia: { h: 310, s: 85 },
+  pink: { h: 335, s: 70 }, rose: { h: 345, s: 75 }, blush: { h: 350, s: 50 },
+  lavender: { h: 270, s: 50 }, mauve: { h: 290, s: 30 }, lilac: { h: 280, s: 45 },
+  coral: { h: 16, s: 80 }, peach: { h: 25, s: 60 }, salmon: { h: 10, s: 65 },
+  brown: { h: 30, s: 50 }, chocolate: { h: 25, s: 60 }, coffee: { h: 30, s: 40 },
+  tan: { h: 35, s: 40 }, sand: { h: 40, s: 45 }, cream: { h: 45, s: 35 },
+  rust: { h: 15, s: 70 }, terracotta: { h: 18, s: 60 }, copper: { h: 22, s: 65 },
+  slate: { h: 215, s: 20 }, charcoal: { h: 0, s: 5 }, graphite: { h: 0, s: 8 },
+  ivory: { h: 50, s: 20 }, bone: { h: 40, s: 15 }, pearl: { h: 0, s: 10 },
+  wine: { h: 340, s: 60 }, burgundy: { h: 345, s: 55 }, maroon: { h: 350, s: 50 },
+  plum: { h: 300, s: 40 }, berry: { h: 320, s: 65 },
+  moss: { h: 100, s: 35 }, fern: { h: 120, s: 40 }, jungle: { h: 130, s: 55 },
+  midnight: { h: 235, s: 50 }, dusk: { h: 260, s: 35 }, twilight: { h: 250, s: 40 },
+  sunrise: { h: 30, s: 80 }, sunset: { h: 15, s: 75 }, dawn: { h: 35, s: 60 },
+  neon: { h: 130, s: 95 }, electric: { h: 195, s: 95 }, fluorescent: { h: 100, s: 90 },
+};
+
+// Mood modifiers extracted from prompts
+interface MoodSignals {
+  temperature: number;   // -1 (cool) to +1 (warm)
+  brightness: number;    // -1 (dark) to +1 (bright)
+  saturation: number;    // -1 (muted) to +1 (vibrant)
+  formality: number;     // -1 (playful) to +1 (formal)
+  energy: number;        // -1 (calm) to +1 (energetic)
+}
+
+const MOOD_WORDS: Record<string, Partial<MoodSignals>> = {
+  // Temperature
+  warm: { temperature: 0.8 }, hot: { temperature: 1 }, cozy: { temperature: 0.6 },
+  cool: { temperature: -0.7 }, cold: { temperature: -1 }, icy: { temperature: -1 },
+  // Brightness
+  bright: { brightness: 0.8 }, light: { brightness: 0.6 }, airy: { brightness: 0.7 },
+  luminous: { brightness: 0.9 }, glowing: { brightness: 0.7 },
+  dark: { brightness: -0.8 }, deep: { brightness: -0.5 }, moody: { brightness: -0.7 },
+  shadow: { brightness: -0.6 }, noir: { brightness: -0.9 }, night: { brightness: -0.8 },
+  // Saturation
+  vibrant: { saturation: 0.9 }, bold: { saturation: 0.7 }, vivid: { saturation: 0.9 },
+  rich: { saturation: 0.6 }, intense: { saturation: 0.8 }, loud: { saturation: 0.9 },
+  muted: { saturation: -0.7 }, soft: { saturation: -0.5 }, pastel: { saturation: -0.6 },
+  subtle: { saturation: -0.5 }, faded: { saturation: -0.7 }, dusty: { saturation: -0.6 },
+  gentle: { saturation: -0.4 }, whisper: { saturation: -0.8 },
+  // Formality
+  elegant: { formality: 0.7 }, luxe: { formality: 0.8 }, luxury: { formality: 0.8 },
+  premium: { formality: 0.6 }, sophisticated: { formality: 0.8 }, refined: { formality: 0.7 },
+  professional: { formality: 0.9 }, corporate: { formality: 1 }, business: { formality: 0.8 },
+  playful: { formality: -0.7 }, fun: { formality: -0.6 }, whimsical: { formality: -0.8 },
+  casual: { formality: -0.4 }, friendly: { formality: -0.3 }, quirky: { formality: -0.7 },
+  // Energy
+  energetic: { energy: 0.8 }, dynamic: { energy: 0.7 }, electric: { energy: 0.9 },
+  punchy: { energy: 0.8 }, exciting: { energy: 0.7 }, fiery: { energy: 0.9 },
+  calm: { energy: -0.7 }, serene: { energy: -0.8 }, zen: { energy: -0.9 },
+  peaceful: { energy: -0.7 }, tranquil: { energy: -0.8 }, relaxed: { energy: -0.5 },
+  quiet: { energy: -0.6 }, still: { energy: -0.7 }, minimal: { energy: -0.4 },
+};
+
+// Font pairings by mood
+const FONT_SETS: { condition: (m: MoodSignals) => boolean; fonts: FontPair }[] = [
+  { condition: m => m.energy > 0.5 && m.saturation > 0.3, fonts: { heading: 'Orbitron', body: 'Rajdhani' } },
+  { condition: m => m.formality > 0.5, fonts: { heading: 'Plus Jakarta Sans', body: 'Inter' } },
+  { condition: m => m.formality > 0.3 && m.temperature > 0, fonts: { heading: 'Playfair Display', body: 'Source Sans 3' } },
+  { condition: m => m.energy < -0.3 && m.saturation < 0, fonts: { heading: 'Sora', body: 'Inter' } },
+  { condition: m => m.temperature > 0.3, fonts: { heading: 'Fraunces', body: 'Outfit' } },
+  { condition: m => m.temperature < -0.3, fonts: { heading: 'Space Grotesk', body: 'Outfit' } },
+  { condition: m => m.saturation < -0.3, fonts: { heading: 'Manrope', body: 'Manrope' } },
+  { condition: m => m.energy > 0.3, fonts: { heading: 'Archivo Black', body: 'DM Sans' } },
+  { condition: m => m.brightness > 0.3, fonts: { heading: 'Sora', body: 'Nunito' } },
+  { condition: m => m.brightness < -0.3, fonts: { heading: 'Space Grotesk', body: 'JetBrains Mono' } },
+];
+
+const DEFAULT_FONTS: FontPair = { heading: 'DM Sans', body: 'Inter' };
+
+function analyzeMood(prompt: string): MoodSignals {
+  const lower = prompt.toLowerCase();
+  const signals: MoodSignals = { temperature: 0, brightness: 0, saturation: 0, formality: 0, energy: 0 };
+  let matches = 0;
+
+  for (const [word, mods] of Object.entries(MOOD_WORDS)) {
+    if (lower.includes(word)) {
+      for (const [key, val] of Object.entries(mods)) {
+        (signals as any)[key] += val;
+      }
+      matches++;
+    }
+  }
+
+  // Normalize to -1..1 range if many matches
+  if (matches > 1) {
+    for (const key of Object.keys(signals) as (keyof MoodSignals)[]) {
+      signals[key] = clamp(signals[key] / Math.sqrt(matches), -1, 1);
+    }
+  }
+
+  return signals;
+}
+
+function extractColors(prompt: string): { h: number; s: number }[] {
+  const lower = prompt.toLowerCase();
+  const found: { h: number; s: number }[] = [];
+  const seen = new Set<number>();
+
+  for (const [word, hint] of Object.entries(COLOR_HINTS)) {
+    if (lower.includes(word) && !seen.has(hint.h)) {
+      found.push(hint);
+      seen.add(hint.h);
+    }
+  }
+  return found;
+}
+
+function pickFonts(mood: MoodSignals): FontPair {
+  for (const set of FONT_SETS) {
+    if (set.condition(mood)) return set.fonts;
+  }
+  return DEFAULT_FONTS;
+}
+
+function synthesizePalette(colors: { h: number; s: number }[], mood: MoodSignals): ThemePalette {
+  // Determine base hue — use first color hint, or derive from temperature
+  let primaryHue: number;
+  let primarySat: number;
+
+  if (colors.length > 0) {
+    primaryHue = colors[0].h;
+    primarySat = colors[0].s;
+  } else {
+    // Derive hue from temperature: warm = reds/oranges, cool = blues/teals
+    primaryHue = mood.temperature > 0
+      ? rand(0, 40) + Math.round(mood.temperature * 20)
+      : rand(180, 260) + Math.round(mood.temperature * 20);
+    primarySat = 65 + Math.round(mood.saturation * 20);
+  }
+
+  // Second color for secondary — use second hint or calculate harmony
+  let secondaryHue: number;
+  let secondarySat: number;
+  if (colors.length > 1) {
+    secondaryHue = colors[1].h;
+    secondarySat = colors[1].s;
+  } else {
+    // Analogous harmony for formal, triadic for playful
+    const offset = mood.formality > 0 ? rand(25, 45) : rand(100, 140);
+    secondaryHue = (primaryHue + offset) % 360;
+    secondarySat = clamp(primarySat - 10 + rand(-5, 5), 30, 90);
+  }
+
+  // Accent — use third hint or complementary
+  let accentHue: number;
+  let accentSat: number;
+  if (colors.length > 2) {
+    accentHue = colors[2].h;
+    accentSat = colors[2].s;
+  } else {
+    accentHue = (primaryHue + 150 + rand(-20, 20)) % 360;
+    accentSat = clamp(primarySat + 10 + rand(-5, 5), 40, 95);
+  }
+
+  // Apply mood modifiers to saturation
+  const satMod = Math.round(mood.saturation * 15);
+  primarySat = clamp(primarySat + satMod, 25, 100);
+  secondarySat = clamp(secondarySat + satMod, 20, 95);
+  accentSat = clamp(accentSat + satMod, 25, 100);
+
+  // Lightness — brightness affects primary lightness
+  const basePrimaryL = 52 + Math.round(mood.brightness * 8);
+  const baseSecondaryL = 50 + Math.round(mood.brightness * 6);
+  const baseAccentL = 54 + Math.round(mood.brightness * 6);
+
+  // Background hue tint — slightly tinted toward primary
+  const bgHue = primaryHue;
+  const bgSat = clamp(5 + Math.round(Math.abs(mood.saturation) * 10), 0, 25);
+  const bgL = mood.brightness > 0 ? rand(97, 99) : rand(94, 97);
+
+  return {
+    background: { h: bgHue, s: bgSat, l: bgL },
+    foreground: { h: bgHue, s: clamp(bgSat + 10, 0, 25), l: rand(8, 15) },
+    primary:    { h: primaryHue, s: primarySat, l: clamp(basePrimaryL + rand(-3, 3), 35, 65) },
+    secondary:  { h: secondaryHue, s: secondarySat, l: clamp(baseSecondaryL + rand(-3, 3), 35, 65) },
+    accent:     { h: accentHue, s: accentSat, l: clamp(baseAccentL + rand(-3, 3), 40, 68) },
+    muted:      { h: bgHue, s: clamp(bgSat + 3, 0, 15), l: rand(91, 94) },
+    border:     { h: bgHue, s: clamp(bgSat + 2, 0, 18), l: rand(84, 88) },
+    card:       { h: bgHue, s: clamp(bgSat - 2, 0, 12), l: rand(98, 100) },
+    input:      { h: bgHue, s: clamp(bgSat - 3, 0, 10), l: rand(97, 99) },
+  };
+}
+
+// ─── PUBLIC API ──────────────────────────────────────────────────────────────
+
+/**
+ * Derive a deterministic seed hue (0-360) from any string so that
+ * even unrecognized prompts produce a unique, repeatable palette.
+ */
+function hashToHue(str: string): number {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = str.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  return ((hash % 360) + 360) % 360;
+}
+
+/**
+ * Generate a full custom theme from any text description.
+ * Always builds from scratch — never falls back to a preset profile.
+ * Analyzes mood keywords and color words to shape the palette, and
+ * uses a hash of the prompt to seed hue values for unrecognized text.
+ * No API key required — runs entirely client-side.
+ */
+export function generateFromPrompt(prompt: string): GeneratedTheme {
+  const mood = analyzeMood(prompt);
+  const colors = extractColors(prompt);
+
+  // If no color words were detected, seed from the prompt text itself
+  // so every unique description produces a unique base hue
+  if (colors.length === 0) {
+    const seedHue = hashToHue(prompt);
+    colors.push({ h: seedHue, s: 65 + rand(-10, 10) });
+  }
+
+  const light = synthesizePalette(colors, mood);
+  const dark = lightToDark(light);
+  const fonts = pickFonts(mood);
+
+  // Build a descriptive name
+  const detectedColors = extractColors(prompt); // re-extract without seed
+  const colorNames = detectedColors.length > 0
+    ? Object.entries(COLOR_HINTS)
+        .filter(([, hint]) => detectedColors.some(c => c.h === hint.h))
+        .map(([name]) => name.charAt(0).toUpperCase() + name.slice(1))
+        .slice(0, 3)
+        .join(' + ')
+    : null;
+
+  const moodLabel = mood.temperature > 0.3 ? 'Warm' : mood.temperature < -0.3 ? 'Cool' : '';
+  const intensityLabel = mood.saturation > 0.3 ? 'Vibrant' : mood.saturation < -0.3 ? 'Soft' : '';
+  const namePrefix = [moodLabel, intensityLabel].filter(Boolean).join(' ');
+  const nameSuffix = colorNames || prompt.slice(0, 30);
+  const themeName = namePrefix ? `${namePrefix} ${nameSuffix}` : nameSuffix;
+
+  return {
+    name: themeName || 'Custom Theme',
+    description: `Custom palette generated from: "${prompt}"`,
+    profileId: 'custom',
+    fonts,
+    light,
+    dark,
+  };
+}
+
+/**
+ * Generate from a specific Aesthetic Profile ID.
+ */
+export function generateFromProfile(profileId: string): GeneratedTheme {
+  const profile = AESTHETIC_PROFILES.find(p => p.id === profileId) || AESTHETIC_PROFILES[0];
+  const light = profile.generate();
+  const dark = lightToDark(light);
+
+  return {
+    name: profile.name,
+    description: profile.description,
+    profileId: profile.id,
+    fonts: profile.fonts,
+    light,
+    dark,
+  };
+}
+
+/**
+ * Shuffle: pick a random Aesthetic Profile and generate.
+ */
+export function generateRandom(): GeneratedTheme {
+  const profile = AESTHETIC_PROFILES[rand(0, AESTHETIC_PROFILES.length - 1)];
+  const light = profile.generate();
+  const dark = lightToDark(light);
+
+  return {
+    name: profile.name,
+    description: profile.description,
+    profileId: profile.id,
+    fonts: profile.fonts,
+    light,
+    dark,
+  };
+}
+
+/**
+ * Convert a ThemePalette to the --app-* CSS variable Record that applyThemeToDom expects.
+ */
+export function paletteToRgbVars(palette: ThemePalette): Record<string, string> {
+  const primaryFg = palette.primary.l > 55 ? '15 23 42' : '255 255 255';
+  const secondaryFg = palette.secondary.l > 55 ? '15 23 42' : '255 255 255';
+  const accentFg = palette.accent.l > 55 ? '15 23 42' : '255 255 255';
+
+  const primary = hslToRgbString(palette.primary);
+
+  return {
+    '--app-primary-color': primary,
+    '--app-primary-foreground-color': primaryFg,
+    '--app-secondary-color': hslToRgbString(palette.secondary),
+    '--app-secondary-foreground-color': secondaryFg,
+    '--app-accent-color': hslToRgbString(palette.accent),
+    '--app-accent-foreground-color': accentFg,
+    '--app-bg-color': hslToRgbString(palette.background),
+    '--app-card-bg-color': hslToRgbString(palette.card),
+    '--app-text-color': hslToRgbString(palette.foreground),
+    '--app-border-color': hslToRgbString(palette.border),
+    '--app-muted-bg': hslToRgbString(palette.muted),
+    '--app-muted-text': hslToRgbString({ ...palette.foreground, l: palette.foreground.l > 50 ? palette.foreground.l - 25 : palette.foreground.l + 25 }),
+    '--app-input-bg-color': hslToRgbString(palette.input),
+    '--app-input-border-color': hslToRgbString(palette.border),
+    '--app-chart-1': primary,
+    '--app-chart-grid-color': hslToRgbString(palette.border),
+  };
+}

package/template/src/hooks/__tests__/useStudioHotkeys.test.ts

@@ -0,0 +1,100 @@
+import { renderHook, act } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock useAppConfig
+const mockSetEnableCRT = vi.fn();
+let mockEnableCRT = false;
+
+vi.mock('../../features/config/AppConfigContext', () => ({
+  useAppConfig: () => ({
+    enableCRT: mockEnableCRT,
+    setEnableCRT: mockSetEnableCRT,
+  }),
+}));
+
+// Import after mock setup
+import { useStudioHotkeys } from '../useStudioHotkeys';
+
+describe('useStudioHotkeys', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockEnableCRT = false;
+    document.body.classList.remove('studio-flash');
+  });
+
+  it('toggles CRT when Ctrl+Shift+C is pressed', () => {
+    renderHook(() => useStudioHotkeys());
+
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'C', ctrlKey: true, shiftKey: true, bubbles: true,
+      }));
+    });
+
+    expect(mockSetEnableCRT).toHaveBeenCalledWith(true);
+  });
+
+  it('does not toggle when only Ctrl+C is pressed (missing Shift)', () => {
+    renderHook(() => useStudioHotkeys());
+
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'C', ctrlKey: true, shiftKey: false, bubbles: true,
+      }));
+    });
+
+    expect(mockSetEnableCRT).not.toHaveBeenCalled();
+  });
+
+  it('does not toggle when target is an input element', () => {
+    renderHook(() => useStudioHotkeys());
+    const input = document.createElement('input');
+    document.body.appendChild(input);
+
+    act(() => {
+      input.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'C', ctrlKey: true, shiftKey: true, bubbles: true,
+      }));
+    });
+
+    expect(mockSetEnableCRT).not.toHaveBeenCalled();
+    document.body.removeChild(input);
+  });
+
+  it('does not toggle when target is a textarea', () => {
+    renderHook(() => useStudioHotkeys());
+    const textarea = document.createElement('textarea');
+    document.body.appendChild(textarea);
+
+    act(() => {
+      textarea.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'C', ctrlKey: true, shiftKey: true, bubbles: true,
+      }));
+    });
+
+    expect(mockSetEnableCRT).not.toHaveBeenCalled();
+    document.body.removeChild(textarea);
+  });
+
+  it('adds studio-flash class to body on toggle', () => {
+    renderHook(() => useStudioHotkeys());
+
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'C', ctrlKey: true, shiftKey: true, bubbles: true,
+      }));
+    });
+
+    expect(document.body.classList.contains('studio-flash')).toBe(true);
+  });
+
+  it('cleans up event listener on unmount', () => {
+    const spy = vi.spyOn(window, 'removeEventListener');
+    const { unmount } = renderHook(() => useStudioHotkeys());
+
+    unmount();
+
+    expect(spy).toHaveBeenCalledWith('keydown', expect.any(Function));
+    spy.mockRestore();
+  });
+});