@appinternalleads/ui 0.4.0 → 0.4.1

package/src/motion/neon/config.ts

@@ -0,0 +1,484 @@
+/* eslint-disable comppack/no-raw-colour -- neon colours are sign content (the brief's presets), not theme colours. */
+/**
+ * **The neon sign's configuration** — one plain JSON object that says everything about a sign. The
+ * four concerns never reach into each other:
+ *
+ *   text        what the sign says ("CAFE", "OPEN\n24/7", anything)
+ *   typography  how the letters are shaped: font, size, weight, spacing, tube width, construction
+ *   neon        the material: tube, core, glow and bloom colours, intensity, radii, shadow
+ *   animation   flicker and glitch: on/off, intensity, frequency, speed, seed
+ *
+ * So CAFE → OPEN → 24/7 changes `text` only, and RED → BLUE changes `neon` only. Units: `fontSize`,
+ * widths and radii are SVG user units (px at scale 1); times are ms; frequencies are events per
+ * second. Measured defaults come from the Vecteezy 7356951 reference (`docs/NEON-TEXT.md`).
+ */
+
+export const NEON_CONSTRUCTIONS = ['outline', 'monoline'] as const;
+/**
+ * How the tube follows the letter.
+ * - `outline`: one tube traces each glyph's outline (the reference's CAFE). Any font works.
+ * - `monoline`: the glyph is the tube: filled and stroked with round joins (the reference's 24/7).
+ *   Light, rounded fonts read best; the glyph's own stem is the hot core.
+ */
+export type NeonConstruction = (typeof NEON_CONSTRUCTIONS)[number];
+export const NEON_ALIGNS = ['start', 'middle', 'end'] as const;
+export type NeonAlign = (typeof NEON_ALIGNS)[number];
+
+export type NeonTypography = {
+  /** Any CSS font-family list. The font must be loaded by the page; nothing is converted to paths. */
+  fontFamily: string;
+  fontSize: number;
+  fontWeight: number;
+  fontStyle: 'normal' | 'italic';
+  /** Extra space between letters, in user units. */
+  letterSpacing: number;
+  /** Line pitch as a multiple of fontSize, for multi-line text ("OPEN\n24/7"). */
+  lineHeight: number;
+  /** The glass tube's width, in user units. The reference's outline tube is ≈ 0.033 × fontSize. */
+  strokeWidth: number;
+  construction: NeonConstruction;
+  align: NeonAlign;
+};
+
+export type NeonShadow = {
+  enabled: boolean;
+  color: string;
+  opacity: number;
+  /** Offset as a fraction of fontSize; the reference casts its shadow down and to the right. */
+  offsetX: number;
+  offsetY: number;
+  /** Blur radius, in user units. */
+  blur: number;
+};
+
+export type NeonMaterialConfig = {
+  /** The primary neon colour. Every colour below that is null is derived from it. */
+  color: string;
+  /** The hot centre line. null → nearly white, tinted by `color`. */
+  coreColor: string | null;
+  /** The lit glass. null → `color`. */
+  tubeColor: string | null;
+  /** The tight coloured halo. null → a deeper, more saturated `color`. */
+  glowColor: string | null;
+  /** The wide light thrown on the wall. null → a dark, saturated `color`. */
+  bloomColor: string | null;
+  /** Glow and bloom strength: 0 is a bare tube, 1 the reference, up to 3. */
+  intensity: number;
+  /** The bloom's own strength, on top of `intensity` (1 = as the reference). */
+  bloomIntensity: number;
+  /** How bright the lit tube is (1 = full; lower shows more dark glass). */
+  tubeBrightness: number;
+  /** How bright the hot core is (1 = full; 0 hides it). */
+  coreBrightness: number;
+  /** How far the tight glow reaches, in user units. */
+  glowRadius: number;
+  /** How far the wall bloom reaches, in user units. */
+  bloomRadius: number;
+  /** The hot core's width as a fraction of the tube (outline construction). Reference: 0.47. */
+  coreWidth: number;
+  /** How visible the unlit glass is when the tube dims (0 hides it). */
+  glassOpacity: number;
+  shadow: NeonShadow;
+};
+
+export type NeonAnimationConfig = {
+  enabled: boolean;
+  /** Plays everything faster (2) or slower (0.5). */
+  speed: number;
+  /** Same seed, same performance. Change it to get a different, equally natural one. */
+  seed: number;
+  flickerEnabled: boolean;
+  /** 0 is a steady tube; 0.25 plays the full hardware ranges (dips to 40–80 %, failures to 20–50 %); 1 is a failing transformer. */
+  flickerIntensity: number;
+  /** Noticeable flicker events (sags, dips, failures) per second. 0.08 ≈ one every 12 s. */
+  flickerFrequency: number;
+  /** How fast each flicker event plays, on top of `speed`. */
+  flickerSpeed: number;
+  /** 0: every event plays its typical shape and depth, evenly; 1: depths, lengths and the hum vary widely. */
+  flickerRandomness: number;
+  /** How fast the tube recovers after a dip or failure: 0 slow (≈ 300 ms tail), 1 instant. */
+  flickerRecovery: number;
+  /** The floor: the tube never falls below this brightness (0…1). */
+  flickerMinBrightness: number;
+  glitchEnabled: boolean;
+  /** 0 is none; 1 is the most a readable sign should glitch. */
+  glitchIntensity: number;
+  /** Glitches per second. 0.04 ≈ one every 25 s. */
+  glitchFrequency: number;
+  /** A glitch's typical length, in ms. */
+  glitchDuration: number;
+  /** Scales the whole-sign sideways jump (0 none, 1 default, 2 double). */
+  glitchDisplacement: number;
+  /** Scales the red/cyan split. */
+  glitchRgbSplit: number;
+  /** Scales the sliced bands' shift. */
+  glitchSlices: number;
+  /** Scales how far the glow slips from the tube. */
+  glitchGlowSeparation: number;
+};
+
+export type NeonTextConfig = {
+  text: string;
+  typography: NeonTypography;
+  neon: NeonMaterialConfig;
+  animation: NeonAnimationConfig;
+  /** A colour behind the sign, or null for transparent. */
+  background: string | null;
+};
+
+export type DeepPartial<T> = { [K in keyof T]?: T[K] extends object ? (T[K] extends unknown[] ? T[K] : DeepPartial<T[K]> | null) : T[K] };
+export type NeonTextConfigInput = DeepPartial<NeonTextConfig>;
+
+export const DEFAULT_NEON_CONFIG: NeonTextConfig = {
+  text: 'CAFE',
+  typography: {
+    fontFamily: "Oswald, 'Arial Narrow', 'Helvetica Neue', Arial, sans-serif",
+    fontSize: 220,
+    fontWeight: 500,
+    fontStyle: 'normal',
+    letterSpacing: 4,
+    lineHeight: 1.15,
+    strokeWidth: 8,
+    construction: 'outline',
+    align: 'middle',
+  },
+  neon: {
+    color: '#FF4655',
+    coreColor: '#FFF5F5',
+    tubeColor: '#FF4655',
+    glowColor: '#FF1838',
+    bloomColor: '#D4002F',
+    intensity: 1,
+    bloomIntensity: 1,
+    tubeBrightness: 1,
+    coreBrightness: 1,
+    glowRadius: 20,
+    bloomRadius: 70,
+    coreWidth: 0.47,
+    glassOpacity: 0.16,
+    shadow: { enabled: true, color: '#000000', opacity: 0.5, offsetX: 0.035, offsetY: 0.045, blur: 6 },
+  },
+  animation: {
+    enabled: true,
+    speed: 1,
+    seed: 7356951,
+    flickerEnabled: true,
+    flickerIntensity: 0.15,
+    flickerFrequency: 0.08,
+    flickerSpeed: 1,
+    flickerRandomness: 0.6,
+    flickerRecovery: 0.7,
+    flickerMinBrightness: 0.05,
+    glitchEnabled: true,
+    glitchIntensity: 0.15,
+    glitchFrequency: 0.04,
+    glitchDuration: 180,
+    glitchDisplacement: 1,
+    glitchRgbSplit: 1,
+    glitchSlices: 1,
+    glitchGlowSeparation: 1,
+  },
+  background: null,
+};
+
+/** The four neon colours of each preset, from the brief. `color` is the tube. */
+export type NeonColorPreset = Pick<NeonMaterialConfig, 'color'> & { coreColor: string; tubeColor: string; glowColor: string; bloomColor: string };
+export const NEON_COLOR_PRESETS = {
+  red: { color: '#FF3B4D', coreColor: '#FFF5F5', tubeColor: '#FF3B4D', glowColor: '#FF1744', bloomColor: '#C40030' },
+  blue: { color: '#00D9FF', coreColor: '#F5FFFF', tubeColor: '#00D9FF', glowColor: '#009DFF', bloomColor: '#0055FF' },
+  purple: { color: '#D66BFF', coreColor: '#FFF5FF', tubeColor: '#D66BFF', glowColor: '#9C27FF', bloomColor: '#5E00B8' },
+  green: { color: '#39FF88', coreColor: '#F5FFF5', tubeColor: '#39FF88', glowColor: '#00D95F', bloomColor: '#008F3D' },
+} satisfies Record<string, NeonColorPreset>;
+export type NeonColorPresetId = keyof typeof NEON_COLOR_PRESETS;
+
+/** Text presets: the words, and the letterform that suits them. Material and animation are untouched. */
+export const NEON_TEXT_PRESETS = {
+  cafe: { text: 'CAFE', typography: { construction: 'outline', fontFamily: DEFAULT_NEON_CONFIG.typography.fontFamily, fontWeight: 500, strokeWidth: 8, letterSpacing: 4 } },
+  open: { text: 'OPEN', typography: { construction: 'outline', fontFamily: DEFAULT_NEON_CONFIG.typography.fontFamily, fontWeight: 500, strokeWidth: 8, letterSpacing: 10 } },
+  night: { text: 'NIGHT', typography: { construction: 'outline', fontFamily: DEFAULT_NEON_CONFIG.typography.fontFamily, fontWeight: 500, strokeWidth: 8, letterSpacing: 6 } },
+  '24/7': { text: '24/7', typography: { construction: 'monoline', fontFamily: "Quicksand, 'Arial Rounded MT Bold', 'Helvetica Neue', Arial, sans-serif", fontWeight: 500, strokeWidth: 10, letterSpacing: 2 } },
+  hello: { text: 'Hello', typography: { construction: 'monoline', fontFamily: "Sacramento, 'Snell Roundhand', 'Brush Script MT', cursive", fontWeight: 400, strokeWidth: 7, letterSpacing: 0 } },
+} satisfies Record<string, NeonTextConfigInput>;
+export type NeonTextPresetId = keyof typeof NEON_TEXT_PRESETS;
+
+/* ---------- colour helpers (pure) ---------- */
+
+const HEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+export const isHexColor = (v: unknown): v is string => typeof v === 'string' && HEX.test(v);
+export function hexToRgb(hex: string): [number, number, number] {
+  const h = hex.length === 4 ? hex.slice(1).split('').map((c) => c + c).join('') : hex.slice(1);
+  return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+}
+export const rgbToHex = (rgb: readonly number[]) => '#' + rgb.map((v) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, '0')).join('').toUpperCase();
+export function mixHex(a: string, b: string, t: number): string {
+  const x = hexToRgb(a);
+  const y = hexToRgb(b);
+  return rgbToHex(x.map((v, i) => v + (y[i]! - v) * t));
+}
+function toHsl([r, g, b]: [number, number, number]): [number, number, number] {
+  const [R, G, B] = [r / 255, g / 255, b / 255];
+  const max = Math.max(R, G, B);
+  const min = Math.min(R, G, B);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  const h = max === R ? (G - B) / d + (G < B ? 6 : 0) : max === G ? (B - R) / d + 2 : (R - G) / d + 4;
+  return [h * 60, s, l];
+}
+function fromHsl(h: number, s: number, l: number): string {
+  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 rgbToHex([f(0) * 255, f(8) * 255, f(4) * 255]);
+}
+
+/**
+ * **One colour in, a whole neon palette out.** Fitted to the brief's four presets: the glow is the
+ * same hue a little deeper and fully saturated; the bloom is darker still and drifts a few degrees
+ * toward blue (a lit wall reads cooler than the tube); the core is the colour at 6 % over white.
+ */
+export function deriveNeonPalette(color: string): { coreColor: string; tubeColor: string; glowColor: string; bloomColor: string } {
+  const base = isHexColor(color) ? color : DEFAULT_NEON_CONFIG.neon.color;
+  const [h, s, l] = toHsl(hexToRgb(base));
+  const drift = (deg: number) => (s < 0.08 ? h : (h + deg + 360) % 360);
+  return {
+    coreColor: mixHex(base, '#FFFFFF', 0.94),
+    tubeColor: rgbToHex(hexToRgb(base)),
+    glowColor: fromHsl(drift(-6), Math.min(1, s + 0.15), Math.max(0.3, l * 0.84)),
+    bloomColor: fromHsl(drift(-10), Math.min(1, s + 0.2), Math.max(0.18, l * 0.6)),
+  };
+}
+
+/* ---------- resolving ---------- */
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+function merge<T>(base: T, over: unknown): T {
+  if (!isObj(base) || !isObj(over)) return (over === undefined ? base : over) as T;
+  const out: Record<string, unknown> = { ...base };
+  for (const [k, v] of Object.entries(over)) {
+    if (v === undefined) continue;
+    out[k] = isObj(out[k]) && isObj(v) ? merge(out[k], v) : v;
+  }
+  return out as T;
+}
+
+/**
+ * **The flat props an agent or a JSX author reaches for**, mapped onto the config. Every one is
+ * optional; each wins over the same value in `config`.
+ */
+export type NeonTextShorthand = {
+  text?: string;
+  fontFamily?: string;
+  fontSize?: number;
+  fontWeight?: number;
+  fontStyle?: 'normal' | 'italic';
+  letterSpacing?: number;
+  lineHeight?: number;
+  strokeWidth?: number;
+  construction?: NeonConstruction;
+  align?: NeonAlign;
+  /** The primary colour: glow, bloom and core follow it unless set themselves. */
+  neonColor?: string;
+  tubeColor?: string;
+  coreColor?: string;
+  glowColor?: string;
+  bloomColor?: string;
+  glowIntensity?: number;
+  glowRadius?: number;
+  bloomRadius?: number;
+  shadow?: boolean;
+  /** Animation on/off (flicker and glitch together). */
+  animated?: boolean;
+  animationSpeed?: number;
+  seed?: number;
+  flicker?: boolean;
+  flickerIntensity?: number;
+  flickerFrequency?: number;
+  flickerSpeed?: number;
+  glitch?: boolean;
+  glitchIntensity?: number;
+  glitchFrequency?: number;
+  glitchDuration?: number;
+  background?: string | null;
+};
+export const NEON_SHORTHAND_KEYS = [
+  'text', 'fontFamily', 'fontSize', 'fontWeight', 'fontStyle', 'letterSpacing', 'lineHeight', 'strokeWidth', 'construction', 'align',
+  'neonColor', 'tubeColor', 'coreColor', 'glowColor', 'bloomColor', 'glowIntensity', 'glowRadius', 'bloomRadius', 'shadow',
+  'animated', 'animationSpeed', 'seed', 'flicker', 'flickerIntensity', 'flickerFrequency', 'flickerSpeed',
+  'glitch', 'glitchIntensity', 'glitchFrequency', 'glitchDuration', 'background',
+] as const satisfies readonly (keyof NeonTextShorthand)[];
+
+/** Shorthand props → a config patch (only the keys that were given). */
+export function shorthandToConfig(p: NeonTextShorthand): NeonTextConfigInput {
+  const drop = <T extends Record<string, unknown>>(o: T) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) as Partial<T>;
+  const out: NeonTextConfigInput = {};
+  if (p.text !== undefined) out.text = p.text;
+  if (p.background !== undefined) out.background = p.background;
+  out.typography = drop({
+    fontFamily: p.fontFamily, fontSize: p.fontSize, fontWeight: p.fontWeight, fontStyle: p.fontStyle, letterSpacing: p.letterSpacing,
+    lineHeight: p.lineHeight, strokeWidth: p.strokeWidth, construction: p.construction, align: p.align,
+  });
+  out.neon = drop({
+    color: p.neonColor, tubeColor: p.tubeColor, coreColor: p.coreColor, glowColor: p.glowColor, bloomColor: p.bloomColor,
+    intensity: p.glowIntensity, glowRadius: p.glowRadius, bloomRadius: p.bloomRadius,
+  });
+  if (p.shadow !== undefined) out.neon.shadow = { enabled: p.shadow };
+  out.animation = drop({
+    enabled: p.animated, speed: p.animationSpeed, seed: p.seed, flickerEnabled: p.flicker, flickerIntensity: p.flickerIntensity,
+    flickerFrequency: p.flickerFrequency, flickerSpeed: p.flickerSpeed, glitchEnabled: p.glitch, glitchIntensity: p.glitchIntensity,
+    glitchFrequency: p.glitchFrequency, glitchDuration: p.glitchDuration,
+  });
+  return out;
+}
+
+/**
+ * **defaults ← config ← shorthand props.** When the primary colour changes (`neon.color` or the
+ * `neonColor` prop) and a derived colour was not given at the same level, that colour is re-derived,
+ * so `{ neon: { color: '#00D9FF' } }` alone turns the whole sign blue.
+ */
+export function resolveNeonConfig(input?: NeonTextConfigInput | null, shorthand?: NeonTextShorthand): NeonTextConfig {
+  let config = DEFAULT_NEON_CONFIG;
+  for (const layer of [isObj(input) ? input : undefined, shorthand ? shorthandToConfig(shorthand) : undefined]) {
+    if (!layer) continue;
+    const neon = isObj(layer.neon) ? (layer.neon as Record<string, unknown>) : undefined;
+    const primary = neon && typeof neon.color === 'string' ? neon.color : neon && typeof neon.tubeColor === 'string' && neon.color === undefined ? neon.tubeColor : undefined;
+    config = merge(config, layer);
+    if (primary !== undefined && isHexColor(primary)) {
+      const derived = deriveNeonPalette(primary);
+      const n = { ...config.neon, color: primary };
+      for (const k of ['coreColor', 'tubeColor', 'glowColor', 'bloomColor'] as const) if (neon![k] === undefined) n[k] = derived[k];
+      config = { ...config, neon: n };
+    }
+  }
+  return config;
+}
+
+/** The effective four colours: each explicit one, or derived from `color`. */
+export function neonColors(neon: NeonMaterialConfig) {
+  const d = deriveNeonPalette(neon.color);
+  return {
+    coreColor: isHexColor(neon.coreColor) ? neon.coreColor : d.coreColor,
+    tubeColor: isHexColor(neon.tubeColor) ? neon.tubeColor : d.tubeColor,
+    glowColor: isHexColor(neon.glowColor) ? neon.glowColor : d.glowColor,
+    bloomColor: isHexColor(neon.bloomColor) ? neon.bloomColor : d.bloomColor,
+  };
+}
+
+/* ---------- validation: never throws ---------- */
+
+export type NeonConfigError = { path: string; message: string };
+export type NeonControl = {
+  path: string;
+  label: string;
+  group: 'Text' | 'Typography' | 'Colour' | 'Light' | 'Flicker' | 'Glitch' | 'Animation';
+  type: 'text' | 'number' | 'color' | 'boolean' | 'enum' | 'color-or-null';
+  min?: number;
+  max?: number;
+  step?: number;
+  unit?: string;
+  options?: readonly string[];
+  description: string;
+};
+
+/** Every editable value, with its range. The playground draws its controls from this; `validateNeonConfig` checks against it. */
+export const NEON_CONTROLS: NeonControl[] = [
+  { path: 'text', label: 'Text', group: 'Text', type: 'text', description: 'What the sign says. A new line (\\n) starts a second row.' },
+  { path: 'typography.fontFamily', label: 'Font', group: 'Typography', type: 'text', description: 'A CSS font-family list; the page must load the font.' },
+  { path: 'typography.fontSize', label: 'Font size', group: 'Typography', type: 'number', min: 12, max: 1000, step: 1, unit: 'units', description: 'The em size, in SVG user units.' },
+  { path: 'typography.fontWeight', label: 'Font weight', group: 'Typography', type: 'number', min: 100, max: 900, step: 100, description: 'CSS font-weight.' },
+  { path: 'typography.fontStyle', label: 'Font style', group: 'Typography', type: 'enum', options: ['normal', 'italic'], description: 'Upright or italic.' },
+  { path: 'typography.letterSpacing', label: 'Letter spacing', group: 'Typography', type: 'number', min: -50, max: 200, step: 1, unit: 'units', description: 'Extra space between letters.' },
+  { path: 'typography.lineHeight', label: 'Line height', group: 'Typography', type: 'number', min: 0.6, max: 3, step: 0.05, unit: '× size', description: 'Row pitch for multi-line text.' },
+  { path: 'typography.strokeWidth', label: 'Tube width', group: 'Typography', type: 'number', min: 0.5, max: 80, step: 0.5, unit: 'units', description: 'The glass tube. The reference is ≈ 0.033 × font size.' },
+  { path: 'typography.construction', label: 'Construction', group: 'Typography', type: 'enum', options: NEON_CONSTRUCTIONS, description: 'outline: the tube traces each letter (CAFE). monoline: the letter is the tube (24/7).' },
+  { path: 'typography.align', label: 'Align', group: 'Typography', type: 'enum', options: NEON_ALIGNS, description: 'Row alignment for multi-line text.' },
+  { path: 'neon.color', label: 'Neon colour', group: 'Colour', type: 'color', description: 'The primary colour; the others follow it unless set.' },
+  { path: 'neon.tubeColor', label: 'Tube colour', group: 'Colour', type: 'color-or-null', description: 'The lit glass. null follows the neon colour.' },
+  { path: 'neon.coreColor', label: 'Core colour', group: 'Colour', type: 'color-or-null', description: 'The hot centre line. null follows the neon colour.' },
+  { path: 'neon.glowColor', label: 'Glow colour', group: 'Colour', type: 'color-or-null', description: 'The tight halo. null follows the neon colour.' },
+  { path: 'neon.bloomColor', label: 'Bloom colour', group: 'Colour', type: 'color-or-null', description: 'The light on the wall. null follows the neon colour.' },
+  { path: 'neon.intensity', label: 'Glow intensity', group: 'Light', type: 'number', min: 0, max: 3, step: 0.05, description: '0 is a bare tube; 1 the reference.' },
+  { path: 'neon.bloomIntensity', label: 'Bloom intensity', group: 'Light', type: 'number', min: 0, max: 3, step: 0.05, description: 'The wall bloom’s own strength.' },
+  { path: 'neon.tubeBrightness', label: 'Tube brightness', group: 'Light', type: 'number', min: 0, max: 1.5, step: 0.01, description: 'How bright the lit glass is.' },
+  { path: 'neon.coreBrightness', label: 'Core brightness', group: 'Light', type: 'number', min: 0, max: 1.5, step: 0.01, description: 'How bright the hot centre line is.' },
+  { path: 'neon.glowRadius', label: 'Glow radius', group: 'Light', type: 'number', min: 0, max: 200, step: 1, unit: 'units', description: 'Reach of the tight halo.' },
+  { path: 'neon.bloomRadius', label: 'Bloom radius', group: 'Light', type: 'number', min: 0, max: 400, step: 1, unit: 'units', description: 'Reach of the wall bloom.' },
+  { path: 'neon.coreWidth', label: 'Core width', group: 'Light', type: 'number', min: 0, max: 1, step: 0.01, unit: '× tube', description: 'The hot core, as a share of the tube.' },
+  { path: 'neon.glassOpacity', label: 'Unlit glass', group: 'Light', type: 'number', min: 0, max: 1, step: 0.01, description: 'How much dark glass shows when the tube dims.' },
+  { path: 'neon.shadow.enabled', label: 'Shadow', group: 'Light', type: 'boolean', description: 'The tube’s dark cast shadow on the wall.' },
+  { path: 'neon.shadow.color', label: 'Shadow colour', group: 'Light', type: 'color', description: 'Shadow colour.' },
+  { path: 'neon.shadow.opacity', label: 'Shadow opacity', group: 'Light', type: 'number', min: 0, max: 1, step: 0.01, description: 'Shadow strength.' },
+  { path: 'neon.shadow.offsetX', label: 'Shadow x', group: 'Light', type: 'number', min: -0.5, max: 0.5, step: 0.005, unit: '× size', description: 'Shadow offset, across.' },
+  { path: 'neon.shadow.offsetY', label: 'Shadow y', group: 'Light', type: 'number', min: -0.5, max: 0.5, step: 0.005, unit: '× size', description: 'Shadow offset, down.' },
+  { path: 'neon.shadow.blur', label: 'Shadow blur', group: 'Light', type: 'number', min: 0, max: 100, step: 0.5, unit: 'units', description: 'Shadow softness.' },
+  { path: 'animation.enabled', label: 'Animation', group: 'Animation', type: 'boolean', description: 'Flicker and glitch on or off.' },
+  { path: 'animation.speed', label: 'Animation speed', group: 'Animation', type: 'number', min: 0.1, max: 5, step: 0.05, unit: '×', description: 'Plays everything faster or slower.' },
+  { path: 'animation.seed', label: 'Seed', group: 'Animation', type: 'number', min: 0, max: 4294967295, step: 1, description: 'Same seed, same performance.' },
+  { path: 'animation.flickerEnabled', label: 'Flicker', group: 'Flicker', type: 'boolean', description: 'Brightness flicker on or off.' },
+  { path: 'animation.flickerIntensity', label: 'Flicker intensity', group: 'Flicker', type: 'number', min: 0, max: 1, step: 0.01, description: '0.25 plays the full hardware ranges.' },
+  { path: 'animation.flickerFrequency', label: 'Flicker frequency', group: 'Flicker', type: 'number', min: 0, max: 5, step: 0.01, unit: '/ s', description: 'Noticeable flicker events per second.' },
+  { path: 'animation.flickerSpeed', label: 'Flicker speed', group: 'Flicker', type: 'number', min: 0.1, max: 5, step: 0.05, unit: '×', description: 'How fast each flicker event plays.' },
+  { path: 'animation.flickerRandomness', label: 'Randomness', group: 'Flicker', type: 'number', min: 0, max: 1, step: 0.01, description: 'How much events vary in depth and length.' },
+  { path: 'animation.flickerRecovery', label: 'Recovery speed', group: 'Flicker', type: 'number', min: 0, max: 1, step: 0.01, description: 'How fast the tube comes back after a dip or failure.' },
+  { path: 'animation.flickerMinBrightness', label: 'Minimum brightness', group: 'Flicker', type: 'number', min: 0, max: 1, step: 0.01, description: 'The tube never falls below this.' },
+  { path: 'animation.glitchEnabled', label: 'Glitch', group: 'Glitch', type: 'boolean', description: 'Occasional glitches on or off.' },
+  { path: 'animation.glitchIntensity', label: 'Glitch intensity', group: 'Glitch', type: 'number', min: 0, max: 1, step: 0.01, description: 'How far slices shift and colours split.' },
+  { path: 'animation.glitchFrequency', label: 'Glitch frequency', group: 'Glitch', type: 'number', min: 0, max: 5, step: 0.01, unit: '/ s', description: 'Glitches per second.' },
+  { path: 'animation.glitchDuration', label: 'Glitch duration', group: 'Glitch', type: 'number', min: 20, max: 2000, step: 10, unit: 'ms', description: 'A glitch’s typical length.' },
+  { path: 'animation.glitchDisplacement', label: 'Horizontal displacement', group: 'Glitch', type: 'number', min: 0, max: 2, step: 0.05, unit: '×', description: 'The whole-sign sideways jump.' },
+  { path: 'animation.glitchRgbSplit', label: 'RGB separation', group: 'Glitch', type: 'number', min: 0, max: 2, step: 0.05, unit: '×', description: 'The red/cyan split.' },
+  { path: 'animation.glitchSlices', label: 'Slice displacement', group: 'Glitch', type: 'number', min: 0, max: 2, step: 0.05, unit: '×', description: 'How far the sliced bands shift.' },
+  { path: 'animation.glitchGlowSeparation', label: 'Glow separation', group: 'Glitch', type: 'number', min: 0, max: 2, step: 0.05, unit: '×', description: 'How far the glow slips from the tube.' },
+  { path: 'background', label: 'Background', group: 'Colour', type: 'color-or-null', description: 'A colour behind the sign, or null for transparent.' },
+];
+
+export function getPath(obj: unknown, path: string): unknown {
+  return path.split('.').reduce<unknown>((o, k) => (isObj(o) ? o[k] : undefined), obj);
+}
+export function setPath<T>(obj: T, path: string, value: unknown): T {
+  const [head, ...rest] = path.split('.');
+  const o = (isObj(obj) ? obj : {}) as Record<string, unknown>;
+  return { ...o, [head!]: rest.length ? setPath(o[head!], rest.join('.'), value) : value } as T;
+}
+
+export const MAX_NEON_TEXT_LENGTH = 200;
+
+/** `[]` when the config can be drawn; otherwise every problem as `{ path, message }`. Never throws. */
+export function validateNeonConfig(config: unknown): NeonConfigError[] {
+  const errors: NeonConfigError[] = [];
+  if (!isObj(config)) return [{ path: '', message: 'The config must be an object.' }];
+  for (const c of NEON_CONTROLS) {
+    const v = getPath(config, c.path);
+    const where = c.path;
+    if (c.type === 'text') {
+      if (typeof v !== 'string') errors.push({ path: where, message: 'Must be text.' });
+      else if (c.path === 'text' && v.length > MAX_NEON_TEXT_LENGTH) errors.push({ path: where, message: `At most ${MAX_NEON_TEXT_LENGTH} characters.` });
+      else if (c.path !== 'text' && !v.trim()) errors.push({ path: where, message: 'Must not be empty.' });
+    } else if (c.type === 'number') {
+      if (typeof v !== 'number' || !Number.isFinite(v)) errors.push({ path: where, message: 'Must be a number.' });
+      else if ((c.min !== undefined && v < c.min) || (c.max !== undefined && v > c.max)) errors.push({ path: where, message: `Must be between ${c.min} and ${c.max}.` });
+    } else if (c.type === 'boolean') {
+      if (typeof v !== 'boolean') errors.push({ path: where, message: 'Must be true or false.' });
+    } else if (c.type === 'enum') {
+      if (!c.options!.includes(v as string)) errors.push({ path: where, message: `Must be one of: ${c.options!.join(', ')}.` });
+    } else if (c.type === 'color') {
+      if (!isHexColor(v)) errors.push({ path: where, message: 'Must be a hex colour like #FF3B4D.' });
+    } else if (v !== null && !isHexColor(v)) {
+      errors.push({ path: where, message: 'Must be a hex colour like #FF3B4D, or null.' });
+    }
+  }
+  return errors;
+}
+
+/**
+ * **A config that can always be drawn.** Every field that fails validation is replaced by its
+ * default, and the problems are returned alongside, so a renderer never crashes and never half-draws.
+ */
+export function sanitizeNeonConfig(config: unknown): { config: NeonTextConfig; errors: NeonConfigError[] } {
+  const base = isObj(config) ? merge(DEFAULT_NEON_CONFIG, config) : DEFAULT_NEON_CONFIG;
+  const errors = validateNeonConfig(base);
+  let out = base;
+  for (const e of errors) out = e.path ? setPath(out, e.path, getPath(DEFAULT_NEON_CONFIG, e.path)) : DEFAULT_NEON_CONFIG;
+  return { config: out, errors: isObj(config) ? errors : [{ path: '', message: 'The config must be an object.' }] };
+}