reelkit-cli 0.6.0 → 0.10.0

package/src/hyperframes/kit/HudOverlay.tsx

@@ -0,0 +1,52 @@
+import React from "react";
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "../frame";
+import { font as loadFont } from "./theme";
+import { rgba } from "./ui-theme";
+import { timecode } from "./ui-math";
+
+// A thin layer of instrument decoration that sits over a scene: corner brackets, two to four small monospace labels in the corners (your own words: a
+// version, a place, a status; they fill top left, top right, bottom left, bottom right in that order), a running timecode from the frame (it takes the next
+// free corner; `timecode={false}` for none) and faint scan lines with a slow band. Labels are never smaller than 0.022 of the frame's width (24 px at 1080
+// wide). `ink` is the colour of everything (default white), `hero` the small recording dot. Cheap: no images, no filters.
+export const HudOverlay: React.FC<{
+  labels?: string[];
+  timecode?: boolean;
+  scanlines?: boolean;
+  hero?: string;
+  ink?: string;
+  font?: string;
+  inset?: number;
+}> = ({ labels = [], timecode: showCode = true, scanlines = true, hero = "#ff4d4d", ink = "#ffffff", font, inset = 0.05 }) => {
+  const frame = useCurrentFrame();
+  const { fps, width: W, height: H } = useVideoConfig();
+  const mono = font ?? loadFont("jetbrainsMono");
+  const m = W * inset, arm = W * 0.07, t = Math.max(3, W * 0.0035);
+  const items = labels.slice(0, 4);
+  if (showCode && items.length < 4) items.push(timecode(frame, fps));
+  const fs = Math.max(W * 0.024, 24);
+  const corner = (i: number): React.CSSProperties => [
+    { left: m, top: m }, { right: m, top: m, textAlign: "right" as const }, { left: m, bottom: m }, { right: m, bottom: m, textAlign: "right" as const },
+  ][i]!;
+  const bracket = (i: number): React.CSSProperties => {
+    const left = i % 2 === 0, top = i < 2;
+    return { position: "absolute", [left ? "left" : "right"]: m * 0.45, [top ? "top" : "bottom"]: m * 0.45, width: arm, height: arm, [left ? "borderLeft" : "borderRight"]: `${t}px solid ${rgba(ink, 0.85)}`, [top ? "borderTop" : "borderBottom"]: `${t}px solid ${rgba(ink, 0.85)}` };
+  };
+  const band = ((frame * 5) % (H * 1.4)) - H * 0.2;
+  return (
+    <AbsoluteFill style={{ pointerEvents: "none", fontFamily: mono, color: ink }}>
+      {scanlines ? (
+        <>
+          <AbsoluteFill style={{ backgroundImage: `repeating-linear-gradient(0deg, ${rgba(ink, 0.045)} 0px, ${rgba(ink, 0.045)} 2px, transparent 2px, transparent 5px)` }} />
+          <div style={{ position: "absolute", left: 0, right: 0, top: band, height: H * 0.12, background: `linear-gradient(180deg, transparent, ${rgba(ink, 0.05)}, transparent)` }} />
+        </>
+      ) : null}
+      {[0, 1, 2, 3].map((i) => <div key={i} style={bracket(i)} />)}
+      {items.map((label, i) => (
+        <div key={i} style={{ position: "absolute", ...corner(i), margin: i < 2 ? `${W * 0.012}px ${W * 0.03}px` : `${W * 0.012}px ${W * 0.03}px`, fontSize: fs, fontWeight: 700, letterSpacing: "0.08em", textTransform: "uppercase", opacity: 0.88, display: "flex", alignItems: "center", gap: fs * 0.5, flexDirection: i % 2 ? "row-reverse" : "row" }}>
+          {i === 0 ? <span style={{ width: fs * 0.55, height: fs * 0.55, borderRadius: 999, background: hero, opacity: Math.floor(frame / 15) % 2 ? 0.25 : 1 }} /> : null}
+          <span style={{ fontVariantNumeric: "tabular-nums" }}>{label}</span>
+        </div>
+      ))}
+    </AbsoluteFill>
+  );
+};

package/src/hyperframes/kit/ImageLayers.tsx

@@ -0,0 +1,48 @@
+import React from "react";
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "../frame";
+import { useMedia } from "./media";
+import { layerMoves, type ImageLayersRecord } from "./image-layers-math";
+
+// What ImageLayers shares with the TextOnImage inside it: the picture's layers, and the element the words go into when they must sit in front of the subject.
+export const ImageLayersContext = React.createContext<{ layers?: ImageLayersRecord; frontRoot: HTMLElement | null } | undefined>(undefined);
+// The ink a TextOnImage chose for its zone, which a Headline inside it takes unless it is given one.
+export const TextInkContext = React.createContext<string | undefined>(undefined);
+
+const fill = (scale: number, tx: number, ty: number, w: number, h: number): React.CSSProperties => ({ transform: `translate(${tx * w}px, ${ty * h}px) scale(${scale})` });
+
+// A picture in layers, with the words as a layer OF the picture. It draws the back picture, then `children` (the middle layer: your words), then the subject cut out
+// of the same picture, then `front`, so a headline can pass BEHIND the subject. Pass `layers` (the manifest scene's imageLayers, from `reelkit assets layers`) or
+// `back` and `subject` yourself; without a subject it is one flat picture with the words over it, and nothing fails. Depth comes from the frame: the back drifts and
+// grows slowly, the subject moves more and the other way (`depth`, 0 to 1, default 0.4; 0 moves them together), and the words between them at their own rate.
+// `focus` softly blurs the other layer ("subject" blurs the back, "back" blurs the subject). Every layer covers the frame at every frame, so no edge is shown.
+// Put a TextOnImage in it for words that sit where the picture is calm.
+export const ImageLayers: React.FC<{
+  layers?: ImageLayersRecord;
+  back?: string;
+  subject?: string;
+  depth?: number;
+  focus?: "subject" | "back";
+  front?: React.ReactNode;
+  children?: React.ReactNode;
+}> = ({ layers, back, subject, depth = 0.4, focus, front, children }) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+  const backSrc = useMedia(back ?? layers?.back ?? ""), subjectSrc = useMedia(subject ?? layers?.subject ?? "");
+  const hasSubject = Boolean(subject ?? layers?.subject);
+  const m = layerMoves(frame, fps, depth);
+  const blur = Math.round(width * 0.006 * 10) / 10;
+  const [frontRoot, setFrontRoot] = React.useState<HTMLElement | null>(null);
+  const img: React.CSSProperties = { width: "100%", height: "100%", objectFit: "cover", display: "block" };
+  const ctx = React.useMemo(() => ({ layers: layers ?? (back ? { back, subject, textZone: { region: "bottom" as const, luminance: 0.3, busy: 0.5 } } : undefined), frontRoot }), [layers, back, subject, frontRoot]);
+  return (
+    <ImageLayersContext.Provider value={ctx}>
+      <AbsoluteFill style={{ overflow: "hidden" }}>
+        {backSrc ? <AbsoluteFill style={{ ...fill(m.back.scale, m.back.tx, m.back.ty, width, height), filter: focus === "subject" ? `blur(${blur}px)` : undefined }}><img src={backSrc} style={img} /></AbsoluteFill> : null}
+        <AbsoluteFill style={{ ...fill(m.text.scale, m.text.tx, m.text.ty, width, height) }}>{children}</AbsoluteFill>
+        {hasSubject && subjectSrc ? <AbsoluteFill style={{ ...fill(m.subject.scale, m.subject.tx, m.subject.ty, width, height), filter: focus === "back" ? `blur(${blur}px)` : undefined }}><img src={subjectSrc} style={img} /></AbsoluteFill> : null}
+        <AbsoluteFill ref={setFrontRoot as never} />
+        {front ? <AbsoluteFill>{front}</AbsoluteFill> : null}
+      </AbsoluteFill>
+    </ImageLayersContext.Provider>
+  );
+};

package/src/{remotion → hyperframes}/kit/KenBurnsImage.tsx

@@ -1,7 +1,7 @@
 import React from "react";
 import { useMedia } from "./media";
 import { ease } from "./theme";
-import { AbsoluteFill, Img, interpolate, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, Img, interpolate, useCurrentFrame, useVideoConfig } from "../frame";
 
 // direction "out" starts zoomed and pulls back; alternate between consecutive image scenes.
 export const KenBurnsImage: React.FC<{ src: string; zoom?: number; direction?: "in" | "out" }> = ({ src, zoom = 1.1, direction = "in" }) => {

package/src/{remotion → hyperframes}/kit/KeyedClip.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { useMedia } from "./media";
-import { AbsoluteFill, OffthreadVideo } from "remotion";
+import { AbsoluteFill, OffthreadVideo } from "../frame";
 
 // A green-screen clip with its green keyed out (the transparent .webm that `--green` makes), laid over whatever is beneath it.
 // x and y are where the clip's bottom-centre sits, as fractions of the frame (x 0 is the left edge, y 1 the bottom edge); scale is the clip's

package/src/{remotion → hyperframes}/kit/Layers.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "../frame";
 
 // The bottom layer of every scene: the base colour with two slow-drifting soft colour fields. Never a flat fill.
 export const BgMesh: React.FC<{ bg: string; hero: string; accent?: string }> = ({ bg, hero, accent = hero }) => {

package/src/{remotion → hyperframes}/kit/LowerThird.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { fonts } from "./theme";
-import { AbsoluteFill, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, spring, useCurrentFrame, useVideoConfig } from "../frame";
 
 export const LowerThird: React.FC<{ title: string; subtitle?: string; accent?: string }> = ({ title, subtitle, accent = "#5b8cff" }) => {
   const frame = useCurrentFrame();

package/src/hyperframes/kit/Music.tsx

@@ -0,0 +1,19 @@
+import React from "react";
+import { Audio, useVideoConfig } from "../frame";
+import { DEFAULT_DUCK_TO, DEFAULT_MUSIC_VOLUME, musicVolume, speechSpans, type MusicDip, type SpeechScene } from "./music-math";
+import { useGain, useManifest, useMedia } from "./media";
+
+// The video's music track. Place it once, outside the scenes. It sits at `duckTo` while the voiceover is heard and comes up to `volume`
+// in real pauses (a gap of 1.2 s or more: it rises over 0.4 s and is back down 0.25 s before the next word), drops to a dip's volume inside each of `dips` (absolute frames: a rest before the big moment), loops when the video is longer than the track, and fades out over the last second. `scenes` defaults to the manifest's.
+export const Music: React.FC<{ src: string; volume?: number; duckTo?: number; scenes?: SpeechScene[]; dips?: MusicDip[] }> = ({ src, volume = DEFAULT_MUSIC_VOLUME, duckTo = DEFAULT_DUCK_TO, scenes, dips }) => {
+  const { fps, durationInFrames } = useVideoConfig();
+  const manifest = useManifest();
+  const gain = useGain(src);
+  const spans = React.useMemo(() => speechSpans(scenes ?? manifest?.scenes ?? [], fps), [scenes, manifest, fps]);
+  return (
+    <Audio
+      src={useMedia(src)} loop loopVolumeCurveBehavior="extend"
+      volume={(f) => musicVolume(f, { fps, totalFrames: durationInFrames, volume, duckTo, spans, gain, dips })}
+    />
+  );
+};

package/src/hyperframes/kit/NamedCursor.tsx

@@ -0,0 +1,54 @@
+import React from "react";
+import { AbsoluteFill, interpolate, useCurrentFrame, useVideoConfig } from "../frame";
+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/hyperframes/kit/Orbit3D.tsx

@@ -0,0 +1,49 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "../frame";
+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/hyperframes/kit/Particles3D.tsx

@@ -0,0 +1,74 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "../frame";
+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/hyperframes/kit/Place.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+import { AbsoluteFill, useVideoConfig } from "../frame";
+
+// 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/hyperframes/kit/PromptBox.tsx

@@ -0,0 +1,84 @@
+import React from "react";
+import { interpolate, spring, useCurrentFrame, useVideoConfig } from "../frame";
+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/hyperframes/kit/Scene3D.tsx

@@ -0,0 +1,70 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "../frame";
+import { ThreeCanvas } from "../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/hyperframes/kit/SceneFrame.tsx

@@ -0,0 +1,96 @@
+import React from "react";
+import { AbsoluteFill, Sequence, useCurrentFrame, useVideoConfig } from "../frame";
+import { transitionAt, transitionCss, type TransitionKind } from "./transition-math";
+
+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 { 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}
+    </>
+  );
+};
+
+// 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}>
+    <Moving durationInFrames={durationInFrames} {...transition}>{children}</Moving>
+  </Sequence>
+);

package/src/{remotion → hyperframes}/kit/ScreenOverlay.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { useMedia } from "./media";
-import { AbsoluteFill, Loop, OffthreadVideo, useVideoConfig } from "remotion";
+import { AbsoluteFill, Loop, OffthreadVideo, useVideoConfig } from "../frame";
 
 // Lays a white-on-black overlay clip (film marks, HUD frames) over the video. The "screen" blend drops the black.
 // Pass durationSec from the overlay's record to loop it for the whole video; without it the clip plays once.

package/src/{remotion → hyperframes}/kit/Sfx.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { useGain, useMedia } from "./media";
-import { Audio, Sequence } from "remotion";
+import { Audio, Sequence } from "../frame";
 
 // Plays one sound effect starting at a frame. at is counted from the start of the enclosing scene, or of the video
 // when placed outside the scenes. Keep volume well under the voiceover.