reelkit-cli 0.6.0 → 0.10.0

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

@@ -1,6 +1,6 @@
 import React from "react";
 import { useMedia } from "./media";
-import { AbsoluteFill, OffthreadVideo } from "remotion";
+import { AbsoluteFill, OffthreadVideo } from "../frame";
 
 // A generated or library video clip as a scene's picture. Place it inside the scene's SceneFrame, as the bottom layer, so it starts with the scene.
 // When the scene runs longer than the clip, the clip holds its last frame (it does not loop: a looped person or animal jumps back and shows the seam).

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

@@ -1,6 +1,6 @@
 import React from "react";
 import { fonts } from "./theme";
-import { AbsoluteFill, interpolate, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, interpolate, useCurrentFrame, useVideoConfig } from "../frame";
 
 export const Counter: React.FC<{ from?: number; to: number; durationFrames?: number; prefix?: string; suffix?: string; color?: string }> = ({
   from = 0, to, durationFrames = 30, prefix = "", suffix = "", color = "#ffffff",

package/src/hyperframes/kit/CounterRoll.tsx

@@ -0,0 +1,75 @@
+import React from "react";
+import { interpolate, useCurrentFrame, useVideoConfig } from "../frame";
+import { Place } from "./Place";
+import { fonts } from "./theme";
+import { DEFAULT_HERO } from "./ui-theme";
+import { rollValue } from "./ui-math";
+
+const DIGITS = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0];
+
+// An odometer: a number whose digits roll like wheels from `from` to `to` over `frames`, easing out and landing exactly, in tabular digits so nothing
+// shifts sideways. `prefix` and `suffix` ("$", "%", "x") sit around it, `decimals` shows places after the point, `group` puts a comma between thousands
+// (default on), `label` is a small line under it. It is sized to fill `width` (a fraction of the frame, default 0.86) at most `maxSize` of the width (0.3).
+// Times are frames from the component's own mount: it starts at `delay` (default 0) and settleFrame({ delay, frames }) is the frame it lands, for a
+// chime. The wheels stay on the final number after that. Colour: `ink` for the digits (default white), `hero` for the prefix, suffix and label.
+export const CounterRoll: React.FC<{
+  to: number;
+  from?: number;
+  frames?: number;
+  delay?: number;
+  prefix?: string;
+  suffix?: string;
+  label?: string;
+  decimals?: number;
+  group?: boolean;
+  hero?: string;
+  ink?: string;
+  font?: string;
+  width?: number;
+  maxSize?: number;
+  y?: number;
+}> = ({ to, from = 0, frames = 45, delay = 0, prefix = "", suffix = "", label, decimals = 0, group = true, hero = DEFAULT_HERO, ink = "#f4f4f5", font = fonts.display, width: fraction = 0.86, maxSize = 0.3, y = 0.5 }) => {
+  const frame = useCurrentFrame();
+  const { width: W } = useVideoConfig();
+  const scale = 10 ** decimals;
+  const value = rollValue(frame, { from, to, frames, delay });
+  const scaled = value * scale;
+  const cols = Math.max(decimals + 1, String(Math.round(Math.max(Math.abs(to), Math.abs(from)) * scale)).length);
+  const extra = prefix.length * 0.6 + suffix.length * 0.6 + (group ? Math.floor((cols - 1 - decimals) / 3) * 0.3 : 0) + (decimals ? 0.3 : 0);
+  const em = cols * 0.64 + extra;
+  const size = Math.min(W * maxSize, (W * fraction) / em);
+  const lh = size * 1.06;
+  const cells: React.ReactNode[] = [];
+  for (let k = cols - 1; k >= 0; k--) {
+    const place = 10 ** k;
+    const lead = Math.floor(scaled / place) === 0 && k > decimals;
+    // The ones wheel turns continuously; every wheel above it only turns as the one below comes round to its carry, like a real odometer.
+    const x = scaled / place, whole = Math.floor(x + 1e-9), frac = Math.max(0, x - whole);
+    const pos = (whole % 10) + (k === 0 ? frac : Math.max(0, Math.min(1, (frac - 0.8) / 0.2)));
+    if (k === decimals - 1 && decimals > 0) cells.push(<span key="dot" style={{ width: size * 0.3, textAlign: "center", lineHeight: `${lh}px` }}>.</span>);
+    cells.push(
+      <span key={k} style={{ display: "inline-block", width: size * 0.64, height: lh, overflow: "hidden", position: "relative", opacity: lead ? 0 : 1, WebkitMaskImage: "linear-gradient(180deg, transparent 0%, #000 22%, #000 78%, transparent 100%)", maskImage: "linear-gradient(180deg, transparent 0%, #000 22%, #000 78%, transparent 100%)" }}>
+        <span style={{ display: "block", transform: `translateY(${-pos * lh}px)` }}>
+          {DIGITS.map((d, i) => <span key={i} style={{ display: "block", height: lh, lineHeight: `${lh}px`, textAlign: "center" }}>{d}</span>)}
+        </span>
+      </span>,
+    );
+    if (group && k > decimals && (k - decimals) % 3 === 0) {
+      const hide = Math.floor(scaled / 10 ** (k - 1)) === 0 && k - 1 > decimals;
+      cells.push(<span key={`c${k}`} style={{ display: "inline-block", width: size * 0.3, textAlign: "center", height: lh, lineHeight: `${lh}px`, opacity: hide || lead ? 0 : 1 }}>,</span>);
+    }
+  }
+  const settle = interpolate(frame, [delay, delay + frames], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
+  return (
+    <Place y={y}>
+      <div style={{ textAlign: "center", fontFamily: font, fontWeight: 800, color: ink, fontVariantNumeric: "tabular-nums" }}>
+        <div style={{ display: "inline-flex", alignItems: "center", fontSize: size, height: lh }}>
+          {prefix ? <span style={{ color: hero, lineHeight: `${lh}px`, marginRight: size * 0.04 }}>{prefix}</span> : null}
+          {cells}
+          {suffix ? <span style={{ color: hero, lineHeight: `${lh}px`, marginLeft: size * 0.04 }}>{suffix}</span> : null}
+        </div>
+        {label ? <div style={{ marginTop: size * 0.1, fontSize: Math.max(W * 0.034, size * 0.2), fontWeight: 600, color: hero, opacity: 0.55 + 0.45 * settle, letterSpacing: "0.02em" }}>{label}</div> : null}
+      </div>
+    </Place>
+  );
+};

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

@@ -1,5 +1,5 @@
 import React from "react";
-import { interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { interpolate, spring, useCurrentFrame, useVideoConfig } from "../frame";
 import { ease, springs } from "./theme";
 
 // The workhorse entrance: fade + rise + scale together, with an optional faster exit and a slow idle "breathe".

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

@@ -1,6 +1,6 @@
 import React from "react";
 import { useMedia } from "./media";
-import { AbsoluteFill, OffthreadVideo } from "remotion";
+import { AbsoluteFill, OffthreadVideo } from "../frame";
 
 export const FootageLayer: React.FC<{ src: string; muted?: boolean; dim?: number }> = ({ src, muted = true, dim = 0 }) => (
   <AbsoluteFill>

package/src/hyperframes/kit/GlassPanel.tsx

@@ -0,0 +1,43 @@
+import React from "react";
+import { spring, useCurrentFrame, useVideoConfig } from "../frame";
+import { Place } from "./Place";
+import { DEFAULT_HERO, rgba, uiColors, type UiTheme } from "./ui-theme";
+import { PANEL_SPRING } from "./ui-math";
+
+// A slab for your own content: a near-black rounded panel (or a light one with theme="light") with a hairline stroke lit along its top edge, a coloured glow pool
+// behind it, an optional slight perspective `tilt` (degrees about the vertical axis, default 0; the horizontal tilt follows at 0.4 of it) and an entrance that
+// slides up and settles with a small overshoot. `delay` is a frame from the component's own mount (default 0); panelSettleFrame(delay, fps) is the frame it
+// lands, for a "snap" sound. `width` is a fraction of the frame's width (0.86), `height` a fraction of the frame's height (default: as tall as the content),
+// `glow` the colour of the pool (default the hero colour), `y` the height of its middle as a fraction of the frame (0.5). Children are laid out inside
+// with padding; text inside should be at least 0.032 of the frame's width.
+export const GlassPanel: React.FC<{
+  children?: React.ReactNode;
+  hero?: string;
+  glow?: string;
+  theme?: UiTheme;
+  width?: number;
+  height?: number;
+  tilt?: number;
+  delay?: number;
+  radius?: number;
+  padding?: number;
+  y?: number;
+}> = ({ children, hero = DEFAULT_HERO, glow, theme = "dark", width: fraction = 0.86, height, tilt = 0, delay = 0, radius = 0.06, padding = 0.05, y = 0.5 }) => {
+  const frame = useCurrentFrame();
+  const { fps, width: W, height: H } = useVideoConfig();
+  const c = uiColors(theme === "glass" ? "glass" : theme, hero);
+  const P = W * fraction;
+  const p = spring({ frame: frame - delay, fps, config: PANEL_SPRING });
+  const g = glow ?? hero;
+  const alpha = Math.min(1, p * 1.4);
+  return (
+    <Place y={y}>
+      <div style={{ position: "relative", width: P, perspective: P * 2.2, opacity: alpha }}>
+        <div style={{ position: "absolute", left: "-12%", right: "-12%", top: "-14%", bottom: "-14%", background: `radial-gradient(ellipse at 50% 55%, ${rgba(g, theme === "light" ? 0.35 : 0.62)} 0%, ${rgba(g, 0.0)} 66%)`, filter: `blur(${P * 0.06}px)`, transform: `translateY(${(1 - p) * H * 0.07}px)` }} />
+        <div style={{ position: "relative", transform: `translateY(${(1 - p) * H * 0.07}px) rotateY(${tilt * p}deg) rotateX(${-Math.abs(tilt) * 0.4 * p}deg)`, transformStyle: "preserve-3d", width: P, height: height === undefined ? undefined : H * height, boxSizing: "border-box", padding: P * padding, borderRadius: P * radius, background: theme === "light" ? c.panel : `linear-gradient(160deg, ${rgba("#2a2a3c", 0.72)} 0%, ${c.panel} 46%)`, border: `${Math.max(2, P * 0.003)}px solid ${c.stroke}`, boxShadow: `0 ${P * 0.05}px ${P * 0.12}px ${c.shadow}, inset 0 ${Math.max(2, P * 0.003)}px 0 ${theme === "light" ? "rgba(255,255,255,0.9)" : "rgba(255,255,255,0.22)"}` }}>
+          {children}
+        </div>
+      </div>
+    </Place>
+  );
+};

package/src/hyperframes/kit/Grounds.tsx

@@ -0,0 +1,177 @@
+import React from "react";
+import { AbsoluteFill, Img, OffthreadVideo, Sequence, useCurrentFrame, useVideoConfig } from "../frame";
+import { auroraBlobs, beamStates, breath, checkItems, grainSeed, gridOffset, gridRows, groundStrength, hueShift, mixHex, plateView, withAlpha, sequenceLayers, videoLayers, type Drift, type SequenceItem, type SequenceTransition } from "./bg-math";
+import { useMedia } from "./media";
+
+const isVideo = (src: string) => /\.(mp4|mov|webm|m4v)(\?|$)/i.test(src);
+
+// What every media ground shares: a dark layer so type stays readable, and a tint laid over at low opacity so a clip or picture takes the film's accent.
+const Finish: React.FC<{ dim: number; tint?: string }> = ({ dim, tint }) => (
+  <>
+    {tint ? <AbsoluteFill style={{ backgroundColor: tint, opacity: 0.18 }} /> : null}
+    {dim > 0 ? <AbsoluteFill style={{ backgroundColor: `rgba(0,0,0,${Math.min(0.8, Math.max(0, dim))})` }} /> : null}
+  </>
+);
+
+type PlateProps = { src: string; scale: number; tx: number; ty: number; blurPx: number; opacity?: number; wipe?: number; loopVideo?: boolean };
+
+// One picture or clip, covering the frame, moved by the given scale and shift. It is drawn muted, always.
+const Plate: React.FC<PlateProps> = ({ src, scale, tx, ty, blurPx, opacity = 1, wipe }) => {
+  const { width, height } = useVideoConfig();
+  const url = useMedia(src);
+  const mask = wipe === undefined ? undefined : `linear-gradient(90deg, #000 ${wipe * 115 - 15}%, transparent ${wipe * 115}%)`;
+  const style: React.CSSProperties = { width: "100%", height: "100%", objectFit: "cover" };
+  return (
+    <AbsoluteFill style={{ opacity, transform: `translate(${tx * width}px, ${ty * height}px) scale(${scale})`, filter: blurPx > 0 ? `blur(${blurPx}px)` : undefined, WebkitMaskImage: mask, maskImage: mask, overflow: "hidden" }}>
+      {isVideo(src) ? <OffthreadVideo src={url} muted style={style} /> : <Img src={url} style={style} />}
+    </AbsoluteFill>
+  );
+};
+
+// A video as the ground, for the whole film or for one scene. dim (0 to 0.8, default 0.35) darkens it so type stays readable; blur is in pixels; zoom is a
+// slow push as a fraction over `durationInFrames` (default the film's length); tint is a colour laid over at low opacity; playbackRate 0.5 is a calmer ground.
+// The clip is always muted. When loop is on (the default) and `durationSec` is given (manifest.background.durationSec), a film longer than the clip starts it
+// again with a short cross-fade over the join, so the restart is not seen; without durationSec the clip plays once and holds its last frame.
+export const BgVideo: React.FC<{ src: string; dim?: number; blur?: number; zoom?: number; tint?: string; loop?: boolean; playbackRate?: number; durationSec?: number; durationInFrames?: number }> = ({
+  src, dim = 0.35, blur = 0, zoom = 0.04, tint, loop = true, playbackRate = 1, durationSec, durationInFrames,
+}) => {
+  const frame = useCurrentFrame();
+  const { fps, width, durationInFrames: total } = useVideoConfig();
+  const view = plateView(frame / Math.max(1, durationInFrames ?? total), { zoom, blurPx: blur, width });
+  const url = useMedia(src);
+  const layers = videoLayers(frame, { clipFrames: durationSec ? (durationSec * fps) / playbackRate : 1, loop: loop && Boolean(durationSec) });
+  const clipFrames = Math.max(1, Math.floor(durationSec ? (durationSec * fps) / playbackRate : 1));
+  return (
+    <AbsoluteFill style={{ overflow: "hidden" }}>
+      <AbsoluteFill style={{ transform: `scale(${view.scale})`, filter: blur > 0 ? `blur(${blur}px)` : undefined }}>
+        {layers.map((l) => (
+          <Sequence key={l.index} from={l.start} durationInFrames={durationSec && loop ? clipFrames : Infinity} layout="none">
+            <AbsoluteFill style={{ opacity: l.opacity }}>
+              <OffthreadVideo src={url} muted playbackRate={playbackRate} style={{ width: "100%", height: "100%", objectFit: "cover" }} />
+            </AbsoluteFill>
+          </Sequence>
+        ))}
+      </AbsoluteFill>
+      <Finish dim={dim} tint={tint} />
+    </AbsoluteFill>
+  );
+};
+
+// One still picture as the ground. It always covers the frame: the pan and the blur never show an edge. zoom is a slow push over its time on screen
+// (default 0.06), drift a slow pan of a few percent, and fit is "cover".
+export const BgImage: React.FC<{ src: string; dim?: number; blur?: number; tint?: string; zoom?: number; drift?: Drift; fit?: "cover"; durationInFrames?: number }> = ({
+  src, dim = 0.35, blur = 0, tint, zoom = 0.06, drift = "none", durationInFrames,
+}) => {
+  const frame = useCurrentFrame();
+  const { width, durationInFrames: total } = useVideoConfig();
+  const v = plateView(frame / Math.max(1, durationInFrames ?? total), { zoom, drift, blurPx: blur, width });
+  return (
+    <AbsoluteFill style={{ overflow: "hidden" }}>
+      <Plate src={src} scale={v.scale} tx={v.tx} ty={v.ty} blurPx={blur} />
+      <Finish dim={dim} tint={tint} />
+    </AbsoluteFill>
+  );
+};
+
+// Several grounds that change smoothly over the film. items are { src, from } (frames, in order, the first visible from frame 0; a video src is drawn too, played once from the start of the film and held on its last frame).
+// The change is centred on `from` unless align is "start"; `transition` is "fade" (default), "blur" (a cross-fade through a blur peak), "wipe" (a soft-edged wipe)
+// or "zoom" (the old one pushes in while the new one settles from slightly larger), over transitionFrames (default 18). Each item keeps its own slow zoom running
+// through the change. dim, blur, tint, zoom and drift are shared, so the film keeps one look. bgPerScene builds items from the scenes.
+export const BgSequence: React.FC<{ items: SequenceItem[]; transition?: SequenceTransition; transitionFrames?: number; align?: "center" | "start"; dim?: number; blur?: number; tint?: string; zoom?: number; drift?: Drift }> = ({
+  items, transition = "fade", transitionFrames = 18, align = "center", dim = 0.35, blur = 0, tint, zoom = 0.06, drift = "none",
+}) => {
+  const frame = useCurrentFrame();
+  const { width } = useVideoConfig();
+  checkItems(items);
+  const layers = sequenceLayers(items, frame, { transition, transitionFrames, align });
+  const peak = transition === "blur" ? 24 : 0;
+  return (
+    <AbsoluteFill style={{ overflow: "hidden" }}>
+      {layers.map((l) => {
+        const v = plateView(l.progress, { zoom, drift, blurPx: blur + peak, width });
+        return <Plate key={l.index} src={items[l.index]!.src} scale={v.scale * l.scale} tx={v.tx} ty={v.ty} blurPx={blur + l.blur * peak} opacity={l.opacity} wipe={l.wipe} />;
+      })}
+      <Finish dim={dim} tint={tint} />
+    </AbsoluteFill>
+  );
+};
+
+// Three large colour fields on the base colour, in the hero colour and its two neighbours on the colour wheel, drifting and crossing: their edges and
+// where they cross show, and they move plainly within two seconds. Radial gradients and one blend mode: cheap. intensity (0 to 1, default 0.6) is how
+// strongly they light the base; Grade and Vignette on top darken a ground, so raise it (0.8) under them.
+export const BgAurora: React.FC<{ bg: string; hero: string; speed?: number; intensity?: number }> = ({ bg, hero, speed = 1, intensity }) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+  const longer = Math.max(width, height), k = groundStrength(intensity);
+  const colors = [hero, hueShift(mixHex(hero, "#ffffff", 0.12), 42), hueShift(mixHex(hero, bg, 0.1), -46)];
+  const peak = [0.95, 0.8, 0.85];
+  return (
+    <AbsoluteFill style={{ backgroundColor: bg, overflow: "hidden" }}>
+      {auroraBlobs(frame, fps, speed).map((b, i) => (
+        <div key={i} style={{
+          position: "absolute", left: b.x * width - b.r * longer, top: b.y * height - b.r * longer, width: b.r * 2 * longer, height: b.r * 2 * longer, mixBlendMode: "screen",
+          background: `radial-gradient(circle closest-side, ${withAlpha(colors[i]!, peak[i]! * k)} 0%, ${withAlpha(colors[i]!, peak[i]! * k * 0.7)} 45%, ${withAlpha(colors[i]!, peak[i]! * k * 0.22)} 80%, ${withAlpha(colors[i]!, 0)} 100%)`,
+        }} />
+      ))}
+    </AbsoluteFill>
+  );
+};
+
+// A perspective grid receding to a horizon and sliding toward the viewer, with a glow where it meets the sky. A few dozen lines in one SVG. intensity (0 to 1,
+// default 0.6) is how bright the lines and the glow are.
+export const BgGrid: React.FC<{ bg: string; hero: string; speed?: number; intensity?: number }> = ({ bg, hero, speed = 1, intensity }) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+  const horizon = height * 0.42, vx = width / 2, rows = gridRows(gridOffset(frame, fps, speed), 16), cols = 15, k = groundStrength(intensity);
+  const line = mixHex(hero, "#ffffff", 0.25);
+  return (
+    <AbsoluteFill style={{ backgroundColor: bg }}>
+      <AbsoluteFill style={{ background: `radial-gradient(ellipse 80% 28% at 50% 42%, ${withAlpha(hero, 0.8 * k)} 0%, ${withAlpha(hero, 0)} 100%)` }} />
+      <svg width={width} height={height} style={{ position: "absolute", left: 0, top: 0 }}>
+        <defs><linearGradient id="rk-grid-fade" gradientUnits="userSpaceOnUse" x1="0" y1={horizon} x2="0" y2={height}><stop offset="0" stopColor={line} stopOpacity="0" /><stop offset="0.3" stopColor={line} stopOpacity={0.55 * k} /><stop offset="1" stopColor={line} stopOpacity={Math.min(1, 1.1 * k)} /></linearGradient></defs>
+        <g stroke="url(#rk-grid-fade)" strokeWidth={Math.max(1.5, width / 420)} fill="none">
+          {rows.map((d, i) => <line key={`r${i}`} x1={0} x2={width} y1={horizon + (height - horizon) * d} y2={horizon + (height - horizon) * d} />)}
+          {Array.from({ length: cols }, (_, i) => { const x = (i / (cols - 1) - 0.5) * width * 3; return <line key={`c${i}`} x1={vx} y1={horizon} x2={vx + x} y2={height} />; })}
+        </g>
+      </svg>
+    </AbsoluteFill>
+  );
+};
+
+// Four wide diagonal beams of light sweeping across the base colour, brightening and dimming, with a glow where they leave the top. They are soft but plainly
+// there: the strongest is about as bright as the hero colour at half strength. intensity (0 to 1, default 0.6) is how bright; Grade and Vignette on top
+// darken a ground, so raise it (0.8) under them.
+export const BgBeams: React.FC<{ bg: string; hero: string; speed?: number; intensity?: number }> = ({ bg, hero, speed = 1, intensity }) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+  const k = groundStrength(intensity), light = mixHex(hero, "#ffffff", 0.2);
+  return (
+    <AbsoluteFill style={{ backgroundColor: bg, overflow: "hidden" }}>
+      <AbsoluteFill style={{ background: `radial-gradient(ellipse 90% 40% at 50% -5%, ${withAlpha(hero, 0.7 * k)} 0%, ${withAlpha(hero, 0)} 100%)` }} />
+      {beamStates(frame, fps, speed).map((b, i) => (
+        <div key={i} style={{
+          position: "absolute", left: (0.3 + b.slide) * width - width * 0.2, top: -height * 0.25, width: width * 0.4, height: height * 1.5, transform: `rotate(${b.angle}deg)`, mixBlendMode: "screen",
+          background: `linear-gradient(90deg, ${withAlpha(light, 0)} 0%, ${withAlpha(light, 0.55 * k * b.strength)} 50%, ${withAlpha(light, 0)} 100%)`,
+        }} />
+      ))}
+    </AbsoluteFill>
+  );
+};
+
+// A still ground with a breathing vignette, a soft glow of the hero colour and film grain. The grain steps every few frames by the frame number, so a
+// frame is always the same. intensity (0 to 1, default 0.6) is how strong the glow and the grain are.
+export const BgGrain: React.FC<{ bg: string; hero: string; speed?: number; intensity?: number }> = ({ bg, hero, speed = 1, intensity }) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+  const b = breath(frame, fps, speed), k = groundStrength(intensity);
+  return (
+    <AbsoluteFill style={{ backgroundColor: bg }}>
+      <AbsoluteFill style={{ background: `radial-gradient(ellipse at ${50 + 6 * Math.sin((frame / fps) * speed * 0.5)}% ${38 + 4 * b}%, ${withAlpha(hero, 0.55 * k)} 0%, ${withAlpha(hero, 0)} 62%)` }} />
+      <AbsoluteFill style={{ background: `radial-gradient(ellipse at center, rgba(0,0,0,0) 45%, rgba(0,0,0,${0.28 + 0.16 * b}) 100%)` }} />
+      <svg width={width} height={height} style={{ position: "absolute", left: 0, top: 0, opacity: 0.06 + 0.1 * k, mixBlendMode: "overlay" }}>
+        <filter id="rk-grain"><feTurbulence type="fractalNoise" baseFrequency="0.8" numOctaves="2" seed={grainSeed(frame)} stitchTiles="stitch" /><feColorMatrix type="saturate" values="0" /></filter>
+        <rect width="100%" height="100%" filter="url(#rk-grain)" />
+      </svg>
+    </AbsoluteFill>
+  );
+};

package/src/hyperframes/kit/Headline.tsx

@@ -0,0 +1,97 @@
+import React from "react";
+import { continueRender, delayRender, spring, useCurrentFrame, useVideoConfig } from "../frame";
+import { Place } from "./Place";
+import { fonts, springs } from "./theme";
+import { inkOn } from "./three-math";
+import { clamp01, headlineFrames, headlineLines, headlineWords, keywordIndex, outCubic } from "./ui-math";
+import { DEFAULT_HERO } from "./ui-theme";
+import { TextInkContext } from "./ImageLayers";
+
+// A headline set heavy: two to five words that come in one by one, with ONE keyword emphasised. `emphasis` is "color" (the keyword in the hero colour),
+// "highlight" (a block of the hero colour sweeps in behind it) or "underline" (a bar draws on under it). `keyword` must be one of the words (case and
+// punctuation ignored) or it throws and lists the words. The text breaks into the fewest lines of about 12 characters and is sized to fill `width` (a fraction
+// of the frame's width, default 0.86): it is measured after layout, so nothing leaves the frame, and at most `maxSize` (a fraction of the width, default
+// 0.2) is used. `delay` and `per` are frames from the component's own mount (0 and 4 frames a word); headlineFrames(text, { delay, per }) gives each word's
+// frame for sound. `ink` is the text colour (default white, or the ink a TextOnImage chose for its zone), `y` the height of its middle as a fraction of the frame (0.5).
+export const Headline: React.FC<{
+  text: string;
+  keyword?: string;
+  emphasis?: "color" | "highlight" | "underline";
+  hero?: string;
+  ink?: string;
+  font?: string;
+  width?: number;
+  maxSize?: number;
+  delay?: number;
+  per?: number;
+  align?: "center" | "left";
+  y?: number;
+}> = ({ text, keyword, emphasis = "color", hero = DEFAULT_HERO, ink: given, font = fonts.display, width: fraction = 0.86, maxSize = 0.2, delay = 0, per = 4, align = "center", y = 0.5 }) => {
+  const frame = useCurrentFrame();
+  const fromText = React.useContext(TextInkContext);
+  const ink = given ?? fromText ?? "#f4f4f5";
+  const { fps, width: W } = useVideoConfig();
+  const words = headlineWords(text);
+  const key = keyword === undefined ? -1 : keywordIndex(text, keyword);
+  const lines = React.useMemo(() => headlineLines(words), [text]);
+  const longest = Math.max(...lines.map((l) => l.map((i) => words[i]!).join(" ").length));
+  const target = W * fraction;
+  const estimate = Math.min(W * maxSize, target / (longest * 0.64));
+  const [fit, setFit] = React.useState(1);
+  const fitRef = React.useRef(1);
+  const refs = React.useRef<(HTMLSpanElement | null)[]>([]);
+  const [hold] = React.useState(() => delayRender("headline fit"));
+  // The estimate is corrected once the real letters are laid out (and again when the fonts have arrived, since a face that is not loaded yet measures
+  // narrower), so a face that is wider or narrower than expected still fills the width and never leaves it. The frame waits for the correction.
+  React.useLayoutEffect(() => {
+    let live = true, same = 0, tries = 0, last = -1;
+    const measure = (): number => {
+      const widest = Math.max(...refs.current.map((r) => r?.offsetWidth ?? 0));
+      if (widest > 0 && live) {
+        const next = Math.max(0.3, Math.min((W * maxSize) / estimate, target / (widest / fitRef.current)));
+        fitRef.current = next;
+        setFit(next);
+      }
+      return widest / fitRef.current;
+    };
+    // The face arrives a moment after the first layout (it is added to the page while this runs), so the width is read again until it has stopped changing.
+    const poll = () => {
+      if (!live) return;
+      const natural = Math.round(measure() * 10) / 10;
+      same = natural === last ? same + 1 : 0;
+      last = natural;
+      tries++;
+      if ((same >= 3 && (typeof document === "undefined" || document.fonts.status === "loaded")) || tries > 60) continueRender(hold); else setTimeout(poll, 40);
+    };
+    poll();
+    return () => { live = false; continueRender(hold); };
+  }, [text, font, W, fraction, maxSize, estimate]);
+  const size = estimate * fit;
+  const ev = headlineFrames(text, { delay, per });
+  return (
+    <Place y={y}>
+      <div style={{ width: target, textAlign: align, fontFamily: font, fontWeight: 800, fontSize: size, lineHeight: 1.04, letterSpacing: "-0.025em", color: ink }}>
+        {lines.map((line, li) => (
+          <div key={li} style={{ display: "flex", justifyContent: align === "center" ? "center" : "flex-start" }}>
+            <span ref={(el) => { refs.current[li] = el; }} style={{ display: "inline-flex", whiteSpace: "nowrap", gap: "0.24em" }}>
+              {line.map((wi) => {
+                const land = ev.words[wi]!;
+                const p = spring({ frame: frame - land + 6, fps, config: springs.snappy });
+                const hot = wi === key;
+                const sweep = outCubic(clamp01((frame - land - 3) / 12));
+                const wordInk = hot && emphasis === "color" ? hero : hot && emphasis === "highlight" ? inkOn(hero) : ink;
+                return (
+                  <span key={wi} style={{ position: "relative", display: "inline-block", opacity: clamp01(p * 1.6), transform: `translateY(${(1 - p) * 0.35}em)`, filter: p < 1 ? `blur(${(1 - p) * size * 0.06}px)` : undefined, color: wordInk }}>
+                    {hot && emphasis === "highlight" ? <span style={{ position: "absolute", left: "-0.1em", right: "-0.1em", top: "0.06em", bottom: "0.0em", background: hero, borderRadius: "0.12em", transformOrigin: "0 50%", transform: `scaleX(${sweep})`, zIndex: -1 }} /> : null}
+                    <span style={{ position: "relative" }}>{words[wi]}</span>
+                    {hot && emphasis === "underline" ? <span style={{ position: "absolute", left: 0, bottom: "-0.02em", height: "0.1em", width: `${sweep * 100}%`, background: hero, borderRadius: "0.1em" }} /> : null}
+                  </span>
+                );
+              })}
+            </span>
+          </div>
+        ))}
+      </div>
+    </Place>
+  );
+};

package/src/hyperframes/kit/Hero3D.tsx

@@ -0,0 +1,197 @@
+import React from "react";
+import { continueRender, delayRender, useCurrentFrame, useVideoConfig } from "../frame";
+import { useThree } from "@react-three/fiber";
+import { CanvasTexture, DoubleSide, ExtrudeGeometry, Shape, ShapeGeometry, SRGBColorSpace, TextureLoader, type BufferGeometry, type Texture } from "three";
+import { RoundedBoxGeometry } from "three/examples/jsm/geometries/RoundedBoxGeometry.js";
+import { TextGeometry } from "three/examples/jsm/geometries/TextGeometry.js";
+import { useMedia } from "./media";
+import { CameraKeysContext } from "./scene3d-context";
+import { typeface } from "./Text3D";
+import { poseAt, type PoseKey } from "./three-fx-math";
+import { degToRad, mixHex, nearestVisible, type Vec3 } from "./three-math";
+
+const roundRect = (w: number, h: number, r: number): Shape => {
+  const s = new Shape(), x = -w / 2, y = -h / 2, k = Math.min(r, w / 2, h / 2);
+  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);
+  return s;
+};
+const uvs = (g: ShapeGeometry, w: number, h: number) => { const p = g.attributes.position!, uv = g.attributes.uv!; for (let i = 0; i < p.count; i++) uv.setXY(i, (p.getX(i) + w / 2) / w, (p.getY(i) + h / 2) / h); return g; };
+
+// A soft dark ellipse for the contact shadow, drawn once.
+const shadowTex = (): CanvasTexture => {
+  const c = document.createElement("canvas");
+  c.width = c.height = 256;
+  const g = c.getContext("2d")!, r = g.createRadialGradient(128, 128, 0, 128, 128, 128);
+  r.addColorStop(0, "rgba(0,0,0,0.75)"); r.addColorStop(0.55, "rgba(0,0,0,0.3)"); r.addColorStop(1, "rgba(0,0,0,0)");
+  g.fillStyle = r; g.fillRect(0, 0, 256, 256);
+  const t = new CanvasTexture(c); t.colorSpace = SRGBColorSpace; return t;
+};
+
+// A screen face when there is no screenshot: a gradient of the hero colour and a few soft bars, so a device is never an empty slab.
+const mockTex = (hero: string, aspect: number): CanvasTexture => {
+  const W = 512, H = Math.round(512 / aspect), c = document.createElement("canvas");
+  c.width = W; c.height = H;
+  const g = c.getContext("2d")!, grad = g.createLinearGradient(0, 0, W, H);
+  grad.addColorStop(0, mixHex(hero, "#ffffff", 0.25)); grad.addColorStop(1, mixHex(hero, "#000000", 0.45));
+  g.fillStyle = grad; g.fillRect(0, 0, W, H);
+  g.fillStyle = "rgba(255,255,255,0.9)"; g.beginPath(); g.roundRect(W * 0.1, H * 0.12, W * 0.45, H * 0.04, 12); g.fill();
+  for (let i = 0; i < 5; i++) { g.fillStyle = `rgba(255,255,255,${0.2 - i * 0.02})`; g.beginPath(); g.roundRect(W * 0.1, H * (0.24 + i * 0.13), W * 0.8, H * 0.1, 18); g.fill(); }
+  const t = new CanvasTexture(c); t.colorSpace = SRGBColorSpace; return t;
+};
+
+export type HeroKind = "device" | "logo" | "box" | "coin";
+
+type Built = { geometry: BufferGeometry; glyph?: BufferGeometry; w: number; h: number; d: number; screen?: { w: number; h: number; z: number } };
+// The body of each kind, centred, in its own units, with its size.
+function build(kind: HeroKind, text: string, aspect: number): Built {
+  if (kind === "device") {
+    const w = 1, h = w / aspect, depth = 0.07, g = new ExtrudeGeometry(roundRect(w, h, 0.09 * w), { depth, bevelEnabled: true, bevelThickness: 0.018, bevelSize: 0.018, bevelSegments: 5, curveSegments: 14 });
+    g.translate(0, 0, -depth / 2);
+    return { geometry: g, w: w + 0.04, h: h + 0.04, d: depth + 0.04, screen: { w: w * 0.92, h: h * 0.94, z: depth / 2 + 0.019 } };
+  }
+  if (kind === "logo") {
+    const g = new TextGeometry(text, { font: typeface(), size: 1, depth: 0.28, curveSegments: 8, bevelEnabled: true, bevelThickness: 0.025, bevelSize: 0.02, bevelSegments: 3 });
+    g.computeBoundingBox();
+    const b = g.boundingBox!;
+    g.translate(-(b.max.x + b.min.x) / 2, -(b.max.y + b.min.y) / 2, -0.14);
+    return { geometry: g, w: b.max.x - b.min.x, h: b.max.y - b.min.y, d: 0.34 };
+  }
+  if (kind === "coin") {
+    // A true disc with a raised rim, and the first letter of `text` standing on its face.
+    const disc = new Shape();
+    disc.absarc(0, 0, 0.5, 0, Math.PI * 2, false);
+    const g = new ExtrudeGeometry(disc, { depth: 0.1, bevelEnabled: true, bevelThickness: 0.04, bevelSize: 0.03, bevelSegments: 8, curveSegments: 64 });
+    g.translate(0, 0, -0.05);
+    const glyph = new TextGeometry(text.slice(0, 1) || "R", { font: typeface(), size: 0.5, depth: 0.04, curveSegments: 8, bevelEnabled: true, bevelThickness: 0.008, bevelSize: 0.008, bevelSegments: 2 });
+    glyph.computeBoundingBox();
+    const b = glyph.boundingBox!;
+    glyph.translate(-(b.max.x + b.min.x) / 2, -(b.max.y + b.min.y) / 2, 0.095);
+    return { geometry: g, w: 1.06, h: 1.06, d: 0.2, glyph };
+  }
+  return { geometry: new RoundedBoxGeometry(1, 1, 1, 6, 0.12), w: 1, h: 1, d: 1 };
+}
+
+// The screenshot as a texture, loaded once; the frame waits for it (and for its size, which sets the screen's shape) so it is never drawn empty.
+function useScreenshot(url: string): { texture: Texture | null; aspect: number | undefined } {
+  const [state, setState] = React.useState<{ texture: Texture | null; aspect: number | undefined; url: string }>({ texture: null, aspect: undefined, url: "" });
+  const hold = React.useRef<number | undefined>(undefined);
+  const release = () => { if (hold.current !== undefined) { continueRender(hold.current); hold.current = undefined; } };
+  React.useLayoutEffect(() => {
+    if (!url) { setState({ texture: null, aspect: undefined, url: "" }); return; }
+    if (hold.current === undefined) hold.current = delayRender(`screenshot ${url.slice(0, 40)}`);
+    let live = true;
+    new TextureLoader().load(url, (t) => { t.colorSpace = SRGBColorSpace; const img = t.image as { width: number; height: number }; if (live) setState({ texture: t, aspect: img.width / Math.max(1, img.height), url }); else release(); }, undefined, () => release());
+    return () => { live = false; };
+  }, [url]);
+  // The frame is released only after the texture has been drawn into the scene: two animation frames after it arrived.
+  // While rendering, the canvas draws only when the frame changes, so a texture that arrives later has to be drawn by asking for a frame.
+  const advance = useThree((t) => t.advance);
+  React.useEffect(() => {
+    if (state.texture && state.url === url) { advance(performance.now()); release(); }
+  }, [state, url, advance]);
+  React.useEffect(() => release, []);
+  return { texture: state.texture, aspect: state.aspect };
+}
+
+const Picture: React.FC<{ texture: Texture; w: number; h: number; opacity?: number }> = ({ texture, w, h, opacity = 1 }) => {
+  const g = React.useMemo(() => uvs(new ShapeGeometry(roundRect(w, h, 0.05), 12), w, h), [w, h]);
+  return <mesh geometry={g}><meshBasicMaterial map={texture} toneMapped={false} transparent={opacity < 1} opacity={opacity} /></mesh>;
+};
+
+// A studio-lit hero: one object, lit like a product shot. `kind` is "device" (a rounded slab with a screen that shows `src`, a screenshot; without it a designed
+// screen), "logo" (`text`, a short word or a single letter, extruded in the kit's typeface), "box" or "coin". Physical material with a clearcoat in `hero`, a key light
+// and two coloured rim lights (`rim1`, `rim2`, by default the hero colour turned toward blue and toward pink). `floor` is "soft" (a contact shadow, default), "mirror"
+// (a flipped, faded copy below) or "none". `spin` is how many degrees a second it turns about the vertical (12 for a logo, box or coin; a device sways by that many
+// degrees instead) and `hover` how much it bobs, 0 to 1 (0.5). It fits the frame by default (`fit`, 0.7, at the closest the camera comes). `poses` are keys {
+// frame, rotation (degrees), position, scale} that re-pose it, the same timing as Camera: one hero carried across scenes. `aspect` is a device's width over height
+// (the screenshot's own when `src` is given, else 0.5).
+export const Hero3D: React.FC<{
+  kind?: HeroKind;
+  src?: string;
+  text?: string;
+  hero?: string;
+  rim1?: string;
+  rim2?: string;
+  floor?: "soft" | "mirror" | "none";
+  spin?: number;
+  hover?: number;
+  fit?: number;
+  aspect?: number;
+  poses?: PoseKey[];
+  lights?: boolean;
+  position?: Vec3;
+}> = ({ kind = "box", src, text = "R", hero = "#7C3AED", rim1, rim2, floor = "soft", spin, hover = 0.5, fit = 0.7, aspect, poses, lights = true, position = [0, 0, 0] }) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+  const keys = React.useContext(CameraKeysContext);
+  const url = useMedia(src ?? "");
+  const shot = useScreenshot(src ? url : "");
+  const natural = shot.aspect;
+  const ratio = aspect ?? natural ?? 0.5;
+  const built = React.useMemo(() => build(kind, text.slice(0, 10), ratio), [kind, text, ratio]);
+  React.useEffect(() => () => built.geometry.dispose(), [built]);
+  const view = nearestVisible(keys, width / height, position[2]);
+  // Fit with room for the turn: a thing that spins is as wide as its width and its depth.
+  const reach = Math.max(built.w, kind === "device" ? built.w : built.d * 0.6 + built.w * 0.6);
+  const base = Math.min((fit * view.width) / reach, (fit * view.height) / built.h);
+  const pose = poseAt(poses, frame, fps);
+  const t = frame / fps;
+  const turn = spin ?? (kind === "device" ? 8 : 12);
+  const yaw = kind === "device" ? Math.sin(t * 0.9) * turn : t * turn;
+  const bob = Math.sin(t * 1.7) * 0.035 * hover * base * built.h;
+  const r1 = rim1 ?? mixHex(hero, "#2a6bff", 0.55), r2 = rim2 ?? mixHex(hero, "#ff3aa8", 0.55);
+  const shadow = React.useMemo(shadowTex, []);
+  const mock = React.useMemo(() => (kind === "device" && !src ? mockTex(hero, ratio) : undefined), [kind, src, hero, ratio]);
+  const metal = kind === "coin" ? 0.85 : kind === "logo" ? 0.35 : 0.2;
+  const body = (opacity: number) => (
+    <group>
+      <mesh geometry={built.geometry}>
+        <meshPhysicalMaterial color={kind === "device" ? mixHex(hero, "#101018", 0.8) : hero} roughness={kind === "coin" ? 0.28 : 0.34} metalness={metal} clearcoat={1} clearcoatRoughness={0.12} transparent={opacity < 1} opacity={opacity} />
+      </mesh>
+      {built.glyph ? (
+        <mesh geometry={built.glyph}>
+          <meshPhysicalMaterial color={mixHex(hero, "#ffffff", 0.45)} roughness={0.25} metalness={0.9} clearcoat={1} clearcoatRoughness={0.1} transparent={opacity < 1} opacity={opacity} />
+        </mesh>
+      ) : null}
+      {kind === "device" && built.screen ? (
+        <group position={[0, 0, built.screen.z]}>
+          {src ? (shot.texture ? <Picture texture={shot.texture} w={built.screen.w} h={built.screen.h} opacity={opacity} /> : null) : mock ? <mesh geometry={uvs(new ShapeGeometry(roundRect(built.screen.w, built.screen.h, 0.05), 12), built.screen.w, built.screen.h)}><meshBasicMaterial map={mock} toneMapped={false} transparent={opacity < 1} opacity={opacity} /></mesh> : null}
+          {/* The sheen: a pale band that crosses the glass once, early, and stays inside it. */}
+          <mesh position={[(Math.min(1, Math.max(0, (frame - 10) / 40)) - 0.5) * built.screen.w * 0.9, 0, 0.002]} scale={[built.screen.w * 0.16, built.screen.h * 0.98, 1]}>
+            <planeGeometry args={[1, 1]} />
+            <meshBasicMaterial color="#ffffff" transparent opacity={0.14 * opacity * (frame < 10 || frame > 50 ? 0 : Math.sin(Math.PI * ((frame - 10) / 40)))} depthWrite={false} side={DoubleSide} />
+          </mesh>
+        </group>
+      ) : null}
+    </group>
+  );
+  const floorY = -(built.h / 2) * base - 0.06 * base;
+  return (
+    <group position={[position[0] + pose.position[0], position[1] + pose.position[1] + bob, position[2] + pose.position[2]]} scale={pose.scale}>
+      {lights ? (
+        <>
+          <directionalLight position={[3, 5, 6]} intensity={2.2} />
+          <pointLight position={[-3.5, 1, -3]} color={r1} intensity={55} distance={14} />
+          <pointLight position={[3.5, 1.5, -3]} color={r2} intensity={55} distance={14} />
+        </>
+      ) : null}
+      <group rotation={[degToRad(pose.rotation[0]), degToRad(pose.rotation[1] + yaw), degToRad(pose.rotation[2])]} scale={base}>{body(1)}</group>
+      {floor === "soft" ? (
+        <mesh position={[0, floorY, 0]} rotation={[-Math.PI / 2, 0, 0]} scale={[base * built.w * 1.8, base * Math.max(built.d, built.w * 0.5) * 1.6, 1]}>
+          <planeGeometry args={[1, 1]} />
+          <meshBasicMaterial map={shadow} transparent depthWrite={false} toneMapped={false} />
+        </mesh>
+      ) : null}
+      {floor === "mirror" ? (
+        <group position={[0, floorY * 2 - 0.0, 0]} scale={[1, -1, 1]}>
+          <group rotation={[degToRad(pose.rotation[0]), degToRad(pose.rotation[1] + yaw), degToRad(pose.rotation[2])]} scale={base}>{body(0.2)}</group>
+        </group>
+      ) : null}
+    </group>
+  );
+};
+
+// A tilted screen in 3D carrying a screenshot (`src`) or a designed mock, with a bezel, a shadow and a sheen: the interface carried across scenes. It is Hero3D kind="device"
+// with no spin (a gentle sway of 5 degrees), so give it `poses` to re-pose the one screen at each scene. Same props as Hero3D otherwise.
+export const Screen3D: React.FC<Omit<React.ComponentProps<typeof Hero3D>, "kind" | "text">> = (props) => <Hero3D kind="device" spin={5} {...props} />;