@appinternalleads/ui 0.4.0 → 0.4.1

package/src/motion/configurable/controls.ts

@@ -0,0 +1,93 @@
+/**
+ * **The control-table kit for configurable-motion templates** (DECISIONS §25–§27). A template declares
+ * every editable value once — path, type, range or options, default, unit, description, who may edit
+ * it — and `createConfigApi` (./config) derives the defaults, validator, JSON Schema, patch API and
+ * diff from that table. The Remotion Studio schema and the site editor read the same table.
+ *
+ * Generalized from promo-product-showcase's own table (`../promo/controls.ts`) so a new template reuses
+ * the machinery instead of copying it. Adds two things promo does not need: multiline text and keyed
+ * lists (a fixed list whose items can also be addressed by their id, e.g. `folds.top.peakAngle`).
+ */
+export type ControlType = 'number' | 'integer' | 'boolean' | 'color' | 'enum' | 'text' | 'easing' | 'asset' | 'overrides';
+export type ControlUnit =
+  | 'frames' | 'du' | 'pu' | 'em' | 'normalized' | 'short' | 'deg' | 'px' | 'hz' | 'du/s' | 'factor' | 'weight' | 'fraction';
+
+export type Control<G extends string = string> = {
+  /** Dotted path into the config (`content.top.headline`); inside a list item, relative to the item (`peakAngle`). */
+  path: string;
+  group: G;
+  type: ControlType;
+  default: unknown;
+  min?: number;
+  max?: number;
+  step?: number;
+  options?: readonly (string | number)[];
+  maxLength?: number;
+  minLength?: number;
+  /** `text`: line breaks (\n) are allowed; every other control character is still refused. */
+  multiline?: boolean;
+  /** `overrides`: the config paths (prefixes) an override map may set. */
+  allow?: readonly string[];
+  unit?: ControlUnit;
+  description: string;
+  userEditable: boolean;
+  agentEditable: boolean;
+};
+
+export type ListSpec<G extends string = string> = {
+  path: string;
+  group: G;
+  minItems: number;
+  maxItems: number;
+  item: readonly Control<G>[];
+  default: unknown[];
+  description: string;
+  /**
+   * A keyed list: its items are exactly `keys`, in order, each carrying its key in `keyField`. Patches
+   * may address an item by index (`folds.0.peakAngle`) or by key (`folds.top.peakAngle`).
+   */
+  keyField?: string;
+  keys?: readonly string[];
+};
+
+export type Opts = Partial<Pick<Control, 'step' | 'unit' | 'userEditable' | 'agentEditable' | 'minLength' | 'multiline'>>;
+
+/** Control builders bound to a template's group resolver (path → group). */
+export function controlKit<G extends string>(groupOf: (path: string) => G, easingNames: readonly string[]) {
+  const base = (o: Opts = {}) => ({
+    userEditable: o.userEditable ?? true, agentEditable: o.agentEditable ?? true,
+    ...(o.unit ? { unit: o.unit } : {}), ...(o.step !== undefined ? { step: o.step } : {}),
+  });
+  const num = (path: string, def: number, min: number, max: number, description: string, o: Opts = {}): Control<G> => ({ path, group: groupOf(path), type: 'number', default: def, min, max, description, ...base({ step: 0.01, ...o }) });
+  const int = (path: string, def: number, min: number, max: number, description: string, o: Opts = {}): Control<G> => ({ path, group: groupOf(path), type: 'integer', default: def, min, max, description, ...base({ step: 1, ...o }) });
+  const k = {
+    num, int,
+    frames: (path: string, def: number, max: number, description: string, min = 0) => int(path, def, min, max, description, { unit: 'frames' }),
+    bool: (path: string, def: boolean, description: string, o: Opts = {}): Control<G> => ({ path, group: groupOf(path), type: 'boolean', default: def, description, ...base(o) }),
+    color: (path: string, def: string, description: string, o: Opts = {}): Control<G> => ({ path, group: groupOf(path), type: 'color', default: def, description, ...base(o) }),
+    choice: (path: string, def: string | number, options: readonly (string | number)[], description: string, o: Opts = {}): Control<G> => ({ path, group: groupOf(path), type: 'enum', default: def, options, description, ...base(o) }),
+    text: (path: string, def: string, maxLength: number, description: string, o: Opts = {}): Control<G> => ({
+      path, group: groupOf(path), type: 'text', default: def, maxLength, minLength: o.minLength ?? 0, ...(o.multiline ? { multiline: true } : {}), description, ...base(o),
+    }),
+    easing: (path: string, def: string, description: string): Control<G> => ({ path, group: groupOf(path), type: 'easing', default: def, options: easingNames, description, ...base() }),
+    asset: (path: string, description: string): Control<G> => ({ path, group: groupOf(path), type: 'asset', default: '', maxLength: 2048, description, ...base() }),
+    opacity: (path: string, def: number, description: string) => num(path, def, 0, 1, description, { unit: 'fraction' }),
+    du: (path: string, def: number, min: number, max: number, description: string) => num(path, def, min, max, description, { step: 1, unit: 'du' }),
+    pu: (path: string, def: number, min: number, max: number, description: string) => num(path, def, min, max, description, { step: 1, unit: 'pu' }),
+    norm: (path: string, def: number, min: number, max: number, description: string) => num(path, def, min, max, description, { step: 0.005, unit: 'normalized' }),
+    deg: (path: string, def: number, min: number, max: number, description: string) => num(path, def, min, max, description, { step: 0.5, unit: 'deg' }),
+    factor: (path: string, def: number, min: number, max: number, description: string) => num(path, def, min, max, description, { step: 0.01, unit: 'factor' }),
+  };
+  return k;
+}
+
+/** Re-home a control into a list item: same control, relative path, fixed group. */
+export const inGroup = <G extends string>(group: G, c: Control<string>): Control<G> => ({ ...c, group });
+
+/** Every editable leaf, lists expanded as `<list>[].<field>` — the count people and agents see. */
+export function expandControls<G extends string>(controls: readonly Control<G>[], lists: readonly ListSpec<G>[]): (Control<G> & { list?: string })[] {
+  return [
+    ...controls,
+    ...lists.flatMap((l) => l.item.map((c) => ({ ...c, path: c.path ? `${l.path}[].${c.path}` : `${l.path}[]`, list: l.path }))),
+  ];
+}

package/src/motion/easing.ts

@@ -0,0 +1,55 @@
+import type { Easing } from './types';
+
+/**
+ * **Named easings, as cubic-béziers.** The motion contract refers to these by name so it stays JSON;
+ * the same functions run in Remotion and in the exported HTML runtime, so both play identical curves.
+ */
+const BEZIERS: Record<Exclude<Easing, 'linear' | 'hold'>, [number, number, number, number]> = {
+  'ease-in': [0.42, 0, 1, 1],
+  'ease-out': [0, 0, 0.58, 1],
+  'ease-in-out': [0.42, 0, 0.58, 1],
+  'expo-out': [0.16, 1, 0.3, 1],
+  'back-out': [0.34, 1.56, 0.64, 1],
+};
+
+/** Standard cubic-bézier solve: Newton steps on x, then bisection if Newton stalls. */
+function bezier(x1: number, y1: number, x2: number, y2: number): (t: number) => number {
+  const cx = 3 * x1, bx = 3 * (x2 - x1) - cx, ax = 1 - cx - bx;
+  const cy = 3 * y1, by = 3 * (y2 - y1) - cy, ay = 1 - cy - by;
+  const sx = (t: number) => ((ax * t + bx) * t + cx) * t;
+  const sy = (t: number) => ((ay * t + by) * t + cy) * t;
+  const dx = (t: number) => (3 * ax * t + 2 * bx) * t + cx;
+  return (x) => {
+    if (x <= 0) return 0;
+    if (x >= 1) return 1;
+    let t = x;
+    for (let i = 0; i < 8; i++) {
+      const err = sx(t) - x;
+      if (Math.abs(err) < 1e-7) return sy(t);
+      const d = dx(t);
+      if (Math.abs(d) < 1e-6) break;
+      t -= err / d;
+    }
+    let lo = 0, hi = 1;
+    t = x;
+    for (let i = 0; i < 40; i++) {
+      const v = sx(t);
+      if (Math.abs(v - x) < 1e-7) break;
+      if (v < x) lo = t; else hi = t;
+      t = (lo + hi) / 2;
+    }
+    return sy(t);
+  };
+}
+
+const CURVES: Record<Easing, (t: number) => number> = {
+  linear: (t) => t,
+  hold: (t) => (t >= 1 ? 1 : 0),
+  ...(Object.fromEntries(Object.entries(BEZIERS).map(([k, p]) => [k, bezier(...p)])) as Record<keyof typeof BEZIERS, (t: number) => number>),
+};
+
+export function ease(name: Easing | undefined, t: number): number {
+  return CURVES[name ?? 'linear'](t);
+}
+
+export const EASING_BEZIERS = BEZIERS;

package/src/motion/fit.ts

@@ -0,0 +1,8 @@
+/**
+ * **Auto-fit for text slots.** A slot has a fixed type size and a fixed maximum width. Text wider
+ * than that is scaled down (through the `--fit` custom property, which the template's CSS multiplies
+ * into `font-size`), never wrapped or moved. Both renderers — Remotion and the HTML runtime — measure
+ * the same DOM in the same browser engine and use this one formula, so the result is identical.
+ */
+export const fitScale = (naturalWidth: number, maxWidth: number) =>
+  naturalWidth <= maxWidth || naturalWidth <= 0 ? 1 : Math.floor((maxWidth / naturalWidth) * 1000) / 1000;

package/src/motion/index.ts

@@ -0,0 +1,29 @@
+/**
+ * **`@appinternalleads/ui/motion` — motion templates.** Animations authored once in Remotion
+ * (`remotion-prototype/`) and shipped as data. People and agents change only the content contract:
+ * text slots, theme colours and optional scenes. `docs/MOTION-TEMPLATES.md`.
+ */
+export type { ConfigurableMotionTemplate, ConfigurableMotionControl, MotionContract, MotionTemplate, MotionTheme, MotionFormat, MotionSequence, SlotSpec, ChoiceSpec, ThemeTokenSpec, SceneTimeline, Track, Keyframe, Easing, AnimatedProperty } from './types';
+export { MOTION_TEMPLATES, CONFIGURABLE_MOTION_TEMPLATES, heyTemplate, wordMotion, replication2, promoProductShowcase, paperFoldPromo } from './templates';
+export { mountMotion, installMotionStyles, MotionContentValidationError, type MotionController, type MountOptions } from './player';
+export { validateMotionContent, countWords, type MotionContentError } from './validate';
+export { createSampler, durationFor, activeScenes, sceneAt, themeVariables, valueAt, playlist, itemScene, formatFor, type Sampler, type TargetStyle, type PlayedScene } from './sample';
+export { fitScale } from './fit';
+export { ease } from './easing';
+export {
+  MOTION_REQUEST_SCHEMA, NOT_CONFIGURABLE, listMotionTemplates, describeMotionTemplate, getMotionTemplate,
+  validateMotionRequest, motionPreviewUrl, motionOutputFormats, decodeMotionPreview, getConfigurableMotionTemplate, configurableOutputFormats, type MotionRequest,
+} from './agent';
+export { MotionPlayer, type MotionPlayerProps } from './MotionPlayer';
+export * as Replication2 from './replication2';
+export { Replication2Player, type Replication2PlayerProps } from './replication2/Replication2Player';
+export * as PromoShowcase from './promo';
+export { PromoShowcasePlayer, type PromoShowcasePlayerProps } from './promo/PromoShowcasePlayer';
+export * as PaperFold from './paperfold';
+export { PaperFoldPlayer, type PaperFoldPlayerProps } from './paperfold/PaperFoldPlayer';
+export * as CatRig from './cat';
+export { Cat, CatPlayer, type CatProps, type CatPlayerProps } from './cat/Cat';
+export * as Neon from './neon';
+export { NeonText, NeonTextFrame, NeonCanvas, type NeonTextProps, type NeonTextFrameProps, type NeonTextConfig, type NeonTextConfigInput, type NeonCanvasProps, type NeonScene } from './neon';
+export * as TypeSurface from './typesurface';
+export { TypeSurfaceCanvas, type TypeSurfaceCanvasProps, type TypeSurfaceConfig } from './typesurface';

package/src/motion/neon/GlowRenderer.tsx

@@ -0,0 +1,83 @@
+import type { ReactNode, Ref, SVGProps } from 'react';
+import type { NeonTypography } from './config';
+import type { NeonFrame } from './frame';
+import { NeonLayers } from './layers';
+import type { NeonMaterial } from './material';
+import type { NeonLayout } from './typography';
+
+/**
+ * **The glow renderer: layout + material + frame → one SVG** for a single text sign. The letters
+ * are defined ONCE, as a live `<text>` in `<defs>`, and `NeonLayers` paints the five light layers
+ * from it. So the words, the font and the material never meet except here, and this file never
+ * mentions a word. `NeonCanvas` uses the same `NeonTextGlyphs` + `NeonLayers` for its text elements.
+ */
+export type GlowRendererProps = Omit<SVGProps<SVGSVGElement>, 'children' | 'viewBox' | 'ref'> & {
+  svgRef?: Ref<SVGSVGElement>;
+  text: string;
+  layout: NeonLayout;
+  typography: NeonTypography;
+  material: NeonMaterial;
+  frame: NeonFrame;
+  background: string | null;
+  /** Prepended to every id, so several signs can share a page. */
+  idPrefix: string;
+  children?: ReactNode;
+};
+
+const r3 = (v: number) => Math.round(v * 1000) / 1000;
+
+/** The rows as one `<text>`, for `<use>`. SVG adds letter-spacing after the last letter too, so the anchor shifts back. */
+export function NeonTextGlyphs({ id, layout, typography: t }: { id: string; layout: NeonLayout; typography: NeonTypography }) {
+  const lsFix = layout.textAnchor === 'middle' ? t.letterSpacing / 2 : layout.textAnchor === 'end' ? t.letterSpacing : 0;
+  return (
+    <text
+      id={id}
+      fontFamily={t.fontFamily}
+      fontSize={t.fontSize}
+      fontWeight={t.fontWeight}
+      fontStyle={t.fontStyle}
+      letterSpacing={t.letterSpacing}
+      textAnchor={layout.textAnchor}
+      style={{ whiteSpace: 'pre' }}
+    >
+      {layout.rows.map((row, i) => (
+        <tspan key={i} x={r3(layout.anchorX + lsFix)} y={r3(row.y)}>{row.text}</tspan>
+      ))}
+    </text>
+  );
+}
+
+export function GlowRenderer({ text, layout, typography: t, material: m, frame, background, idPrefix: p, children, svgRef, ...svg }: GlowRendererProps) {
+  const vb = layout.viewBox;
+  return (
+    <svg
+      ref={svgRef}
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox={`${r3(vb.x)} ${r3(vb.y)} ${r3(vb.width)} ${r3(vb.height)}`}
+      width={Math.round(vb.width)}
+      height={Math.round(vb.height)}
+      role="img"
+      aria-label={text}
+      data-neon-event={frame.levels.event ?? undefined}
+      data-neon-glitch={frame.glitch ? 'on' : undefined}
+      {...svg}
+    >
+      <title>{text}</title>
+      <defs>
+        <NeonTextGlyphs id={`${p}neon-glyphs`} layout={layout} typography={t} />
+      </defs>
+      {background ? <rect data-layer="background" x={r3(vb.x)} y={r3(vb.y)} width={r3(vb.width)} height={r3(vb.height)} fill={background} /> : null}
+      <NeonLayers
+        source={{ kind: 'vector', href: `${p}neon-glyphs`, filled: m.filled }}
+        material={m}
+        levels={frame.levels}
+        glitch={frame.glitch}
+        box={layout.box}
+        em={t.fontSize}
+        pad={layout.pad}
+        idPrefix={`${p}neon-`}
+      />
+      {children}
+    </svg>
+  );
+}

package/src/motion/neon/NeonCanvas.tsx

@@ -0,0 +1,175 @@
+import type { ReactNode, Ref, SVGProps } from 'react';
+import { mixHex } from './config';
+import { neonFrame, type NeonFrame } from './frame';
+import { NeonTextGlyphs } from './GlowRenderer';
+import { NeonLayers, type NeonSource } from './layers';
+import { resolveMaterial } from './material';
+import { elementGeometry, elementTriggers, sanitizeNeonScene, type NeonElement, type NeonElementGeometry, type NeonScene, type NeonSceneInput, type SceneTrigger } from './scene';
+import type { TextMeasurer } from './typography';
+import { neonWallMaskSvg, neonWallSvg, svgDataUrl, type NeonWallConfig } from './wall';
+import type { SvgNode } from './artwork';
+
+/**
+ * **The neon canvas: a whole scene at one moment.** Wall, light spill and every element, in one
+ * SVG. Pure (no hooks, no clock): `timeMs` and `triggers` decide every flicker and glitch, so a
+ * timeline can scrub it and Remotion can render it.
+ *
+ * Paint order, back to front:
+ *   1 wall        the procedural bricks, drawn once as an image (static; never re-rasterised)
+ *   2 spill       each element's light on the wall: a soft coloured pool around it, scaled by that
+ *                 element's live bloom level, masked by the wall's albedo so it lands on brick
+ *                 faces more than in the joints, blended with `screen`. It flickers, darkens in a
+ *                 failure and comes back on the re-strike, with the sign.
+ *   3 shadows     every element's cast shadow, above the light it blocks
+ *   4 elements    bloom → glow → tube → core for each element (`NeonLayers`)
+ */
+export type NeonCanvasProps = Omit<SVGProps<SVGSVGElement>, 'children' | 'viewBox' | 'ref'> & {
+  scene: NeonSceneInput | NeonScene;
+  timeMs?: number;
+  triggers?: readonly SceneTrigger[];
+  measure?: TextMeasurer;
+  idPrefix?: string;
+  svgRef?: Ref<SVGSVGElement>;
+  /** Drawn over the scene, in stage units (selection handles). */
+  children?: ReactNode;
+};
+
+const r3 = (v: number) => Math.round(v * 1000) / 1000;
+
+/* The wall is a few hundred bricks and a noise filter: build its image once per look and size. */
+const wallCache = new Map<string, { wall: string; mask: string }>();
+export function neonWallImages(wall: NeonWallConfig, width: number, height: number) {
+  const key = JSON.stringify([wall, width, height]);
+  let hit = wallCache.get(key);
+  if (!hit) {
+    hit = { wall: svgDataUrl(neonWallSvg(wall, width, height)), mask: svgDataUrl(neonWallMaskSvg(wall, width, height)) };
+    if (wallCache.size > 24) wallCache.delete(wallCache.keys().next().value!);
+    wallCache.set(key, hit);
+  }
+  return hit;
+}
+
+function SvgTree({ nodes }: { nodes: SvgNode[] }) {
+  return (
+    <>
+      {nodes.map((n, i) => {
+        const { tag: Tag, attrs, children } = n;
+        const props: Record<string, string> = {};
+        for (const [k, v] of Object.entries(attrs)) props[k === 'fill-rule' ? 'fillRule' : k] = v;
+        return children.length ? <Tag key={i} {...props}><SvgTree nodes={children} /></Tag> : <Tag key={i} {...props} />;
+      })}
+    </>
+  );
+}
+
+/** Each element's resting state + live frame: everything the painter and the wall light need. */
+export type NeonElementState = { element: NeonElement; geometry: NeonElementGeometry; frame: NeonFrame };
+export function neonSceneState(scene: NeonScene, timeMs: number, triggers?: readonly SceneTrigger[], measure?: TextMeasurer): NeonElementState[] {
+  return scene.elements.filter((e) => e.visible).map((element) => ({
+    element,
+    geometry: elementGeometry(element, measure),
+    frame: neonFrame(element, timeMs, elementTriggers(triggers, element.id)),
+  }));
+}
+
+export function NeonCanvas({ scene: input, timeMs = 0, triggers, measure, idPrefix = 'nc-', svgRef, children, ...svg }: NeonCanvasProps) {
+  const { scene, errors } = sanitizeNeonScene(input);
+  const triggersAll = [...(scene.timeline.triggers ?? []), ...(triggers ?? [])];
+  const W = scene.stage.width;
+  const H = scene.stage.height;
+  const states = neonSceneState(scene, timeMs, triggersAll, measure);
+  const wall = scene.wall.enabled ? neonWallImages(scene.wall, W, H) : null;
+  const p = idPrefix;
+  const label = scene.elements.filter((e) => e.visible).map((e) => (e.type === 'text' ? e.text : e.type === 'emoji' ? e.emoji : 'artwork')).join(' ');
+
+  const defs: ReactNode[] = [];
+  const shadows: ReactNode[] = [];
+  const lights: ReactNode[] = [];
+  const spill: ReactNode[] = [];
+
+  states.forEach(({ element: el, geometry: g, frame }, i) => {
+    const ep = `${p}e${i}-`;
+    const shapeId = `${ep}shape`;
+    const material = resolveMaterial(g.neon, g.metrics);
+    let source: NeonSource | null = null;
+    if (g.shape.kind === 'text') {
+      defs.push(<NeonTextGlyphs key={shapeId} id={shapeId} layout={g.shape.layout} typography={g.shape.typography} />);
+      source = { kind: 'vector', href: shapeId, filled: material.filled };
+    } else if (g.shape.kind === 'svg') {
+      defs.push(<g key={shapeId} id={shapeId}><SvgTree nodes={g.shape.art.nodes} /></g>);
+      source = { kind: 'vector', href: shapeId, filled: material.filled };
+    } else if (g.shape.kind === 'raster') {
+      defs.push(<image key={shapeId} id={shapeId} href={g.shape.src} x={0} y={0} width={g.shape.width} height={g.shape.height} preserveAspectRatio="none" />);
+      source = { kind: 'raster', href: shapeId, width: g.shape.width, height: g.shape.height, mode: g.shape.mode, threshold: g.shape.threshold, filled: material.filled };
+    }
+    if (!source) return;
+    const common = { source, material, levels: frame.levels, glitch: frame.glitch, box: g.box, em: g.em, pad: g.pad };
+    shadows.push(
+      <g key={`s${i}`} transform={g.transform} opacity={r3(el.opacity)} data-element={el.id} data-part="shadow">
+        <NeonLayers {...common} idPrefix={`${ep}s-`} part="shadow" />
+      </g>,
+    );
+    lights.push(
+      <g key={`l${i}`} transform={g.transform} opacity={r3(el.opacity)} data-element={el.id} data-element-type={el.type} data-neon-event={frame.levels.event ?? undefined} data-neon-glitch={frame.glitch ? 'on' : undefined}>
+        <NeonLayers {...common} idPrefix={ep} part="light" />
+        {/* The whole box answers the pointer, not just the thin tube: grab a letter anywhere. */}
+        <rect data-hit={el.id} x={r3(g.box.x)} y={r3(g.box.y)} width={r3(g.box.width)} height={r3(g.box.height)} fill="transparent" pointerEvents="all" />
+      </g>,
+    );
+    /* The wall light: a pool of the element's colour, as wide as the element plus the spill radius. */
+    const strength = scene.wall.lightSpill * Math.min(1.5, el.neon.intensity) * el.opacity * frame.levels.bloom * (scene.wall.glitchAffectsWall && frame.glitch ? frame.glitch.keep : 1);
+    if (scene.wall.enabled && strength > 0.002) {
+      const b = g.bounds;
+      const R = Math.max(0, scene.wall.spillRadius);
+      const color = mixHex(el.neon.bloomColor ?? el.neon.color, el.neon.glowColor ?? el.neon.color, 0.45);
+      const gid = `${ep}spill`;
+      const jolt = scene.wall.glitchAffectsWall && frame.glitch ? frame.glitch.glowShiftX * g.em / g.unit * el.scale : 0;
+      defs.push(
+        <radialGradient key={gid} id={gid}>
+          <stop offset="0" stopColor={color} stopOpacity={0.95} />
+          <stop offset="0.4" stopColor={color} stopOpacity={0.5} />
+          <stop offset="0.75" stopColor={color} stopOpacity={0.14} />
+          <stop offset="1" stopColor={color} stopOpacity={0} />
+        </radialGradient>,
+      );
+      const cx = r3(b.x + b.width / 2 + jolt);
+      const cy = r3(b.y + b.height / 2);
+      /* A wide pool that reaches `spillRadius`, and a hot one hugging the element. */
+      spill.push(
+        <g key={gid} data-spill={el.id}>
+          <ellipse cx={cx} cy={cy} rx={r3(b.width / 2 + R)} ry={r3(b.height / 2 + R * 0.85)} fill={`url(#${gid})`} opacity={r3(Math.min(1, 0.85 * strength))} />
+          <ellipse cx={cx} cy={cy} rx={r3(b.width / 2 + R * 0.3)} ry={r3(b.height / 2 + R * 0.28)} fill={`url(#${gid})`} opacity={r3(Math.min(1, 0.55 * strength))} />
+        </g>,
+      );
+    }
+  });
+
+  return (
+    <svg
+      ref={svgRef}
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox={`0 0 ${W} ${H}`}
+      width={W}
+      height={H}
+      role="img"
+      aria-label={label || 'Neon sign'}
+      data-neon-invalid={errors.length ? errors.map((e) => e.path).join(' ') : undefined}
+      {...svg}
+    >
+      <title>{label || 'Neon sign'}</title>
+      <defs>
+        {defs}
+        {wall ? (
+          <mask id={`${p}albedo`} maskUnits="userSpaceOnUse" x={0} y={0} width={W} height={H}>
+            <image href={wall.mask} x={0} y={0} width={W} height={H} />
+          </mask>
+        ) : null}
+      </defs>
+      {wall ? <image data-layer="wall" href={wall.wall} x={0} y={0} width={W} height={H} preserveAspectRatio="none" /> : null}
+      {spill.length ? <g data-layer="wall-light" mask={`url(#${p}albedo)`} style={{ mixBlendMode: 'screen' }}>{spill}</g> : null}
+      <g data-layer="shadows">{shadows}</g>
+      <g data-layer="elements">{lights}</g>
+      {children}
+    </svg>
+  );
+}

package/src/motion/neon/NeonText.tsx

@@ -0,0 +1,113 @@
+'use client';
+
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
+import { resolveNeonConfig, type NeonTypography } from './config';
+import { NeonTextFrame, type NeonTextFrameProps } from './NeonTextFrame';
+import { estimateTextWidth, fontShorthand, type TextMeasurer } from './typography';
+
+export type NeonTextProps = Omit<NeonTextFrameProps, 'timeMs' | 'measure'> & {
+  /** Hold the current frame. */
+  paused?: boolean;
+  /** Drive the clock yourself (ms); the component then never runs its own. */
+  timeMs?: number;
+  /** Keep the sign steady for people who ask for reduced motion (default true). */
+  respectReducedMotion?: boolean;
+};
+
+/** A canvas-backed measurer; falls back to the estimate if canvas text isn't available. Browser only. */
+export function createCanvasMeasurer(): TextMeasurer {
+  let ctx: CanvasRenderingContext2D | null = null;
+  try { ctx = document.createElement('canvas').getContext('2d'); } catch { ctx = null; }
+  const cache = new Map<string, number>();
+  return (text: string, t: NeonTypography) => {
+    if (!ctx) return estimateTextWidth(text, t);
+    const key = `${fontShorthand(t)}|${text}`;
+    const hit = cache.get(key);
+    if (hit !== undefined) return hit;
+    ctx.font = fontShorthand(t);
+    const w = ctx.measureText(text).width;
+    const value = Number.isFinite(w) && w > 0 ? w : estimateTextWidth(text, t);
+    cache.set(key, value);
+    return value;
+  };
+}
+
+/**
+ * **A live neon sign.** Everything is data: change `text`, the font, the colours or the animation
+ * props (or pass one `config` object) and the same renderer draws it.
+ *
+ *   <NeonText text="OPEN" fontFamily="Oswald" fontSize={220} neonColor="#FF3B4D"
+ *             glowIntensity={1} flickerIntensity={0.15} glitchIntensity={0.1} />
+ *   <NeonText config={neonConfig} />
+ *
+ * The clock runs only while the sign is on screen, animation is on and motion isn't reduced. Row
+ * widths are measured with a canvas once fonts load; the first paint (and a server render) uses an
+ * estimate, so server and client HTML match.
+ */
+export function NeonText({ paused = false, timeMs: controlledTime, respectReducedMotion = true, idPrefix, ...props }: NeonTextProps) {
+  const autoId = useId().replace(/[^a-zA-Z0-9_-]/g, '');
+  const prefix = idPrefix ?? `n${autoId}-`;
+  const [time, setTime] = useState(0);
+  const [measure, setMeasure] = useState<TextMeasurer | undefined>(undefined);
+  const [reduced, setReduced] = useState(false);
+  const [visible, setVisible] = useState(true);
+  const ref = useRef<SVGSVGElement>(null);
+
+  const animated = useMemo(() => resolveNeonConfig(props.config, { animated: props.animated }).animation.enabled, [props.config, props.animated]);
+  const fontKey = `${props.config?.typography?.fontFamily ?? ''}|${props.fontFamily ?? ''}|${props.fontWeight ?? props.config?.typography?.fontWeight ?? ''}|${props.fontStyle ?? props.config?.typography?.fontStyle ?? ''}`;
+
+  /* Measure with a canvas once fonts are ready, and again whenever a font finishes loading. */
+  useEffect(() => {
+    let live = true;
+    const refresh = () => { if (live) setMeasure(() => createCanvasMeasurer()); };
+    refresh();
+    const fonts = typeof document !== 'undefined' ? document.fonts : undefined;
+    fonts?.ready.then(refresh).catch(() => undefined);
+    fonts?.addEventListener?.('loadingdone', refresh);
+    return () => { live = false; fonts?.removeEventListener?.('loadingdone', refresh); };
+  }, [fontKey]);
+
+  useEffect(() => {
+    if (!respectReducedMotion || typeof matchMedia !== 'function') return;
+    const q = matchMedia('(prefers-reduced-motion: reduce)');
+    const on = () => setReduced(q.matches);
+    on();
+    q.addEventListener?.('change', on);
+    return () => q.removeEventListener?.('change', on);
+  }, [respectReducedMotion]);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || typeof IntersectionObserver !== 'function') return;
+    const io = new IntersectionObserver((entries) => setVisible(entries.some((e) => e.isIntersecting)));
+    io.observe(el);
+    return () => io.disconnect();
+  }, []);
+
+  const running = controlledTime === undefined && animated && !paused && !reduced && visible;
+  useEffect(() => {
+    if (!running || typeof requestAnimationFrame !== 'function') return;
+    let raf = 0;
+    let last: number | null = null;
+    const tick = (now: number) => {
+      /* A backgrounded tab resumes with a huge gap: step at most 100 ms so nothing jumps. */
+      if (last !== null) { const dt = now - last; if (dt > 0) setTime((v) => v + Math.min(dt, 100)); }
+      last = now;
+      raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [running]);
+
+  const steady = reduced && controlledTime === undefined;
+  return (
+    <NeonTextFrame
+      {...props}
+      animated={steady ? false : props.animated}
+      svgRef={ref}
+      idPrefix={prefix}
+      timeMs={controlledTime ?? time}
+      measure={measure}
+    />
+  );
+}

package/src/motion/neon/NeonTextFrame.tsx

@@ -0,0 +1,67 @@
+import type { ReactNode, Ref, SVGProps } from 'react';
+import { resolveNeonConfig, sanitizeNeonConfig, type NeonTextConfigInput, type NeonTextShorthand } from './config';
+import { neonFrame } from './frame';
+import { GlowRenderer } from './GlowRenderer';
+import { materialPad, resolveMaterial } from './material';
+import { layoutText, type TextMeasurer } from './typography';
+
+export type NeonTextFrameProps = NeonTextShorthand & Omit<SVGProps<SVGSVGElement>, 'children' | 'viewBox' | 'fontFamily' | 'fontSize' | 'fontWeight' | 'fontStyle' | 'letterSpacing' | 'strokeWidth' | 'ref'> & {
+  /** The root <svg> element. */
+  svgRef?: Ref<SVGSVGElement>;
+  /** The whole configuration; the shorthand props win over it. */
+  config?: NeonTextConfigInput | null;
+  /** The clock, in ms. The caller owns time, so a frame is a pure function of it. */
+  timeMs?: number;
+  /** Row widths; the browser player passes a canvas measurer, otherwise an estimate is used. */
+  measure?: TextMeasurer;
+  /** Prepended to every element id, so several signs can share a page. */
+  idPrefix?: string;
+  children?: ReactNode;
+};
+
+/**
+ * **One still frame of a neon sign.** No hooks and no clock: `timeMs` decides the flicker and the
+ * glitch, so the same props always draw the same picture — what Remotion and a server render need.
+ * `<NeonText>` is this plus a clock.
+ *
+ *   NeonText → Typography (layoutText) → NeonMaterial (resolveMaterial) → FlickerController +
+ *   GlitchController (neonFrame) → GlowRenderer
+ *
+ * A config with bad values still draws: each bad field falls back to its default, and the SVG says
+ * so in `data-neon-invalid` (the list is `validateNeonConfig`'s).
+ */
+export function NeonTextFrame(props: NeonTextFrameProps) {
+  const {
+    config: input, timeMs = 0, measure, idPrefix = '', children,
+    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,
+    ...svg
+  } = props;
+  const resolved = resolveNeonConfig(input, {
+    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,
+  });
+  const { config, errors } = sanitizeNeonConfig(resolved);
+  const layout = layoutText(config.text, config.typography, materialPad(config.neon, config.typography), measure);
+  const material = resolveMaterial(config.neon, config.typography);
+  const frame = neonFrame(config, timeMs);
+  return (
+    <GlowRenderer
+      text={config.text}
+      layout={layout}
+      typography={config.typography}
+      material={material}
+      frame={frame}
+      background={config.background}
+      idPrefix={idPrefix}
+      data-neon-invalid={errors.length ? errors.map((e) => e.path).join(' ') : undefined}
+      {...svg}
+    >
+      {children}
+    </GlowRenderer>
+  );
+}