reelkit-cli 0.6.0 → 0.10.0

package/src/{remotion → hyperframes}/kit/theme.ts

@@ -1,42 +1,44 @@
-import { loadFont as loadBody } from "@remotion/google-fonts/Inter";
-import { loadFont as loadDisplay } from "@remotion/google-fonts/Sora";
-import { loadFont as loadArchivoBlack } from "@remotion/google-fonts/ArchivoBlack";
-import { loadFont as loadBebasNeue } from "@remotion/google-fonts/BebasNeue";
-import { loadFont as loadGreatVibes } from "@remotion/google-fonts/GreatVibes";
-import { loadFont as loadKanit } from "@remotion/google-fonts/Kanit";
-import { loadFont as loadModak } from "@remotion/google-fonts/Modak";
-import { loadFont as loadMontserrat } from "@remotion/google-fonts/Montserrat";
-import { loadFont as loadRoboto } from "@remotion/google-fonts/Roboto";
-import { loadFont as loadRobotoSlab } from "@remotion/google-fonts/RobotoSlab";
-import { loadFont as loadSacramento } from "@remotion/google-fonts/Sacramento";
-import { loadFont as loadUnbounded } from "@remotion/google-fonts/Unbounded";
-import { loadFont as loadBungeeShade } from "@remotion/google-fonts/BungeeShade";
-import { loadFont as loadCinzel } from "@remotion/google-fonts/Cinzel";
-import { loadFont as loadCreepster } from "@remotion/google-fonts/Creepster";
-import { loadFont as loadHeebo } from "@remotion/google-fonts/Heebo";
-import { loadFont as loadKaushanScript } from "@remotion/google-fonts/KaushanScript";
-import { loadFont as loadLilitaOne } from "@remotion/google-fonts/LilitaOne";
-import { loadFont as loadMrsSaintDelafield } from "@remotion/google-fonts/MrsSaintDelafield";
-import { loadFont as loadOrbitron } from "@remotion/google-fonts/Orbitron";
-import { loadFont as loadOutfit } from "@remotion/google-fonts/Outfit";
-import { loadFont as loadPermanentMarker } from "@remotion/google-fonts/PermanentMarker";
-import { loadFont as loadPlayfairDisplay } from "@remotion/google-fonts/PlayfairDisplay";
-import { loadFont as loadRubik } from "@remotion/google-fonts/Rubik";
-import { loadFont as loadRye } from "@remotion/google-fonts/Rye";
-import { loadFont as loadSyne } from "@remotion/google-fonts/Syne";
-import { loadFont as loadYellowtail } from "@remotion/google-fonts/Yellowtail";
-import { loadFont as loadAlef } from "@remotion/google-fonts/Alef";
-import { loadFont as loadAmaticSC } from "@remotion/google-fonts/AmaticSC";
-import { loadFont as loadAssistant } from "@remotion/google-fonts/Assistant";
-import { loadFont as loadDavidLibre } from "@remotion/google-fonts/DavidLibre";
-import { loadFont as loadFrankRuhlLibre } from "@remotion/google-fonts/FrankRuhlLibre";
-import { loadFont as loadFredoka } from "@remotion/google-fonts/Fredoka";
-import { loadFont as loadKarantina } from "@remotion/google-fonts/Karantina";
-import { loadFont as loadNotoSansHebrew } from "@remotion/google-fonts/NotoSansHebrew";
-import { loadFont as loadSecularOne } from "@remotion/google-fonts/SecularOne";
-import { loadFont as loadSuezOne } from "@remotion/google-fonts/SuezOne";
-import { loadFont as loadVarelaRound } from "@remotion/google-fonts/VarelaRound";
-import { Easing } from "remotion";
+import { loadFont } from "../fonts";
+const loadBody = (_style: string, _options: unknown) => loadFont("Inter", "inter");
+const loadDisplay = (_style: string, _options: unknown) => loadFont("Sora", "sora");
+const loadArchivoBlack = (_style: string, _options: unknown) => loadFont("Archivo Black", "archivo-black");
+const loadBebasNeue = (_style: string, _options: unknown) => loadFont("Bebas Neue", "bebas-neue");
+const loadGreatVibes = (_style: string, _options: unknown) => loadFont("Great Vibes", "great-vibes");
+const loadJetBrainsMono = (_style: string, _options: unknown) => loadFont("JetBrains Mono", "jetbrains-mono");
+const loadKanit = (_style: string, _options: unknown) => loadFont("Kanit", "kanit");
+const loadModak = (_style: string, _options: unknown) => loadFont("Modak", "modak");
+const loadMontserrat = (_style: string, _options: unknown) => loadFont("Montserrat", "montserrat");
+const loadRoboto = (_style: string, _options: unknown) => loadFont("Roboto", "roboto");
+const loadRobotoSlab = (_style: string, _options: unknown) => loadFont("Roboto Slab", "roboto-slab");
+const loadSacramento = (_style: string, _options: unknown) => loadFont("Sacramento", "sacramento");
+const loadUnbounded = (_style: string, _options: unknown) => loadFont("Unbounded", "unbounded");
+const loadBungeeShade = (_style: string, _options: unknown) => loadFont("Bungee Shade", "bungee-shade");
+const loadCinzel = (_style: string, _options: unknown) => loadFont("Cinzel", "cinzel");
+const loadCreepster = (_style: string, _options: unknown) => loadFont("Creepster", "creepster");
+const loadHeebo = (_style: string, _options: unknown) => loadFont("Heebo", "heebo");
+const loadKaushanScript = (_style: string, _options: unknown) => loadFont("Kaushan Script", "kaushan-script");
+const loadLilitaOne = (_style: string, _options: unknown) => loadFont("Lilita One", "lilita-one");
+const loadMrsSaintDelafield = (_style: string, _options: unknown) => loadFont("Mrs Saint Delafield", "mrs-saint-delafield");
+const loadOrbitron = (_style: string, _options: unknown) => loadFont("Orbitron", "orbitron");
+const loadOutfit = (_style: string, _options: unknown) => loadFont("Outfit", "outfit");
+const loadPermanentMarker = (_style: string, _options: unknown) => loadFont("Permanent Marker", "permanent-marker");
+const loadPlayfairDisplay = (_style: string, _options: unknown) => loadFont("Playfair Display", "playfair-display");
+const loadRubik = (_style: string, _options: unknown) => loadFont("Rubik", "rubik");
+const loadRye = (_style: string, _options: unknown) => loadFont("Rye", "rye");
+const loadSyne = (_style: string, _options: unknown) => loadFont("Syne", "syne");
+const loadYellowtail = (_style: string, _options: unknown) => loadFont("Yellowtail", "yellowtail");
+const loadAlef = (_style: string, _options: unknown) => loadFont("Alef", "alef");
+const loadAmaticSC = (_style: string, _options: unknown) => loadFont("Amatic SC", "amatic-sc");
+const loadAssistant = (_style: string, _options: unknown) => loadFont("Assistant", "assistant");
+const loadDavidLibre = (_style: string, _options: unknown) => loadFont("David Libre", "david-libre");
+const loadFrankRuhlLibre = (_style: string, _options: unknown) => loadFont("Frank Ruhl Libre", "frank-ruhl-libre");
+const loadFredoka = (_style: string, _options: unknown) => loadFont("Fredoka", "fredoka");
+const loadKarantina = (_style: string, _options: unknown) => loadFont("Karantina", "karantina");
+const loadNotoSansHebrew = (_style: string, _options: unknown) => loadFont("Noto Sans Hebrew", "noto-sans-hebrew");
+const loadSecularOne = (_style: string, _options: unknown) => loadFont("Secular One", "secular-one");
+const loadSuezOne = (_style: string, _options: unknown) => loadFont("Suez One", "suez-one");
+const loadVarelaRound = (_style: string, _options: unknown) => loadFont("Varela Round", "varela-round");
+import { Easing } from "../frame";
 
 // Loaded once for every video. Hero text must never fall back to a system default font.
 const display = loadDisplay("normal", { weights: ["600", "700", "800"], subsets: ["latin"] });
@@ -77,6 +79,7 @@ const loaders = {
   // Genre faces for film-style titles (original designs, not imitations of any film's logo):
   cinzel: () => loadCinzel("normal", { weights: ["700", "900"], ...latin }), // Roman inscription capitals: epic, historical
   playfairDisplay: () => loadPlayfairDisplay("normal", { weights: ["700", "900"], ...latin }), // high-contrast serif: elegant, editorial
+  jetbrainsMono: () => loadJetBrainsMono("normal", { weights: ["400", "700"], ...latin }), // monospace: terminals, code, small labels
   orbitron: () => loadOrbitron("normal", { weights: ["700", "900"], ...latin }), // geometric sci-fi
   rye: () => loadRye("normal", { weights: ["400"], ...latin }), // western poster
   creepster: () => loadCreepster("normal", { weights: ["400"], ...latin }), // horror
@@ -96,6 +99,7 @@ const loaders = {
   amaticSC: () => loadAmaticSC("normal", { weights: ["400", "700"], ...hebrew }), // hand-lettered capitals
 };
 export type KitFont = keyof typeof loaders;
+export const KIT_FONTS = Object.keys(loaders) as KitFont[];
 const loaded = new Map<KitFont, string>();
 export function font(name: KitFont): string {
   let family = loaded.get(name);

package/src/hyperframes/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/hyperframes/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/hyperframes/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) } };
+}