reelkit-cli 0.6.0 → 0.8.0

package/src/remotion/kit/three-fx-math.ts

@@ -0,0 +1,192 @@
+// The arithmetic behind Assemble3D, Particles3D, Hero3D/Screen3D, Warp3D and Scene3D's moods, with no three.js in it. Everything is a pure function of the frame and
+// of a seed (mulberry32 through hash01, never Math.random), so any frame can be drawn on its own and the same frame is always the same.
+import { hash01 } from "./seeded";
+import { locate, sortKeys, mix } from "./motion-math";
+import type { Vec3 } from "./three-math";
+
+const clamp01 = (n: number) => (n > 0 ? (n < 1 ? n : 1) : 0);
+export const easeOutCubic = (t: number) => 1 - (1 - clamp01(t)) ** 3;
+const smooth = (t: number) => { const x = clamp01(t); return x * x * (3 - 2 * x); };
+
+// ---------- Assemble3D ----------
+export type AssembleShape = "grid" | "ring" | "sphere" | "wall" | "text";
+export type AssembleOrder = "y" | "x" | "radial" | "random";
+export const MAX_PIECES = 4000;
+
+// The slots of a shape, `count` of them, centred on the origin and scaled so that the widest side is 1 (the height of a ring or a sphere may be anything within it).
+// "text" is made by the typeface sampler (sample-text.ts), not here; its slots arrive as `targets`.
+export function shapeSlots(shape: Exclude<AssembleShape, "text">, count: number): Vec3[] {
+  const n = Math.max(1, Math.min(MAX_PIECES, Math.round(count)));
+  const out: Vec3[] = [];
+  if (shape === "sphere") {
+    // A Fibonacci lattice: evenly spread over the surface.
+    const golden = Math.PI * (3 - Math.sqrt(5));
+    for (let i = 0; i < n; i++) { const y = n === 1 ? 0 : 1 - (i / (n - 1)) * 2, r = Math.sqrt(Math.max(0, 1 - y * y)), a = i * golden; out.push([Math.cos(a) * r * 0.5, y * 0.5, Math.sin(a) * r * 0.5]); }
+    return out;
+  }
+  if (shape === "ring") {
+    // A band: rows of pieces round a circle, the rows stacked, so it reads as a ring seen from the front too.
+    const rows = Math.max(1, Math.round(Math.sqrt(n / 6))), per = Math.ceil(n / rows);
+    for (let i = 0; i < n; i++) { const r = Math.floor(i / per), k = i % per, a = ((k + (r % 2) * 0.5) / per) * Math.PI * 2; out.push([Math.cos(a) * 0.5, (r - (rows - 1) / 2) * (0.5 / Math.max(rows, 4)) * 1.1, Math.sin(a) * 0.5]); }
+    return out;
+  }
+  if (shape === "wall") {
+    // A brick wall one piece deep, every other row shifted half a piece.
+    const cols = Math.max(1, Math.round(Math.sqrt(n * 1.6))), rows = Math.ceil(n / cols);
+    for (let i = 0; i < n; i++) { const r = Math.floor(i / cols), c = i % cols; out.push([(c + (r % 2) * 0.5) / cols - 0.5 + 0.5 / cols, 0.5 * (rows / cols) * 0.0 + ((rows - 1) / 2 - r) / cols, 0]); }
+    return centred(out);
+  }
+  // grid: a slab, close to a cube in proportion, a few pieces deep.
+  const d = Math.max(1, Math.round(Math.cbrt(n / 4))), cols = Math.max(1, Math.round(Math.sqrt((n / d) * 1.4))), rows = Math.ceil(n / d / cols);
+  for (let i = 0; i < n; i++) { const z = Math.floor(i / (cols * rows)), r = Math.floor(i / cols) % rows, c = i % cols; out.push([c / cols, (rows - 1 - r) / cols, z / cols]); }
+  return centred(out);
+}
+
+// Moves a set of slots so its middle is the origin and scales it so its widest side is 1.
+export function centred(points: Vec3[]): Vec3[] {
+  if (!points.length) return points;
+  const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
+  for (const p of points) for (let k = 0; k < 3; k++) { lo[k] = Math.min(lo[k]!, p[k]!); hi[k] = Math.max(hi[k]!, p[k]!); }
+  const size = Math.max(hi[0]! - lo[0]!, hi[1]! - lo[1]!, hi[2]! - lo[2]!, 1e-9);
+  return points.map((p) => [(p[0] - (lo[0]! + hi[0]!) / 2) / size, (p[1] - (lo[1]! + hi[1]!) / 2) / size, (p[2] - (lo[2]! + hi[2]!) / 2) / size] as Vec3);
+}
+
+// Each piece's place in the order, 0 to 1: bottom to top ("y"), left to right ("x"), from the middle out ("radial") or shuffled ("random").
+export function assembleRanks(targets: readonly Vec3[], order: AssembleOrder = "y", seed = 0): number[] {
+  const key = targets.map((p, i) => (order === "y" ? p[1] : order === "x" ? p[0] : order === "radial" ? Math.hypot(p[0], p[1], p[2]) : hash01(i, seed + 11)));
+  const idx = key.map((_, i) => i).sort((a, b) => key[a]! - key[b]! || a - b);
+  const ranks = new Array<number>(targets.length).fill(0);
+  idx.forEach((piece, place) => { ranks[piece] = targets.length > 1 ? place / (targets.length - 1) : 0; });
+  return ranks;
+}
+
+export type AssembleTiming = { ranks: readonly number[]; from?: number; frames?: number };
+// How far piece `i` has come at `frame`, 0 (still in the cloud) to 1 (in its slot): the pieces start one after another in the order of their rank over the first
+// 60 percent of `frames` and each takes the other 40 percent; every piece is home at from + frames and none moves before its own start.
+export function assembleProgress(frame: number, i: number, o: AssembleTiming): number {
+  const from = o.from ?? 0, frames = Math.max(2, o.frames ?? 60), each = frames * 0.4, spread = frames - each;
+  const start = from + (o.ranks[i] ?? 0) * spread;
+  return clamp01((frame - start) / each);
+}
+// How many pieces are home at `frame`: for a piece counter.
+export function assembledCount(frame: number, o: AssembleTiming): number {
+  let n = 0;
+  for (let i = 0; i < o.ranks.length; i++) if (assembleProgress(frame, i, o) >= 1) n++;
+  return n;
+}
+// The frame the last piece lands: put the lock sound here (cuesFor "assemble": [from, this]).
+export const assembleEnd = (o: { from?: number; frames?: number }): number => (o.from ?? 0) + Math.max(2, o.frames ?? 60);
+
+export type PieceState = { position: Vec3; rotation: Vec3; scale: number };
+// Where piece `i` is: a seeded start in a cloud (`spread` times the arrangement's size, around `from`), a flight to its slot on an arc with a lift and a turn
+// that unwinds, then rest. `slot` is the slot in the arrangement's own units.
+export function pieceAt(frame: number, i: number, slot: Vec3, o: AssembleTiming & { seed?: number; spread?: number }): PieceState {
+  const p = assembleProgress(frame, i, o), seed = o.seed ?? 0, spread = o.spread ?? 3;
+  const a = hash01(i, seed + 1) * Math.PI * 2, b = Math.acos(2 * hash01(i, seed + 2) - 1), r = spread * (0.55 + 0.45 * hash01(i, seed + 3));
+  const start: Vec3 = [Math.sin(b) * Math.cos(a) * r, Math.cos(b) * r * 0.8 + 0.4, Math.sin(b) * Math.sin(a) * r - 0.5];
+  const e = easeOutCubic(p), lift = Math.sin(Math.PI * p) * (0.25 + 0.35 * hash01(i, seed + 4));
+  const turn = (1 - e) * Math.PI * 2 * (0.5 + hash01(i, seed + 5));
+  return {
+    position: [mix(start[0], slot[0], e), mix(start[1], slot[1], e) + lift, mix(start[2], slot[2], e)],
+    rotation: [turn * (hash01(i, seed + 6) - 0.5) * 2, turn * (hash01(i, seed + 7) - 0.5) * 2, turn * (hash01(i, seed + 8) - 0.5)],
+    scale: 0.35 + 0.65 * smooth(p * 1.6),
+  };
+}
+
+// ---------- Particles3D ----------
+export type ParticleShape = "sphere" | "torus" | "knot" | "galaxy" | "plane" | "text";
+export const MAX_POINTS = 60_000;
+// `count` points on a shape, as a flat [x, y, z, x, y, z, ...] array, centred, the widest side 1. Seeded: the same shape and seed give the same points.
+export function particleShape(shape: Exclude<ParticleShape, "text">, count: number, seed = 0): Float32Array {
+  const n = Math.max(1, Math.min(MAX_POINTS, Math.round(count))), out = new Float32Array(n * 3);
+  const put = (i: number, x: number, y: number, z: number) => { out[i * 3] = x; out[i * 3 + 1] = y; out[i * 3 + 2] = z; };
+  for (let i = 0; i < n; i++) {
+    const u = hash01(i, seed + 21), v = hash01(i, seed + 22), w = hash01(i, seed + 23);
+    if (shape === "sphere") { const a = u * Math.PI * 2, c = 2 * v - 1, s = Math.sqrt(1 - c * c); put(i, Math.cos(a) * s * 0.5, c * 0.5, Math.sin(a) * s * 0.5); }
+    else if (shape === "torus") { const a = u * Math.PI * 2, b = v * Math.PI * 2, R = 0.32, r = 0.15 + 0.03 * w; put(i, (R + r * Math.cos(b)) * Math.cos(a), r * Math.sin(b), (R + r * Math.cos(b)) * Math.sin(a)); }
+    else if (shape === "knot") {
+      // A (2,3) torus knot curve with the points spread in a thin tube round it.
+      const t = u * Math.PI * 2, q = 3, p = 2, rad = 0.3 + 0.12 * Math.cos(q * t), tube = 0.035 * Math.sqrt(w), ang = v * Math.PI * 2;
+      put(i, rad * Math.cos(p * t) + tube * Math.cos(ang), 0.14 * Math.sin(q * t) + tube * Math.sin(ang), rad * Math.sin(p * t) + tube * Math.cos(ang * 2));
+    } else if (shape === "galaxy") {
+      // Three arms winding out from a bright core, thin in height.
+      const arm = Math.floor(w * 3), r = Math.pow(u, 0.7) * 0.5, a = arm * ((Math.PI * 2) / 3) + r * 7 + (v - 0.5) * 0.7 * (1 - r), h = (hash01(i, seed + 24) - 0.5) * 0.06 * (1 - r * 1.2);
+      put(i, Math.cos(a) * r, h, Math.sin(a) * r);
+    } else put(i, u - 0.5, (hash01(i, seed + 25) - 0.5) * 0.03, v - 0.5);
+  }
+  return out;
+}
+
+// The point set at `morph` between two sets of the same length, with a little seeded drift that breathes with the frame and is zero at the ends of the morph.
+export function morphPoints(a: Float32Array, b: Float32Array, morph: number, frame: number, fps: number, o: { drift?: number; seed?: number } = {}): Float32Array {
+  const n = Math.min(a.length, b.length), out = new Float32Array(n), t = smooth(morph), d = (o.drift ?? 0.012) * (1 + 3 * Math.sin(Math.PI * t)), s = (frame / fps) * 0.8;
+  for (let i = 0; i < n; i += 3) {
+    const k = i / 3, ph = hash01(k, (o.seed ?? 0) + 31) * 6.283;
+    // Points leave their start in a staggered way so the morph is a flow and not a slide.
+    const lt = smooth(clamp01((morph - 0.25 * hash01(k, (o.seed ?? 0) + 32)) / 0.75));
+    for (let c = 0; c < 3; c++) out[i + c] = a[i + c]! + (b[i + c]! - a[i + c]!) * lt + Math.sin(s + ph + c * 2.1) * d;
+  }
+  return out;
+}
+// The morph between `range[0]` and `range[1]` frames (20 to 80 unless set): 0 before, 1 after.
+export const morphAt = (frame: number, range: [number, number] = [20, 80]): number => clamp01((frame - range[0]) / Math.max(1, range[1] - range[0]));
+
+// ---------- Hero3D / Screen3D ----------
+export type PoseKey = { frame: number; rotation?: Vec3; position?: Vec3; scale?: number };
+export type Pose = { rotation: Vec3; position: Vec3; scale: number };
+export const REST_POSE: Pose = { rotation: [0, 0, 0], position: [0, 0, 0], scale: 1 };
+// The pose at `frame`: each key's values carry forward when a key leaves them out, and the move toward a key starts 12 frames before its frame on a spring and lands on it
+// (the same rule as Camera and Carry). Rotation is in degrees.
+export function poseAt(keys: readonly PoseKey[] | undefined, frame: number, fps: number, base: Pose = REST_POSE): Pose {
+  if (!keys?.length) return base;
+  const sorted = sortKeys(keys);
+  let cur = base;
+  const resolved = sorted.map((k) => { cur = { rotation: k.rotation ?? cur.rotation, position: k.position ?? cur.position, scale: k.scale ?? cur.scale }; return { frame: k.frame, ...cur }; });
+  const first = { frame: resolved[0]!.frame - 1, ...base };
+  const all = [first, ...resolved];
+  const { from, to, p } = locate(all, frame, fps, {});
+  const m = (a: Vec3, b: Vec3): Vec3 => [mix(a[0], b[0], p), mix(a[1], b[1], p), mix(a[2], b[2], p)];
+  return { rotation: m(from.rotation, to.rotation), position: m(from.position, to.position), scale: mix(from.scale, to.scale, p) };
+}
+
+// ---------- Warp3D ----------
+export type SpeedKey = { frame: number; speed: number };
+// The warp's speed at `frame`: a number is constant; keys are smoothly joined (and hold their last value). `burst` makes a short rise and fall instead: for a
+// transition burst of 12 to 20 frames, 0 outside it and `peak` in the middle.
+export function warpSpeed(frame: number, speed: number | readonly SpeedKey[] | undefined, burst?: { frame: number; frames: number; peak?: number }): number {
+  if (burst) { const t = (frame - burst.frame) / Math.max(2, burst.frames); return t < 0 || t > 1 ? 0 : (burst.peak ?? 1) * Math.sin(Math.PI * t) ** 1.5; }
+  if (typeof speed === "number") return speed;
+  if (!speed?.length) return 1;
+  const k = sortKeys(speed);
+  if (frame <= k[0]!.frame) return k[0]!.speed;
+  for (let i = 1; i < k.length; i++) if (frame <= k[i]!.frame) return mix(k[i - 1]!.speed, k[i]!.speed, smooth((frame - k[i - 1]!.frame) / Math.max(1, k[i]!.frame - k[i - 1]!.frame)));
+  return k[k.length - 1]!.speed;
+}
+// How far the field has travelled by `frame`: the sum of the speed of every frame before it. Deterministic and the same in any order.
+export function warpTravel(frame: number, speed: number | readonly SpeedKey[] | undefined, burst?: { frame: number; frames: number; peak?: number }): number {
+  let s = 0;
+  for (let f = 0; f < Math.max(0, Math.floor(frame)); f++) s += warpSpeed(f, speed, burst);
+  return s;
+}
+export type Streak = { x: number; y: number; z: number; mix: number };
+// The streaks' fixed places: seeded angle and distance from the vanishing point and a depth, spread so that the middle stays quieter than the edges.
+export function warpStreaks(count: number, seed = 0): Streak[] {
+  return Array.from({ length: Math.max(1, Math.min(4000, Math.round(count))) }, (_, i) => {
+    const a = hash01(i, seed + 41) * Math.PI * 2, r = 0.12 + 1.6 * Math.sqrt(hash01(i, seed + 42));
+    return { x: Math.cos(a) * r, y: Math.sin(a) * r, z: hash01(i, seed + 43), mix: hash01(i, seed + 44) };
+  });
+}
+
+// ---------- Scene3D mood ----------
+export type Mood = "studio" | "night" | "sunset" | "neon";
+export const MOODS: readonly Mood[] = ["studio", "night", "sunset", "neon"];
+export type MoodLights = { ambient: { color: string; intensity: number }; key: { color: string; intensity: number; position: Vec3 }; fill: { color: string; intensity: number; position: Vec3 }; rim: { color: string; intensity: number; position: Vec3 }; fog: { color: string; near: number; far: number } };
+// The lights and the fog tint of each mood, chosen together so that they agree: the light colours are what the fog is the colour of in the distance.
+export function moodLights(mood: Mood): MoodLights {
+  switch (mood) {
+    case "night": return { ambient: { color: "#8aa0e0", intensity: 1.0 }, key: { color: "#b9ceff", intensity: 2.4, position: [3, 6, 7] }, fill: { color: "#27345f", intensity: 0.7, position: [-6, 2, 4] }, rim: { color: "#5b7cff", intensity: 2.2, position: [0, 3, -8] }, fog: { color: "#0b1226", near: 9, far: 34 } };
+    case "sunset": return { ambient: { color: "#ffb48a", intensity: 0.9 }, key: { color: "#ffd2a0", intensity: 2.6, position: [6, 3, 6] }, fill: { color: "#b05a8a", intensity: 0.9, position: [-6, 1, 4] }, rim: { color: "#ff7a5a", intensity: 2.2, position: [-2, 3, -8] }, fog: { color: "#c9694f", near: 10, far: 36 } };
+    case "neon": return { ambient: { color: "#3a2a6a", intensity: 0.5 }, key: { color: "#ffffff", intensity: 1.2, position: [3, 5, 8] }, fill: { color: "#ff2fb4", intensity: 1.6, position: [-7, 1, 4] }, rim: { color: "#22d3ee", intensity: 3.0, position: [6, 2, -6] }, fog: { color: "#12062a", near: 9, far: 32 } };
+    default: return { ambient: { color: "#ffffff", intensity: 1.2 }, key: { color: "#fff7ee", intensity: 2.8, position: [4, 6, 8] }, fill: { color: "#dfe8ff", intensity: 1.1, position: [-6, 2, 4] }, rim: { color: "#ffffff", intensity: 1.4, position: [0, 3, -8] }, fog: { color: "#e8eaf0", near: 12, far: 40 } };
+  }
+}

package/src/remotion/kit/three-math.ts

@@ -0,0 +1,145 @@
+// The arithmetic behind the kit's 3D components, with no three.js or React in it. Everything is a pure function of the frame (a renderer draws
+// frames out of order and in parallel), and uses the same timing rule as the 2D Camera: the move toward a key starts `lead` frames before its
+// frame on a spring and lands on the key's frame exactly.
+import { locate, mix, sortKeys, travel } from "./motion-math";
+import { springs } from "./theme";
+
+export type Vec3 = [number, number, number];
+export type Camera3DKey = { frame: number; x?: number; y?: number; z?: number; lookAt?: Vec3; fov?: number };
+export type Camera3DView = { position: Vec3; lookAt: Vec3; fov: number };
+
+export const DEFAULT_CAMERA: Camera3DView = { position: [0, 0, 6], lookAt: [0, 0, 0], fov: 50 };
+
+// A key that leaves a value out keeps the one before it; the first key starts from the default camera.
+function resolve(keys: readonly Camera3DKey[]): (Camera3DView & { frame: number })[] {
+  let last: Camera3DView = DEFAULT_CAMERA;
+  return sortKeys(keys).map((k) => {
+    last = { position: [k.x ?? last.position[0], k.y ?? last.position[1], k.z ?? last.position[2]], lookAt: k.lookAt ?? last.lookAt, fov: k.fov ?? last.fov };
+    return { frame: k.frame, ...last };
+  });
+}
+
+// The scene units the camera sees. At fov 50 the height is about 0.93 times the distance to the object plane, and the width that times the frame's
+// aspect (width over height): on a 9:16 phone frame about 0.52 times the distance, so 3.1 units across at z 6, not 5.5. Pure geometry.
+export const visibleHeight = (z: number, fov = DEFAULT_CAMERA.fov): number => 2 * Math.abs(z) * Math.tan(degToRad(fov) / 2);
+export const visibleWidth = (z: number, aspect: number, fov = DEFAULT_CAMERA.fov): number => visibleHeight(z, fov) * aspect;
+
+// The camera's key views, resolved: the distance to a plane at `planeZ` and the field of view at each key. Without keys, the default camera.
+export function cameraViews(keys: readonly Camera3DKey[] | undefined, planeZ = 0): { distance: number; fov: number }[] {
+  const views = keys?.length ? resolve(keys) : [{ position: DEFAULT_CAMERA.position, fov: DEFAULT_CAMERA.fov }];
+  return views.map((v) => ({ distance: Math.max(0.5, v.position[2] - planeZ), fov: v.fov }));
+}
+
+// How much of the plane at `planeZ` the camera sees at the key where it sees the least (its closest, or its narrowest field of view): the width and
+// height in scene units that a thing must fit inside to be whole at every moment of the shot.
+export function nearestVisible(keys: readonly Camera3DKey[] | undefined, aspect: number, planeZ = 0): { width: number; height: number; distance: number } {
+  let best = { width: Infinity, height: Infinity, distance: 0 };
+  for (const v of cameraViews(keys, planeZ)) {
+    const width = visibleWidth(v.distance, aspect, v.fov);
+    if (width < best.width) best = { width, height: visibleHeight(v.distance, v.fov), distance: v.distance };
+  }
+  return best;
+}
+
+// The size at which a word measured at size 1 (`unit` width and height) fills `fit` of the visible width, and no more than `fit` of the height.
+export const fitTextSize = (unit: { width: number; height: number }, view: { width: number; height: number }, fit: number): number =>
+  Math.min((fit * view.width) / Math.max(1e-6, unit.width), (fit * view.height) / Math.max(1e-6, unit.height));
+
+// The scale at which a ring (see ringPosition) lies inside `fit` of the frame at every key of the camera, however it has turned. `radius` is the ring's
+// radius at scale 1, `itemW` and `itemH` the size of one card, `at` where the ring's middle is. An item seen side-on is narrow, a billboard is not.
+export function ringFitScale(o: {
+  keys?: readonly Camera3DKey[]; aspect: number; fit: number; radius: number; itemW: number; itemH: number; tiltDeg?: number; billboard?: boolean; at?: Vec3;
+}): number {
+  const at = o.at ?? [0, 0, 0], tilt = degToRad(o.tiltDeg ?? 0);
+  const views = (o.keys?.length ? resolve(o.keys) : [{ position: DEFAULT_CAMERA.position, fov: DEFAULT_CAMERA.fov }]);
+  let best = Infinity;
+  for (const view of views) {
+    const camZ = view.position[2];
+    const spread = (s: number): number => {
+      let worst = 0;
+      for (let deg = 0; deg < 360; deg += 6) {
+        const a = degToRad(deg);
+        const x = s * o.radius * Math.sin(a), z = s * o.radius * Math.cos(a) * Math.cos(tilt), y = -s * o.radius * Math.cos(a) * Math.sin(tilt);
+        const d = camZ - (at[2] + z);
+        if (d < 0.4) return Infinity;
+        const halfW = (s * o.itemW) / 2 * (o.billboard ? 1 : Math.max(Math.abs(Math.cos(a)), 0.1));
+        worst = Math.max(worst, (Math.abs(x + at[0] - view.position[0]) + halfW) / (visibleWidth(d, o.aspect, view.fov) / 2), (Math.abs(y + at[1] - view.position[1]) + (s * o.itemH) / 2) / (visibleHeight(d, view.fov) / 2));
+      }
+      return worst;
+    };
+    let lo = 0.001, hi = 60;
+    for (let i = 0; i < 40; i++) { const mid = (lo + hi) / 2; if (spread(mid) <= o.fit) lo = mid; else hi = mid; }
+    best = Math.min(best, lo);
+  }
+  return best;
+}
+
+// A radius at which `count` cards of width `itemW` stand side by side on a ring without touching.
+export const naturalRingRadius = (count: number, itemW: number): number => Math.max(itemW * 0.7, (itemW * 1.15) / (2 * Math.sin(Math.PI / Math.max(2, count))));
+
+const mixVec = (a: Vec3, b: Vec3, p: number): Vec3 => [mix(a[0], b[0], p), mix(a[1], b[1], p), mix(a[2], b[2], p)];
+
+// Where the 3D camera is, what it looks at and its field of view at `frame`.
+export function camera3DAt(keys: readonly Camera3DKey[] | undefined, frame: number, fps: number, timing: { lead?: number; stiffness?: number; damping?: number } = {}): Camera3DView {
+  if (!keys?.length) return DEFAULT_CAMERA;
+  const { from, to, p } = locate(resolve(keys), frame, fps, timing);
+  return { position: mixVec(from.position, to.position, p), lookAt: mixVec(from.lookAt, to.lookAt, p), fov: Math.max(1, Math.min(170, mix(from.fov, to.fov, p))) };
+}
+
+export type Entrance3D = "rise" | "turn" | "fly" | "none";
+export type EntranceState = { offset: Vec3; rotation: Vec3; scale: number; opacity: number };
+export const ENTRANCE_FRAMES = 24;
+
+// How an object arrives, as offsets from where it rests. `size` scales the distances, so a large word travels as far, in proportion, as a small one.
+// Before `delay` it is not there; after the entrance it rests exactly (offsets 0, scale 1, opacity 1).
+export function entranceAt(kind: Entrance3D, frame: number, delay: number, fps: number, size = 1): EntranceState {
+  const rest: EntranceState = { offset: [0, 0, 0], rotation: [0, 0, 0], scale: 1, opacity: 1 };
+  if (kind === "none") return rest;
+  const t = (frame - delay) / ENTRANCE_FRAMES;
+  const p = travel(t, fps, springs.smooth, ENTRANCE_FRAMES);
+  const left = 1 - p;
+  if (t <= 0) return { offset: kind === "rise" ? [0, -size * 0.8, 0] : kind === "fly" ? [0, size * 0.4, -size * 14] : [0, 0, 0], rotation: kind === "turn" ? [0, -Math.PI / 2, 0] : [0, 0, 0], scale: kind === "turn" ? 0.9 : 1, opacity: 0 };
+  const opacity = Math.min(1, Math.max(0, t * 3));
+  switch (kind) {
+    // Adding 0 turns a negative zero into a plain one, so a finished entrance equals the resting state exactly.
+    case "rise": return { ...rest, offset: [0, -size * 0.8 * left + 0, 0], opacity };
+    case "turn": return { ...rest, rotation: [0, (-Math.PI / 2) * left + 0, 0], scale: 0.9 + 0.1 * p, opacity };
+    case "fly": return { ...rest, offset: [0, size * 0.4 * left, -size * 14 * left + 0], opacity };
+  }
+}
+
+// Where item `i` of `count` sits on a ring in the horizontal plane around the origin, which turns by `speed` degrees a frame and is tipped
+// toward the camera by `tiltDeg`. Item 0 starts at the front. `facing` is the turn about the vertical axis that makes it look outward, so that
+// the item at the front faces the camera.
+export function ringPosition(i: number, count: number, frame: number, o: { radius?: number; speed?: number; tiltDeg?: number } = {}): { position: Vec3; facing: number; tilt: number } {
+  const radius = o.radius ?? 3, speed = o.speed ?? 0.5, tilt = ((o.tiltDeg ?? 0) * Math.PI) / 180;
+  const angle = (((i / Math.max(1, count)) * 360 + speed * frame) * Math.PI) / 180;
+  const x = radius * Math.sin(angle), z = radius * Math.cos(angle);
+  // The tilt turns the ring about the horizontal axis: the front dips and the back rises.
+  return { position: [x, -z * Math.sin(tilt), z * Math.cos(tilt)], facing: angle, tilt };
+}
+
+// A slow drift for an object that floats: small, smooth, and the same for the same frame. `seed` gives each object its own phase.
+export function floatAt(frame: number, fps: number, amount = 1, seed = 0): { offset: Vec3; rotation: Vec3 } {
+  const t = (frame / fps) * 2 * Math.PI;
+  return {
+    offset: [Math.sin(t / 7 + seed) * 0.04 * amount, Math.sin(t / 5 + seed * 1.7) * 0.07 * amount, 0],
+    rotation: [Math.sin(t / 9 + seed * 0.6) * 0.03 * amount, Math.sin(t / 6 + seed) * 0.05 * amount, Math.sin(t / 8 + seed * 2.1) * 0.015 * amount],
+  };
+}
+
+export const degToRad = (d: number) => (d * Math.PI) / 180;
+
+// Colour arithmetic for the faces of cards, on "#rrggbb" strings (the card normalises any CSS colour to that first).
+const parseHex = (c: string): [number, number, number] => {
+  const h = c.replace("#", "");
+  const f = h.length === 3 ? h.split("").map((x) => x + x).join("") : h;
+  return [parseInt(f.slice(0, 2), 16) || 0, parseInt(f.slice(2, 4), 16) || 0, parseInt(f.slice(4, 6), 16) || 0];
+};
+const toHex = (v: number[]) => "#" + v.map((x) => Math.max(0, Math.min(255, Math.round(x))).toString(16).padStart(2, "0")).join("");
+// `a` moved `t` (0 to 1) of the way toward `b`.
+export const mixHex = (a: string, b: string, t: number): string => { const x = parseHex(a), y = parseHex(b); return toHex(x.map((v, i) => v + (y[i]! - v) * t)); };
+// Relative luminance, 0 (black) to 1 (white).
+export const luminance = (c: string): number => { const [r, g, b] = parseHex(c).map((v) => v / 255); return 0.2126 * r! + 0.7152 * g! + 0.0722 * b!; };
+// Dark ink on a light face and white ink on a dark one.
+export const inkOn = (face: string): string => (luminance(face) > 0.62 ? "#14141c" : "#ffffff");

package/src/remotion/kit/transition-math.ts

@@ -0,0 +1,116 @@
+// The arithmetic behind SceneFrame's transitions, with no React in it. Everything is a pure function of the frame, so a renderer may draw
+// frames out of order. A scene's exit plays in its last frames and the next scene's enter in its first, so nothing overlaps scenes and a
+// transition is complete exactly at the boundary: the cut stays where the beat is.
+export const TRANSITION_KINDS = ["fade", "cut", "zoom-in", "zoom-out", "zoom-through", "push-left", "push-right", "push-up", "push-down", "whip-left", "whip-right", "blur", "turn", "color-push", "rgb-whip", "flash", "ring", "flip"] as const;
+export type TransitionKind = (typeof TRANSITION_KINDS)[number];
+
+export const DEFAULT_TRANSITION_FRAMES = 8;
+export const MAX_TRANSITION_FRAMES = 20;
+
+// How a scene looks at one moment. tx and ty are fractions of the frame's width and height; blur is in fractions of the width (so the same
+// transition looks the same at every size); rotateY is in degrees; scale grows from `origin`.
+// `fx` is present only for the kinds that draw something over or around the scene: a field of colour, a channel split, a flash, a ring, an inverted frame.
+// `amount` is how far from rest it is, 0 to 1, the same `away` as above: 1 is the scene fully covered (a field or a flash), fully closed (a ring) or inverted (a flip).
+export type FxKind = "color-push" | "rgb-whip" | "flash" | "ring" | "flip";
+export type TransitionFx = { kind: FxKind; phase: "enter" | "exit"; amount: number };
+export type TransitionState = { opacity: number; scale: number; tx: number; ty: number; blurX: number; blurY: number; rotateY: number; fx?: TransitionFx };
+export const IDENTITY: TransitionState = { opacity: 1, scale: 1, tx: 0, ty: 0, blurX: 0, blurY: 0, rotateY: 0 };
+
+// How many frames one edge of a scene takes for a kind: `transitionFrames` if given, else the kind's own length (a colour push 10, a rgb whip 6, a ring 12, 8
+// for every other). A flash is never longer than 4 frames (3 unless set) and a flip is always 1 frame: they are hits, not moves.
+export function transitionSpan(kind: TransitionKind | undefined, frames: number | undefined): number {
+  if (kind === "flip") return 1;
+  const own = kind === "color-push" ? 10 : kind === "rgb-whip" ? 6 : kind === "ring" ? 12 : kind === "flash" ? 3 : DEFAULT_TRANSITION_FRAMES;
+  const n = transitionLength(Number.isFinite(frames) ? frames : own);
+  return kind === "flash" ? Math.min(4, n) : n;
+}
+// The kinds whose picture changes most on the scene boundary itself (the frame the next scene starts): the field, the flash, the closed ring and the inverted frame are at their fullest there.
+export const PEAKS_ON_BOUNDARY: readonly TransitionKind[] = ["cut", "color-push", "flash", "ring", "flip"];
+
+const clamp01 = (n: number) => (n > 0 ? (n < 1 ? n : 1) : 0);
+const inOut = (t: number) => (t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2);
+const out = (t: number) => 1 - (1 - t) ** 3;
+const inn = (t: number) => t * t * t;
+const mix = (a: number, b: number, t: number) => a + (b - a) * t;
+
+// The number of frames a transition takes: 8 unless asked, never fewer than 1 and at most 20.
+export function transitionLength(frames: number | undefined): number {
+  const n = Number.isFinite(frames) ? Math.round(frames as number) : DEFAULT_TRANSITION_FRAMES;
+  return Math.max(1, Math.min(MAX_TRANSITION_FRAMES, n));
+}
+
+const BLUR = 0.03; // of the frame's width: about 32 px on a phone-wide frame
+const WHIP_BLUR = 0.09;
+
+// The state of a scene that is `away` (0 is the scene as it should be, 1 is as far away as the transition takes it), for one kind and phase.
+// For an enter the scene travels from away to the identity and for an exit from the identity to away, so p runs 0 to 1 either way
+// and the caller says which end is "away". Opacity of every kind other than "cut" and "fade" is 1 except where a blur or a scale hides it.
+function awayState(kind: TransitionKind, phase: "enter" | "exit", away: number): TransitionState {
+  const a = clamp01(away);
+  // An entering scene comes from the positive side and an exiting one leaves toward the negative side, so a push moves everything one way.
+  const dir = phase === "enter" ? 1 : -1;
+  switch (kind) {
+    case "fade": return { ...IDENTITY, opacity: 1 - a };
+    case "cut": return IDENTITY;
+    case "zoom-in": return { ...IDENTITY, scale: mix(1, 1.25, a), blurX: BLUR * a, blurY: BLUR * a, opacity: 1 - clamp01((a - 0.3) / 0.7) };
+    case "zoom-out": return { ...IDENTITY, scale: mix(1, 0.8, a), blurX: BLUR * a, blurY: BLUR * a, opacity: 1 - clamp01((a - 0.3) / 0.7) };
+    // Going through: the old scene rushes toward the aimed point and blurs away; the new one arrives from small at the same point.
+    case "zoom-through": return phase === "exit"
+      ? { ...IDENTITY, scale: mix(1, 3, a), blurX: BLUR * 1.5 * a, blurY: BLUR * 1.5 * a, opacity: 1 - clamp01((a - 0.35) / 0.65) }
+      : { ...IDENTITY, scale: mix(1, 0.4, a), blurX: BLUR * a, blurY: BLUR * a, opacity: 1 - clamp01(a * 1.4 - 0.4) };
+    case "push-left": return { ...IDENTITY, tx: dir * a };
+    case "push-right": return { ...IDENTITY, tx: -dir * a };
+    case "push-up": return { ...IDENTITY, ty: dir * a };
+    case "push-down": return { ...IDENTITY, ty: -dir * a };
+    // A whip is a push that is fast and smeared along its own direction; the smear grows with how far from rest the scene is.
+    case "whip-left": return { ...IDENTITY, tx: dir * a, blurX: WHIP_BLUR * a };
+    case "whip-right": return { ...IDENTITY, tx: -dir * a, blurX: WHIP_BLUR * a };
+    case "blur": return { ...IDENTITY, blurX: BLUR * 1.5 * a, blurY: BLUR * 1.5 * a, opacity: 1 - a * 0.9 };
+    // A quarter turn about the vertical axis: the old scene turns edge-on and is gone, the new one turns in from edge-on.
+    case "turn": return { ...IDENTITY, rotateY: dir * 90 * a, opacity: 1 - clamp01((a - 0.85) / 0.15) };
+    case "color-push": case "flash": case "ring": return a > 0 ? { ...IDENTITY, fx: { kind, phase, amount: a } } : IDENTITY;
+    case "flip": return a > 0 ? { ...IDENTITY, fx: { kind, phase, amount: 1 } } : IDENTITY;
+    // A whip with the red and blue channels pulled apart: the split grows with the same amount as the smear.
+    case "rgb-whip": return a > 0 ? { ...IDENTITY, tx: dir * a * 0.6, blurX: WHIP_BLUR * 0.7 * a, fx: { kind, phase, amount: a } } : IDENTITY;
+  }
+}
+
+// How far along a scene's enter is at `frame` and how far its exit is, as 0..1 progress, given the scene's length and each edge's own length.
+export function edges(frame: number, durationInFrames: number, enterFrames: number, exitFrames = enterFrames): { enter: number; exit: number } {
+  const en = Math.min(enterFrames, Math.floor(durationInFrames / 2)), ex = Math.min(exitFrames, Math.floor(durationInFrames / 2));
+  return { enter: en <= 0 ? 1 : clamp01(frame / en), exit: ex <= 0 ? 0 : clamp01((frame - (durationInFrames - ex)) / ex) };
+}
+
+// The state of one scene at one frame. The default for both is "fade", which is the scene's opacity going 0 to 1 over the first frames and
+// 1 to 0 over the last, linearly, as it always was.
+export function transitionAt(frame: number, durationInFrames: number, o: { enter?: TransitionKind; exit?: TransitionKind; transitionFrames?: number } = {}): TransitionState {
+  const ek = o.enter ?? "fade", xk = o.exit ?? "fade";
+  const { enter, exit } = edges(frame, durationInFrames, transitionSpan(ek, o.transitionFrames), transitionSpan(xk, o.transitionFrames));
+  const ease = (kind: TransitionKind, phase: "enter" | "exit", p: number) => {
+    // A fade stays linear; a whip accelerates out and brakes in; a flash is linear (it is 3 frames); everything else eases both ways.
+    if (kind === "fade" || kind === "flash" || kind === "flip") return p;
+    if (kind === "whip-left" || kind === "whip-right" || kind === "rgb-whip") return phase === "exit" ? inn(p) : out(p);
+    return inOut(p);
+  };
+  const entering = awayState(ek, "enter", 1 - ease(ek, "enter", enter));
+  const leaving = awayState(xk, "exit", ease(xk, "exit", exit));
+  // Only one of the two is ever away from the identity (the windows do not overlap); multiply to be safe at the one frame where both are 0 and 1.
+  const state: TransitionState = {
+    opacity: entering.opacity * leaving.opacity, scale: entering.scale * leaving.scale, tx: entering.tx + leaving.tx, ty: entering.ty + leaving.ty,
+    blurX: Math.max(entering.blurX, leaving.blurX), blurY: Math.max(entering.blurY, leaving.blurY), rotateY: entering.rotateY + leaving.rotateY,
+  };
+  const fx = entering.fx && leaving.fx ? (entering.fx.amount >= leaving.fx.amount ? entering.fx : leaving.fx) : entering.fx ?? leaving.fx;
+  return fx ? { ...state, fx } : state;
+}
+
+const r = (n: number, d = 4) => Math.round(n * 10 ** d) / 10 ** d;
+
+// The CSS for a state in a frame of w by h pixels. `blurFilter` is set when the blur is the same in both directions and `directional`
+// when it is not (a whip), which needs an SVG filter because CSS blur has no direction.
+export function transitionCss(s: TransitionState, w: number, h: number, origin: { x: number; y: number } = { x: 0.5, y: 0.5 }): { opacity: number; transform: string; transformOrigin: string; blurPx: { x: number; y: number } } {
+  const parts: string[] = [];
+  if (s.rotateY) parts.push(`perspective(${Math.round(w * 1.6)}px) rotateY(${r(s.rotateY, 2)}deg)`);
+  if (s.tx || s.ty) parts.push(`translate(${r(s.tx * w, 2)}px, ${r(s.ty * h, 2)}px)`);
+  if (s.scale !== 1) parts.push(`scale(${r(s.scale)})`);
+  return { opacity: r(s.opacity), transform: parts.length ? parts.join(" ") : "none", transformOrigin: `${r(origin.x * 100, 2)}% ${r(origin.y * 100, 2)}%`, blurPx: { x: r(s.blurX * w, 2), y: r(s.blurY * w, 2) } };
+}

package/src/remotion/kit/ui-math.ts

@@ -0,0 +1,145 @@
+// The arithmetic behind the product-surface components, with no React in it. Every component's timing props are frames counted from the component's own
+// mount: the frame useCurrentFrame() gives where the component stands (inside a SceneFrame, the scene's own frame; inside a Sequence, the sequence's).
+// Each component has a companion function here that takes the SAME props and returns the frames of its events, in that same clock, so a sound can be
+// placed on them: add the scene's startFrame (or pass it as `offset` to cuesFor) to make them absolute.
+import { measureSpring } from "remotion";
+
+export const clamp01 = (n: number) => (n > 0 ? (n < 1 ? n : 1) : 0);
+export const outCubic = (t: number) => 1 - (1 - clamp01(t)) ** 3;
+export const inOutCubic = (t: number) => { const x = clamp01(t); return x < 0.5 ? 4 * x * x * x : 1 - (-2 * x + 2) ** 3 / 2; };
+
+// The frame at which each character of `text` appears when typed at `cps` characters a second from frame `start`: the first at `start`. Length is text.length.
+export function typedFrames(text: string, cps: number, fps: number, start = 0): number[] {
+  const step = fps / Math.max(0.1, cps);
+  return Array.from({ length: [...text].length }, (_, i) => start + Math.floor(i * step));
+}
+// How many characters are showing at `frame`.
+export function typedCount(frame: number, text: string, cps: number, fps: number, start = 0): number {
+  const f = typedFrames(text, cps, fps, start);
+  let n = 0;
+  while (n < f.length && f[n]! <= frame) n++;
+  return n;
+}
+
+export type PromptTiming = { text: string; cps?: number; delay?: number; reply?: string; replyCps?: number; sendPause?: number; replyDelay?: number };
+export type PromptEvents = { type: number[]; typedEnd: number; send: number; replyStart: number; reply: number[]; end: number };
+export const PROMPT_DEFAULTS = { cps: 22, delay: 6, replyCps: 70, sendPause: 9, replyDelay: 12 } as const;
+// The events of a PromptBox, from the same props: the frame of every typed character, the frame typing is over, the frame the send button presses, the frame
+// the reply starts and the frame of each of its characters, and the last frame of it all.
+export function promptFrames(p: PromptTiming, fps: number): PromptEvents {
+  const cps = p.cps ?? PROMPT_DEFAULTS.cps, delay = p.delay ?? PROMPT_DEFAULTS.delay;
+  const type = typedFrames(p.text, cps, fps, delay);
+  const typedEnd = (type[type.length - 1] ?? delay) + 1;
+  const send = typedEnd + (p.sendPause ?? PROMPT_DEFAULTS.sendPause);
+  const replyStart = send + (p.replyDelay ?? PROMPT_DEFAULTS.replyDelay);
+  const reply = p.reply ? typedFrames(p.reply, p.replyCps ?? PROMPT_DEFAULTS.replyCps, fps, replyStart) : [];
+  return { type, typedEnd, send, replyStart, reply, end: Math.max(send + 8, (reply[reply.length - 1] ?? 0) + 1) };
+}
+
+export type LineKind = "cmd" | "out" | "ok" | "warn" | "edit";
+export type TerminalLine = { kind: LineKind; text: string; add?: number; del?: number; wait?: number };
+// The frame each line of a TerminalLog appears: `rate` lines a second (default 3) from `delay` (default 6); a line's `wait` adds frames before it.
+export function lineFrames(lines: readonly TerminalLine[], rate = 3, fps = 30, delay = 6): number[] {
+  const step = fps / Math.max(0.1, rate);
+  let t = delay;
+  return lines.map((l, i) => { t += (i === 0 ? 0 : step) + (l.wait ?? 0); return Math.round(t); });
+}
+export type TerminalTiming = { lines: readonly TerminalLine[]; rate?: number; delay?: number; checklist?: readonly string[]; checkEvery?: number };
+// The events of a TerminalLog: each line's frame, each checklist item's frame (the strike-through, one every `checkEvery` frames, default 16, starting a beat
+// after the last line), and the frame the work is done.
+export function terminalFrames(p: TerminalTiming, fps: number): { lines: number[]; checks: number[]; done: number } {
+  const lines = lineFrames(p.lines, p.rate, fps, p.delay);
+  const first = (lines[lines.length - 1] ?? p.delay ?? 6) + 6, every = p.checkEvery ?? 16;
+  const checks = (p.checklist ?? []).map((_, i) => first + i * every);
+  return { lines, checks, done: Math.max(lines[lines.length - 1] ?? 0, checks[checks.length - 1] ?? 0) + 10 };
+}
+// "m:ss" for `seconds`.
+export const clock = (seconds: number): string => `${Math.floor(Math.max(0, seconds) / 60)}:${String(Math.floor(Math.max(0, seconds) % 60)).padStart(2, "0")}`;
+
+export type CursorPoint = { x: number; y: number; click?: boolean; hold?: number };
+export const CURSOR_MOVE_FRAMES = 22;
+// The frame the cursor reaches each point: the first at `delay` (default 4), then `moveFrames` (default 22) after leaving the one before, which it does
+// after `hold` frames (default 10 on a click, 5 otherwise).
+export function cursorArrivals(points: readonly CursorPoint[], o: { delay?: number; moveFrames?: number } = {}): number[] {
+  const move = o.moveFrames ?? CURSOR_MOVE_FRAMES;
+  let t = o.delay ?? 4;
+  return points.map((p, i) => { if (i > 0) t += (points[i - 1]!.hold ?? (points[i - 1]!.click ? 10 : 5)) + move; return t; });
+}
+// The frame of each click: 3 frames after the cursor reaches a point marked `click`.
+export function clickFrames(points: readonly CursorPoint[], o: { delay?: number; moveFrames?: number } = {}): number[] {
+  const at = cursorArrivals(points, o);
+  return points.flatMap((p, i) => (p.click ? [at[i]! + 3] : []));
+}
+// Where the cursor is at `frame`, as fractions of the frame: it travels each leg on an ease with a gentle arc, never a straight line, and rests on the points.
+export function cursorAt(points: readonly CursorPoint[], frame: number, o: { delay?: number; moveFrames?: number } = {}): { x: number; y: number } {
+  const at = cursorArrivals(points, o), move = o.moveFrames ?? CURSOR_MOVE_FRAMES;
+  if (points.length === 0) return { x: 0.5, y: 0.5 };
+  for (let i = points.length - 1; i > 0; i--) {
+    if (frame < at[i]! - move) continue;
+    const a = points[i - 1]!, b = points[i]!, t = inOutCubic((frame - (at[i]! - move)) / move);
+    const dx = b.x - a.x, dy = b.y - a.y, bend = 0.14 * (i % 2 ? 1 : -1);
+    const cx = (a.x + b.x) / 2 - dy * bend, cy = (a.y + b.y) / 2 + dx * bend;
+    return { x: (1 - t) ** 2 * a.x + 2 * (1 - t) * t * cx + t * t * b.x, y: (1 - t) ** 2 * a.y + 2 * (1 - t) * t * cy + t * t * b.y };
+  }
+  return { x: points[0]!.x, y: points[0]!.y };
+}
+
+// The frame at which a spring of the given kind has settled (within 1% of its end): the frame a panel or a badge is seen to land.
+export const settledAfter = (config: { stiffness: number; damping: number }, fps: number): number => measureSpring({ fps, config, threshold: 0.01 });
+export const PANEL_SPRING = { stiffness: 170, damping: 19 };
+// The frame a GlassPanel has settled, from its `delay` (default 0).
+export const panelSettleFrame = (delay = 0, fps = 30): number => delay + settledAfter(PANEL_SPRING, fps);
+
+export type ChapterTiming = { delay?: number; badges?: number };
+// The events of a ChapterFrame: the frame each badge pops (the first 14 frames in, then 6 apart) and the frame the progress rule has filled.
+export function chapterFrames(p: ChapterTiming = {}): { badges: number[]; progressDone: number } {
+  const d = p.delay ?? 0;
+  return { badges: Array.from({ length: Math.min(3, p.badges ?? 0) }, (_, i) => d + 14 + i * 6), progressDone: d + 24 };
+}
+
+export const headlineWords = (text: string): string[] => text.trim().split(/\s+/).filter(Boolean);
+const bare = (w: string) => w.replace(/[^\p{L}\p{N}]/gu, "").toLowerCase();
+// The index of `keyword` among the words of `text`, ignoring case and punctuation; throws, listing the words, when it is not one of them.
+export function keywordIndex(text: string, keyword: string): number {
+  const words = headlineWords(text), i = words.findIndex((w) => bare(w) === bare(keyword));
+  if (i < 0) throw new Error(`Headline: the keyword "${keyword}" is not one of the words of "${text}". The words are: ${words.join(", ")}.`);
+  return i;
+}
+// The events of a Headline: the frame each word lands (`per` frames apart, 4 unless set, from `delay`) and the frame its emphasis finishes.
+export function headlineFrames(text: string, o: { delay?: number; per?: number } = {}): { words: number[]; emphasisDone: number } {
+  const n = headlineWords(text).length, d = o.delay ?? 0, per = o.per ?? 4;
+  const words = Array.from({ length: n }, (_, i) => d + i * per + 6);
+  return { words, emphasisDone: (words[n - 1] ?? d) + 14 };
+}
+// Splits the words into the fewest lines that keep the longest near `maxChars`, in order, and returns the lines' word indices.
+export function headlineLines(words: readonly string[], maxChars = 12): number[][] {
+  const lines: number[][] = [[]];
+  let len = 0;
+  words.forEach((w, i) => {
+    const cur = lines[lines.length - 1]!;
+    if (cur.length && len + 1 + w.length > maxChars) { lines.push([i]); len = w.length; } else { cur.push(i); len += (cur.length > 1 ? 1 : 0) + w.length; }
+  });
+  return lines;
+}
+
+// The value of a CounterRoll at `frame`: it eases out over `frames` frames from `delay` and holds `to`.
+export function rollValue(frame: number, o: { from?: number; to: number; frames?: number; delay?: number }): number {
+  const from = o.from ?? 0, t = (frame - (o.delay ?? 0)) / Math.max(1, o.frames ?? 45);
+  return from + (o.to - from) * (1 - (1 - clamp01(t)) ** 4);
+}
+// The frame a CounterRoll lands on its number (`delay` + `frames`, defaults 0 and 45): put the settle chime here.
+export const settleFrame = (o: { delay?: number; frames?: number } = {}): number => (o.delay ?? 0) + (o.frames ?? 45);
+// The frame of the last tick of the roll: it starts at `delay`.
+export const rollStart = (o: { delay?: number } = {}): number => o.delay ?? 0;
+
+// A timecode "mm:ss:ff" of `frame`.
+export const timecode = (frame: number, fps: number): string => {
+  const s = Math.floor(frame / fps);
+  return `${String(Math.floor(s / 60)).padStart(2, "0")}:${String(s % 60).padStart(2, "0")}:${String(Math.floor(frame % fps)).padStart(2, "0")}`;
+};
+
+// The frames of a BrowserFrame: the frame it has settled, and the frames the sheen starts and ends.
+export function browserFrames(o: { delay?: number; fps?: number } = {}): { settled: number; sheenStart: number; sheenEnd: number } {
+  const d = o.delay ?? 0;
+  return { settled: d + settledAfter(PANEL_SPRING, o.fps ?? 30), sheenStart: d + 18, sheenEnd: d + 44 };
+}

package/src/remotion/kit/ui-theme.ts

@@ -0,0 +1,25 @@
+import { inkOn, luminance, mixHex } from "./three-math";
+
+// What the product-surface components (PromptBox, TerminalLog, GlassPanel, ...) share: the three looks, the colours each one gives, and the helpers that
+// say where a component sits. Nothing here needs React.
+export type UiTheme = "light" | "dark" | "glass";
+export const DEFAULT_HERO = "#7C3AED";
+
+// "light" on a light ground and "dark" on a dark one: the theme a component should take when its ground is `bg`.
+export const themeFor = (bg: string): UiTheme => (luminance(bg) > 0.5 ? "light" : "dark");
+
+export type UiColors = { panel: string; stroke: string; ink: string; dim: string; field: string; chip: string; shadow: string; heroInk: string; ok: string; warn: string; bad: string };
+
+// One set of colours per theme. `glass` is the dark slab with a lit hairline: it is meant to sit over a coloured glow and is a little see-through.
+export function uiColors(theme: UiTheme, hero: string): UiColors {
+  const heroInk = inkOn(hero);
+  if (theme === "light") return { panel: "#ffffff", stroke: "rgba(20,20,30,0.12)", ink: "#16161d", dim: "#6b6b78", field: "#f1f1f5", chip: "#e9e9f0", shadow: "rgba(20,20,40,0.22)", heroInk, ok: "#16a34a", warn: "#d97706", bad: "#dc2626" };
+  if (theme === "glass") return { panel: "rgba(14,14,22,0.62)", stroke: "rgba(255,255,255,0.20)", ink: "#f4f4f5", dim: "#a8a8b6", field: "rgba(255,255,255,0.07)", chip: "rgba(255,255,255,0.12)", shadow: "rgba(0,0,0,0.5)", heroInk, ok: "#4ade80", warn: "#fbbf24", bad: "#f87171" };
+  return { panel: "#121219", stroke: "rgba(255,255,255,0.10)", ink: "#f4f4f5", dim: "#9a9aa6", field: "#1b1b26", chip: "#262634", shadow: "rgba(0,0,0,0.55)", heroInk, ok: "#4ade80", warn: "#fbbf24", bad: "#f87171" };
+}
+
+export const rgba = (hex: string, a: number): string => {
+  const m = /^#?([0-9a-f]{6})$/i.exec(mixHex(hex, hex, 0));
+  const n = parseInt(m ? m[1]! : "000000", 16);
+  return `rgba(${(n >> 16) & 255},${(n >> 8) & 255},${n & 255},${a})`;
+};