@appinternalleads/ui 0.4.0 → 0.4.1

package/src/motion/neon/synth.ts

@@ -0,0 +1,188 @@
+/**
+ * **Neon sound, synthesised.** Six short sounds built from the physics of a neon sign rather than
+ * sampled: a transformer hums at twice the mains frequency (120 Hz) with odd and even harmonics and
+ * a faint high sizzle; a flicker is a few tiny arc ticks; a dip is the hum sagging and stuttering; a
+ * failure is the arc chattering on and off; a glitch is a short band-limited electrical zap; a
+ * restore is the click and swell of the gas re-striking.
+ *
+ * Deterministic (seeded noise), so the same build writes the same files. `tools/neon-text/make-audio.ts`
+ * writes them as WAVs for the site; `NeonAudioEngine` can also synthesise them in the browser.
+ */
+export type NeonSoundId = 'hum' | 'flicker' | 'dip' | 'failure' | 'glitch' | 'restore';
+export const NEON_SOUND_IDS: readonly NeonSoundId[] = ['hum', 'flicker', 'dip', 'failure', 'glitch', 'restore'];
+/** Lengths, seconds. The hum is a seamless loop. */
+export const NEON_SOUND_SECONDS: Record<NeonSoundId, number> = { hum: 2, flicker: 0.3, dip: 0.42, failure: 0.9, glitch: 0.22, restore: 0.6 };
+
+function prng(seed: number) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const TAU = Math.PI * 2;
+/** The transformer buzz at `f`: harmonics of a slightly clipped wave. */
+function buzz(phase: number, bright = 1): number {
+  const h = [1, 0.55, 0.36, 0.22, 0.13, 0.08, 0.05];
+  let v = 0;
+  for (let k = 0; k < h.length; k++) v += h[k]! * Math.pow(bright, k * 0.5) * Math.sin(phase * (k + 1));
+  return Math.tanh(1.4 * v) / 1.2;
+}
+
+/** A one-pole high-pass, in place. */
+function highpass(x: Float32Array, fc: number, sr: number) {
+  const rc = 1 / (TAU * fc);
+  const a = rc / (rc + 1 / sr);
+  let y = 0;
+  let prev = 0;
+  for (let i = 0; i < x.length; i++) { const xi = x[i]!; y = a * (y + xi - prev); prev = xi; x[i] = y; }
+}
+/** A one-pole low-pass, in place. */
+function lowpass(x: Float32Array, fc: number, sr: number) {
+  const a = 1 - Math.exp((-TAU * fc) / sr);
+  let y = 0;
+  for (let i = 0; i < x.length; i++) { y += a * (x[i]! - y); x[i] = y; }
+}
+/** A resonant band-pass (biquad, constant peak gain), in place. */
+function bandpass(x: Float32Array, fc: number, q: number, sr: number) {
+  const w = (TAU * fc) / sr;
+  const alpha = Math.sin(w) / (2 * q);
+  const b0 = alpha, b2 = -alpha, a0 = 1 + alpha, a1 = -2 * Math.cos(w), a2 = 1 - alpha;
+  let x1 = 0, x2 = 0, y1 = 0, y2 = 0;
+  for (let i = 0; i < x.length; i++) {
+    const x0 = x[i]!;
+    const y0 = (b0 * x0 + b2 * x2 - a1 * y1 - a2 * y2) / a0;
+    x2 = x1; x1 = x0; y2 = y1; y1 = y0;
+    x[i] = y0;
+  }
+}
+function normalise(x: Float32Array, peak: number) {
+  let m = 0;
+  for (const v of x) m = Math.max(m, Math.abs(v));
+  if (m > 0) for (let i = 0; i < x.length; i++) x[i] = (x[i]! / m) * peak;
+  return x;
+}
+/** A short noise tick at `at` seconds: a few ms of high-passed noise with a fast decay. */
+function tick(out: Float32Array, sr: number, at: number, amp: number, ms: number, rnd: () => number) {
+  const start = Math.floor(at * sr);
+  const len = Math.floor((ms / 1000) * sr);
+  const buf = new Float32Array(len);
+  for (let i = 0; i < len; i++) buf[i] = (rnd() * 2 - 1) * Math.exp(-i / (len * 0.25));
+  highpass(buf, 900, sr);
+  lowpass(buf, 3800, sr);
+  for (let i = 0; i < len && start + i < out.length; i++) out[start + i] = out[start + i]! + buf[i]! * amp;
+}
+
+export function synthesizeNeonSound(id: NeonSoundId, sampleRate = 44100): Float32Array {
+  const sr = sampleRate;
+  const n = Math.round(NEON_SOUND_SECONDS[id] * sr);
+  const out = new Float32Array(n);
+  const rnd = prng({ hum: 11, flicker: 23, dip: 37, failure: 41, glitch: 53, restore: 67 }[id]);
+  const F = 120;
+
+  if (id === 'hum') {
+    /* 2 s × 120 Hz = 240 whole cycles: the tone loops without a seam. The sizzle is crossfaded. */
+    const xf = Math.round(0.08 * sr);
+    const noise = new Float32Array(n + xf);
+    for (let i = 0; i < noise.length; i++) noise[i] = rnd() * 2 - 1;
+    bandpass(noise, 4200, 0.9, sr);
+    for (let i = 0; i < n; i++) {
+      const t = i / sr;
+      const hz = buzz(TAU * F * t, 0.9) * 0.8 + 0.12 * Math.sin(TAU * 60 * t);
+      let s = noise[i]!;
+      if (i < xf) { const u = i / xf; s = noise[i]! * u + noise[n + i]! * (1 - u); }
+      out[i] = hz + s * 0.035 * (0.5 + 0.5 * Math.abs(Math.sin(TAU * 60 * t)));
+    }
+    return normalise(out, 0.5);
+  }
+
+  if (id === 'flicker') {
+    let at = 0.004;
+    for (let k = 0; k < 4; k++) { tick(out, sr, at, 0.6 + 0.4 * rnd(), 3 + 4 * rnd(), rnd); at += 0.045 + 0.04 * rnd(); }
+    for (let i = 0; i < n; i++) {
+      const t = i / sr;
+      const gate = Math.floor(t / 0.035) % 2 === 0 ? 0.22 : 0.05;
+      out[i] = out[i]! + buzz(TAU * F * t) * gate * Math.exp(-t / 0.18);
+    }
+    return normalise(out, 0.6);
+  }
+
+  if (id === 'dip') {
+    tick(out, sr, 0.002, 0.7, 4, rnd);
+    let phase = 0;
+    for (let i = 0; i < n; i++) {
+      const t = i / sr;
+      const u = t / NEON_SOUND_SECONDS.dip;
+      const sag = u < 0.1 ? 1 - u / 0.1 * 0.7 : u < 0.62 ? 0.3 + (Math.floor(t / 0.028) % 3 === 0 ? 0.25 : 0) : 0.3 + 0.7 * Math.min(1, (u - 0.62) / 0.25);
+      const fade = u > 0.85 ? 1 - (u - 0.85) / 0.15 : 1;
+      phase += (TAU * F * (1 - 0.06 * (1 - sag))) / sr;
+      out[i] = out[i]! + buzz(phase, 0.6 + 0.4 * sag) * 0.5 * sag * fade;
+    }
+    return normalise(out, 0.6);
+  }
+
+  if (id === 'failure') {
+    for (let i = 0; i < Math.min(n, Math.round(0.14 * sr)); i++) { const t = i / sr; out[i] = out[i]! + Math.sin(TAU * 58 * t) * 0.5 * Math.exp(-t / 0.05); }
+    let at = 0.01;
+    const gates: [number, number][] = [];
+    while (at < NEON_SOUND_SECONDS.failure * 0.82) {
+      const on = rnd() < 0.5;
+      const len = 0.018 + 0.02 * rnd();
+      gates.push([at, on ? 1 : 0.15]);
+      tick(out, sr, at, 0.35 + 0.6 * rnd(), 3 + 7 * rnd(), rnd);
+      at += len;
+    }
+    for (let i = 0; i < n; i++) {
+      const t = i / sr;
+      let g = 0.2;
+      for (const [s, v] of gates) if (t >= s) g = v;
+      const fade = t > NEON_SOUND_SECONDS.failure * 0.8 ? Math.max(0, 1 - (t - NEON_SOUND_SECONDS.failure * 0.8) / (NEON_SOUND_SECONDS.failure * 0.2)) : 1;
+      out[i] = out[i]! + buzz(TAU * F * t, 1) * 0.3 * g * fade;
+    }
+    return normalise(out, 0.7);
+  }
+
+  if (id === 'glitch') {
+    const z = new Float32Array(n);
+    for (let i = 0; i < n; i++) z[i] = rnd() * 2 - 1;
+    bandpass(z, 2600, 3.5, sr);
+    let phase = 0;
+    for (let i = 0; i < n; i++) {
+      const t = i / sr;
+      const env = Math.min(1, t / 0.004) * Math.exp(-t / 0.07);
+      const am = Math.sin(TAU * 90 * t) > 0 ? 1 : 0.3;
+      phase += (TAU * (1800 - 1400 * Math.min(1, t / 0.12))) / sr;
+      out[i] = z[i]! * 3 * env * am + Math.sin(phase) * 0.12 * env + buzz(TAU * F * t) * 0.15 * env;
+    }
+    return normalise(out, 0.5);
+  }
+
+  /* restore: a click, a tiny ring, and the hum swelling back */
+  tick(out, sr, 0.001, 1, 2, rnd);
+  let phase = 0;
+  for (let i = 0; i < n; i++) {
+    const t = i / sr;
+    const u = t / NEON_SOUND_SECONDS.restore;
+    out[i] = out[i]! + Math.sin(TAU * 3200 * t) * 0.18 * Math.exp(-t / 0.05);
+    const swell = Math.min(1, t / 0.22) * (u > 0.6 ? Math.max(0, 1 - (u - 0.6) / 0.4) : 1);
+    phase += (TAU * F * (0.86 + 0.14 * Math.min(1, t / 0.25))) / sr;
+    out[i] = out[i]! + buzz(phase, 0.5 + 0.5 * Math.min(1, t / 0.2)) * 0.45 * swell;
+  }
+  return normalise(out, 0.6);
+}
+
+/** 16-bit mono PCM WAV bytes. */
+export function encodeWav(samples: Float32Array, sampleRate = 44100): Uint8Array {
+  const bytes = new Uint8Array(44 + samples.length * 2);
+  const v = new DataView(bytes.buffer);
+  const str = (o: number, s: string) => { for (let i = 0; i < s.length; i++) v.setUint8(o + i, s.charCodeAt(i)); };
+  str(0, 'RIFF'); v.setUint32(4, 36 + samples.length * 2, true); str(8, 'WAVE');
+  str(12, 'fmt '); v.setUint32(16, 16, true); v.setUint16(20, 1, true); v.setUint16(22, 1, true);
+  v.setUint32(24, sampleRate, true); v.setUint32(28, sampleRate * 2, true); v.setUint16(32, 2, true); v.setUint16(34, 16, true);
+  str(36, 'data'); v.setUint32(40, samples.length * 2, true);
+  for (let i = 0; i < samples.length; i++) v.setInt16(44 + i * 2, Math.max(-1, Math.min(1, samples[i]!)) * 32767, true);
+  return bytes;
+}

package/src/motion/neon/typography.ts

@@ -0,0 +1,102 @@
+import type { NeonTypography } from './config';
+
+/**
+ * **Typography: text + font → rows and a frame.** The letters stay live SVG `<text>`: nothing is
+ * converted to paths, so any font the page loads works, the text stays selectable and readable by
+ * assistive tech, and changing the words never touches the renderer.
+ *
+ * The only thing SVG text can't tell us without a browser is how wide a row is, and the frame
+ * (viewBox) depends on it. So widths come from a `TextMeasurer`: the browser player passes one that
+ * uses a canvas; anywhere else (server render, Remotion, tests) an advance-width estimate is used.
+ * Rows are drawn centred on their anchor either way, so an estimate only changes the margin.
+ */
+
+/** Measures one row's advance width (without letter spacing) in user units. */
+export type TextMeasurer = (text: string, typography: NeonTypography) => number;
+
+/** `normal 500 220px Oswald, …` — the CSS font shorthand for a canvas `measureText`. */
+export function fontShorthand(t: Pick<NeonTypography, 'fontStyle' | 'fontWeight' | 'fontSize' | 'fontFamily'>): string {
+  return `${t.fontStyle} ${t.fontWeight} ${t.fontSize}px ${t.fontFamily}`;
+}
+
+/* Rough advance widths, in em, for a medium sans. Narrow and wide glyphs matter most; the rest
+   average 0.58. Condensed families (Oswald, Bebas, Narrow) run about 20 % narrower. */
+const NARROW = new Set([...'iIl.,:;!|\'`jft1']);
+const WIDE = new Set([...'MWmw@%']);
+const CAPS = /[A-Z0-9]/;
+export const estimateTextWidth: TextMeasurer = (text, t) => {
+  const condensed = /oswald|bebas|narrow|condensed|compressed|league gothic|anton/i.test(t.fontFamily) ? 0.8 : 1;
+  const weight = 0.92 + (t.fontWeight - 400) / 2500;
+  let em = 0;
+  for (const ch of text) {
+    if (ch === ' ') em += 0.28;
+    else if (NARROW.has(ch)) em += 0.3;
+    else if (WIDE.has(ch)) em += 0.86;
+    else if (ch === '/') em += 0.4;
+    else if (CAPS.test(ch)) em += 0.64;
+    else em += 0.54;
+  }
+  return em * condensed * weight * t.fontSize;
+};
+
+export type NeonRow = {
+  text: string;
+  /** Baseline, in user units. */
+  y: number;
+  /** Advance width including letter spacing. */
+  width: number;
+};
+
+export type NeonLayout = {
+  rows: NeonRow[];
+  /** x of every row's anchor (text-anchor follows `align`). */
+  anchorX: number;
+  textAnchor: 'start' | 'middle' | 'end';
+  /** The letters' box, in user units (caps top → descender of the last row). */
+  box: { x: number; y: number; width: number; height: number };
+  /** The frame: the box plus room for tube, glow, bloom and shadow. */
+  viewBox: { x: number; y: number; width: number; height: number };
+  /** How much room the frame leaves around the box. */
+  pad: number;
+};
+
+/** Normalises text into rows: `\n` (or a literal "\\n" an agent typed) splits rows; tabs become spaces; empty text is one space. */
+export function textRows(text: string): string[] {
+  const rows = String(text ?? '').replace(/\\n/g, '\n').replace(/\r\n?/g, '\n').replace(/\t/g, ' ').split('\n');
+  return rows.length && rows.some((r) => r.length) ? rows : [' '];
+}
+
+/** Cap height and descender as fractions of the em: typical of display sans faces. */
+const CAP = 0.74;
+const DESCENT = 0.24;
+
+/**
+ * **Lay out the rows** and size a frame that holds the sign, its light and its shadow. `pad` is the
+ * room the material needs (from `materialPad`); `measure` defaults to the estimate.
+ */
+export function layoutText(text: string, t: NeonTypography, pad: number, measure: TextMeasurer = estimateTextWidth): NeonLayout {
+  const rows = textRows(text);
+  const pitch = t.fontSize * t.lineHeight;
+  const measured = rows.map((r, i) => {
+    const glyphs = [...r].length;
+    let w: number;
+    try { w = measure(r, t); } catch { w = estimateTextWidth(r, t); }
+    if (!Number.isFinite(w) || w < 0) w = estimateTextWidth(r, t);
+    return { text: r, y: i * pitch, width: w + t.letterSpacing * Math.max(0, glyphs - 1) };
+  });
+  const width = Math.max(t.fontSize * 0.3, ...measured.map((r) => r.width));
+  const textAnchor = t.align;
+  const anchorX = textAnchor === 'start' ? -width / 2 : textAnchor === 'end' ? width / 2 : 0;
+  /* Monoline tubes stand proud of the glyph by half the tube on every side. */
+  const top = -t.fontSize * CAP - t.strokeWidth;
+  const bottom = (rows.length - 1) * pitch + t.fontSize * DESCENT + t.strokeWidth;
+  const box = { x: -width / 2 - t.strokeWidth, y: top, width: width + 2 * t.strokeWidth, height: bottom - top };
+  return {
+    rows: measured,
+    anchorX,
+    textAnchor,
+    box,
+    viewBox: { x: box.x - pad, y: box.y - pad, width: box.width + 2 * pad, height: box.height + 2 * pad },
+    pad,
+  };
+}

package/src/motion/neon/wall.ts

@@ -0,0 +1,157 @@
+/* eslint-disable comppack/no-raw-colour -- wall colours are scene content (measured from the reference), not theme colours. */
+import { hexToRgb, isHexColor, mixHex } from './config';
+import { rand } from './random';
+
+/**
+ * **The brick wall behind the sign — procedural, seeded, vector.** The reference's wall is baked
+ * into the same pixels as its neon (the EPS is six raster tiles), so it can't be lifted out as a
+ * reusable layer. It is rebuilt from what the reference shows (`docs/NEON-TEXT.md`):
+ *
+ *   - running bond, a brick ≈ 180 × 62 on the 2000-unit artboard (≈ 2.9 : 1), mortar ≈ 4
+ *   - dark navy bricks with rounded corners, a lighter upper face whose lower edge is wavy and
+ *     chipped, a darker foot, and a thin lit top edge
+ *   - near-black at the edges (≈ #07090A), saturated navy where the light reaches (≈ #00086A)
+ *
+ * Two outputs, both static SVG strings, drawn once as images (so a flickering sign never makes the
+ * browser re-rasterise hundreds of bricks and a noise filter every frame):
+ *   `neonWallSvg`      the wall as seen, with its own ambient light, grain and vignette
+ *   `neonWallMaskSvg`  its albedo: bright bricks, dark mortar. The canvas masks the neon's light
+ *                      spill with it, so the light lands on brick faces and not in the joints.
+ */
+export type NeonWallConfig = {
+  enabled: boolean;
+  seed: number;
+  /** Brick size and joint, in stage units. */
+  brickWidth: number;
+  brickHeight: number;
+  mortar: number;
+  brickColor: string;
+  mortarColor: string;
+  /** Brick-to-brick shade variation, 0…1. */
+  variation: number;
+  /** Surface grain, 0…1. */
+  texture: number;
+  /** The room's own light on the wall (the reference's blue/purple cast). */
+  ambientColor: string;
+  /** Ambient light intensity, 0…1. */
+  ambient: number;
+  /** Edge darkening, 0…1. */
+  vignette: number;
+  /** How strongly each neon element lights the wall, 0…2. */
+  lightSpill: number;
+  /** How far that light reaches beyond the element, in stage units. */
+  spillRadius: number;
+  /** Whether a glitch also jolts the wall light. */
+  glitchAffectsWall: boolean;
+};
+
+export const DEFAULT_NEON_WALL: NeonWallConfig = {
+  enabled: true,
+  seed: 7356951,
+  brickWidth: 150,
+  brickHeight: 52,
+  mortar: 4,
+  brickColor: '#0D1230',
+  mortarColor: '#030409',
+  variation: 0.5,
+  texture: 0.5,
+  ambientColor: '#1F2FD0',
+  ambient: 0.55,
+  vignette: 0.85,
+  lightSpill: 1,
+  spillRadius: 260,
+  glitchAffectsWall: true,
+};
+
+export type Brick = { x: number; y: number; w: number; h: number; shade: number; face: [number, number][]; foot: number; slot: number };
+
+const r1 = (v: number) => Math.round(v * 10) / 10;
+const safeHex = (v: string, fallback: string) => (isHexColor(v) ? v : fallback);
+
+/** Every brick that touches a `width × height` stage, in running bond. */
+export function wallBricks(wall: NeonWallConfig, width: number, height: number): Brick[] {
+  const bw = Math.max(20, wall.brickWidth);
+  const bh = Math.max(10, wall.brickHeight);
+  const m = Math.max(0, Math.min(bh / 3, wall.mortar));
+  const bricks: Brick[] = [];
+  const rows = Math.ceil(height / bh) + 1;
+  const cols = Math.ceil(width / bw) + 2;
+  for (let row = 0; row < rows; row++) {
+    const offset = row % 2 ? -bw / 2 : 0;
+    for (let col = 0; col < cols; col++) {
+      const slot = row * 1000 + col;
+      const r = (salt: number) => rand(wall.seed, slot, 300 + salt);
+      const x = offset + col * bw + m / 2 + (r(1) - 0.5) * m * 0.6;
+      const y = row * bh + m / 2 + (r(2) - 0.5) * m * 0.4;
+      const w = bw - m + (r(3) - 0.5) * m * 0.6;
+      const h = bh - m;
+      if (x > width || x + w < 0 || y > height) continue;
+      /* The lighter face: its lower edge sits at 40–62 % of the brick and wanders, with a chip or two. */
+      const base = 0.4 + 0.22 * r(4);
+      const n = 7 + Math.floor(r(5) * 5);
+      const face: [number, number][] = [];
+      for (let i = 0; i <= n; i++) {
+        const u = i / n;
+        const chip = r(20 + i) < 0.18 ? 0.12 * r(40 + i) : 0;
+        face.push([x + u * w, y + h * (base + (r(60 + i) - 0.5) * 0.1 - chip)]);
+      }
+      bricks.push({ x, y, w, h, shade: (r(6) - 0.5) * 2 * wall.variation, face, foot: 0.78 + 0.1 * r(7), slot });
+    }
+  }
+  return bricks;
+}
+
+function brickMarkup(b: Brick, fill: string, faceFill: string, footFill: string, edge: string, faceOpacity: number): string {
+  const rx = Math.min(5, b.h * 0.12);
+  const face = [`M${r1(b.x + rx)} ${r1(b.y + 1.5)}`, `L${r1(b.x + b.w - rx)} ${r1(b.y + 1.5)}`, `Q${r1(b.x + b.w - 1.5)} ${r1(b.y + 1.5)} ${r1(b.x + b.w - 1.5)} ${r1(b.y + rx)}`]
+    .concat([...b.face].reverse().map(([x, y]) => `L${r1(Math.min(b.x + b.w - 1.5, Math.max(b.x + 1.5, x)))} ${r1(y)}`))
+    .concat([`L${r1(b.x + 1.5)} ${r1(b.y + rx)}`, `Q${r1(b.x + 1.5)} ${r1(b.y + 1.5)} ${r1(b.x + rx)} ${r1(b.y + 1.5)}Z`]).join('');
+  return `<rect x="${r1(b.x)}" y="${r1(b.y)}" width="${r1(b.w)}" height="${r1(b.h)}" rx="${r1(rx)}" fill="${fill}"/>`
+    + `<path d="${face}" fill="${faceFill}" opacity="${faceOpacity}"/>`
+    + `<rect x="${r1(b.x + 2)}" y="${r1(b.y + b.h * b.foot)}" width="${r1(b.w - 4)}" height="${r1(b.h * (1 - b.foot) - 1.5)}" rx="${r1(rx * 0.6)}" fill="${footFill}" opacity="0.55"/>`
+    + `<rect x="${r1(b.x + rx)}" y="${r1(b.y + 0.6)}" width="${r1(b.w - 2 * rx)}" height="1.2" fill="${edge}" opacity="0.35"/>`;
+}
+
+const shadeHex = (hex: string, s: number) => (s >= 0 ? mixHex(hex, '#FFFFFF', s * 0.12) : mixHex(hex, '#000000', -s * 0.35));
+
+/** The wall as seen: bricks, grain, the room's ambient light and the vignette. A standalone SVG document. */
+export function neonWallSvg(wall: NeonWallConfig, width: number, height: number): string {
+  const brick = safeHex(wall.brickColor, DEFAULT_NEON_WALL.brickColor);
+  const mortar = safeHex(wall.mortarColor, DEFAULT_NEON_WALL.mortarColor);
+  const ambient = safeHex(wall.ambientColor, DEFAULT_NEON_WALL.ambientColor);
+  const bricks = wallBricks(wall, width, height)
+    .map((b) => {
+      const fill = shadeHex(brick, b.shade);
+      return brickMarkup(b, fill, mixHex(fill, '#3F55FF', 0.16), mixHex(fill, '#000000', 0.5), mixHex(fill, '#8FA0FF', 0.45), 0.9);
+    })
+    .join('');
+  const grain = Math.max(0, Math.min(1, wall.texture));
+  const [ar = 0, ag = 0, ab = 0] = hexToRgb(ambient).map((v) => v / 255);
+  const amb = Math.max(0, Math.min(1, wall.ambient));
+  const vig = Math.max(0, Math.min(1, wall.vignette));
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}">`
+    + `<defs>`
+    + `<filter id="g" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="${wall.seed % 1000}"/>`
+    + `<feColorMatrix values="0 0 0 0 0.6  0 0 0 0 0.65  0 0 0 0 0.9  0 0 0 ${(0.6 * grain).toFixed(3)} -${(0.3 * grain).toFixed(3)}"/><feComposite in2="SourceGraphic" operator="in"/></filter>`
+    + `<filter id="s" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.018 0.05" numOctaves="3" seed="${(wall.seed + 7) % 1000}"/>`
+    + `<feColorMatrix values="0 0 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0 ${(0.9 * grain).toFixed(3)} -0.3"/><feComposite in2="SourceGraphic" operator="in"/></filter>`
+    + `<radialGradient id="a" cx="50%" cy="47%" r="55%"><stop offset="0" stop-color="rgb(${Math.round(ar * 255)},${Math.round(ag * 255)},${Math.round(ab * 255)})" stop-opacity="${(0.95 * amb).toFixed(3)}"/><stop offset="0.5" stop-color="${ambient}" stop-opacity="${(0.4 * amb).toFixed(3)}"/><stop offset="1" stop-color="${ambient}" stop-opacity="0"/></radialGradient>`
+    + `<radialGradient id="v" cx="50%" cy="48%" r="72%"><stop offset="0.35" stop-color="#000" stop-opacity="0"/><stop offset="1" stop-color="#000" stop-opacity="${(0.92 * vig).toFixed(3)}"/></radialGradient>`
+    + `<mask id="m"><rect width="100%" height="100%" fill="#555"/><g fill="#fff">${wallBricks(wall, width, height).map((b) => `<rect x="${r1(b.x)}" y="${r1(b.y)}" width="${r1(b.w)}" height="${r1(b.h)}" rx="3"/>`).join('')}</g></mask>`
+    + `</defs>`
+    + `<rect width="${width}" height="${height}" fill="${mortar}"/>`
+    + `<g>${bricks}</g>`
+    + (grain > 0 ? `<g filter="url(#s)">${wallBricks(wall, width, height).map((b) => `<rect x="${r1(b.x)}" y="${r1(b.y)}" width="${r1(b.w)}" height="${r1(b.h)}" fill="#000"/>`).join('')}</g><rect width="${width}" height="${height}" fill="#fff" filter="url(#g)" opacity="0.28"/>` : '')
+    + (amb > 0 ? `<rect width="${width}" height="${height}" fill="url(#a)" mask="url(#m)" style="mix-blend-mode:screen"/>` : '')
+    + (vig > 0 ? `<rect width="${width}" height="${height}" fill="url(#v)"/>` : '')
+    + `</svg>`;
+}
+
+/** The wall's albedo, as a luminance mask: brick faces bright, feet dimmer, mortar dark. */
+export function neonWallMaskSvg(wall: NeonWallConfig, width: number, height: number): string {
+  const bricks = wallBricks(wall, width, height).map((b) => brickMarkup(b, '#B8B8B8', '#FFFFFF', '#6A6A6A', '#FFFFFF', 0.85)).join('');
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}"><rect width="${width}" height="${height}" fill="#2A2A2A"/>${bricks}</svg>`;
+}
+
+/** A standalone SVG document as a data URL. */
+export const svgDataUrl = (svg: string) => `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;

package/src/motion/paperfold/PaperFold.tsx

@@ -0,0 +1,45 @@
+import { useMemo } from 'react';
+import { applyPatch, type PaperFoldConfig } from './config';
+import { timeline } from './engine';
+import { PaperFoldFrame, type PaperFoldFrameProps } from './PaperFoldFrame';
+
+export type HandPoseProps = { x?: number; y?: number; rotation?: number; scale?: number; wrist?: number; grip?: number; fingerCurl?: number; thumbBend?: number };
+export type PaperFoldProps = Omit<PaperFoldFrameProps, 'config' | 'frame'> & {
+  /** A validated, complete config (resolveConfig / presetConfig). */
+  config: PaperFoldConfig;
+  /** FOLD PROGRESS, 0‥1: 0 = flat, 0.5 = the first fold done, 1 = completely folded. Omit to play the timeline at `frame`. */
+  progress?: number;
+  /** Per-hand pose over the config (grip anchor x/y on the sheet, rotation, scale, wrist bend, grip, finger curl, thumb bend). */
+  handPose?: { top?: HandPoseProps; bottom?: HandPoseProps };
+  /** Multiplies every crease's line and ridge (paperMaterial.creaseShadow / creaseHighlight). */
+  creaseStrength?: number;
+  /** Authored motion frame. With `progress` it defaults to the end of the intro (the hands already hold the paper). */
+  frame?: number;
+};
+
+const HAND_PATHS: Record<keyof HandPoseProps, string> = {
+  x: 'x', y: 'y', rotation: 'rotation', scale: 'scale', wrist: 'pose.wrist', grip: 'pose.grip', fingerCurl: 'pose.fingerCurl', thumbBend: 'pose.thumbBend',
+};
+
+/**
+ * **`<PaperFold progress handPose creaseStrength />`** — the paper-fold template as a component driven
+ * by values, not by a clock. Its props become a patch over `config` — the same validated patch an agent
+ * or the editor would send — and the package renderer draws the result, so a Remotion composition can
+ * pass `progress={frame / durationInFrames}` and every frame is decided by that number alone.
+ * A prop outside its control's range is refused: the config is drawn unchanged.
+ */
+export function PaperFold({ config, progress, handPose, creaseStrength, frame, ...rest }: PaperFoldProps) {
+  const patched = useMemo(() => {
+    const patch: Record<string, unknown> = {};
+    if (progress !== undefined) Object.assign(patch, { 'motion.progressMode': 'manual', 'motion.foldProgress': Math.min(1, Math.max(0, progress)) });
+    if (creaseStrength !== undefined) Object.assign(patch, { 'paperMaterial.creaseShadow': creaseStrength, 'paperMaterial.creaseHighlight': creaseStrength });
+    for (const id of ['top', 'bottom'] as const) {
+      for (const [k, v] of Object.entries(handPose?.[id] ?? {})) if (v !== undefined) patch[`hands.${id}.${HAND_PATHS[k as keyof HandPoseProps]}`] = v;
+    }
+    if (!Object.keys(patch).length) return config;
+    const r = applyPatch(config, { patch });
+    return r.valid ? r.config : config;
+  }, [config, progress, handPose, creaseStrength]);
+  const at = frame ?? (progress !== undefined ? timeline(patched).phases.intro.end : 0);
+  return <PaperFoldFrame config={patched} frame={at} {...rest} />;
+}