reelkit-cli 0.6.0 → 0.10.0

package/src/hyperframes/kit/Assemble3D.tsx

@@ -0,0 +1,92 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "../frame";
+import { Color, Object3D, type InstancedMesh } from "three";
+import { CameraKeysContext } from "./scene3d-context";
+import { hash01 } from "./seeded";
+import { textSlots } from "./sample-text";
+import { assembleRanks, centred, MAX_PIECES, pieceAt, shapeSlots, type AssembleOrder, type AssembleShape } from "./three-fx-math";
+import { nearestVisible, type Vec3 } from "./three-math";
+
+// Instanced blocks that fly from a seeded scattered cloud into an arrangement, one after another, each on an arc with a turn that unwinds, then rest: the build-up
+// beat, up to 4000 pieces in one draw. `shape` is "grid" (a slab), "ring" (a band), "sphere", "wall" (bricks) or "text" (the blocks fall inside the letters of `text`, a
+// short Latin word in the kit's typeface), or give `targets` (any [x, y, z] list; it is centred and fitted). `count` (400 unless set, at most 4000) is how many pieces;
+// `order` is who goes first: "y" bottom to top (default), "x", "radial" from the middle out or "random"; `from` is the frame it starts (default 0) and `frames` how long
+// the whole build takes (default 60: every piece is home at from + frames); `colors` are two or three colours, jittered a little per piece; `fit` is how much of the
+// frame's width the arrangement fills at the closest the Scene3D camera comes (0.8), or give `size` in scene units. `spread` is how far the cloud reaches, in arrangements
+// (1.6). Everything is seeded (`seed`), so a frame is the same every time. assembleProgress, assembledCount and assembleEnd (exported) give a piece counter and the frame of the lock sound.
+export const Assemble3D: React.FC<{
+  shape?: AssembleShape;
+  text?: string;
+  targets?: Vec3[];
+  count?: number;
+  order?: AssembleOrder;
+  from?: number;
+  frames?: number;
+  colors?: string[];
+  fit?: number;
+  size?: number;
+  spread?: number;
+  seed?: number;
+  position?: Vec3;
+}> = ({ shape = "grid", text = "Relay", targets, count = 400, order = "y", from = 0, frames = 60, colors = ["#7C3AED", "#22D3EE"], fit = 0.8, size, spread = 1.6, seed = 0, position = [0, 0, 0] }) => {
+  const frame = useCurrentFrame();
+  const { width, height } = useVideoConfig();
+  const keys = React.useContext(CameraKeysContext);
+  const n0 = Math.max(1, Math.min(MAX_PIECES, Math.round(count)));
+  const slots = React.useMemo(() => (targets?.length ? centred(targets.slice(0, MAX_PIECES)) : shape === "text" ? textSlots(text, n0) : shapeSlots(shape, n0)), [shape, text, targets, n0]);
+  const n = slots.length;
+  const ranks = React.useMemo(() => assembleRanks(slots, order, seed), [slots, order, seed]);
+  // The arrangement's extent, so that it fits the frame, and the size of a piece from how close its neighbours are.
+  const geo = React.useMemo(() => {
+    let x0 = Infinity, x1 = -Infinity, y0 = Infinity, y1 = -Infinity;
+    for (const p of slots) { x0 = Math.min(x0, p[0]); x1 = Math.max(x1, p[0]); y0 = Math.min(y0, p[1]); y1 = Math.max(y1, p[1]); }
+    const probe = Math.min(n, 48), gaps: number[] = [];
+    for (let a = 0; a < probe; a++) {
+      const i = Math.floor((a / probe) * n);
+      let best = Infinity;
+      for (let j = 0; j < n; j++) if (j !== i) best = Math.min(best, Math.hypot(slots[i]![0] - slots[j]![0], slots[i]![1] - slots[j]![1], slots[i]![2] - slots[j]![2]));
+      if (Number.isFinite(best)) gaps.push(best);
+    }
+    gaps.sort((a, b) => a - b);
+    return { w: Math.max(1e-3, x1 - x0), h: Math.max(1e-3, y1 - y0), gap: gaps[Math.floor(gaps.length / 2)] ?? 0.1 };
+  }, [slots, n]);
+  const view = nearestVisible(keys, width / height, position[2]);
+  const scale = size ? size / geo.w : Math.min((fit * view.width) / geo.w, (fit * view.height) / geo.h);
+  const piece = geo.gap * 0.84;
+  const mesh = React.useRef<InstancedMesh>(null);
+  const dummy = React.useMemo(() => new Object3D(), []);
+  const palette = React.useMemo(() => colors.map((c) => new Color(c)), [colors]);
+  React.useLayoutEffect(() => {
+    const m = mesh.current;
+    if (!m) return;
+    const c = new Color();
+    for (let i = 0; i < n; i++) {
+      const t = hash01(i, seed + 61) * (palette.length - 1), k = Math.min(palette.length - 2, Math.floor(t));
+      c.copy(palette[Math.max(0, k)]!).lerp(palette[Math.min(palette.length - 1, k + 1)]!, palette.length > 1 ? t - k : 0);
+      c.offsetHSL(0, 0, (hash01(i, seed + 62) - 0.5) * 0.16);
+      m.setColorAt(i, c);
+    }
+    if (m.instanceColor) m.instanceColor.needsUpdate = true;
+  }, [palette, n, seed]);
+  React.useLayoutEffect(() => {
+    const m = mesh.current;
+    if (!m) return;
+    for (let i = 0; i < n; i++) {
+      const s = pieceAt(frame, i, slots[i]!, { ranks, from, frames, seed, spread });
+      dummy.position.set(s.position[0] * scale, s.position[1] * scale, s.position[2] * scale);
+      dummy.rotation.set(s.rotation[0], s.rotation[1], s.rotation[2]);
+      dummy.scale.setScalar(piece * scale * s.scale);
+      dummy.updateMatrix();
+      m.setMatrixAt(i, dummy.matrix);
+    }
+    m.instanceMatrix.needsUpdate = true;
+  }, [frame, n, slots, ranks, from, frames, seed, spread, scale, piece, dummy]);
+  return (
+    <group position={position}>
+      <instancedMesh ref={mesh} args={[undefined, undefined, n]} frustumCulled={false}>
+        <boxGeometry args={[1, 1, 1]} />
+        <meshStandardMaterial roughness={0.42} metalness={0.12} />
+      </instancedMesh>
+    </group>
+  );
+};

package/src/hyperframes/kit/BrandTransform3D.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "../frame";
+import { brandTransformAt, type BrandTransform, type BrandTransformTiming } from "./brand-transform";
+
+// A branded object turning into view, arriving on an arc, or launching from depth. Use inside Scene3D around a Card3D, Hero3D or Text3D.
+// The final pose holds exactly: the real logo or product can be read without a continuous spin. Sound stays outside Scene3D; brandTransformFrames gives its landing frame.
+export const BrandTransform3D: React.FC<BrandTransformTiming & { mode?: BrandTransform; strength?: number; children?: React.ReactNode }> = ({ children, ...options }) => {
+  const frame = useCurrentFrame(), { fps } = useVideoConfig();
+  const pose = brandTransformAt(frame, fps, options);
+  if (!pose.visible) return null;
+  return <group position={pose.position} rotation={pose.rotation} scale={pose.scale}>{children}</group>;
+};

package/src/hyperframes/kit/BrowserFrame.tsx

@@ -0,0 +1,83 @@
+import React from "react";
+import { continueRender, delayRender, interpolate, spring, useCurrentFrame, useVideoConfig } from "../frame";
+import { Place } from "./Place";
+import { useMedia } from "./media";
+import { fonts } from "./theme";
+import { DEFAULT_HERO, rgba, uiColors, type UiTheme } from "./ui-theme";
+import { PANEL_SPRING, inOutCubic, browserFrames } from "./ui-math";
+
+// The natural size of an image, read once. The frame waits for it, so every frame knows how far the picture can scroll.
+function useImageSize(url: string): { w: number; h: number } | null {
+  const [size, setSize] = React.useState<{ w: number; h: number } | null>(null);
+  React.useEffect(() => {
+    const handle = delayRender(`size of ${url.slice(0, 40)}`);
+    const img = new Image();
+    img.onload = () => { setSize({ w: img.naturalWidth, h: img.naturalHeight }); continueRender(handle); };
+    img.onerror = () => continueRender(handle);
+    img.src = url;
+    return () => { continueRender(handle); };
+  }, [url]);
+  return size;
+}
+
+// A browser window (or, with device="phone", a phone) in perspective, carrying your own screenshot `src` (a project path or urls[...]). The picture starts at
+// its top and scrolls down by `scroll`, a fraction of the window's height (default 0.7), over `frames` (default 90) frames from `delay`; it never scrolls past
+// the end of the picture. A soft shadow lies under it and a sheen sweeps across once as it lands. `tilt` is the turn about the vertical axis in degrees
+// (default -12 for a browser, -16 for a phone; 0 faces the camera), `url` the text of the address bar. CSS 3D, no three.js. Times are frames from the
+// component's own mount; browserFrames({ delay }) gives the frame it settles and the sheen's span. `width` is a fraction of the frame's width (0.86 for a
+// browser, 0.5 for a phone); `theme` "dark" (default) or "light" colours the frame.
+export const BrowserFrame: React.FC<{
+  src: string;
+  device?: "browser" | "phone";
+  scroll?: number;
+  frames?: number;
+  delay?: number;
+  tilt?: number;
+  url?: string;
+  theme?: UiTheme;
+  hero?: string;
+  font?: string;
+  width?: number;
+  viewAspect?: number;
+  y?: number;
+}> = ({ src, device = "browser", scroll = 0.7, frames = 90, delay = 0, tilt, url = "relay.app", theme = "dark", hero = DEFAULT_HERO, font = fonts.body, width: given, viewAspect, y = 0.5 }) => {
+  const frame = useCurrentFrame();
+  const { fps, width: W, height: H } = useVideoConfig();
+  const link = useMedia(src);
+  const size = useImageSize(link);
+  const c = uiColors(theme, hero);
+  const phone = device === "phone";
+  const P = W * (given ?? (phone ? 0.5 : 0.86));
+  const turn = tilt ?? (phone ? -16 : -12);
+  const p = spring({ frame: frame - delay, fps, config: PANEL_SPRING });
+  const bar = phone ? 0 : P * 0.085, bezel = phone ? P * 0.035 : 0;
+  const viewW = P - bezel * 2, viewH = viewW * (viewAspect ?? (phone ? 2.05 : 0.78));
+  const imgH = size ? (viewW * size.h) / size.w : viewH;
+  const travel = Math.max(0, Math.min(scroll * viewH, imgH - viewH));
+  const ev = browserFrames({ delay, fps });
+  const sc = inOutCubic((frame - delay - 10) / Math.max(1, frames)) * travel;
+  const sheen = interpolate(frame, [ev.sheenStart, ev.sheenEnd], [-0.4, 1.4], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
+  const totalH = bar + viewH + bezel * 2;
+  return (
+    <Place y={y}>
+      <div style={{ position: "relative", width: P, height: totalH, perspective: P * 2.4, opacity: Math.min(1, p * 1.5) }}>
+        <div style={{ position: "absolute", left: "6%", right: "6%", bottom: -P * 0.07, height: P * 0.1, background: "radial-gradient(ellipse at 50% 50%, rgba(0,0,0,0.55), rgba(0,0,0,0) 70%)", filter: `blur(${P * 0.03}px)`, transform: `translateY(${(1 - p) * H * 0.05}px)` }} />
+        <div style={{ position: "absolute", inset: 0, transform: `translateY(${(1 - p) * H * 0.06}px) rotateY(${turn * p}deg) rotateX(${Math.abs(turn) * 0.38 * p}deg)`, transformStyle: "preserve-3d" }}>
+          <div style={{ position: "absolute", inset: 0, borderRadius: phone ? P * 0.12 : P * 0.035, background: phone ? "#0b0b10" : c.panel, border: `${Math.max(2, P * 0.004)}px solid ${phone ? "rgba(255,255,255,0.28)" : c.stroke}`, boxShadow: `0 ${P * 0.06}px ${P * 0.14}px ${c.shadow}, 0 0 ${P * 0.18}px ${rgba(hero, 0.2)}`, overflow: "hidden" }}>
+            {!phone ? (
+              <div style={{ height: bar, display: "flex", alignItems: "center", gap: P * 0.015, padding: `0 ${P * 0.035}px`, background: c.field, borderBottom: `1px solid ${c.stroke}` }}>
+                {["#ff5f57", "#febc2e", "#28c840"].map((d) => <div key={d} style={{ width: P * 0.022, height: P * 0.022, borderRadius: 999, background: d }} />)}
+                <div style={{ flex: 1, margin: `0 ${P * 0.03}px 0 ${P * 0.03}px`, background: c.chip, borderRadius: 999, padding: `${P * 0.008}px ${P * 0.03}px`, fontFamily: font, fontSize: P * 0.032, color: c.dim, textAlign: "center", fontWeight: 500 }}>{url}</div>
+              </div>
+            ) : null}
+            <div style={{ position: "absolute", left: bezel, right: bezel, top: bar + bezel, height: viewH, overflow: "hidden", borderRadius: phone ? P * 0.09 : 0, background: "#ffffff" }}>
+              <img src={link} style={{ display: "block", width: "100%", height: "auto", transform: `translateY(${-sc}px)` }} />
+              {phone ? <div style={{ position: "absolute", left: "50%", top: viewW * 0.03, width: viewW * 0.3, height: viewW * 0.085, borderRadius: 999, background: "#000", transform: "translateX(-50%)" }} /> : null}
+            </div>
+            <div style={{ position: "absolute", inset: 0, pointerEvents: "none", background: `linear-gradient(105deg, rgba(255,255,255,0) ${sheen * 100 - 14}%, rgba(255,255,255,0.22) ${sheen * 100}%, rgba(255,255,255,0) ${sheen * 100 + 14}%)` }} />
+          </div>
+        </div>
+      </div>
+    </Place>
+  );
+};

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

@@ -1,22 +1,24 @@
 import React from "react";
-import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
-import { cameraAt, cameraTransform, type CameraKey } from "./motion-math";
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "../frame";
+import { applyPunches, cameraAt, cameraTransform, type CameraKey, type Punch } from "./motion-math";
 
 // Moves the whole picture. Wrap all the scenes in it for one camera that never cuts, or wrap one scene's content.
 // Each key gives the point of the content, as fractions of the frame, that sits at the middle of the screen (x, y), the zoom (1 shows
 // the content as it fits) and a turn in degrees; what a key leaves out stays as it was. The move toward a key starts `lead` frames
 // before its frame (12 unless set) on a spring and lands on the key's frame. drift is a very slow push on top, as a fraction of the
-// zoom per second (0.02 is two percent a second), so a held shot is never perfectly still.
+// zoom per second (0.02 is two percent a second), so a held shot is never perfectly still. punches are quick emphasis pushes of 8 to 15 percent onto a
+// point, { frame, x, y, amount?: 0.1, frames?: 5, hold?: 6 }, on top of the keys. To push into an element until it fills the frame, put zoomTo(frame, box) in keys.
 export const Camera: React.FC<{
   keys: CameraKey[];
   drift?: number;
+  punches?: Punch[];
   lead?: number;
   stiffness?: number;
   damping?: number;
   children: React.ReactNode;
-}> = ({ keys, drift, lead, stiffness, damping, children }) => {
+}> = ({ keys, drift, punches, lead, stiffness, damping, children }) => {
   const frame = useCurrentFrame();
   const { fps, width, height } = useVideoConfig();
-  const { origin, transform } = cameraTransform(cameraAt(keys, frame, fps, { lead, stiffness, damping, drift }), width, height);
+  const { origin, transform } = cameraTransform(applyPunches(cameraAt(keys, frame, fps, { lead, stiffness, damping, drift }), punches ?? [], frame), width, height);
   return <AbsoluteFill style={{ transformOrigin: origin, transform }}>{children}</AbsoluteFill>;
 };

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

@@ -1,7 +1,8 @@
 import React from "react";
-import { AbsoluteFill, interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, interpolate, spring, useCurrentFrame, useVideoConfig } from "../frame";
 import type { WordTiming } from "../../pipeline/schema";
-import { captionGroups, groupAt, type CaptionGroup } from "./caption-groups";
+import { captionGroups, DEFAULT_GROUP_WORDS, groupAt, type CaptionGroup } from "./caption-groups";
+import { inkOnAccent, legibleAccent, PLATE_COLOR } from "./caption-style";
 import { fonts, springs } from "./theme";
 
 export type CaptionMode = "highlight" | "pop" | "karaoke";
@@ -10,11 +11,15 @@ export type CaptionMode = "highlight" | "pop" | "karaoke";
 //   highlight: a line of words, the spoken one in the highlight colour (calm, educational)
 //   pop:       one to three words at a time, each popping in as it is spoken (high energy)
 //   karaoke:   a line that fills with the highlight colour as it is spoken (voiceover, music)
-// group, when given, decides which words share the screen and replaces perLine:
-//   "word":   exactly one word at a time
-//   "phrase": words grouped as they are spoken: a group ends at a sentence end, at a comma or dash after three words, or at a pause of
-//             0.35 s, and never holds more than 6 words or about 32 characters
+// The words sit on a dark rounded plate (about 58% opaque) in white, so they read on cream and on a busy photo alike without choosing colours; the
+// spoken word is on a chip of `highlight` (the film's accent) with white or dark ink, whichever reads better on it (karaoke has no chip: its fill is
+// the accent mixed toward white only as far as it needs to stay legible on the plate).
+// group decides which words share the screen:
+//   "word":   exactly one word at a time (only when the plan says `captions: "word"`)
+//   "phrase": words grouped as they are spoken, at most `maxWords` (default 3) and about 32 characters: a group ends at a sentence end (. ? !, never
+//             spanning two sentences), at a comma or dash after three words, or at a pause of 0.35 s
 //   "none":   nothing is drawn (the plan's `captions: "none"`), so the manifest's value can be passed straight through
+// With neither group nor perLine the groups are the same as "phrase": a few words (3), never one. perLine alone counts words as it always did.
 export const Captions: React.FC<{
   words: WordTiming[];
   mode?: CaptionMode;
@@ -22,28 +27,37 @@ export const Captions: React.FC<{
   color?: string;
   perLine?: number;
   group?: CaptionGroup;
+  // The most words in a group (default 3) for "phrase" and for the default.
+  maxWords?: number;
   uppercase?: boolean;
   // Distance of the caption baseline from the bottom, as a fraction of the height. Default keeps it clear of platform UI.
   bottom?: number;
   // Font family. Set to font("heebo") or font("rubik") for Hebrew; rtl also reverses the word order on the line.
   face?: string;
   rtl?: boolean;
-}> = ({ words, mode = "highlight", highlight = "#ffe14d", color = "#ffffff", perLine, group, uppercase = false, bottom = 0.16, face, rtl = false }) => {
+}> = ({ words, mode = "highlight", highlight = "#ffe14d", color = "#ffffff", perLine, group, maxWords, uppercase = false, bottom = 0.16, face, rtl = false }) => {
   const frame = useCurrentFrame();
   const { fps, width, height } = useVideoConfig();
   const t = frame / fps;
   if (words.length === 0 || group === "none") return null;
 
   if (group === "word" && t < words[0]!.startSec) return null;
+  // Without group or perLine a group is a few words (3), as with "phrase".
+  const grouping = group ?? (perLine === undefined ? "phrase" : undefined);
+  const accent = legibleAccent(highlight);
+  const chipInk = inkOnAccent(highlight);
+  // Every word has the same padding, so the line does not shift as the chip moves from word to word.
+  const pad: React.CSSProperties = { borderRadius: "0.3em", padding: "0 0.14em" };
+  const chip: React.CSSProperties = { ...pad, background: highlight, color: chipInk, textShadow: "none" };
   let active: number, lineStart: number, line: WordTiming[];
-  if (group) {
-    const groups = captionGroups(words, group);
+  if (grouping) {
+    const groups = captionGroups(words, grouping, { maxWords: maxWords ?? DEFAULT_GROUP_WORDS });
     const at = groupAt(words, groups, t);
     active = at.active;
     [lineStart] = groups[at.index]!;
     line = words.slice(lineStart, groups[at.index]![1]);
   } else {
-    const size = perLine ?? (mode === "pop" ? 2 : 4);
+    const size = perLine ?? DEFAULT_GROUP_WORDS;
     active = words.findIndex((w) => t < w.endSec);
     if (active === -1) active = words.length - 1;
     lineStart = Math.floor(active / size) * size;
@@ -53,15 +67,16 @@ export const Captions: React.FC<{
 
   const base: React.CSSProperties = {
     fontFamily: face ?? fonts.body, fontWeight: 800, textAlign: "center", direction: rtl ? "rtl" : "ltr", padding: `0 ${width * 0.06}px`,
-    fontSize: width * (mode === "pop" || group === "word" ? 0.075 : 0.055), lineHeight: 1.15, color,
-    // A dark outline plus shadow keeps contrast above 4.5:1 on any background.
-    WebkitTextStroke: `${width * 0.006}px rgba(0,0,0,0.85)`, paintOrder: "stroke fill",
-    textShadow: "0 4px 18px rgba(0,0,0,0.7)",
+    fontSize: width * (mode === "pop" || group === "word" ? 0.075 : 0.055), lineHeight: 1.5, color,
+    textShadow: "0 2px 10px rgba(0,0,0,0.45)",
   };
+  // The plate: one dark rounded box behind each line of the group, so the white ink has 4.5:1 or more on any ground.
+  const plate: React.CSSProperties = { background: PLATE_COLOR, borderRadius: "0.42em", padding: "0.12em 0.5em", boxDecorationBreak: "clone", WebkitBoxDecorationBreak: "clone" };
 
   return (
     <AbsoluteFill style={{ justifyContent: "flex-end", alignItems: "center", paddingBottom: height * bottom }}>
       <div style={base}>
+        <span style={plate}>
         {line.map((w, i) => {
           const index = lineStart + i;
           const started = t >= w.startSec;
@@ -69,7 +84,7 @@ export const Captions: React.FC<{
             // A word appears on the frame it starts, never before, with a small overshoot.
             const p = spring({ frame: frame - Math.round(w.startSec * fps), fps, config: springs.snappy });
             return (
-              <span key={index} style={{ display: "inline-block", margin: `0 ${width * 0.012}px`, opacity: started ? 1 : 0, transform: `scale(${interpolate(p, [0, 1], [0.6, 1])})`, color: index === active ? highlight : color }}>
+              <span key={index} style={{ display: "inline-block", margin: `0 ${width * 0.012}px`, opacity: started ? 1 : 0, transform: `scale(${interpolate(p, [0, 1], [0.6, 1])})`, color, ...pad, ...(index === active ? chip : {}) }}>
                 {show(w)}
               </span>
             );
@@ -77,17 +92,18 @@ export const Captions: React.FC<{
           if (mode === "karaoke") {
             const fill = interpolate(t, [w.startSec, Math.max(w.endSec, w.startSec + 0.01)], [0, 100], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
             return (
-              <span key={index} style={{ display: "inline-block", marginRight: "0.28em", backgroundImage: `linear-gradient(90deg, ${highlight} ${fill}%, ${color} ${fill}%)`, WebkitBackgroundClip: "text", backgroundClip: "text", color: "transparent", WebkitTextStroke: "0px transparent", textShadow: "none", filter: "drop-shadow(0 3px 6px rgba(0,0,0,0.75))" }}>
+              <span key={index} style={{ display: "inline-block", marginRight: "0.28em", backgroundImage: `linear-gradient(90deg, ${accent} ${fill}%, ${color} ${fill}%)`, WebkitBackgroundClip: "text", backgroundClip: "text", color: "transparent", WebkitTextStroke: "0px transparent", textShadow: "none", filter: "drop-shadow(0 3px 6px rgba(0,0,0,0.75))" }}>
                 {show(w)}
               </span>
             );
           }
           return (
-            <span key={index} style={{ color: index === active && started ? highlight : color }}>
-              {show(w)}{" "}
+            <span key={index} style={index === active && started ? chip : { color, ...pad }}>
+              {show(w)}{i < line.length - 1 ? " " : ""}
             </span>
           );
         })}
+        </span>
       </div>
     </AbsoluteFill>
   );

package/src/hyperframes/kit/Card3D.tsx

@@ -0,0 +1,211 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "../frame";
+import { useLoader } from "@react-three/fiber";
+import { CanvasTexture, FrontSide, Shape, ShapeGeometry, SRGBColorSpace, TextureLoader, type Texture } from "three";
+import { delayRender, continueRender } from "../frame";
+import { useMedia } from "./media";
+import { fonts } from "./theme";
+import { degToRad, floatAt, inkOn, mixHex, type Vec3 } from "./three-math";
+
+// A rounded rectangle, with its texture coordinates running 0 to 1 across it so that a picture fills it.
+function roundedCard(w: number, h: number, r: number): ShapeGeometry {
+  const x = -w / 2, y = -h / 2, k = Math.min(r, w / 2, h / 2);
+  const s = new Shape();
+  s.moveTo(x + k, y);
+  s.lineTo(x + w - k, y); s.quadraticCurveTo(x + w, y, x + w, y + k);
+  s.lineTo(x + w, y + h - k); s.quadraticCurveTo(x + w, y + h, x + w - k, y + h);
+  s.lineTo(x + k, y + h); s.quadraticCurveTo(x, y + h, x, y + h - k);
+  s.lineTo(x, y + k); s.quadraticCurveTo(x, y, x + k, y);
+  const g = new ShapeGeometry(s, 8);
+  const p = g.attributes.position!, uv = g.attributes.uv!;
+  for (let i = 0; i < p.count; i++) uv.setXY(i, (p.getX(i) - x) / w, (p.getY(i) - y) / h);
+  return g;
+}
+
+// A soft dark blur in the card's shape, for the shadow behind it. Drawn once on a canvas; it needs no light.
+function shadowTexture(): CanvasTexture {
+  const c = document.createElement("canvas");
+  c.width = 256; c.height = 256;
+  const g = c.getContext("2d")!;
+  g.filter = "blur(18px)";
+  g.fillStyle = "rgba(0,0,0,0.55)";
+  g.beginPath();
+  g.roundRect(48, 48, 160, 160, 28);
+  g.fill();
+  const t = new CanvasTexture(c);
+  t.colorSpace = SRGBColorSpace;
+  return t;
+}
+
+// Any CSS colour as "#rrggbb", by letting a canvas parse it.
+function normalise(color: string): string {
+  const g = document.createElement("canvas").getContext("2d")!;
+  g.fillStyle = "#000000";
+  g.fillStyle = color;
+  const v = String(g.fillStyle);
+  return v.startsWith("#") ? v : "#e8e8f0";
+}
+
+type Face = { color: string; accent?: string; label?: string; icon?: HTMLImageElement; family: string; ratio: number; radius: number };
+
+// The face of a card drawn on a canvas: a gradient (lighter at the top left), a soft highlight, a rim in the accent and, if given, an icon above a large
+// label. Drawn once; nothing here depends on the frame, so every frame shows the same face. The ink is white on a dark face and dark on a light one.
+function drawFace(f: Face): CanvasTexture {
+  const long = 1024, W = Math.round(long * Math.min(1, f.ratio)), H = Math.round(long * Math.min(1, 1 / f.ratio));
+  const c = document.createElement("canvas");
+  c.width = W; c.height = H;
+  const g = c.getContext("2d")!;
+  const base = normalise(f.color), accent = normalise(f.accent ?? mixHex(base, "#ffffff", 0.55));
+  const r = Math.min(W, H) * Math.min(0.5, f.radius / Math.min(f.ratio, 1) * 0.33);
+  const body = new Path2D();
+  body.roundRect(0, 0, W, H, r);
+  g.save();
+  g.clip(body);
+  const grad = g.createLinearGradient(0, 0, W * 0.8, H);
+  grad.addColorStop(0, mixHex(base, "#ffffff", 0.16));
+  grad.addColorStop(0.55, base);
+  grad.addColorStop(1, mixHex(base, "#000000", 0.3));
+  g.fillStyle = grad;
+  g.fillRect(0, 0, W, H);
+  const hi = g.createLinearGradient(0, 0, 0, H * 0.5);
+  hi.addColorStop(0, "rgba(255,255,255,0.20)");
+  hi.addColorStop(1, "rgba(255,255,255,0)");
+  g.fillStyle = hi;
+  g.fillRect(0, 0, W, H * 0.5);
+  g.restore();
+  // The rim: an outer line in the accent and a fine light line just inside it.
+  const edge = Math.max(4, Math.min(W, H) * 0.018);
+  g.lineWidth = edge;
+  g.strokeStyle = accent;
+  g.beginPath(); g.roundRect(edge / 2, edge / 2, W - edge, H - edge, Math.max(1, r - edge / 2)); g.stroke();
+  g.lineWidth = Math.max(1.5, edge * 0.35);
+  g.strokeStyle = "rgba(255,255,255,0.28)";
+  g.beginPath(); g.roundRect(edge * 1.7, edge * 1.7, W - edge * 3.4, H - edge * 3.4, Math.max(1, r - edge * 1.7)); g.stroke();
+
+  const ink = inkOn(base), m = Math.min(W, H);
+  const lines = (f.label ?? "").split("\n").filter(Boolean);
+  let px = m * 0.2;
+  if (lines.length) {
+    g.font = `800 ${px}px ${f.family}`;
+    const widest = Math.max(...lines.map((l) => g.measureText(l).width));
+    if (widest > W * 0.8) px *= (W * 0.8) / widest;
+    px = Math.min(px, H * 0.22);
+  }
+  const labelH = lines.length * px * 1.12;
+  const iconSize = f.icon ? (lines.length ? m * 0.4 : m * 0.55) : 0;
+  const gap = f.icon && lines.length ? m * 0.07 : 0;
+  let y = (H - (iconSize + gap + labelH)) / 2;
+  if (f.icon) {
+    // Fitted into a square of iconSize, keeping its shape.
+    const ratio = (f.icon.naturalWidth || 1) / (f.icon.naturalHeight || 1);
+    const dw = ratio >= 1 ? iconSize : iconSize * ratio, dh = ratio >= 1 ? iconSize / ratio : iconSize;
+    g.drawImage(f.icon, (W - dw) / 2, y + (iconSize - dh) / 2, dw, dh);
+    y += iconSize + gap;
+  }
+  g.fillStyle = ink;
+  g.textAlign = "center"; g.textBaseline = "middle";
+  g.font = `800 ${px}px ${f.family}`;
+  lines.forEach((l, i) => g.fillText(l, W / 2, y + (i + 0.5) * px * 1.12));
+  const t = new CanvasTexture(c);
+  t.colorSpace = SRGBColorSpace;
+  t.anisotropy = 8;
+  return t;
+}
+
+// Waits, before the frame is drawn, for the typeface and the icon, so that the label is set in the film's font and never in a fallback.
+function useFaceAssets(label: string | undefined, iconUrl: string | undefined, family: string): { ready: boolean; icon?: HTMLImageElement } {
+  const need = Boolean(label || iconUrl);
+  const [state, setState] = React.useState<{ ready: boolean; icon?: HTMLImageElement }>({ ready: !need });
+  React.useLayoutEffect(() => {
+    if (!need) { setState({ ready: true }); return; }
+    const handle = delayRender("Card3D face");
+    let live = true;
+    (async () => {
+      try { await Promise.all([document.fonts.load(`800 64px ${family}`, label ?? "A"), document.fonts.ready]); } catch { /* the fallback face is fine */ }
+      let icon: HTMLImageElement | undefined;
+      if (iconUrl) {
+        icon = new Image();
+        try { await new Promise<void>((ok, bad) => { icon!.onload = () => ok(); icon!.onerror = () => bad(new Error("icon")); icon!.src = iconUrl; }); } catch { icon = undefined; }
+      }
+      if (live) setState({ ready: true, icon });
+    })().finally(() => continueRender(handle));
+    return () => { live = false; };
+  }, [need, label, iconUrl, family]);
+  return state;
+}
+
+const Designed: React.FC<{ width: number; height: number; radius: number; color: string; accent?: string; label?: string; icon?: string; family: string }> = ({ width, height, radius, color, accent, label, icon, family }) => {
+  const iconUrl = useMedia(icon ?? "");
+  const assets = useFaceAssets(label, icon ? iconUrl : undefined, family);
+  const flat = React.useMemo(() => roundedCard(width, height, radius), [width, height, radius]);
+  const texture = React.useMemo(() => drawFace({ color, accent, label, icon: assets.icon, family, ratio: width / height, radius }), [color, accent, label, assets, family, width, height, radius]);
+  React.useEffect(() => () => texture.dispose(), [texture]);
+  return <Body geometry={flat} width={width} height={height}><meshBasicMaterial map={texture} toneMapped={false} /></Body>;
+};
+
+const Picture: React.FC<{ url: string; width: number; height?: number; radius: number }> = ({ url, width, height, radius }) => {
+  const texture = useLoader(TextureLoader, url) as Texture;
+  texture.colorSpace = SRGBColorSpace;
+  const img = texture.image as { width: number; height: number } | undefined;
+  const h = height ?? (img ? (width * img.height) / img.width : width * 0.66);
+  const geometry = React.useMemo(() => roundedCard(width, h, radius), [width, h, radius]);
+  return <Body geometry={geometry} width={width} height={h}><meshBasicMaterial map={texture} toneMapped={false} /></Body>;
+};
+
+// The card's body with its soft shadow. A face is drawn on both sides, so that one seen from behind (the far side of a ring) reads the right way round
+// rather than as a mirror image.
+const Body: React.FC<{ geometry: ShapeGeometry; width: number; height: number; children: React.ReactElement }> = ({ geometry, width, height, children }) => {
+  const shadow = React.useMemo(shadowTexture, []);
+  const face = React.cloneElement(children, { side: FrontSide } as never);
+  return (
+    <>
+      <mesh position={[0.04 * width, -0.07 * height, -0.04]} scale={[width * 1.7, height * 1.7, 1]}>
+        <planeGeometry args={[1, 1]} />
+        <meshBasicMaterial map={shadow} transparent depthWrite={false} toneMapped={false} />
+      </mesh>
+      <mesh geometry={geometry}>{face}</mesh>
+      <mesh geometry={geometry} rotation={[0, Math.PI, 0]} position={[0, 0, -0.004]}>{React.cloneElement(children, { side: FrontSide } as never)}</mesh>
+    </>
+  );
+};
+
+// A rounded plane in space that shows a picture (`src`, a project path or urls[...]) or a designed face, for screenshots and for cards that carry a
+// word or a mark. Without `src` the face is a gradient of `color` with a soft highlight and a rim in `accent` (default a light tint of the colour);
+// `label` is drawn large on it in the film's font (`font`, default the kit's display face) and `icon` (a project path to an image or svg, drawn in its
+// own colours) above the label; the ink is white on a dark colour and dark on a light one. Give every card in a ring a label or an icon. width is in
+// scene units (default 3); the height follows the picture's shape unless set. position is [x, y, z]; rotation is [x, y, z] in degrees; `tilt` is a
+// shorthand for the one tilt a card needs: a turn about the vertical axis in degrees, with a lean the other way about the horizontal. A soft shadow sits
+// behind it, and `float` makes it drift slowly (true, or a number for how much), the same at the same frame.
+export const Card3D: React.FC<{
+  src?: string;
+  color?: string;
+  width?: number;
+  height?: number;
+  radius?: number;
+  position?: Vec3;
+  rotation?: Vec3;
+  tilt?: number;
+  float?: boolean | number;
+  label?: string;
+  icon?: string;
+  accent?: string;
+  font?: string;
+}> = ({ src, color = "#e8e8f0", width = 3, height, radius = 0.12, position = [0, 0, 0], rotation = [0, 0, 0], tilt = 0, float: drift, label, icon, accent, font = fonts.display }) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const url = useMedia(src ?? "");
+  const f = drift ? floatAt(frame, fps, drift === true ? 1 : drift, position[0] * 3 + position[1]) : { offset: [0, 0, 0] as Vec3, rotation: [0, 0, 0] as Vec3 };
+  const h = height ?? width * 0.66;
+  return (
+    <group
+      position={[position[0] + f.offset[0], position[1] + f.offset[1], position[2] + f.offset[2]]}
+      rotation={[degToRad(rotation[0] - tilt * 0.3) + f.rotation[0], degToRad(rotation[1] + tilt) + f.rotation[1], degToRad(rotation[2]) + f.rotation[2]]}
+    >
+      {src ? (
+        <React.Suspense fallback={null}><Picture url={url} width={width} height={height} radius={radius} /></React.Suspense>
+      ) : (
+        <Designed width={width} height={h} radius={radius} color={color} accent={accent} label={label} icon={icon} family={font} />
+      )}
+    </group>
+  );
+};

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

@@ -1,5 +1,5 @@
 import React from "react";
-import { useCurrentFrame, useVideoConfig } from "remotion";
+import { useCurrentFrame, useVideoConfig } from "../frame";
 import { boxAt, type Box, type BoxKey } from "./motion-math";
 
 // What a function child is given: the box now, as fractions of the frame, and its size in pixels.

package/src/hyperframes/kit/ChapterFrame.tsx

@@ -0,0 +1,68 @@
+import React from "react";
+import { AbsoluteFill, interpolate, spring, useCurrentFrame, useVideoConfig } from "../frame";
+import { font as loadFont, fonts, springs } from "./theme";
+import { inkOn, mixHex } from "./three-math";
+import { chapterFrames, clamp01 } from "./ui-math";
+import { rgba } from "./ui-theme";
+
+// The grammar of one chapter of a film, as slots, so that every scene of a film is built the same way: a counter "03 / 07" at the top with a progress rule
+// under it, a large ghost word behind everything, `children` as the hero in the middle, up to three `badges` (pills that pop in) and one `caption` line at the
+// bottom. `color` is the chapter's ground and fills the frame (a different one per chapter is the colour script); the ink is chosen to read on it. Use it
+// once per scene, with the same props shape in every scene. Times are frames from the component's own mount; chapterFrames({ delay, badges }) gives the
+// frames the badges pop, for sound. `index` counts from 1. `hero` tints the first badge and the rule's head.
+export const ChapterFrame: React.FC<{
+  index: number;
+  total: number;
+  color: string;
+  ghost?: string;
+  caption?: string;
+  badges?: string[];
+  hero?: string;
+  ink?: string;
+  font?: string;
+  delay?: number;
+  children?: React.ReactNode;
+}> = ({ index, total, color, ghost, caption, badges = [], hero, ink, font = fonts.display, delay = 0, children }) => {
+  const frame = useCurrentFrame();
+  const { fps, width: W, height: H } = useVideoConfig();
+  const text = ink ?? inkOn(color);
+  const mono = loadFont("jetbrainsMono");
+  const ev = chapterFrames({ delay, badges: badges.length });
+  const fill = interpolate(frame, [delay, ev.progressDone], [(index - 1) / total, index / total], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
+  const letters = ghost ? [...ghost.toUpperCase()].length : 1;
+  const ghostSize = Math.max(W * 0.16, Math.min(W * 0.46, (W * 0.96) / (letters * 0.66)));
+  const ghostIn = spring({ frame: frame - delay, fps, config: springs.heavy });
+  const capIn = spring({ frame: frame - delay - 8, fps, config: springs.smooth });
+  const heroIn = spring({ frame: frame - delay + 2, fps, config: springs.smooth });
+  return (
+    <AbsoluteFill style={{ background: color, color: text, fontFamily: font, overflow: "hidden" }}>
+      {ghost ? (
+        <div style={{ position: "absolute", left: 0, right: 0, top: H * 0.5, transform: `translate(${interpolate(frame, [0, 150], [-W * 0.012, W * 0.012], { extrapolateRight: "extend" })}px, -50%) scale(${0.94 + 0.06 * ghostIn})`, textAlign: "center", fontSize: ghostSize, fontWeight: 900, letterSpacing: "-0.04em", lineHeight: 1, color: rgba(text, 0.1), whiteSpace: "nowrap", opacity: ghostIn }}>
+          {ghost.toUpperCase()}
+        </div>
+      ) : null}
+      <div style={{ position: "absolute", left: W * 0.07, right: W * 0.07, top: H * 0.055 }}>
+        <div style={{ display: "flex", alignItems: "baseline", justifyContent: "space-between", fontFamily: mono, fontWeight: 700, fontSize: W * 0.04, letterSpacing: "0.04em" }}>
+          <span>{String(index).padStart(2, "0")}<span style={{ opacity: 0.45 }}> / {String(total).padStart(2, "0")}</span></span>
+        </div>
+        <div style={{ position: "relative", marginTop: W * 0.025, height: Math.max(4, W * 0.007), background: rgba(text, 0.18), borderRadius: 999 }}>
+          <div style={{ position: "absolute", left: 0, top: 0, bottom: 0, width: `${clamp01(fill) * 100}%`, background: text, borderRadius: 999 }} />
+          {hero ? <div style={{ position: "absolute", top: "50%", left: `${clamp01(fill) * 100}%`, width: W * 0.026, height: W * 0.026, borderRadius: 999, background: hero, transform: "translate(-50%, -50%)", boxShadow: `0 0 ${W * 0.02}px ${rgba(hero, 0.8)}` }} /> : null}
+        </div>
+      </div>
+      <div style={{ position: "absolute", left: 0, right: 0, top: H * 0.15, bottom: H * 0.3, display: "flex", alignItems: "center", justifyContent: "center", opacity: heroIn, transform: `translateY(${(1 - heroIn) * H * 0.03}px)` }}>{children}</div>
+      <div style={{ position: "absolute", left: W * 0.05, right: W * 0.05, top: H * 0.72, display: "flex", justifyContent: "center", gap: W * 0.025, flexWrap: "wrap" }}>
+        {badges.slice(0, 3).map((b, i) => {
+          const p = spring({ frame: frame - ev.badges[i]!, fps, config: { stiffness: 260, damping: 14 } });
+          const lead = i === 0 && hero;
+          return (
+            <div key={i} style={{ transform: `scale(${p})`, opacity: clamp01(p * 2), fontWeight: 700, fontSize: W * 0.034, padding: `${W * 0.014}px ${W * 0.04}px`, borderRadius: 999, background: lead ? hero : rgba(text, 0.12), color: lead ? inkOn(hero!) : text, border: lead ? "none" : `${Math.max(2, W * 0.002)}px solid ${rgba(text, 0.3)}`, whiteSpace: "nowrap" }}>{b}</div>
+          );
+        })}
+      </div>
+      {caption ? (
+        <div style={{ position: "absolute", left: W * 0.07, right: W * 0.07, top: H * 0.8, textAlign: "center", fontWeight: 700, fontSize: W * 0.05, lineHeight: 1.18, letterSpacing: "-0.01em", color: mixHex(text, color, 0.08), opacity: capIn, transform: `translateY(${(1 - capIn) * W * 0.03}px)` }}>{caption}</div>
+      ) : null}
+    </AbsoluteFill>
+  );
+};