@appinternalleads/ui 0.4.0 → 0.4.1

package/src/motion/neon/scene.ts

@@ -0,0 +1,610 @@
+/* eslint-disable comppack/no-raw-colour -- neon colours are scene content (presets and named colours), not theme colours. */
+import {
+  DEFAULT_NEON_CONFIG, NEON_COLOR_PRESETS, deriveNeonPalette, isHexColor, validateNeonConfig, getPath, setPath,
+  type NeonAnimationConfig, type NeonConfigError, type NeonConstruction, type NeonMaterialConfig, type NeonTypography, type DeepPartial,
+} from './config';
+import { flickerCuesBetween, type FlickerKind, type NeonTrigger } from './flicker';
+import { glitchCuesBetween } from './glitch';
+import { NEON_ARTWORK_LIBRARY, parseSvgArtwork, type ParsedSvg } from './artwork';
+import { NEON_EMOJI_FONT, NEON_FONTS, findNeonFont } from './fonts';
+import { materialPad, type NeonShapeMetrics } from './material';
+import { estimateTextWidth, layoutText, type NeonLayout, type TextMeasurer } from './typography';
+import { DEFAULT_NEON_WALL, type NeonWallConfig } from './wall';
+
+/**
+ * **A neon scene: several neon elements on a wall, as one JSON document.** Text, emoji and artwork
+ * are all `NeonElement`s and share one contract — position, scale, rotation, opacity, a neon
+ * material and an animation — so an agent builds "CAFE + ☕ + a pink heart" the same way it builds
+ * one word. The scene adds the wall, the sound and a timeline of scripted moments.
+ *
+ *   NeonCanvas
+ *    ├── elements: NeonText | NeonEmoji | NeonArtwork   (each: material + animation)
+ *    ├── wall: procedural bricks, ambient light, light spill from every element
+ *    ├── audio: hum, flicker, dip, failure, glitch, recovery
+ *    └── timeline: duration, loop, triggers (scripted events)
+ */
+export type NeonElementCommon = {
+  id: string;
+  /** Centre, in stage units. */
+  x: number;
+  y: number;
+  scale: number;
+  /** Degrees, clockwise. */
+  rotation: number;
+  opacity: number;
+  visible: boolean;
+  /** Pinned: dragging on a stage never moves it (config and agents still can). */
+  locked: boolean;
+  neon: NeonMaterialConfig;
+  animation: NeonAnimationConfig;
+};
+export type NeonTextElement = NeonElementCommon & { type: 'text'; text: string; typography: NeonTypography };
+export type NeonEmojiElement = NeonElementCommon & {
+  type: 'emoji';
+  emoji: string;
+  /** The glyph's em size, stage units. */
+  size: number;
+  strokeWidth: number;
+  construction: NeonConstruction;
+  fontWeight: number;
+  /** The outline emoji face (monochrome, vector): Noto Emoji by default. */
+  fontFamily: string;
+};
+export type NeonArtworkSource =
+  | { kind: 'library'; id: string }
+  | { kind: 'svg'; svg: string; name?: string }
+  | { kind: 'raster'; src: string; width: number; height: number; mode: 'alpha' | 'luminance'; threshold: number; name?: string };
+export type NeonArtworkElement = NeonElementCommon & {
+  type: 'artwork';
+  artwork: NeonArtworkSource;
+  /** The artwork's longer side, stage units. */
+  size: number;
+  strokeWidth: number;
+  construction: NeonConstruction;
+};
+export type NeonElement = NeonTextElement | NeonEmojiElement | NeonArtworkElement;
+export type NeonElementType = NeonElement['type'];
+
+export type NeonAudioConfig = {
+  enabled: boolean;
+  muted: boolean;
+  /** 0…1 each. */
+  master: number;
+  hum: number;
+  flicker: number;
+  dip: number;
+  failure: number;
+  glitch: number;
+  recovery: number;
+  /** Preview sounds while scrubbing the timeline, throttled. */
+  scrub: boolean;
+  scrubVolume: number;
+};
+
+export type SceneTrigger = NeonTrigger & { /** Only this element (default: all). */ target?: string };
+export type NeonTimeline = { duration: number; loop: boolean; triggers: SceneTrigger[] };
+
+export type NeonScene = {
+  type: 'neonScene';
+  version: 1;
+  stage: { width: number; height: number };
+  elements: NeonElement[];
+  wall: NeonWallConfig;
+  audio: NeonAudioConfig;
+  timeline: NeonTimeline;
+};
+export type NeonSceneInput = DeepPartial<Omit<NeonScene, 'elements'>> & { elements?: NeonElementInput[] };
+export type NeonElementInput = DeepPartial<Omit<NeonTextElement, 'type'>> & { type?: NeonElementType } & Record<string, unknown>;
+
+export const DEFAULT_NEON_AUDIO: NeonAudioConfig = {
+  enabled: false, muted: false, master: 0.7, hum: 0.45, flicker: 0.45, dip: 0.55, failure: 0.6, glitch: 0.3, recovery: 0.45, scrub: true, scrubVolume: 0.5,
+};
+
+const common = (id: string, seed: number): NeonElementCommon => ({
+  id, x: 800, y: 500, scale: 1, rotation: 0, opacity: 1, visible: true, locked: false,
+  neon: { ...DEFAULT_NEON_CONFIG.neon, shadow: { ...DEFAULT_NEON_CONFIG.neon.shadow } },
+  animation: { ...DEFAULT_NEON_CONFIG.animation, seed },
+});
+export const DEFAULT_NEON_ELEMENTS: { text: NeonTextElement; emoji: NeonEmojiElement; artwork: NeonArtworkElement } = {
+  text: { ...common('text-1', 7356951), type: 'text', text: 'CAFE', typography: { ...DEFAULT_NEON_CONFIG.typography, fontSize: 300, strokeWidth: 10.5, letterSpacing: 6 } },
+  emoji: { ...common('emoji-1', 7356952), type: 'emoji', emoji: '☕', size: 240, strokeWidth: 8, construction: 'outline', fontWeight: 500, fontFamily: NEON_EMOJI_FONT.family },
+  artwork: { ...common('artwork-1', 7356953), type: 'artwork', artwork: { kind: 'library', id: 'heart' }, size: 260, strokeWidth: 8, construction: 'outline' },
+};
+
+export const DEFAULT_NEON_SCENE: NeonScene = {
+  type: 'neonScene',
+  version: 1,
+  stage: { width: 1600, height: 1000 },
+  elements: [DEFAULT_NEON_ELEMENTS.text],
+  wall: DEFAULT_NEON_WALL,
+  audio: DEFAULT_NEON_AUDIO,
+  timeline: { duration: 8000, loop: true, triggers: [] },
+};
+
+/* ---------- 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;
+}
+
+/** Re-derives the element's derived colours when only `neon.color` (or `tubeColor`) was given. */
+function withDerivedColours(el: NeonElement, input: unknown): NeonElement {
+  const n = isObj(input) && isObj(input.neon) ? input.neon : undefined;
+  const primary = n && typeof n.color === 'string' ? n.color : n && typeof n.tubeColor === 'string' ? n.tubeColor : undefined;
+  if (!n || !isHexColor(primary)) return el;
+  const d = deriveNeonPalette(primary);
+  const neon = { ...el.neon, color: primary };
+  for (const k of ['coreColor', 'tubeColor', 'glowColor', 'bloomColor'] as const) if (n[k] === undefined) neon[k] = d[k];
+  return { ...el, neon };
+}
+
+/** One element: its type's defaults ← the input. Colours follow `neon.color` unless given. */
+export function resolveNeonElement(input: unknown, index = 0): NeonElement {
+  const type = isObj(input) && (input.type === 'emoji' || input.type === 'artwork') ? input.type : 'text';
+  const base = DEFAULT_NEON_ELEMENTS[type];
+  const seeded = { ...base, id: `${type}-${index + 1}`, animation: { ...base.animation, seed: base.animation.seed + index * 101 } };
+  const el = merge(seeded as NeonElement, isObj(input) ? input : {});
+  return withDerivedColours({ ...el, type } as NeonElement, input);
+}
+
+/** defaults ← input, element by element. Never throws; `validateNeonScene` says what is wrong. */
+export function resolveNeonScene(input?: NeonSceneInput | null): NeonScene {
+  const i = isObj(input) ? input : {};
+  const elements = Array.isArray(i.elements) ? i.elements.map((e, n) => resolveNeonElement(e, n)) : DEFAULT_NEON_SCENE.elements;
+  return {
+    ...DEFAULT_NEON_SCENE,
+    stage: merge(DEFAULT_NEON_SCENE.stage, i.stage),
+    wall: merge(DEFAULT_NEON_SCENE.wall, i.wall),
+    audio: merge(DEFAULT_NEON_SCENE.audio, i.audio),
+    timeline: merge(DEFAULT_NEON_SCENE.timeline, i.timeline),
+    elements,
+  };
+}
+
+/* ---------- validation: never throws ---------- */
+
+const num = (v: unknown, min: number, max: number) => typeof v === 'number' && Number.isFinite(v) && v >= min && v <= max;
+const WALL_RANGES: [keyof NeonWallConfig, number, number][] = [
+  ['brickWidth', 20, 1000], ['brickHeight', 10, 500], ['mortar', 0, 40], ['variation', 0, 1], ['texture', 0, 1], ['ambient', 0, 1],
+  ['vignette', 0, 1], ['lightSpill', 0, 2], ['spillRadius', 0, 2000], ['seed', 0, 4294967295],
+];
+const AUDIO_KEYS = ['master', 'hum', 'flicker', 'dip', 'failure', 'glitch', 'recovery', 'scrubVolume'] as const;
+
+/** The shape's metrics and layout inputs, for validation and geometry. */
+function textLike(el: NeonTextElement | NeonEmojiElement): { text: string; typography: NeonTypography } {
+  if (el.type === 'text') return { text: el.text, typography: el.typography };
+  return {
+    text: emojiText(el.emoji),
+    typography: { fontFamily: el.fontFamily, fontSize: el.size, fontWeight: el.fontWeight, fontStyle: 'normal', letterSpacing: 0, lineHeight: 1, strokeWidth: el.strokeWidth, construction: el.construction, align: 'middle' },
+  };
+}
+
+/** Text presentation for an emoji: the outline face draws it, not a colour bitmap. */
+export const emojiText = (e: string) => `${String(e ?? '').replace(/️/g, '')}︎`;
+
+export function validateNeonElement(el: unknown, at = ''): NeonConfigError[] {
+  if (!isObj(el)) return [{ path: at, message: 'An element must be an object.' }];
+  const errors: NeonConfigError[] = [];
+  const p = (k: string) => (at ? `${at}.${k}` : k);
+  if (!['text', 'emoji', 'artwork'].includes(el.type as string)) errors.push({ path: p('type'), message: 'Must be text, emoji or artwork.' });
+  if (typeof el.id !== 'string' || !el.id) errors.push({ path: p('id'), message: 'Must be a non-empty id.' });
+  for (const [k, lo, hi] of [['x', -5000, 10000], ['y', -5000, 10000], ['scale', 0.01, 20], ['rotation', -360, 360], ['opacity', 0, 1]] as const) {
+    if (!num(el[k], lo, hi)) errors.push({ path: p(k), message: `Must be a number between ${lo} and ${hi}.` });
+  }
+  if (typeof el.visible !== 'boolean') errors.push({ path: p('visible'), message: 'Must be true or false.' });
+  if (typeof el.locked !== 'boolean') errors.push({ path: p('locked'), message: 'Must be true or false.' });
+  /* Material and animation: the same rules as a single sign. */
+  const asText = { ...DEFAULT_NEON_CONFIG, neon: el.neon, animation: el.animation };
+  for (const e of validateNeonConfig(asText)) if (e.path.startsWith('neon') || e.path.startsWith('animation')) errors.push({ path: p(e.path), message: e.message });
+  if (el.type === 'text') {
+    for (const e of validateNeonConfig({ ...DEFAULT_NEON_CONFIG, text: el.text, typography: el.typography })) if (e.path === 'text' || e.path.startsWith('typography')) errors.push({ path: p(e.path), message: e.message });
+  } else if (el.type === 'emoji' || el.type === 'artwork') {
+    if (!num(el.size, 8, 2000)) errors.push({ path: p('size'), message: 'Must be a number between 8 and 2000.' });
+    if (!num(el.strokeWidth, 0.5, 80)) errors.push({ path: p('strokeWidth'), message: 'Must be a number between 0.5 and 80.' });
+    if (el.construction !== 'outline' && el.construction !== 'monoline') errors.push({ path: p('construction'), message: 'Must be outline or monoline.' });
+    if (el.type === 'emoji') {
+      if (typeof el.emoji !== 'string' || !el.emoji.trim() || [...el.emoji].length > 12) errors.push({ path: p('emoji'), message: 'Must be one emoji (or a few characters).' });
+      if (!num(el.fontWeight, 100, 900)) errors.push({ path: p('fontWeight'), message: 'Must be between 100 and 900.' });
+      if (typeof el.fontFamily !== 'string' || !el.fontFamily.trim()) errors.push({ path: p('fontFamily'), message: 'Must be a font-family.' });
+    } else {
+      const a = el.artwork;
+      if (!isObj(a)) errors.push({ path: p('artwork'), message: 'Must be { kind: library | svg | raster, … }.' });
+      else if (a.kind === 'library') { if (!NEON_ARTWORK_LIBRARY[a.id as string]) errors.push({ path: p('artwork.id'), message: `Must be one of: ${Object.keys(NEON_ARTWORK_LIBRARY).join(', ')}.` }); }
+      else if (a.kind === 'svg') { try { parseSvgArtwork(a.svg as string); } catch (err) { errors.push({ path: p('artwork.svg'), message: (err as Error).message }); } }
+      else if (a.kind === 'raster') {
+        if (typeof a.src !== 'string' || !/^(data:image\/(png|webp|jpeg|gif);base64,|https?:\/\/|\/)/.test(a.src)) errors.push({ path: p('artwork.src'), message: 'Must be a PNG/WebP data URL or an image URL.' });
+        if (!num(a.width, 1, 20000) || !num(a.height, 1, 20000)) errors.push({ path: p('artwork.width'), message: 'Width and height must be the image’s pixel size.' });
+        if (a.mode !== 'alpha' && a.mode !== 'luminance') errors.push({ path: p('artwork.mode'), message: 'Must be alpha or luminance.' });
+        if (!num(a.threshold, 0, 1)) errors.push({ path: p('artwork.threshold'), message: 'Must be between 0 and 1.' });
+      } else errors.push({ path: p('artwork.kind'), message: 'Must be library, svg or raster.' });
+    }
+  }
+  return errors;
+}
+
+/** `[]` when the scene can be drawn as given; otherwise every problem as `{ path, message }`. */
+export function validateNeonScene(scene: unknown): NeonConfigError[] {
+  if (!isObj(scene)) return [{ path: '', message: 'The scene must be an object.' }];
+  const errors: NeonConfigError[] = [];
+  const st = scene.stage;
+  if (!isObj(st) || !num(st.width, 100, 8000) || !num(st.height, 100, 8000)) errors.push({ path: 'stage', message: 'width and height must be 100…8000.' });
+  if (!Array.isArray(scene.elements)) errors.push({ path: 'elements', message: 'Must be a list.' });
+  else {
+    if (scene.elements.length > 40) errors.push({ path: 'elements', message: 'At most 40 elements.' });
+    const ids = new Set<string>();
+    scene.elements.forEach((el, i) => {
+      errors.push(...validateNeonElement(el, `elements.${i}`));
+      if (isObj(el) && typeof el.id === 'string') { if (ids.has(el.id)) errors.push({ path: `elements.${i}.id`, message: 'Ids must be unique.' }); ids.add(el.id); }
+    });
+  }
+  const w = scene.wall;
+  if (!isObj(w)) errors.push({ path: 'wall', message: 'Must be an object.' });
+  else {
+    if (typeof w.enabled !== 'boolean') errors.push({ path: 'wall.enabled', message: 'Must be true or false.' });
+    for (const [k, lo, hi] of WALL_RANGES) if (!num(w[k], lo, hi)) errors.push({ path: `wall.${k}`, message: `Must be a number between ${lo} and ${hi}.` });
+    for (const k of ['brickColor', 'mortarColor', 'ambientColor'] as const) if (!isHexColor(w[k])) errors.push({ path: `wall.${k}`, message: 'Must be a hex colour.' });
+  }
+  const a = scene.audio;
+  if (!isObj(a)) errors.push({ path: 'audio', message: 'Must be an object.' });
+  else {
+    for (const k of ['enabled', 'muted', 'scrub'] as const) if (typeof a[k] !== 'boolean') errors.push({ path: `audio.${k}`, message: 'Must be true or false.' });
+    for (const k of AUDIO_KEYS) if (!num(a[k], 0, 1)) errors.push({ path: `audio.${k}`, message: 'Must be a number between 0 and 1.' });
+  }
+  const t = scene.timeline;
+  if (!isObj(t) || !num(t.duration, 500, 600_000) || typeof t.loop !== 'boolean' || !Array.isArray(t.triggers)) errors.push({ path: 'timeline', message: 'Needs duration (500…600000 ms), loop and a triggers list.' });
+  else t.triggers.forEach((tr, i) => {
+    if (!isObj(tr) || !['sag', 'flicker', 'dip', 'failure', 'glitch', 'normal'].includes(tr.kind as string) || !num(tr.at, 0, 600_000)) errors.push({ path: `timeline.triggers.${i}`, message: 'Needs kind (sag, flicker, dip, failure, glitch, normal) and at (ms).' });
+  });
+  return errors;
+}
+
+/** A scene that can always be drawn: each bad field falls back to its default; the problems come back too. */
+export function sanitizeNeonScene(input: unknown): { scene: NeonScene; errors: NeonConfigError[] } {
+  const scene = resolveNeonScene(isObj(input) ? (input as NeonSceneInput) : null);
+  const errors = validateNeonScene(scene);
+  let out: NeonScene = scene;
+  for (const e of errors) {
+    const m = /^elements\.(\d+)/.exec(e.path);
+    if (m) {
+      const i = Number(m[1]);
+      const el = out.elements[i]!;
+      const rest = e.path.slice(m[0].length + 1);
+      const def = DEFAULT_NEON_ELEMENTS[(['text', 'emoji', 'artwork'].includes(el?.type) ? el.type : 'text') as NeonElementType];
+      const fixed = rest ? setPath(el, rest, getPath(def, rest)) : def;
+      out = { ...out, elements: out.elements.map((x, n) => (n === i ? (fixed as NeonElement) : x)) };
+    } else if (e.path && e.path !== 'elements') {
+      out = setPath(out, e.path, getPath(DEFAULT_NEON_SCENE, e.path));
+    } else if (e.path === 'elements') {
+      out = { ...out, elements: out.elements.slice(0, 40) };
+    }
+  }
+  if (errors.length && validateNeonScene(out).length) out = { ...DEFAULT_NEON_SCENE, elements: out.elements.filter((el) => !validateNeonElement(el).length) };
+  return { scene: out, errors };
+}
+
+/* ---------- geometry ---------- */
+
+export type NeonElementGeometry = {
+  /** What the renderer draws. */
+  shape:
+    | { kind: 'text'; layout: NeonLayout; typography: NeonTypography; text: string }
+    | { kind: 'svg'; art: ParsedSvg }
+    | { kind: 'raster'; src: string; width: number; height: number; mode: 'alpha' | 'luminance'; threshold: number }
+    | { kind: 'none'; reason: string };
+  /** The shape's box in its local units. */
+  box: { x: number; y: number; width: number; height: number };
+  /** Local units per stage unit (before the element's own `scale`). */
+  unit: number;
+  /** One em in local units (glitch offsets). */
+  em: number;
+  /** Material metrics and the neon config, in local units. */
+  metrics: NeonShapeMetrics;
+  neon: NeonMaterialConfig;
+  pad: number;
+  /** The SVG transform that places the local shape on the stage. */
+  transform: string;
+  /** Axis-aligned bounds on the stage (for the wall light, placement and selection). */
+  bounds: { x: number; y: number; width: number; height: number };
+};
+
+const r3 = (v: number) => Math.round(v * 1000) / 1000;
+
+/** Scale a material's lengths into local units. */
+function localNeon(neon: NeonMaterialConfig, k: number): NeonMaterialConfig {
+  return { ...neon, glowRadius: neon.glowRadius * k, bloomRadius: neon.bloomRadius * k, shadow: { ...neon.shadow, blur: neon.shadow.blur * k } };
+}
+
+/** Where and how big an element is. `measure` defaults to the width estimate. */
+export function elementGeometry(el: NeonElement, measure: TextMeasurer = estimateTextWidth): NeonElementGeometry {
+  let shape: NeonElementGeometry['shape'];
+  let box: NeonElementGeometry['box'];
+  let unit = 1;
+  let em: number;
+  let metrics: NeonShapeMetrics;
+  if (el.type === 'text' || el.type === 'emoji') {
+    const { text, typography } = textLike(el);
+    const layout = layoutText(text, typography, 0, el.type === 'emoji' ? (() => typography.fontSize * 1.05) : measure);
+    shape = { kind: 'text', layout, typography, text };
+    box = layout.box;
+    em = typography.fontSize;
+    metrics = { fontSize: typography.fontSize, strokeWidth: typography.strokeWidth, construction: typography.construction };
+  } else {
+    let vb: [number, number, number, number] = [0, 0, 100, 100];
+    const a = el.artwork;
+    try {
+      if (a.kind === 'raster') {
+        /* Drawn at its stage size, so the outline filters work at stage resolution, like the vectors' strokes. */
+        const w = Math.max(1, el.size);
+        const h = (w * a.height) / Math.max(1, a.width);
+        vb = [0, 0, a.width >= a.height ? w : (w * a.width) / a.height, a.width >= a.height ? h : w];
+        shape = { kind: 'raster', src: a.src, width: vb[2], height: vb[3], mode: a.mode, threshold: a.threshold };
+      }
+      else {
+        const art = parseSvgArtwork(a.kind === 'library' ? (NEON_ARTWORK_LIBRARY[a.id] ?? NEON_ARTWORK_LIBRARY.heart!).svg : a.svg);
+        vb = art.viewBox;
+        shape = { kind: 'svg', art };
+      }
+    } catch (err) {
+      shape = { kind: 'none', reason: (err as Error).message };
+    }
+    const side = Math.max(vb[2], vb[3]);
+    unit = side / Math.max(1, el.size);
+    box = { x: vb[0], y: vb[1], width: vb[2], height: vb[3] };
+    em = side;
+    metrics = { fontSize: side, strokeWidth: el.strokeWidth * unit, construction: el.construction };
+  }
+  const neon = unit === 1 ? el.neon : localNeon(el.neon, unit);
+  const pad = materialPad(neon, metrics);
+  const cx = box.x + box.width / 2;
+  const cy = box.y + box.height / 2;
+  const s = el.scale / unit;
+  const transform = `translate(${r3(el.x)} ${r3(el.y)}) rotate(${r3(el.rotation)}) scale(${r3(s)}) translate(${r3(-cx)} ${r3(-cy)})`;
+  /* Rotated box → axis-aligned stage bounds. */
+  const hw = (box.width / 2) * s;
+  const hh = (box.height / 2) * s;
+  const rad = (el.rotation * Math.PI) / 180;
+  const bw = Math.abs(hw * Math.cos(rad)) + Math.abs(hh * Math.sin(rad));
+  const bh = Math.abs(hw * Math.sin(rad)) + Math.abs(hh * Math.cos(rad));
+  return { shape, box, unit, em, metrics, neon, pad, transform, bounds: { x: el.x - bw, y: el.y - bh, width: 2 * bw, height: 2 * bh } };
+}
+
+/* ---------- sound cues ---------- */
+
+export type NeonCueKind = FlickerKind | 'restore' | 'glitch';
+export type NeonCue = { kind: NeonCueKind; at: number; elementId: string; depth: number };
+
+/** Triggers that apply to this element, without the target field. */
+export const elementTriggers = (triggers: readonly SceneTrigger[] | undefined, id: string): NeonTrigger[] =>
+  (triggers ?? []).filter((t) => !t.target || t.target === id).map(({ kind, at }) => ({ kind, at }));
+
+/**
+ * **Sound cues between two clock times**: every flicker event start, every re-strike after a dip or
+ * failure, and every glitch start, across visible elements. Elements that share a seed share a
+ * circuit, so identical cues within 30 ms are merged.
+ */
+export function neonSceneCues(scene: NeonScene, t0: number, t1: number, triggers?: readonly SceneTrigger[]): NeonCue[] {
+  if (!(t1 > t0)) return [];
+  const out: NeonCue[] = [];
+  for (const el of scene.elements) {
+    if (!el.visible || !el.animation.enabled) continue;
+    const a = el.animation;
+    const sp = Math.max(0, a.speed);
+    const fs = Math.max(0.01, a.flickerSpeed);
+    const tr = elementTriggers(triggers, el.id);
+    if (sp > 0) {
+      for (const c of flickerCuesBetween(a, t0 * sp * fs, t1 * sp * fs, tr, (ms) => ms * sp * fs)) out.push({ kind: c.kind, at: c.at / (sp * fs), elementId: el.id, depth: c.depth });
+      for (const g of glitchCuesBetween(a, t0 * sp, t1 * sp, tr, (ms) => ms * sp)) out.push({ kind: 'glitch', at: g.at / sp, elementId: el.id, depth: 1 });
+    }
+  }
+  out.sort((x, y) => x.at - y.at);
+  return out.filter((c, i) => !out.slice(0, i).some((p) => p.kind === c.kind && Math.abs(p.at - c.at) < 30));
+}
+
+/* ---------- presets ---------- */
+
+const fontFor = (id: string) => NEON_FONTS.find((x) => x.id === id)!;
+function textEl(id: string, text: string, fontId: string, color: Partial<NeonMaterialConfig>, over: Partial<NeonTextElement> = {}): NeonElementInput {
+  const font = fontFor(fontId);
+  return {
+    id, type: 'text', text,
+    typography: { fontFamily: font.family, fontWeight: font.weight, construction: font.construction, fontSize: 300, strokeWidth: Math.round(300 * font.stroke * 2) / 2, ...(over.typography ?? {}) },
+    neon: color,
+    ...Object.fromEntries(Object.entries(over).filter(([k]) => k !== 'typography')),
+  } as NeonElementInput;
+}
+
+export type NeonScenePreset = { id: string; name: string; description: string; scene: NeonSceneInput };
+const anim = (o: Partial<NeonAnimationConfig>) => o;
+
+/** Complete scenes: text, font, colours, glow, flicker, glitch, wall and sound. */
+export const NEON_SCENE_PRESETS: NeonScenePreset[] = [
+  { id: 'cafe-red', name: 'CAFE RED', description: 'The reference: red outline CAFE on a navy brick wall.', scene: { elements: [textEl('text-1', 'CAFE', 'oswald', NEON_COLOR_PRESETS.red, { animation: anim({ flickerIntensity: 0.18, flickerFrequency: 0.25, glitchFrequency: 0.1 }) as NeonAnimationConfig })] } },
+  { id: 'cafe-blue', name: 'CAFE BLUE', description: 'CAFE in ice blue.', scene: { elements: [textEl('text-1', 'CAFE', 'oswald', NEON_COLOR_PRESETS.blue)] } },
+  { id: 'cafe-purple', name: 'CAFE PURPLE', description: 'CAFE in violet.', scene: { elements: [textEl('text-1', 'CAFE', 'oswald', NEON_COLOR_PRESETS.purple)] } },
+  { id: 'cafe-green', name: 'CAFE GREEN', description: 'CAFE in acid green.', scene: { elements: [textEl('text-1', 'CAFE', 'oswald', NEON_COLOR_PRESETS.green)] } },
+  {
+    id: 'retro-red', name: 'RETRO RED', description: 'A 1950s diner sign: Righteous, warm red, a tired transformer.',
+    scene: {
+      elements: [
+        textEl('text-1', 'DINER', 'righteous', { color: '#FF3040' }, { y: 470, animation: anim({ flickerIntensity: 0.3, flickerFrequency: 0.45, flickerRandomness: 0.8, glitchEnabled: false }) as NeonAnimationConfig }),
+        { id: 'artwork-1', type: 'artwork', artwork: { kind: 'library', id: 'star' }, size: 170, x: 1370, y: 300, rotation: 12, neon: { color: '#FFC24A' }, animation: { seed: 91 } },
+      ],
+      wall: { ambientColor: '#3A1F7A', ambient: 0.45, lightSpill: 1.2 },
+      audio: { hum: 0.55, failure: 0.7 },
+    },
+  },
+  {
+    id: 'cyber-blue', name: 'CYBER BLUE', description: 'Orbitron in electric blue with frequent digital glitches.',
+    scene: {
+      elements: [textEl('text-1', 'CYBER', 'orbitron', NEON_COLOR_PRESETS.blue, { animation: anim({ flickerIntensity: 0.12, flickerFrequency: 0.15, glitchIntensity: 0.6, glitchFrequency: 0.35, glitchRgbSplit: 1.6 }) as NeonAnimationConfig })],
+      wall: { ambientColor: '#0D3DD8', ambient: 0.6 },
+      audio: { glitch: 0.5 },
+    },
+  },
+  {
+    id: 'purple-night', name: 'PURPLE NIGHT', description: 'A handwritten “night” under a neon moon.',
+    scene: {
+      elements: [
+        textEl('text-1', 'night', 'sacramento', NEON_COLOR_PRESETS.purple, { y: 540, typography: { fontSize: 420, strokeWidth: 9 } as NeonTypography }),
+        { id: 'emoji-1', type: 'emoji', emoji: '🌙', size: 200, x: 1200, y: 290, neon: { color: '#E0B3FF' }, animation: { seed: 7356951 } },
+      ],
+      wall: { ambientColor: '#4A1FB8', ambient: 0.5 },
+    },
+  },
+  {
+    id: 'electric-green', name: 'ELECTRIC GREEN', description: 'Audiowide “24/7” with a bolt, both on one circuit.',
+    scene: {
+      elements: [
+        textEl('text-1', '24/7', 'audiowide', NEON_COLOR_PRESETS.green, { x: 700, animation: anim({ seed: 4242, flickerIntensity: 0.22, flickerFrequency: 0.3 }) as NeonAnimationConfig }),
+        { id: 'emoji-1', type: 'emoji', emoji: '⚡', size: 230, x: 1300, y: 480, neon: { color: '#F4FF3A' }, animation: { seed: 4242, flickerIntensity: 0.22, flickerFrequency: 0.3 } },
+      ],
+      wall: { ambientColor: '#123A7A', ambient: 0.5 },
+    },
+  },
+  {
+    id: 'warm-white', name: 'WARM WHITE', description: 'Tilt Neon “Hello” in warm white; nearly steady.',
+    scene: {
+      elements: [textEl('text-1', 'Hello', 'tilt-neon', { color: '#FFE3B8', coreColor: '#FFFFFF', tubeColor: '#FFE3B8', glowColor: '#FFC98A', bloomColor: '#C98A3A' }, { typography: { fontSize: 340, strokeWidth: 12 } as NeonTypography, animation: anim({ flickerIntensity: 0.06, flickerFrequency: 0.05, glitchEnabled: false }) as NeonAnimationConfig })],
+      wall: { ambientColor: '#2A2A6A', ambient: 0.4, lightSpill: 1.3 },
+      audio: { hum: 0.35 },
+    },
+  },
+];
+
+/* ---------- agent vocabulary ---------- */
+
+/** Named colours an agent can say. Each is a primary: glow, bloom and core derive from it. */
+export const NEON_NAMED_COLORS: Record<string, string> = {
+  red: NEON_COLOR_PRESETS.red.color, blue: NEON_COLOR_PRESETS.blue.color, purple: NEON_COLOR_PRESETS.purple.color, green: NEON_COLOR_PRESETS.green.color,
+  pink: '#FF4FB8', magenta: '#FF2BD6', cyan: '#2BF7FF', teal: '#1FFFD0', amber: '#FFB300', orange: '#FF7A1A', yellow: '#F4FF3A',
+  white: '#F2F6FF', 'warm white': '#FFE3B8', 'cool white': '#DDEBFF', violet: '#9C5BFF', lime: '#B6FF2B',
+};
+/** Flicker by word: "none" … "failing". */
+export const NEON_FLICKER_LEVELS: Record<string, Pick<NeonAnimationConfig, 'flickerEnabled' | 'flickerIntensity' | 'flickerFrequency'>> = {
+  none: { flickerEnabled: false, flickerIntensity: 0, flickerFrequency: 0 },
+  subtle: { flickerEnabled: true, flickerIntensity: 0.1, flickerFrequency: 0.06 },
+  medium: { flickerEnabled: true, flickerIntensity: 0.2, flickerFrequency: 0.2 },
+  heavy: { flickerEnabled: true, flickerIntensity: 0.3, flickerFrequency: 0.5 },
+  failing: { flickerEnabled: true, flickerIntensity: 0.6, flickerFrequency: 1.2 },
+};
+/** Glitch by word: "none" … "frequent". */
+export const NEON_GLITCH_LEVELS: Record<string, Pick<NeonAnimationConfig, 'glitchEnabled' | 'glitchIntensity' | 'glitchFrequency'>> = {
+  none: { glitchEnabled: false, glitchIntensity: 0, glitchFrequency: 0 },
+  rare: { glitchEnabled: true, glitchIntensity: 0.15, glitchFrequency: 0.03 },
+  occasional: { glitchEnabled: true, glitchIntensity: 0.3, glitchFrequency: 0.1 },
+  frequent: { glitchEnabled: true, glitchIntensity: 0.5, glitchFrequency: 0.35 },
+};
+
+/** A colour by name or hex. Unknown names come back undefined. */
+export function neonColor(nameOrHex: string): string | undefined {
+  if (isHexColor(nameOrHex)) return nameOrHex.toUpperCase();
+  return NEON_NAMED_COLORS[String(nameOrHex).trim().toLowerCase().replace(/[-_]+/g, ' ')];
+}
+
+export type NeonElementSpec = {
+  type?: NeonElementType;
+  text?: string;
+  emoji?: string;
+  /** A library artwork id ("heart"), or SVG markup. */
+  artwork?: string;
+  font?: string;
+  color?: string;
+  flicker?: keyof typeof NEON_FLICKER_LEVELS | string;
+  glitch?: keyof typeof NEON_GLITCH_LEVELS | string;
+  /** Next to an existing element, or at a point. */
+  placement?: 'right' | 'left' | 'above' | 'below' | 'center' | { x: number; y: number };
+  relativeTo?: string;
+  size?: number;
+  id?: string;
+};
+
+/** The element an agent described, as config. Unknown words are ignored, not guessed. */
+export function neonElementFromSpec(spec: NeonElementSpec, index = 0): NeonElementInput {
+  const type: NeonElementType = spec.type ?? (spec.emoji ? 'emoji' : spec.artwork ? 'artwork' : 'text');
+  const out: NeonElementInput = { type, id: spec.id ?? `${type}-${index + 1}` };
+  const color = spec.color ? neonColor(spec.color) : undefined;
+  if (color) out.neon = { color };
+  const flicker = spec.flicker ? NEON_FLICKER_LEVELS[spec.flicker] : undefined;
+  const glitch = spec.glitch ? NEON_GLITCH_LEVELS[spec.glitch] : undefined;
+  if (flicker || glitch) out.animation = { ...flicker, ...glitch };
+  if (type === 'text') {
+    out.text = spec.text ?? 'OPEN';
+    const font = spec.font ? findNeonFont(spec.font) : undefined;
+    const size = spec.size ?? 300;
+    out.typography = { fontSize: size, ...(font ? { fontFamily: font.family, fontWeight: font.weight, construction: font.construction, strokeWidth: Math.max(2, Math.round(size * font.stroke * 2) / 2) } : {}) };
+  } else if (type === 'emoji') {
+    out.emoji = spec.emoji ?? '⭐';
+    out.size = spec.size ?? 240;
+  } else {
+    const art = spec.artwork ?? 'heart';
+    out.artwork = NEON_ARTWORK_LIBRARY[art] ? { kind: 'library', id: art } : { kind: 'svg', svg: art };
+    out.size = spec.size ?? 260;
+  }
+  return out;
+}
+
+/**
+ * **“A blue neon sign saying OPEN in Orbitron, medium flicker, occasional glitch.”** Builds the
+ * scene from words an agent already has. Anything more specific goes straight into the JSON.
+ */
+export function createNeonScene(spec: NeonElementSpec & { elements?: NeonElementSpec[]; wall?: Partial<NeonWallConfig> } = {}): NeonScene {
+  let scene = resolveNeonScene({ elements: [neonElementFromSpec({ ...spec, type: 'text' }, 0)], wall: spec.wall });
+  for (const extra of spec.elements ?? []) scene = addNeonElement(scene, extra);
+  return scene;
+}
+
+/** **“Add a pink neon heart next to the text.”** Places the new element beside another, clear of it. */
+export function addNeonElement(scene: NeonScene, spec: NeonElementSpec, measure?: TextMeasurer): NeonScene {
+  const index = scene.elements.length;
+  const input = neonElementFromSpec(spec, index);
+  let id = String(input.id);
+  for (let n = 2; scene.elements.some((e) => e.id === id); n++) id = `${input.type}-${index + n}`;
+  const el = resolveNeonElement({ ...input, id }, index);
+  const anchor = scene.elements.find((e) => e.id === spec.relativeTo) ?? scene.elements[0];
+  const place = spec.placement ?? 'right';
+  let { x, y } = el;
+  if (typeof place === 'object') ({ x, y } = place);
+  else if (place === 'center') { x = scene.stage.width / 2; y = scene.stage.height / 2; }
+  else if (anchor) {
+    /* The asked-for side of the anchor first; then the other sides of every element; then a grid.
+       A spot must fit on the stage and not overlap anything already there. */
+    const self = elementGeometry({ ...el, x: 0, y: 0 }, measure).bounds;
+    const others = scene.elements.filter((e) => e.visible).map((e) => elementGeometry(e, measure).bounds);
+    const gap = 50;
+    const fits = (cx: number, cy: number) => {
+      const r = { x: cx - self.width / 2, y: cy - self.height / 2, width: self.width, height: self.height };
+      if (r.x < 10 || r.y < 10 || r.x + r.width > scene.stage.width - 10 || r.y + r.height > scene.stage.height - 10) return false;
+      return !others.some((o) => r.x < o.x + o.width + 12 && o.x < r.x + r.width + 12 && r.y < o.y + o.height + 12 && o.y < r.y + r.height + 12);
+    };
+    const around = (a: { x: number; y: number; width: number; height: number }, side: string): [number, number] => {
+      const ax = a.x + a.width / 2;
+      const ay = a.y + a.height / 2;
+      if (side === 'right') return [a.x + a.width + gap + self.width / 2, ay];
+      if (side === 'left') return [a.x - gap - self.width / 2, ay];
+      if (side === 'above') return [ax, a.y - gap - self.height / 2];
+      return [ax, a.y + a.height + gap + self.height / 2];
+    };
+    const anchorBox = elementGeometry(anchor, measure).bounds;
+    const sides = [place, ...['right', 'left', 'above', 'below'].filter((q) => q !== place)];
+    const candidates: [number, number][] = [
+      ...sides.map((q) => around(anchorBox, q)),
+      ...others.flatMap((o) => sides.map((q) => around(o, q))),
+    ];
+    for (let gy = 1; gy <= 5; gy++) for (let gx = 1; gx <= 7; gx++) candidates.push([(scene.stage.width * gx) / 8, (scene.stage.height * gy) / 6]);
+    const hit = candidates.find(([cx, cy]) => fits(cx, cy));
+    [x, y] = hit ?? around(anchorBox, place);
+  }
+  return { ...scene, elements: [...scene.elements, { ...el, x: r3(x), y: r3(y) }] };
+}
+
+/** The single-sign config (`NeonTextConfig`) as a scene with one text element on the wall. */
+export function neonSceneFromText(config: { text: string; typography: NeonTypography; neon: NeonMaterialConfig; animation: NeonAnimationConfig }): NeonScene {
+  return resolveNeonScene({ elements: [{ type: 'text', id: 'text-1', text: config.text, typography: config.typography, neon: config.neon, animation: config.animation }] });
+}