reelkit-cli 0.6.0 → 0.8.0

package/src/remotion/kit/NamedCursor.tsx

@@ -0,0 +1,54 @@
+import React from "react";
+import { AbsoluteFill, interpolate, useCurrentFrame, useVideoConfig } from "remotion";
+import { fonts } from "./theme";
+import { inkOn } from "./three-math";
+import { DEFAULT_HERO, rgba } from "./ui-theme";
+import { clickFrames, cursorAt, CURSOR_MOVE_FRAMES, type CursorPoint } from "./ui-math";
+
+// A mouse arrow with a coloured name pill (a teammate, an agent), moving along `points` (x, y as fractions of the frame; `click: true` makes it click there,
+// `hold` is the frames it rests, 10 on a click and 5 otherwise) on a smooth arc with ease, and clicking with a ripple. Place it over the scene, above the
+// interface it points at. Times are frames from the component's own mount: it appears at `delay` (default 4) and each leg takes `moveFrames` (22);
+// clickFrames(points, { delay, moveFrames }) gives the click frames for sound. `color` is the pill and the ripple (default the hero colour); `name` is the pill's
+// text. The kit's own cursor: it does not depend on any library cursor.
+export const NamedCursor: React.FC<{
+  points: CursorPoint[];
+  name?: string;
+  color?: string;
+  hero?: string;
+  font?: string;
+  delay?: number;
+  moveFrames?: number;
+  size?: number;
+}> = ({ points, name = "Ava", color, hero = DEFAULT_HERO, font = fonts.body, delay = 4, moveFrames = CURSOR_MOVE_FRAMES, size = 0.055 }) => {
+  const frame = useCurrentFrame();
+  const { width: W, height: H } = useVideoConfig();
+  const tint = color ?? hero;
+  const o = { delay, moveFrames };
+  const pos = cursorAt(points, frame, o);
+  const clicks = clickFrames(points, o);
+  const appear = interpolate(frame, [delay - 4, delay + 2], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
+  const last = clicks.filter((c) => c <= frame).pop();
+  const since = last === undefined ? 99 : frame - last;
+  const press = since < 6 ? 0.88 : 1;
+  const a = W * size;
+  const x = pos.x * W, y = pos.y * H;
+  return (
+    <AbsoluteFill style={{ pointerEvents: "none" }}>
+      {clicks.map((c, i) => {
+        const t = (frame - c) / 18;
+        if (t < 0 || t > 1) return null;
+        const at = cursorAtClick(points, i);
+        return <div key={i} style={{ position: "absolute", left: at.x * W - a * 1.6 * t - a * 0.3, top: at.y * H - a * 1.6 * t - a * 0.3, width: (a * 1.6 * t + a * 0.3) * 2, height: (a * 1.6 * t + a * 0.3) * 2, borderRadius: 999, border: `${Math.max(3, W * 0.005)}px solid ${rgba(tint, 1 - t)}`, background: rgba(tint, 0.18 * (1 - t)) }} />;
+      })}
+      <div style={{ position: "absolute", left: x, top: y, opacity: appear, transform: `scale(${press})`, transformOrigin: "0 0" }}>
+        <svg width={a} height={a * 1.3} viewBox="0 0 24 31" style={{ display: "block", filter: `drop-shadow(0 ${a * 0.06}px ${a * 0.1}px rgba(0,0,0,0.4))` }}>
+          <path d="M2 1.5v24l6.2-5.6 4.1 9.3 4-1.8-4-9.2h8.4Z" fill={tint} stroke="#ffffff" strokeWidth="1.8" strokeLinejoin="round" />
+        </svg>
+        <div style={{ position: "absolute", left: a * 0.72, top: a * 1.0, background: tint, color: inkOn(tint), fontFamily: font, fontWeight: 700, fontSize: W * 0.032, padding: `${W * 0.008}px ${W * 0.026}px`, borderRadius: 999, whiteSpace: "nowrap", boxShadow: `0 ${W * 0.005}px ${W * 0.02}px rgba(0,0,0,0.35)` }}>{name}</div>
+      </div>
+    </AbsoluteFill>
+  );
+};
+
+// The point of the i-th click (clicks are the points marked click, in order).
+const cursorAtClick = (points: readonly CursorPoint[], i: number) => points.filter((p) => p.click)[i] ?? { x: 0.5, y: 0.5 };

package/src/remotion/kit/Orbit3D.tsx

@@ -0,0 +1,49 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+import { CameraKeysContext } from "./scene3d-context";
+import { naturalRingRadius, ringFitScale, ringPosition, type Vec3 } from "./three-math";
+
+// The width and height a child asks for (a Card3D's own props, default 3 by 2), to size the ring around it.
+const itemSize = (child: React.ReactNode): { w: number; h: number } => {
+  const p = (React.isValidElement(child) ? child.props : {}) as { width?: number; height?: number };
+  const w = p.width ?? 3;
+  return { w, h: p.height ?? w * 0.66 };
+};
+
+// Arranges its children on a ring around a point and turns the ring slowly: for a set of cards or logos. Place it inside a Scene3D. Leave `radius` out
+// and the ring sizes itself: the radius is the one at which the cards stand side by side, and the whole ring (radius and cards together) is scaled so
+// that it lies inside `fit` of the frame (default 0.85) at the closest the Scene3D's camera comes, on any aspect and however far it has turned. A
+// `radius` you give wins, in scene units, and then nothing is scaled. speed is degrees a frame (default 0.5, which is a full turn in 24 seconds), tiltDeg
+// tips the ring toward the camera so that the front is lower and the back higher (default 0). Each child faces outward, so the one at the front faces the
+// camera; set billboard to keep every child facing the camera instead. `position` moves the middle of the ring. Put a label or an icon on every card.
+export const Orbit3D: React.FC<{
+  radius?: number;
+  fit?: number;
+  speed?: number;
+  tiltDeg?: number;
+  billboard?: boolean;
+  position?: Vec3;
+  children: React.ReactNode;
+}> = ({ radius, fit = 0.85, speed = 0.5, tiltDeg = 0, billboard = false, position = [0, 0, 0], children }) => {
+  const frame = useCurrentFrame();
+  const { width, height } = useVideoConfig();
+  const keys = React.useContext(CameraKeysContext);
+  const items = React.useMemo(() => React.Children.toArray(children), [children]);
+  let r = radius ?? 3, scale = 1;
+  if (radius === undefined && items.length) {
+    const sizes = items.map(itemSize);
+    const w = Math.max(...sizes.map((s) => s.w)), h = Math.max(...sizes.map((s) => s.h));
+    r = naturalRingRadius(items.length, w);
+    scale = ringFitScale({ keys, aspect: width / height, fit, radius: r, itemW: w, itemH: h, tiltDeg, billboard, at: position });
+  }
+  return (
+    <group position={position}>
+      <group scale={scale}>
+        {items.map((child, i) => {
+          const p = ringPosition(i, items.length, frame, { radius: r, speed, tiltDeg });
+          return <group key={i} position={p.position} rotation={[0, billboard ? 0 : p.facing, 0]}>{child}</group>;
+        })}
+      </group>
+    </group>
+  );
+};

package/src/remotion/kit/Particles3D.tsx

@@ -0,0 +1,74 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+import { AdditiveBlending, BufferAttribute, CanvasTexture, Color, SRGBColorSpace } from "three";
+import { CameraKeysContext } from "./scene3d-context";
+import { textPoints } from "./sample-text";
+import { MAX_POINTS, morphAt, morphPoints, particleShape, type ParticleShape } from "./three-fx-math";
+import { nearestVisible, type Vec3 } from "./three-math";
+
+// A soft round dot, drawn once: the glow of a point.
+const dot = (): CanvasTexture => {
+  const c = document.createElement("canvas");
+  c.width = c.height = 64;
+  const g = c.getContext("2d")!;
+  const r = g.createRadialGradient(32, 32, 0, 32, 32, 32);
+  r.addColorStop(0, "rgba(255,255,255,1)"); r.addColorStop(0.35, "rgba(255,255,255,0.55)"); r.addColorStop(1, "rgba(255,255,255,0)");
+  g.fillStyle = r; g.fillRect(0, 0, 64, 64);
+  const t = new CanvasTexture(c);
+  t.colorSpace = SRGBColorSpace;
+  return t;
+};
+
+// A cloud of glowing points that morphs from one shape to another: an abstract idea made of light. `from` and `to` are "sphere", "torus", "knot", "galaxy", "plane" or
+// "text" (the points fall inside the letters of `text`, a short Latin word). `count` points (12000 unless set, at most 60000). The morph is driven by the frame: it runs
+// between the frames in `morphFrames` (default [20, 80]) and holds either side, or give `morph` (0 to 1) yourself. The points go from the first of `colors` to the second
+// by height, additive and soft, with a gentle seeded drift (`drift`, 0.012) that breathes and is zero at the ends of the morph. `fit` is how much of the frame's width the
+// shape fills at the closest the camera comes (0.8); `size` is the size of a point as a fraction of the shape's width (0.026). Done on the CPU with ordinary points, so it is the same on every machine.
+export const Particles3D: React.FC<{
+  from?: ParticleShape;
+  to?: ParticleShape;
+  text?: string;
+  count?: number;
+  morph?: number;
+  morphFrames?: [number, number];
+  colors?: [string, string];
+  drift?: number;
+  fit?: number;
+  size?: number;
+  seed?: number;
+  spin?: number;
+  position?: Vec3;
+}> = ({ from = "sphere", to = "torus", text = "Relay", count = 12000, morph, morphFrames = [20, 80], colors = ["#7C3AED", "#22D3EE"], drift = 0.012, fit = 0.8, size = 0.026, seed = 0, spin = 6, position = [0, 0, 0] }) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+  const keys = React.useContext(CameraKeysContext);
+  const n = Math.max(1, Math.min(MAX_POINTS, Math.round(count)));
+  const A = React.useMemo(() => (from === "text" ? textPoints(text, n, seed) : particleShape(from, n, seed)), [from, text, n, seed]);
+  const B = React.useMemo(() => (to === "text" ? textPoints(text, n, seed + 7) : particleShape(to, n, seed + 7)), [to, text, n, seed]);
+  const view = nearestVisible(keys, width / height, position[2]);
+  const scale = fit * view.width;
+  const sprite = React.useMemo(dot, []);
+  const tint = React.useMemo(() => {
+    const a = new Color(colors[0]), b = new Color(colors[1]), c = new Color(), out = new Float32Array(n * 3);
+    for (let i = 0; i < n; i++) { const y = (A[i * 3 + 1]! + B[i * 3 + 1]!) / 2 + 0.5; c.copy(a).lerp(b, Math.max(0, Math.min(1, y * 1.1))); out[i * 3] = c.r; out[i * 3 + 1] = c.g; out[i * 3 + 2] = c.b; }
+    return out;
+  }, [colors, n, A, B]);
+  const m = morph ?? morphAt(frame, morphFrames);
+  const pts = React.useMemo(() => morphPoints(A, B, m, frame, fps, { drift, seed }), [A, B, m, frame, fps, drift, seed]);
+  const geometry = React.useRef<import("three").BufferGeometry>(null);
+  React.useLayoutEffect(() => {
+    const g = geometry.current;
+    if (!g) return;
+    g.setAttribute("position", new BufferAttribute(pts, 3));
+    g.setAttribute("color", new BufferAttribute(tint, 3));
+    g.computeBoundingSphere();
+  }, [pts, tint]);
+  return (
+    <group position={position} scale={scale} rotation={[0, (frame / fps) * (spin * Math.PI) / 180, 0]}>
+      <points frustumCulled={false}>
+        <bufferGeometry ref={geometry} />
+        <pointsMaterial map={sprite} size={size * scale} vertexColors transparent opacity={0.92} depthWrite={false} blending={AdditiveBlending} sizeAttenuation />
+      </points>
+    </group>
+  );
+};

package/src/remotion/kit/Place.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+import { AbsoluteFill, useVideoConfig } from "remotion";
+
+// Centres a product-surface component in the frame, at fraction `y` of the height (0.5 is the middle). Used inside the components themselves.
+export const Place: React.FC<{ y?: number; children: React.ReactNode }> = ({ y = 0.5, children }) => {
+  const { height } = useVideoConfig();
+  return (
+    <AbsoluteFill style={{ display: "flex", alignItems: "center", justifyContent: "center", transform: y === 0.5 ? undefined : `translateY(${(y - 0.5) * height}px)` }}>
+      {children}
+    </AbsoluteFill>
+  );
+};

package/src/remotion/kit/PromptBox.tsx

@@ -0,0 +1,84 @@
+import React from "react";
+import { interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { Place } from "./Place";
+import { fonts, springs } from "./theme";
+import { DEFAULT_HERO, rgba, uiColors, type UiTheme } from "./ui-theme";
+import { PROMPT_DEFAULTS, promptFrames, typedCount } from "./ui-math";
+
+// A rounded input with a question typed into it, the way an assistant or a tool is used: the text appears at `cps` characters a second with a caret, `chips`
+// sit under it, a round send button presses when the typing is over, and an optional `reply` streams in below. Every time is a frame from the component's
+// own mount (see ui-math): `delay` is when typing starts (default 6), and promptFrames(props, fps) gives the frame of every character, of the send and of
+// the reply for sound. `width` is a fraction of the frame's width (default 0.86); `theme` is "dark", "light" or "glass" (default "dark"); `y` is the
+// height of the box's middle as a fraction of the frame (default 0.5, the reply hangs below it).
+export const PromptBox: React.FC<{
+  text: string;
+  cps?: number;
+  chips?: string[];
+  reply?: string;
+  replyCps?: number;
+  placeholder?: string;
+  hero?: string;
+  theme?: UiTheme;
+  font?: string;
+  width?: number;
+  delay?: number;
+  sendPause?: number;
+  replyDelay?: number;
+  y?: number;
+}> = ({ text, cps = PROMPT_DEFAULTS.cps, chips = [], reply, replyCps = PROMPT_DEFAULTS.replyCps, placeholder = "Ask anything", hero = DEFAULT_HERO, theme = "dark", font = fonts.body, width: fraction = 0.86, delay = PROMPT_DEFAULTS.delay, sendPause, replyDelay, y = 0.5 }) => {
+  const frame = useCurrentFrame();
+  const { fps, width: W } = useVideoConfig();
+  const c = uiColors(theme, hero);
+  const P = W * fraction;
+  const ev = promptFrames({ text, cps, delay, reply, replyCps, sendPause, replyDelay }, fps);
+  const n = typedCount(frame, text, cps, fps, delay);
+  const typing = frame >= delay && frame < ev.typedEnd + 2;
+  const caretOn = typing || frame < delay || Math.floor((frame - ev.typedEnd) / 8) % 2 === 0;
+  const enter = spring({ frame: frame - 0, fps, config: springs.smooth });
+  const press = interpolate(frame, [ev.send, ev.send + 3, ev.send + 9], [1, 0.86, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
+  const sent = frame >= ev.send;
+  const glow = interpolate(frame, [ev.send, ev.send + 4, ev.send + 18], [0, 1, 0.35], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
+  const chars = [...text], rchars = [...(reply ?? "")];
+  const rn = reply ? ev.reply.filter((f) => f <= frame).length : 0;
+  const fs = P * 0.046;
+  const sparkle = (
+    <svg width={P * 0.06} height={P * 0.06} viewBox="0 0 24 24" style={{ flex: "none", marginTop: P * 0.008 }}>
+      <path d="M12 1.5 14.6 9.4 22.5 12 14.6 14.6 12 22.5 9.4 14.6 1.5 12 9.4 9.4Z" fill={hero} />
+    </svg>
+  );
+  return (
+    <Place y={y}>
+      <div style={{ width: P, opacity: enter, transform: `translateY(${(1 - enter) * P * 0.04}px)`, fontFamily: font }}>
+        <div style={{ background: c.panel, border: `${Math.max(2, P * 0.0025)}px solid ${c.stroke}`, borderRadius: P * 0.055, padding: `${P * 0.05}px ${P * 0.05}px ${P * 0.04}px`, boxShadow: `0 ${P * 0.03}px ${P * 0.08}px ${c.shadow}, 0 0 ${P * 0.12}px ${rgba(hero, 0.18 + 0.2 * glow)}` }}>
+          <div style={{ minHeight: fs * 1.4 * 3, fontSize: fs, lineHeight: 1.4, color: c.ink, fontWeight: 500, position: "relative", overflowWrap: "anywhere" }}>
+            {n === 0 && placeholder ? <span style={{ color: c.dim, position: "absolute", left: 0, top: 0, opacity: sent ? 0 : 1 }}>{placeholder}</span> : null}
+            <span style={{ color: sent ? c.dim : c.ink }}>{chars.slice(0, n).join("")}</span>
+            <span style={{ display: "inline-block", width: 0, height: fs * 1.05, verticalAlign: "text-bottom", position: "relative" }}>
+              <span style={{ position: "absolute", left: P * 0.004, top: fs * 0.02, width: Math.max(3, P * 0.0075), height: fs * 1.08, background: hero, opacity: caretOn && !sent ? 1 : 0, borderRadius: 2 }} />
+            </span>
+            <span style={{ color: "transparent" }}>{chars.slice(n).join("")}</span>
+          </div>
+          <div style={{ display: "flex", alignItems: "center", gap: P * 0.025, marginTop: P * 0.035 }}>
+            <div style={{ display: "flex", gap: P * 0.02, flex: 1, flexWrap: "wrap" }}>
+              {chips.map((chip, i) => (
+                <div key={i} style={{ fontSize: P * 0.033, fontWeight: 600, color: c.dim, background: c.chip, borderRadius: 999, padding: `${P * 0.012}px ${P * 0.03}px`, whiteSpace: "nowrap" }}>{chip}</div>
+              ))}
+            </div>
+            <div style={{ width: P * 0.125, height: P * 0.125, borderRadius: 999, background: hero, display: "flex", alignItems: "center", justifyContent: "center", transform: `scale(${press})`, boxShadow: `0 0 ${P * 0.07 * glow}px ${rgba(hero, 0.9)}`, opacity: n > 0 ? 1 : 0.45, flex: "none" }}>
+              <svg width={P * 0.06} height={P * 0.06} viewBox="0 0 24 24" fill="none" stroke={c.heroInk} strokeWidth="3" strokeLinecap="round" strokeLinejoin="round"><path d="M12 19V5M5 12l7-7 7 7" /></svg>
+            </div>
+          </div>
+        </div>
+        {reply ? (
+          <div style={{ display: "flex", gap: P * 0.03, marginTop: P * 0.05, padding: `0 ${P * 0.02}px`, opacity: interpolate(frame, [ev.replyStart - 2, ev.replyStart + 4], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" }) }}>
+            {sparkle}
+            <div style={{ fontSize: fs * 0.95, lineHeight: 1.42, color: c.ink, fontWeight: 500, overflowWrap: "anywhere" }}>
+              <span>{rchars.slice(0, rn).join("")}</span>
+              <span style={{ color: "transparent" }}>{rchars.slice(rn).join("")}</span>
+            </div>
+          </div>
+        ) : null}
+      </div>
+    </Place>
+  );
+};

package/src/remotion/kit/Scene3D.tsx

@@ -0,0 +1,70 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+import { ThreeCanvas } from "@remotion/three";
+import { useThree } from "@react-three/fiber";
+import { ManifestContext, UrlsContext } from "./media";
+import { camera3DAt, type Camera3DKey } from "./three-math";
+import { CameraKeysContext } from "./scene3d-context";
+import { moodLights, type Mood } from "./three-fx-math";
+import "./quiet-three";
+
+// Moves the three.js camera along the keys, at every frame, with the same timing rule as the 2D Camera. It writes the camera in a layout effect, which
+// runs before the canvas draws the frame, and it keeps no state of its own, so any frame can be drawn on its own.
+const Rig: React.FC<{ keys?: Camera3DKey[]; lead?: number; stiffness?: number; damping?: number }> = ({ keys, lead, stiffness, damping }) => {
+  const camera = useThree((s) => s.camera) as import("three").PerspectiveCamera;
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  React.useLayoutEffect(() => {
+    const v = camera3DAt(keys, frame, fps, { lead, stiffness, damping });
+    camera.position.set(...v.position);
+    camera.fov = v.fov;
+    camera.lookAt(...v.lookAt);
+    camera.updateProjectionMatrix();
+    camera.updateMatrixWorld();
+  }, [camera, keys, frame, fps, lead, stiffness, damping]);
+  return null;
+};
+
+// A three.js scene at the size of the composition, for real depth: extruded type, cards in space, a ring of objects. The canvas is transparent unless
+// `background` is set, so it lays over a 2D ground, and a soft three-point light is placed for you. Place it inside a SceneFrame, with captions and
+// small labels in 2D on top of it. It draws nothing, and makes no GL context, until a Scene3D is on screen. `camera.keys` move the camera: x, y, z are its
+// place, lookAt the point it faces (default the origin) and fov its field of view in degrees (default 50); a key that leaves a value out keeps the one before.
+// The default camera sits at z 6 looking at the origin. What the camera sees: at fov 50 the visible height is about 0.93 times the distance to the object
+// and the width that times the frame's aspect, so 0.52 times the distance on a 9:16 phone frame (about 3.1 units across at z 6, 4.9 at z 9.5) and 1.66
+// times the distance on 16:9. `mood` ("studio", "night", "sunset" or "neon") chooses the light colours and intensities and the fog tint together, so lights are never hand-tuned; without it the
+// default three-point light is used, as before. Text3D and Orbit3D read the camera keys, and size themselves to fit the frame at the key where it comes closest.
+export const Scene3D: React.FC<{
+  camera?: { keys: Camera3DKey[]; lead?: number; stiffness?: number; damping?: number };
+  background?: string;
+  lights?: boolean;
+  mood?: Mood;
+  children?: React.ReactNode;
+}> = ({ camera, background, lights = true, mood, children }) => {
+  const { width, height } = useVideoConfig();
+  // The canvas is a separate React tree, so the kit's own contexts are carried across by hand: without them a Card3D could not find its picture.
+  const urls = React.useContext(UrlsContext), manifest = React.useContext(ManifestContext);
+  return (
+    <ThreeCanvas width={width} height={height} style={{ position: "absolute", left: 0, top: 0 }} camera={{ fov: 50, position: [0, 0, 6], near: 0.1, far: 200 }}>
+      {background ? <color attach="background" args={[background]} /> : null}
+      <Rig keys={camera?.keys} lead={camera?.lead} stiffness={camera?.stiffness} damping={camera?.damping} />
+      {lights && mood ? (
+        <>
+          <ambientLight color={moodLights(mood).ambient.color} intensity={moodLights(mood).ambient.intensity} />
+          <directionalLight color={moodLights(mood).key.color} intensity={moodLights(mood).key.intensity} position={moodLights(mood).key.position} />
+          <directionalLight color={moodLights(mood).fill.color} intensity={moodLights(mood).fill.intensity} position={moodLights(mood).fill.position} />
+          <directionalLight color={moodLights(mood).rim.color} intensity={moodLights(mood).rim.intensity} position={moodLights(mood).rim.position} />
+        </>
+      ) : null}
+      {mood ? <fog attach="fog" args={[moodLights(mood).fog.color, moodLights(mood).fog.near, moodLights(mood).fog.far]} /> : null}
+      {lights && !mood ? (
+        <>
+          <ambientLight intensity={1.4} />
+          <directionalLight position={[4, 6, 8]} intensity={2.6} />
+          <directionalLight position={[-6, 2, 4]} intensity={1.1} />
+          <directionalLight position={[0, 3, -8]} intensity={1.4} />
+        </>
+      ) : null}
+      <UrlsContext.Provider value={urls}><ManifestContext.Provider value={manifest}><CameraKeysContext.Provider value={camera?.keys}>{children}</CameraKeysContext.Provider></ManifestContext.Provider></UrlsContext.Provider>
+    </ThreeCanvas>
+  );
+};

package/src/remotion/kit/SceneFrame.tsx

@@ -1,19 +1,96 @@
 import React from "react";
-import { AbsoluteFill, interpolate, Sequence, useCurrentFrame } from "remotion";
+import { AbsoluteFill, Sequence, useCurrentFrame, useVideoConfig } from "remotion";
+import { transitionAt, transitionCss, type TransitionKind } from "./transition-math";
 
-const Fade: React.FC<{ durationInFrames: number; children: React.ReactNode }> = ({ durationInFrames, children }) => {
+export type SceneTransition = {
+  // How the scene arrives and leaves: "fade" (the default), "cut", "zoom-in", "zoom-out", "zoom-through", "push-left", "push-right", "push-up",
+  // "push-down", "whip-left", "whip-right", "blur", "turn", "color-push" (a field of `color` covers the frame as a circle, a bar or a diagonal and uncovers the
+  // next scene), "rgb-whip" (a whip with the red and blue channels pulled apart), "flash" (2 to 3 frames of white or `color`), "ring" (the scene closes into a
+  // ring that sweeps in from `origin`, the next opens out of one) or "flip" (a one-frame inverted flash on a hard cut, for the beat). A scene's exit and the next
+  // scene's enter are meant to be the same kind.
+  enter?: TransitionKind;
+  exit?: TransitionKind;
+  // How many frames the transition takes: 8 unless set (color-push 10, rgb-whip 6, ring 12, flash 3, flip 1), at most 20, never more than half the scene.
+  transitionFrames?: number;
+  // The colour of a color-push's field, a flash and a ring (default "#7C3AED" for a field and a ring, "#ffffff" for a flash), and the shape of a color-push's field: "circle" (grows from `origin`), "bar" or "diagonal".
+  color?: string;
+  shape?: "circle" | "bar" | "diagonal";
+  // Where a zoom aims, as fractions of the frame (default the centre).
+  origin?: { x: number; y: number };
+};
+
+// The overlay and the clip a state with an `fx` needs. The exit makes the scene covered or closed, and the enter uncovers or opens it, from the same side, so the frame is
+// whole on the boundary and the two edges of a cut read as one move.
+const fxView = (s: NonNullable<ReturnType<typeof transitionAt>["fx"]>, w: number, h: number, origin: { x: number; y: number }, color: string | undefined, shape: "circle" | "bar" | "diagonal") => {
+  const a = s.amount, diag = Math.hypot(w, h);
+  const ox = origin.x * w, oy = origin.y * h;
+  let clip: string | undefined, overlay: React.CSSProperties | undefined, filter: string | undefined;
+  if (s.kind === "flash") overlay = { background: color ?? "#ffffff", opacity: a };
+  else if (s.kind === "flip") filter = "invert(1) hue-rotate(180deg)";
+  else if (s.kind === "color-push") {
+    const c = color ?? "#7C3AED";
+    if (shape === "circle") overlay = { background: c, clipPath: `circle(${a * Math.hypot(Math.max(ox, w - ox), Math.max(oy, h - oy))}px at ${ox}px ${oy}px)` };
+    else if (shape === "bar") overlay = { background: c, left: s.phase === "exit" ? 0 : "auto", right: s.phase === "enter" ? 0 : "auto", width: `${a * 100}%` };
+    else {
+      // A slanted edge that sweeps across: the field is the part of the frame on one side of a line leaning 20 percent of the width.
+      const lean = 0.2, x = a * (1 + lean) * 100;
+      overlay = { background: c, clipPath: s.phase === "exit" ? `polygon(0 0, ${x}% 0, ${x - lean * 100}% 100%, 0 100%)` : `polygon(${100 - x}% 0, 100% 0, 100% 100%, ${100 - x - lean * 100}% 100%)` };
+    }
+  } else if (s.kind === "ring") {
+    // The scene is only inside a circle that grows from the origin (or shrinks to it); the ring is drawn on the circle's edge.
+    const r = (1 - a) * Math.hypot(Math.max(ox, w - ox), Math.max(oy, h - oy));
+    clip = `circle(${r}px at ${ox}px ${oy}px)`;
+    const t = Math.max(6, w * 0.014);
+    overlay = { left: ox - r, top: oy - r, width: r * 2, height: r * 2, right: "auto", bottom: "auto", borderRadius: "50%", border: `${t}px solid ${color ?? "#7C3AED"}`, boxShadow: `0 0 ${t * 3}px ${color ?? "#7C3AED"}`, opacity: Math.min(1, Math.max(0, (r - t) / (t * 3))), boxSizing: "border-box" };
+  }
+  return { clip, overlay, filter };
+};
+
+const Moving: React.FC<SceneTransition & { durationInFrames: number; children: React.ReactNode }> = ({ durationInFrames, enter, exit, transitionFrames, origin, color, shape = "circle", children }) => {
   const frame = useCurrentFrame();
-  const edge = Math.min(8, Math.floor(durationInFrames / 2));
-  const opacity = interpolate(frame, [0, edge, durationInFrames - edge, durationInFrames], [0, 1, 1, 0], {
-    extrapolateLeft: "clamp", extrapolateRight: "clamp",
-  });
-  return <AbsoluteFill style={{ opacity }}>{children}</AbsoluteFill>;
+  const { width, height } = useVideoConfig();
+  const state = transitionAt(frame, durationInFrames, { enter, exit, transitionFrames });
+  const css = transitionCss(state, width, height, origin);
+  const { x, y } = css.blurPx;
+  const split = state.fx?.kind === "rgb-whip";
+  const directional = x !== y && (x > 0 || y > 0);
+  const id = `rk-blur-${React.useId().replace(/[^a-zA-Z0-9]/g, "")}`;
+  const view = state.fx && !split ? fxView(state.fx, width, height, origin ?? { x: 0.5, y: 0.5 }, color, shape) : undefined;
+  const filter = split || directional ? `url(#${id})` : view?.filter ?? (x > 0 ? `blur(${x}px)` : undefined);
+  const k = split ? state.fx!.amount * width * 0.03 : 0;
+  return (
+    <>
+      <AbsoluteFill style={{ opacity: css.opacity, transform: css.transform === "none" ? undefined : css.transform, transformOrigin: css.transformOrigin, filter, clipPath: view?.clip }}>
+        {split ? (
+          // Red pulled one way, blue the other, green kept, then smeared along the move: the channels are separated with a colour matrix each and put back with a screen blend.
+          <svg width="0" height="0" style={{ position: "absolute" }} aria-hidden>
+            <filter id={id} x="-20%" y="-20%" width="140%" height="140%" colorInterpolationFilters="sRGB">
+              <feColorMatrix in="SourceGraphic" type="matrix" values="1 0 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0 1 0" result="r" />
+              <feOffset in="r" dx={-k} result="r2" />
+              <feColorMatrix in="SourceGraphic" type="matrix" values="0 0 0 0 0  0 1 0 0 0  0 0 0 0 0  0 0 0 1 0" result="g" />
+              <feColorMatrix in="SourceGraphic" type="matrix" values="0 0 0 0 0  0 0 0 0 0  0 0 1 0 0  0 0 0 1 0" result="b" />
+              <feOffset in="b" dx={k} result="b2" />
+              <feBlend in="r2" in2="g" mode="screen" result="rg" />
+              <feBlend in="rg" in2="b2" mode="screen" result="all" />
+              <feGaussianBlur in="all" stdDeviation={`${x} 0`} />
+            </filter>
+          </svg>
+        ) : directional ? (
+          <svg width="0" height="0" style={{ position: "absolute" }} aria-hidden>
+            <filter id={id} x="-20%" y="-20%" width="140%" height="140%"><feGaussianBlur stdDeviation={`${x} ${y}`} /></filter>
+          </svg>
+        ) : null}
+        {children}
+      </AbsoluteFill>
+      {view?.overlay ? <AbsoluteFill style={{ pointerEvents: "none", ...view.overlay }} /> : null}
+    </>
+  );
 };
 
-export const SceneFrame: React.FC<{ from: number; durationInFrames: number; children: React.ReactNode }> = ({
-  from, durationInFrames, children,
-}) => (
+// One scene on the timeline. By default it fades in and out over up to 8 frames. `enter` and `exit` choose other transitions, all complete
+// exactly at the scene's edges so that the cuts stay on the beat.
+export const SceneFrame: React.FC<{ from: number; durationInFrames: number; children: React.ReactNode } & SceneTransition> = ({ from, durationInFrames, children, ...transition }) => (
   <Sequence from={from} durationInFrames={durationInFrames}>
-    <Fade durationInFrames={durationInFrames}>{children}</Fade>
+    <Moving durationInFrames={durationInFrames} {...transition}>{children}</Moving>
   </Sequence>
 );

package/src/remotion/kit/SoundCues.tsx

@@ -0,0 +1,22 @@
+import React, { useContext } from "react";
+import { Audio, Sequence } from "remotion";
+import { gainFor, ManifestContext, UrlsContext } from "./media";
+import { resolveCues, type SoundCue } from "./sound-cues";
+
+// Plays many sound effects from one place: a list of cues, each a frame of the whole video and a name from `sounds`. Place it once, outside
+// the scenes, when a video is scored with sound (a video with no voice has dozens of cues). Like Sfx it applies the manifest's levelling gain,
+// so the same volume is equally loud for every file. A cue without a volume plays at 0.35.
+export const SoundCues: React.FC<{ cues: SoundCue[]; sounds: Record<string, string>; volume?: number }> = ({ cues, sounds, volume = 1 }) => {
+  const urls = useContext(UrlsContext);
+  const gains = useContext(ManifestContext)?.soundGain;
+  const plan = React.useMemo(() => resolveCues({ cues, sounds, volume, urls, gainFor: (src) => gainFor(gains, urls, src) }), [cues, sounds, volume, urls, gains]);
+  return (
+    <>
+      {plan.map((c, i) => (
+        <Sequence key={`${c.from}-${i}`} from={c.from} layout="none">
+          <Audio src={c.src} volume={c.volume} />
+        </Sequence>
+      ))}
+    </>
+  );
+};

package/src/remotion/kit/TerminalLog.tsx

@@ -0,0 +1,98 @@
+import React from "react";
+import { interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { Place } from "./Place";
+import { font as loadFont, fonts, springs } from "./theme";
+import { DEFAULT_HERO, rgba, uiColors, type UiTheme } from "./ui-theme";
+import { clock, terminalFrames, type TerminalLine } from "./ui-math";
+
+// A terminal or agent window: a title bar, lines that stream in (`cmd` a typed command, `out` plain output, `ok` a success, `warn` a warning, `edit` a file
+// changed with `add` and `del` counts), an optional checklist whose items get struck through, and a status line with an elapsed counter that turns to
+// "Done" at the end. `rate` is lines a second (default 3); the window shows the last `maxLines` (default 8) and the newest is at the bottom. Times are frames
+// from the component's own mount; terminalFrames(props, fps) gives each line's frame and each tick's for sound. Text is monospace (jetbrainsMono) unless
+// `font` is given. `width` is a fraction of the frame (0.86); `theme` "dark" (default), "light" or "glass".
+export const TerminalLog: React.FC<{
+  lines: TerminalLine[];
+  rate?: number;
+  title?: string;
+  status?: string;
+  checklist?: string[];
+  checkEvery?: number;
+  maxLines?: number;
+  speed?: number;
+  hero?: string;
+  theme?: UiTheme;
+  font?: string;
+  width?: number;
+  delay?: number;
+  y?: number;
+}> = ({ lines, rate = 3, title = "agent", status = "Working", checklist = [], checkEvery, maxLines = 8, speed = 8, hero = DEFAULT_HERO, theme = "dark", font, width: fraction = 0.86, delay = 6, y = 0.5 }) => {
+  const frame = useCurrentFrame();
+  const { fps, width: W } = useVideoConfig();
+  const c = uiColors(theme, hero);
+  const P = W * fraction;
+  const mono = font ?? loadFont("jetbrainsMono");
+  const ev = terminalFrames({ lines, rate, delay, checklist, checkEvery }, fps);
+  const shown = lines.map((_, i) => i).filter((i) => ev.lines[i]! <= frame);
+  const visible = shown.slice(-maxLines);
+  const fs = P * 0.034, row = fs * 1.62;
+  const enter = spring({ frame, fps, config: springs.smooth });
+  const done = frame >= ev.done;
+  const seconds = Math.max(0, ((done ? ev.done : frame) - delay) / fps * speed);
+  const spin = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"][Math.floor(frame / 2) % 10];
+  const colorOf = (k: TerminalLine["kind"]) => (k === "cmd" ? c.ink : k === "ok" ? c.ok : k === "warn" ? c.warn : k === "edit" ? c.ink : c.dim);
+  return (
+    <Place y={y}>
+      <div style={{ width: P, opacity: enter, transform: `translateY(${(1 - enter) * P * 0.04}px)`, fontFamily: mono }}>
+        <div style={{ background: c.panel, border: `${Math.max(2, P * 0.0025)}px solid ${c.stroke}`, borderRadius: P * 0.04, overflow: "hidden", boxShadow: `0 ${P * 0.03}px ${P * 0.08}px ${c.shadow}` }}>
+          <div style={{ display: "flex", alignItems: "center", gap: P * 0.018, padding: `${P * 0.032}px ${P * 0.04}px`, background: c.field, borderBottom: `1px solid ${c.stroke}` }}>
+            {["#ff5f57", "#febc2e", "#28c840"].map((d) => <div key={d} style={{ width: P * 0.03, height: P * 0.03, borderRadius: 999, background: d }} />)}
+            <div style={{ flex: 1, textAlign: "center", fontSize: fs * 0.9, color: c.dim, fontFamily: font ?? fonts.body, fontWeight: 600, marginRight: P * 0.1 }}>{title}</div>
+          </div>
+          <div style={{ padding: `${P * 0.04}px ${P * 0.045}px`, height: row * maxLines + P * 0.08, display: "flex", flexDirection: "column", justifyContent: "flex-end" }}>
+            {visible.map((i) => {
+              const l = lines[i]!, age = frame - ev.lines[i]!;
+              const o = interpolate(age, [0, 5], [0, 1], { extrapolateRight: "clamp" });
+              const mark = l.kind === "cmd" ? "$" : l.kind === "ok" ? "✓" : l.kind === "warn" ? "!" : l.kind === "edit" ? "✎" : " ";
+              return (
+                <div key={i} style={{ display: "flex", gap: fs * 0.7, height: row, alignItems: "center", fontSize: fs, color: colorOf(l.kind), opacity: o, transform: `translateY(${(1 - o) * fs * 0.4}px)`, whiteSpace: "nowrap" }}>
+                  <span style={{ width: fs * 0.9, color: l.kind === "cmd" ? hero : colorOf(l.kind), fontWeight: 700, flex: "none" }}>{mark}</span>
+                  <span style={{ overflow: "hidden", textOverflow: "ellipsis", flex: 1, fontWeight: l.kind === "cmd" ? 700 : 400 }}>{l.text}</span>
+                  {l.kind === "edit" ? (
+                    <span style={{ flex: "none", fontWeight: 700 }}>
+                      {l.add !== undefined ? <span style={{ color: c.ok }}>+{l.add} </span> : null}
+                      {l.del !== undefined ? <span style={{ color: c.bad }}>-{l.del}</span> : null}
+                    </span>
+                  ) : null}
+                </div>
+              );
+            })}
+          </div>
+          {checklist.length ? (
+            <div style={{ padding: `${P * 0.03}px ${P * 0.045}px`, borderTop: `1px solid ${c.stroke}`, display: "flex", flexDirection: "column", gap: P * 0.012 }}>
+              {checklist.map((item, i) => {
+                const at = ev.checks[i]!, k = interpolate(frame, [at, at + 6], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
+                return (
+                  <div key={i} style={{ display: "flex", alignItems: "center", gap: fs * 0.7, fontSize: fs, color: k > 0.5 ? c.dim : c.ink }}>
+                    <div style={{ width: fs, height: fs, borderRadius: fs * 0.25, border: `2px solid ${k > 0 ? hero : c.dim}`, background: k > 0.5 ? hero : "transparent", display: "flex", alignItems: "center", justifyContent: "center", flex: "none" }}>
+                      {k > 0.5 ? <svg width={fs * 0.7} height={fs * 0.7} viewBox="0 0 24 24" fill="none" stroke={c.heroInk} strokeWidth="4" strokeLinecap="round" strokeLinejoin="round"><path d="M4 12l5 5L20 6" /></svg> : null}
+                    </div>
+                    <span style={{ position: "relative", whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>
+                      {item}
+                      <span style={{ position: "absolute", left: 0, top: "52%", height: Math.max(2, fs * 0.08), width: `${k * 100}%`, background: c.dim }} />
+                    </span>
+                  </div>
+                );
+              })}
+            </div>
+          ) : null}
+          <div style={{ display: "flex", alignItems: "center", gap: fs * 0.6, padding: `${P * 0.03}px ${P * 0.045}px`, background: c.field, borderTop: `1px solid ${c.stroke}`, fontSize: fs * 0.92, color: done ? c.ok : hero, fontWeight: 700 }}>
+            <span style={{ width: fs, textAlign: "center" }}>{done ? "✓" : spin}</span>
+            <span>{done ? "Done" : `${status}...`}</span>
+            <span style={{ marginLeft: "auto", color: c.dim, fontWeight: 400 }}>{clock(seconds)}</span>
+          </div>
+        </div>
+      </div>
+      <div style={{ position: "absolute", inset: 0, pointerEvents: "none", boxShadow: `inset 0 0 0 0 ${rgba(hero, 0)}` }} />
+    </Place>
+  );
+};