@appinternalleads/ui 0.4.0 → 0.4.1

package/src/motion/neon/flicker.ts

@@ -0,0 +1,225 @@
+import type { NeonAnimationConfig } from './config';
+import { rand, valueNoise } from './random';
+
+/**
+ * **The flicker controller: tube brightness as a pure function of time.** Not an opacity loop: the
+ * brightness is the product of a constant low shimmer and rare, randomly placed electrical events,
+ * and each layer responds to it differently.
+ *
+ *   shimmer   always on, 95–103 %: two octaves of smooth noise (gas and supply ripple)
+ *   sag       0.3–0.9 s, down to 85–100 %: a soft, slightly rippled droop        (62 % of events)
+ *   flicker   0.12–0.32 s, two to four quick 20–40 ms blinks to 70–88 %          (16 %)
+ *   dip       80–260 ms, down to 40–80 %: fast fall, one or two stutters          (15 %)
+ *   failure   0.2–0.65 s, down to 20–50 %: the arc chatters on and off, then
+ *             re-strikes with a brief 3 % overshoot                               (7 %)
+ *
+ * After a dip or failure the tube recovers along an exponential tail whose length is set by
+ * `flickerRecovery` (0 → ≈ 300 ms, 1 → instant). `flickerRandomness` 0 plays every event at its
+ * typical depth and length on an even grid; 1 varies them fully. `flickerMinBrightness` is a floor.
+ *
+ * Events start at random moments: time is cut into 100 ms slots and each slot starts an event with
+ * probability `flickerFrequency × 0.1`. Every decision is a hash of (seed, slot), so there is no
+ * loop to notice and any moment can be computed on its own. Triggers (`NeonTrigger`) add events at
+ * chosen times — the playground's buttons, or a scripted timeline — just as deterministically.
+ *
+ * Depths are the brief's ranges at `flickerIntensity` 0.25, scaled linearly by intensity (0 = steady).
+ *
+ * Layer response (tube dims → core a little → glow → bloom, which lags):
+ *   tube  = b                          core  = b^0.75 (dims less than the tube)
+ *   glow  = mean(b over 50 ms)^1.3     bloom = mean(b over 120 ms, delayed)^1.8
+ */
+export type FlickerKind = 'sag' | 'flicker' | 'dip' | 'failure';
+export const FLICKER_KINDS: readonly FlickerKind[] = ['sag', 'flicker', 'dip', 'failure'];
+export type FlickerEvent = { kind: FlickerKind; start: number; duration: number; depth: number; slot: number; forced?: boolean };
+export type FlickerLevels = { brightness: number; tube: number; core: number; glow: number; bloom: number; event: FlickerKind | null };
+
+/**
+ * An event placed on purpose, at `at` ms of the caller's clock (the same clock as `timeMs`).
+ * `normal` holds the sign steady for `NORMAL_HOLD_MS` and cancels anything already playing.
+ */
+export type NeonTriggerKind = FlickerKind | 'glitch' | 'normal';
+export type NeonTrigger = { kind: NeonTriggerKind; at: number };
+export const NORMAL_HOLD_MS = 3000;
+
+const SLOT = 100;
+const MAX_DURATION = 650;
+const OVERSHOOT = 160;
+const SALT = { starts: 11, offset: 12, kind: 13, duration: 14, depth: 15, shape: 16 };
+const RANGES: Record<FlickerKind, { duration: [number, number]; depth: [number, number] }> = {
+  sag: { duration: [300, 900], depth: [0.03, 0.15] },
+  flicker: { duration: [120, 320], depth: [0.12, 0.3] },
+  dip: { duration: [80, 260], depth: [0.2, 0.6] },
+  failure: { duration: [200, MAX_DURATION], depth: [0.5, 0.8] },
+};
+
+/** The reference intensity at which the brief's ranges play exactly. */
+export const FLICKER_REFERENCE_INTENSITY = 0.25;
+
+/** A value in [lo, hi]: the middle at randomness 0, anywhere at randomness 1. */
+function spread([lo, hi]: [number, number], u: number, randomness: number): number {
+  const mid = (lo + hi) / 2;
+  return mid + (u - 0.5) * (hi - lo) * Math.max(0, Math.min(1, randomness));
+}
+
+/** The recovery tail's time constant, ms. */
+const tailTau = (a: NeonAnimationConfig) => 12 + 290 * (1 - Math.max(0, Math.min(1, a.flickerRecovery ?? 0.7)));
+const hasTail = (k: FlickerKind) => k === 'dip' || k === 'failure';
+/** How long after its end an event still pulls (tail and overshoot). */
+const afterglow = (a: NeonAnimationConfig, e: FlickerEvent) => (hasTail(e.kind) ? Math.max(tailTau(a) * 5, e.kind === 'failure' ? OVERSHOOT : 0) : 0);
+
+function makeEvent(a: NeonAnimationConfig, kind: FlickerKind, start: number, slot: number, forced = false): FlickerEvent {
+  const r = a.flickerRandomness ?? 0.6;
+  const range = RANGES[kind];
+  return {
+    kind, start, slot, forced,
+    duration: spread(range.duration, rand(a.seed, slot, SALT.duration), r),
+    depth: spread(range.depth, rand(a.seed, slot, SALT.depth), r),
+  };
+}
+
+/** The event that starts in `slot`, if any. */
+export function flickerEventInSlot(a: NeonAnimationConfig, slot: number): FlickerEvent | null {
+  const p = Math.min(0.9, Math.max(0, a.flickerFrequency) * (SLOT / 1000));
+  if (p <= 0 || rand(a.seed, slot, SALT.starts) >= p) return null;
+  const jitter = 0.5 + (rand(a.seed, slot, SALT.offset) - 0.5) * Math.max(0, Math.min(1, a.flickerRandomness ?? 0.6));
+  const k = rand(a.seed, slot, SALT.kind);
+  const kind: FlickerKind = k < 0.62 ? 'sag' : k < 0.78 ? 'flicker' : k < 0.93 ? 'dip' : 'failure';
+  return makeEvent(a, kind, slot * SLOT + jitter * SLOT, slot);
+}
+
+/** Trigger events for the flicker, in flicker time (`toFlicker` maps the caller's clock). */
+function forcedEvents(a: NeonAnimationConfig, triggers: readonly NeonTrigger[] | undefined, toFlicker: (ms: number) => number): FlickerEvent[] {
+  if (!triggers?.length) return [];
+  return triggers.flatMap((tr, i) => (tr.kind === 'glitch' || tr.kind === 'normal' ? [] : [makeEvent(a, tr.kind, toFlicker(tr.at), -1_000_003 - i * 7, true)]));
+}
+
+/** The latest `normal` hold covering flicker time `t`, as [start, end] in flicker time. */
+function normalHold(triggers: readonly NeonTrigger[] | undefined, toFlicker: (ms: number) => number, t: number): [number, number] | null {
+  let hold: [number, number] | null = null;
+  for (const tr of triggers ?? []) {
+    if (tr.kind !== 'normal') continue;
+    const s = toFlicker(tr.at);
+    const e = toFlicker(tr.at + NORMAL_HOLD_MS);
+    if (t >= s && t < e && (!hold || s > hold[0])) hold = [s, e];
+  }
+  return hold;
+}
+
+/** Every event whose effect (including its recovery tail) covers flicker time `t`. */
+export function flickerEventsAt(a: NeonAnimationConfig, t: number, triggers?: readonly NeonTrigger[], toFlicker: (ms: number) => number = (ms) => ms): FlickerEvent[] {
+  const hold = normalHold(triggers, toFlicker, t);
+  const covers = (e: FlickerEvent) => t >= e.start && t < e.start + e.duration + afterglow(a, e) && (!hold || e.start >= hold[0]);
+  const out: FlickerEvent[] = [];
+  if (!hold) {
+    const back = Math.ceil((MAX_DURATION + Math.max(OVERSHOOT, tailTau(a) * 5)) / SLOT) + 1;
+    const now = Math.floor(t / SLOT);
+    for (let s = now - back; s <= now; s++) {
+      const e = flickerEventInSlot(a, s);
+      if (e && covers(e)) out.push(e);
+    }
+  }
+  for (const e of forcedEvents(a, triggers, toFlicker)) if (covers(e)) out.push(e);
+  return out;
+}
+
+const smooth = (x: number) => (x <= 0 ? 0 : x >= 1 ? 1 : x * x * (3 - 2 * x));
+
+/** How far (0…1 of its depth) event `e` pulls the brightness down at `t`; negative is an overshoot. */
+function eventPull(a: NeonAnimationConfig, e: FlickerEvent, t: number): number {
+  const u = (t - e.start) / e.duration;
+  if (u >= 1) {
+    if (!hasTail(e.kind)) return 0;
+    const after = t - e.start - e.duration;
+    const tail = (e.kind === 'failure' ? 0.5 : 0.35) * Math.exp(-after / tailTau(a));
+    const over = e.kind === 'failure' && after < OVERSHOOT ? (0.03 / e.depth) * Math.sin(Math.PI * (after / OVERSHOOT)) : 0;
+    return tail - over;
+  }
+  if (e.kind === 'sag') {
+    const env = Math.pow(Math.sin(Math.PI * Math.min(1, Math.max(0, u))), 1.5);
+    return env * (0.85 + 0.15 * Math.sin(u * Math.PI * 6));
+  }
+  if (e.kind === 'flicker') {
+    /* Two to four quick blinks: 20–40 ms chunks alternating off and on. */
+    const len = 20 + 20 * rand(a.seed, e.slot, SALT.shape, 998);
+    const chunk = Math.floor((t - e.start) / len);
+    return chunk % 2 === 0 ? 0.6 + 0.4 * rand(a.seed, e.slot, SALT.shape, chunk) : 0.05;
+  }
+  if (e.kind === 'dip') {
+    if (u < 0.15) return smooth(u / 0.15);
+    if (u > 0.7) return 1 - smooth((u - 0.7) / 0.3) * 0.65;
+    /* One or two stutters: 25 ms chunks that partly recover. */
+    const chunk = Math.floor((t - e.start) / 25);
+    return rand(a.seed, e.slot, SALT.shape, chunk) < 0.3 ? 0.55 : 1;
+  }
+  /* failure */
+  if (u < 0.06) return smooth(u / 0.06);
+  if (u > 0.88) return 1 - smooth((u - 0.88) / 0.12) * 0.5;
+  /* The arc chatters: 16–33 ms chunks, each either out (full depth) or half re-struck. */
+  const chunk = Math.floor((t - e.start) / (16 + 17 * rand(a.seed, e.slot, SALT.shape, 999)));
+  const r = rand(a.seed, e.slot, SALT.shape, chunk);
+  return r < 0.55 ? 1 : r < 0.85 ? 0.45 : 0.15;
+}
+
+/** Tube brightness at flicker time `t`. 1 is nominal; it can reach ~1.03. */
+export function tubeBrightness(a: NeonAnimationConfig, t: number, triggers?: readonly NeonTrigger[], toFlicker?: (ms: number) => number): number {
+  const k = Math.max(0, a.flickerIntensity) / FLICKER_REFERENCE_INTENSITY;
+  const floor = Math.max(0, Math.min(1, a.flickerMinBrightness ?? 0.05));
+  const forced = !!triggers?.some((tr) => tr.kind !== 'glitch');
+  if ((!a.flickerEnabled || k === 0) && !forced) return 1;
+  /* Triggers always play at least at the reference depth, so a button press is visible even with a gentle sign. */
+  const kEvents = Math.max(k, forced ? 1 : 0);
+  const amp = a.flickerEnabled ? 0.04 * Math.min(k, 1.5) * (0.5 + 0.833 * Math.max(0, Math.min(1, a.flickerRandomness ?? 0.6))) : 0;
+  let b = 1 - amp * 0.25 + amp * (0.6 * valueNoise(a.seed, t / 140, 1) + 0.4 * valueNoise(a.seed, t / 43, 2));
+  for (const e of flickerEventsAt(a, t, triggers, toFlicker)) {
+    if (!e.forced && (!a.flickerEnabled || k === 0)) continue;
+    const depth = Math.min(0.95, e.depth * (e.forced ? kEvents : k));
+    b *= 1 - depth * eventPull(a, e, t);
+  }
+  return Math.max(floor, Math.max(0.02, b));
+}
+
+/** The flicker's time: animation time × `flickerSpeed`. */
+export const flickerTime = (a: NeonAnimationConfig, t: number) => t * Math.max(0.01, a.flickerSpeed);
+
+/**
+ * Every layer's brightness at animation time `t` (ms, already × speed). `toFlicker` maps a trigger's
+ * clock time to flicker time; `neonFrame` supplies it.
+ */
+export function flickerLevels(a: NeonAnimationConfig, t: number, triggers?: readonly NeonTrigger[], toFlicker?: (ms: number) => number): FlickerLevels {
+  const live = a.enabled && (a.flickerEnabled && a.flickerIntensity > 0 || !!triggers?.some((tr) => tr.kind !== 'glitch' && tr.kind !== 'normal'));
+  if (!live) return { brightness: 1, tube: 1, core: 1, glow: 1, bloom: 1, event: null };
+  const ft = flickerTime(a, t);
+  const map = toFlicker ?? ((ms: number) => flickerTime(a, ms));
+  const at = (dt: number) => tubeBrightness(a, ft - dt, triggers, map);
+  const b = at(0);
+  const glow = (b + at(25) + at(50)) / 3;
+  const bloom = (at(20) + at(45) + at(70) + at(95) + at(120)) / 5;
+  const events = flickerEventsAt(a, ft, triggers, map).filter((e) => ft < e.start + e.duration);
+  const rank: Record<FlickerKind, number> = { failure: 4, dip: 3, flicker: 2, sag: 1 };
+  const worst = events.sort((x, y) => rank[y.kind] - rank[x.kind] || y.depth - x.depth)[0];
+  return { brightness: b, tube: b, core: Math.pow(b, 0.75), glow: Math.pow(glow, 1.3), bloom: Math.pow(bloom, 1.8), event: worst?.kind ?? null };
+}
+
+/**
+ * **Event starts and ends between two flicker times**, for sound: each flicker event's start, and
+ * each dip's or failure's end (the re-strike). Ordered by time.
+ */
+export type FlickerCue = { kind: FlickerKind | 'restore'; at: number; depth: number };
+export function flickerCuesBetween(a: NeonAnimationConfig, t0: number, t1: number, triggers?: readonly NeonTrigger[], toFlicker: (ms: number) => number = (ms) => ms): FlickerCue[] {
+  if (!(t1 > t0)) return [];
+  const out: FlickerCue[] = [];
+  const push = (e: FlickerEvent) => {
+    if (e.start >= t0 && e.start < t1) out.push({ kind: e.kind, at: e.start, depth: e.depth });
+    const end = e.start + e.duration;
+    if (hasTail(e.kind) && end >= t0 && end < t1) out.push({ kind: 'restore', at: end, depth: e.depth });
+  };
+  const hold = (t: number) => normalHold(triggers, toFlicker, t);
+  if (a.flickerEnabled && a.flickerIntensity > 0 && t1 - t0 < 120_000) {
+    for (let s = Math.floor((t0 - MAX_DURATION) / SLOT); s <= Math.floor(t1 / SLOT); s++) {
+      const e = flickerEventInSlot(a, s);
+      if (e && !hold(e.start)) push(e);
+    }
+  }
+  for (const e of forcedEvents(a, triggers, toFlicker)) push(e);
+  return out.sort((x, y) => x.at - y.at);
+}

package/src/motion/neon/fonts.ts

@@ -0,0 +1,76 @@
+import type { NeonConstruction } from './config';
+
+/**
+ * **Fonts that suit neon, by name.** Every entry is an open-licence (OFL) Google Font, so an agent
+ * can say "Orbitron" and a page can load exactly that. Each carries the construction and weight it
+ * reads best in: bold and display faces as `outline` tubes, thin and rounded faces as `monoline`.
+ * Nothing here loads a font: the page does, with `neonGoogleFontsUrl`.
+ */
+export type NeonFontCategory =
+  | 'neon tube' | 'retro' | 'condensed' | 'geometric' | 'rounded' | 'bold' | 'thin' | 'futuristic'
+  | 'handwritten' | 'display' | 'monospace' | 'signage' | 'industrial' | 'arcade' | 'elegant' | 'system';
+
+export type NeonFont = {
+  id: string;
+  name: string;
+  category: NeonFontCategory;
+  /** The CSS font-family list (the named face first, then sensible fallbacks). */
+  family: string;
+  /** The Google Fonts `family=` value that loads it (null: a system face). */
+  google: string | null;
+  weight: number;
+  construction: NeonConstruction;
+  /** Tube width as a fraction of the font size, for this face. */
+  stroke: number;
+};
+
+const f = (id: string, name: string, category: NeonFontCategory, fallback: string, google: string | null, weight: number, construction: NeonConstruction, stroke: number): NeonFont =>
+  ({ id, name, category, family: google ? `'${name}', ${fallback}` : fallback, google, weight, construction, stroke });
+
+export const NEON_FONTS: NeonFont[] = [
+  f('tilt-neon', 'Tilt Neon', 'neon tube', 'Quicksand, sans-serif', 'Tilt+Neon', 400, 'monoline', 0.04),
+  f('bebas-neue', 'Bebas Neue', 'condensed', "Oswald, 'Arial Narrow', sans-serif", 'Bebas+Neue', 400, 'outline', 0.033),
+  f('anton', 'Anton', 'bold', "'Arial Narrow', Impact, sans-serif", 'Anton', 400, 'outline', 0.03),
+  f('oswald', 'Oswald', 'condensed', "'Arial Narrow', 'Helvetica Neue', Arial, sans-serif", 'Oswald:wght@300;400;500;600;700', 500, 'outline', 0.036),
+  f('space-grotesk', 'Space Grotesk', 'geometric', "'Helvetica Neue', Arial, sans-serif", 'Space+Grotesk:wght@400;500;700', 500, 'outline', 0.033),
+  f('orbitron', 'Orbitron', 'futuristic', "'Eurostile', sans-serif", 'Orbitron:wght@400;600;800', 600, 'outline', 0.03),
+  f('audiowide', 'Audiowide', 'futuristic', 'sans-serif', 'Audiowide', 400, 'outline', 0.03),
+  f('russo-one', 'Russo One', 'signage', "Impact, 'Arial Black', sans-serif", 'Russo+One', 400, 'outline', 0.03),
+  f('rajdhani', 'Rajdhani', 'industrial', "'Arial Narrow', sans-serif", 'Rajdhani:wght@500;600;700', 600, 'outline', 0.033),
+  f('exo-2', 'Exo 2', 'futuristic', 'sans-serif', 'Exo+2:wght@300;500;700', 500, 'outline', 0.033),
+  f('montserrat', 'Montserrat', 'geometric', "'Helvetica Neue', Arial, sans-serif", 'Montserrat:wght@300;500;700', 500, 'outline', 0.033),
+  f('inter', 'Inter', 'geometric', "system-ui, 'Helvetica Neue', Arial, sans-serif", 'Inter:wght@300;500;700', 500, 'outline', 0.033),
+  f('archivo', 'Archivo', 'signage', "'Helvetica Neue', Arial, sans-serif", 'Archivo:wght@400;600;800', 600, 'outline', 0.033),
+  f('barlow-condensed', 'Barlow Condensed', 'condensed', "'Arial Narrow', sans-serif", 'Barlow+Condensed:wght@400;600', 600, 'outline', 0.034),
+  f('sora', 'Sora', 'geometric', 'sans-serif', 'Sora:wght@300;500;700', 500, 'outline', 0.033),
+  f('raleway', 'Raleway', 'thin', "'Helvetica Neue', sans-serif", 'Raleway:wght@200;300;500', 300, 'monoline', 0.03),
+  f('press-start-2p', 'Press Start 2P', 'arcade', "'Courier New', monospace", 'Press+Start+2P', 400, 'outline', 0.03),
+  f('pacifico', 'Pacifico', 'handwritten', "'Brush Script MT', cursive", 'Pacifico', 400, 'outline', 0.026),
+  f('dm-sans', 'DM Sans', 'rounded', "'Helvetica Neue', Arial, sans-serif", 'DM+Sans:wght@300;500;700', 500, 'outline', 0.033),
+  f('quicksand', 'Quicksand', 'rounded', "'Arial Rounded MT Bold', 'Helvetica Neue', Arial, sans-serif", 'Quicksand:wght@300;400;500;600;700', 500, 'monoline', 0.045),
+  f('sacramento', 'Sacramento', 'handwritten', "'Snell Roundhand', 'Brush Script MT', cursive", 'Sacramento', 400, 'monoline', 0.03),
+  f('righteous', 'Righteous', 'retro', 'sans-serif', 'Righteous', 400, 'outline', 0.03),
+  f('space-mono', 'Space Mono', 'monospace', "'Courier New', monospace", 'Space+Mono:wght@400;700', 400, 'monoline', 0.03),
+  f('great-vibes', 'Great Vibes', 'elegant', "'Snell Roundhand', cursive", 'Great+Vibes', 400, 'monoline', 0.022),
+  f('black-ops-one', 'Black Ops One', 'industrial', "Impact, sans-serif", 'Black+Ops+One', 400, 'outline', 0.026),
+  f('monoton', 'Monoton', 'display', 'sans-serif', 'Monoton', 400, 'monoline', 0.008),
+  f('system', 'System', 'system', "system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif", null, 600, 'outline', 0.033),
+];
+
+/** The monochrome emoji face: vector outlines, so an emoji can be bent into a tube like a letter. */
+export const NEON_EMOJI_FONT: NeonFont = f('noto-emoji', 'Noto Emoji', 'display', 'sans-serif', 'Noto+Emoji:wght@400;500;700', 500, 'outline', 0.03);
+
+/** Find a font by id, name or family, case-insensitively ("Orbitron", "orbitron", "Bebas"). */
+export function findNeonFont(query: string): NeonFont | undefined {
+  const q = query.trim().toLowerCase().replace(/[-_]+/g, ' ');
+  if (!q) return undefined;
+  return NEON_FONTS.find((x) => x.id.replace(/-/g, ' ') === q || x.name.toLowerCase() === q)
+    ?? NEON_FONTS.find((x) => x.name.toLowerCase().startsWith(q) || x.family.toLowerCase().startsWith(`'${q}`))
+    ?? NEON_FONTS.find((x) => x.name.toLowerCase().includes(q));
+}
+
+/** One Google Fonts stylesheet URL for these fonts (default: all of them, plus Noto Emoji). */
+export function neonGoogleFontsUrl(fonts: NeonFont[] = [...NEON_FONTS, NEON_EMOJI_FONT]): string {
+  const families = [...new Set(fonts.map((x) => x.google).filter((g): g is string => !!g))];
+  return `https://fonts.googleapis.com/css2?${families.map((g) => `family=${g}`).join('&')}&display=swap`;
+}

package/src/motion/neon/frame.ts

@@ -0,0 +1,34 @@
+import type { NeonTextConfig } from './config';
+import { flickerLevels, type FlickerLevels, type NeonTrigger } from './flicker';
+import { glitchAt, type GlitchState } from './glitch';
+
+/**
+ * **One frame of the sign's state** — what the renderer needs from the animation at `timeMs`:
+ * each layer's brightness (flicker) and the glitch, if one is playing. Pure: the same config, time
+ * and triggers always give the same frame, so the caller owns the clock (Remotion passes
+ * frame / fps × 1000) and a timeline can be scrubbed backwards and forwards.
+ *
+ * `triggers` are events placed on purpose at clock times (`timeMs` units): a button press, or a
+ * scripted moment. They play whatever the frequencies say.
+ */
+export type NeonFrame = { timeMs: number; levels: FlickerLevels; glitch: GlitchState | null };
+
+export const STEADY_LEVELS: FlickerLevels = { brightness: 1, tube: 1, core: 1, glow: 1, bloom: 1, event: null };
+
+type Timed = Pick<NeonTextConfig, 'animation'>;
+
+export function neonFrame(config: Timed, timeMs: number, triggers?: readonly NeonTrigger[]): NeonFrame {
+  const a = config.animation;
+  if (!a.enabled || !Number.isFinite(timeMs)) return { timeMs, levels: STEADY_LEVELS, glitch: null };
+  const speed = Math.max(0, a.speed);
+  const fs = Math.max(0.01, a.flickerSpeed);
+  const t = timeMs * speed;
+  const glitch = glitchAt(a, t, triggers, (ms) => ms * speed);
+  const levels = flickerLevels(a, t, triggers, (ms) => ms * speed * fs);
+  /* A glitch that loses brightness pulls the tube and its light down with it. */
+  if (glitch && glitch.keep < 1) {
+    const k = glitch.keep;
+    return { timeMs, levels: { ...levels, tube: levels.tube * k, core: levels.core * (0.5 + 0.5 * k), glow: levels.glow * k, bloom: levels.bloom * (0.7 + 0.3 * k) }, glitch };
+  }
+  return { timeMs, levels, glitch };
+}

package/src/motion/neon/glitch.ts

@@ -0,0 +1,142 @@
+import type { NeonAnimationConfig } from './config';
+import { NORMAL_HOLD_MS, type NeonTrigger } from './flicker';
+import { between, rand } from './random';
+
+/**
+ * **The glitch controller: independent of the flicker, and silent most of the time.** Time is cut
+ * into 250 ms slots; each starts a glitch with probability `glitchFrequency × 0.25`, lasting about
+ * `glitchDuration` (×0.6–1.4). Inside a glitch the picture changes in 45 ms steps (a glitch steps; it
+ * doesn't ease), and each step draws a few of:
+ *
+ *   - a small horizontal shift of the whole sign (≤ 0.035 em at intensity 1)
+ *   - one to three horizontal slices shifted sideways (≤ 0.09 em), some dimmed
+ *   - an RGB split: red and cyan ghosts of the tube, either side (≤ 0.025 em)
+ *   - the glow and bloom slipping behind the tube (glow separation)
+ *   - one thin scanline band torn further than the slices
+ *   - a partial brightness loss
+ *
+ * About one step in four is quiet, so a glitch stutters. Everything scales with `glitchIntensity`;
+ * the caps keep the words readable. `glitchDisplacement`, `glitchRgbSplit`, `glitchSlices` and
+ * `glitchGlowSeparation` scale each part (0…2). Offsets are in em (× fontSize at render).
+ *
+ * A `glitch` trigger plays one glitch at its time, whatever the frequency; a `normal` trigger
+ * silences random glitches for `NORMAL_HOLD_MS`.
+ */
+export type GlitchSlice = {
+  /** Top and height as fractions of the letters' box. */
+  y: number;
+  h: number;
+  /** Sideways shift, em. */
+  dx: number;
+  /** Brightness kept, 0…1. */
+  keep: number;
+};
+export type GlitchState = {
+  /** Whole-sign shift, em. */
+  shiftX: number;
+  slices: GlitchSlice[];
+  /** RGB ghost offset, em (0 → none). */
+  rgbSplit: number;
+  /** Glow and bloom offset relative to the tube, em. */
+  glowShiftX: number;
+  /** Brightness kept by the whole sign, 0…1. */
+  keep: number;
+  /** 0…1 through the glitch. */
+  progress: number;
+};
+
+const SLOT = 250;
+const STEP = 45;
+const SALT = { starts: 21, offset: 22, duration: 23, step: 24 };
+
+export type GlitchEvent = { start: number; duration: number; slot: number; forced?: boolean };
+
+export function glitchEventInSlot(a: NeonAnimationConfig, slot: number): GlitchEvent | null {
+  const p = Math.min(0.9, Math.max(0, a.glitchFrequency) * (SLOT / 1000));
+  if (p <= 0 || rand(a.seed, slot, SALT.starts) >= p) return null;
+  return {
+    start: slot * SLOT + rand(a.seed, slot, SALT.offset) * SLOT,
+    duration: Math.max(20, a.glitchDuration) * between(0.6, 1.4, a.seed, slot, SALT.duration),
+    slot,
+  };
+}
+
+/**
+ * The glitch playing at animation time `t`, if any. `toAnim` maps a trigger's clock time to
+ * animation time (× speed); `neonFrame` supplies it.
+ */
+export function glitchEventAt(a: NeonAnimationConfig, t: number, triggers?: readonly NeonTrigger[], toAnim: (ms: number) => number = (ms) => ms): GlitchEvent | null {
+  let forced: GlitchEvent | null = null;
+  let hold = false;
+  (triggers ?? []).forEach((tr, i) => {
+    const s = toAnim(tr.at);
+    if (tr.kind === 'normal' && t >= s && t < toAnim(tr.at + NORMAL_HOLD_MS)) hold = true;
+    if (tr.kind !== 'glitch') return;
+    const e = { start: s, duration: Math.max(60, a.glitchDuration) * 1.2, slot: -2_000_017 - i * 11, forced: true };
+    if (t >= e.start && t < e.start + e.duration && (!forced || e.start > forced.start)) forced = e;
+  });
+  if (forced) return forced;
+  if (hold) return null;
+  const now = Math.floor(t / SLOT);
+  const back = Math.ceil((Math.max(20, a.glitchDuration) * 1.4) / SLOT) + 1;
+  for (let s = now; s >= now - back; s--) {
+    const e = glitchEventInSlot(a, s);
+    if (e && t >= e.start && t < e.start + e.duration) return e;
+  }
+  return null;
+}
+
+/** The glitch at time `t` (ms of animation time), or null — which is almost always. */
+export function glitchAt(a: NeonAnimationConfig, t: number, triggers?: readonly NeonTrigger[], toAnim?: (ms: number) => number): GlitchState | null {
+  if (!a.enabled) return null;
+  const random = a.glitchEnabled && a.glitchIntensity > 0;
+  const hasForced = !!triggers?.some((tr) => tr.kind === 'glitch');
+  if (!random && !hasForced) return null;
+  const e = glitchEventAt(a, t, triggers, toAnim);
+  if (!e || (!e.forced && !random)) return null;
+  /* A triggered glitch is always visible, even on a sign set to glitch gently. */
+  const I = Math.min(1, Math.max(e.forced ? 0.5 : 0, Math.max(0, a.glitchIntensity)));
+  const step = Math.floor((t - e.start) / STEP);
+  const r = (salt: number) => rand(a.seed, e.slot, SALT.step + salt, step);
+  const progress = (t - e.start) / e.duration;
+  if (r(0) < 0.25) return { shiftX: 0, slices: [], rgbSplit: 0, glowShiftX: 0, keep: 1, progress };
+  const sign = (salt: number) => (r(salt) < 0.5 ? -1 : 1);
+  const k = (v: number | undefined) => Math.max(0, Math.min(2, v ?? 1));
+  const [kShift, kRgb, kSlice, kGlow] = [k(a.glitchDisplacement), k(a.glitchRgbSplit), k(a.glitchSlices), k(a.glitchGlowSeparation)];
+  const shiftX = sign(1) * r(2) * 0.035 * I * kShift;
+  const count = r(3) < 0.35 ? 0 : 1 + Math.floor(r(4) * (1 + 2 * I));
+  const slices: GlitchSlice[] = [];
+  for (let i = 0; i < count; i++) {
+    const h = 0.06 + r(10 + i) * 0.16;
+    slices.push({ y: r(20 + i) * (1 - h), h, dx: sign(30 + i) * (0.02 + r(40 + i) * 0.07) * I * kSlice, keep: r(50 + i) < 0.4 ? 0.45 + 0.4 * r(60 + i) : 1 });
+  }
+  /* A scanline: one thin band, torn further. */
+  if (r(5) < 0.45) slices.push({ y: r(6) * 0.97, h: 0.012 + r(7) * 0.02, dx: sign(8) * (0.06 + 0.06 * r(9)) * I * kSlice, keep: 0.8 });
+  return {
+    shiftX,
+    slices,
+    rgbSplit: r(70) < 0.6 ? (0.008 + 0.017 * r(71)) * I * kRgb : 0,
+    glowShiftX: r(72) < 0.5 ? (-shiftX * 0.8 - sign(73) * 0.01 * I) * kGlow : 0,
+    keep: 1 - 0.3 * I * r(74),
+    progress,
+  };
+}
+
+/** Glitch starts between two animation times (random and triggered), for sound. */
+export function glitchCuesBetween(a: NeonAnimationConfig, t0: number, t1: number, triggers?: readonly NeonTrigger[], toAnim: (ms: number) => number = (ms) => ms): { at: number; duration: number }[] {
+  if (!(t1 > t0) || !a.enabled) return [];
+  const out: { at: number; duration: number }[] = [];
+  const held = (t: number) => (triggers ?? []).some((tr) => tr.kind === 'normal' && t >= toAnim(tr.at) && t < toAnim(tr.at + NORMAL_HOLD_MS));
+  if (a.glitchEnabled && a.glitchIntensity > 0 && t1 - t0 < 120_000) {
+    for (let s = Math.floor(t0 / SLOT); s <= Math.floor(t1 / SLOT); s++) {
+      const e = glitchEventInSlot(a, s);
+      if (e && e.start >= t0 && e.start < t1 && !held(e.start)) out.push({ at: e.start, duration: e.duration });
+    }
+  }
+  for (const tr of triggers ?? []) {
+    if (tr.kind !== 'glitch') continue;
+    const s = toAnim(tr.at);
+    if (s >= t0 && s < t1) out.push({ at: s, duration: Math.max(60, a.glitchDuration) * 1.2 });
+  }
+  return out.sort((x, y) => x.at - y.at);
+}

package/src/motion/neon/index.ts

@@ -0,0 +1,41 @@
+/**
+ * **Neon text** — a reusable neon-sign typography primitive. Any text, any loaded font, any colour;
+ * five light layers with a sharp tube and core; seeded electrical flicker and occasional glitches.
+ * Reference: Vecteezy 7356951 (typography only). `docs/NEON-TEXT.md`.
+ *
+ *   text → Typography → NeonMaterial → FlickerController + GlitchController → GlowRenderer
+ */
+export {
+  DEFAULT_NEON_CONFIG, NEON_COLOR_PRESETS, NEON_TEXT_PRESETS, NEON_CONTROLS, NEON_CONSTRUCTIONS, NEON_ALIGNS, NEON_SHORTHAND_KEYS, MAX_NEON_TEXT_LENGTH,
+  resolveNeonConfig, sanitizeNeonConfig, validateNeonConfig, shorthandToConfig, deriveNeonPalette, neonColors, isHexColor, mixHex, getPath, setPath,
+  type NeonTextConfig, type NeonTextConfigInput, type NeonTextShorthand, type NeonTypography, type NeonMaterialConfig, type NeonAnimationConfig,
+  type NeonShadow, type NeonConstruction, type NeonAlign, type NeonColorPreset, type NeonColorPresetId, type NeonTextPresetId, type NeonControl,
+  type NeonConfigError,
+} from './config';
+export { layoutText, textRows, estimateTextWidth, fontShorthand, type NeonLayout, type NeonRow, type TextMeasurer } from './typography';
+export { resolveMaterial, materialPad, NEON_LAYERS, type NeonMaterial, type NeonLayerId } from './material';
+export { flickerLevels, tubeBrightness, flickerEventsAt, flickerEventInSlot, FLICKER_REFERENCE_INTENSITY, type FlickerLevels, type FlickerEvent, type FlickerKind } from './flicker';
+export { glitchAt, glitchEventAt, glitchEventInSlot, type GlitchState, type GlitchSlice, type GlitchEvent } from './glitch';
+export { neonFrame, STEADY_LEVELS, type NeonFrame } from './frame';
+export { GlowRenderer, type GlowRendererProps } from './GlowRenderer';
+export { NeonTextFrame, type NeonTextFrameProps } from './NeonTextFrame';
+export { NeonText, createCanvasMeasurer, type NeonTextProps } from './NeonText';
+export { NeonLayers, NEON_LAYER_ORDER, type NeonLayersProps, type NeonSource } from './layers';
+export { NeonTextGlyphs } from './GlowRenderer';
+export { flickerCuesBetween, flickerTime, FLICKER_KINDS, NORMAL_HOLD_MS, type NeonTrigger, type NeonTriggerKind, type FlickerCue } from './flicker';
+export { glitchCuesBetween } from './glitch';
+export { NEON_FONTS, NEON_EMOJI_FONT, findNeonFont, neonGoogleFontsUrl, type NeonFont, type NeonFontCategory } from './fonts';
+export { parseSvgArtwork, NEON_ARTWORK_LIBRARY, type ParsedSvg, type SvgNode, type SvgTag } from './artwork';
+export { DEFAULT_NEON_WALL, neonWallSvg, neonWallMaskSvg, wallBricks, svgDataUrl, type NeonWallConfig, type Brick } from './wall';
+export {
+  DEFAULT_NEON_SCENE, DEFAULT_NEON_ELEMENTS, DEFAULT_NEON_AUDIO, NEON_SCENE_PRESETS, NEON_NAMED_COLORS, NEON_FLICKER_LEVELS, NEON_GLITCH_LEVELS,
+  resolveNeonScene, resolveNeonElement, validateNeonScene, validateNeonElement, sanitizeNeonScene, elementGeometry, elementTriggers, neonSceneCues,
+  createNeonScene, addNeonElement, neonElementFromSpec, neonColor, neonSceneFromText, emojiText,
+  type NeonScene, type NeonSceneInput, type NeonElement, type NeonElementInput, type NeonElementType, type NeonTextElement, type NeonEmojiElement,
+  type NeonArtworkElement, type NeonArtworkSource, type NeonAudioConfig, type NeonTimeline, type SceneTrigger, type NeonElementGeometry, type NeonCue,
+  type NeonCueKind, type NeonScenePreset, type NeonElementSpec, type NeonElementCommon,
+} from './scene';
+export { NeonCanvas, neonSceneState, neonWallImages, type NeonCanvasProps, type NeonElementState } from './NeonCanvas';
+export { synthesizeNeonSound, encodeWav, NEON_SOUND_IDS, NEON_SOUND_SECONDS, type NeonSoundId } from './synth';
+export { NeonAudioEngine, type NeonAudioState } from './audio';
+export { type NeonShapeMetrics } from './material';