reelkit-cli 0.6.0 → 0.10.0

package/src/hyperframes/kit/ui-math.ts

@@ -0,0 +1,145 @@
+// The arithmetic behind the product-surface components, with no React in it. Every component's timing props are frames counted from the component's own
+// mount: the frame useCurrentFrame() gives where the component stands (inside a SceneFrame, the scene's own frame; inside a Sequence, the sequence's).
+// Each component has a companion function here that takes the SAME props and returns the frames of its events, in that same clock, so a sound can be
+// placed on them: add the scene's startFrame (or pass it as `offset` to cuesFor) to make them absolute.
+import { measureSpring } from "../frame";
+
+export const clamp01 = (n: number) => (n > 0 ? (n < 1 ? n : 1) : 0);
+export const outCubic = (t: number) => 1 - (1 - clamp01(t)) ** 3;
+export const inOutCubic = (t: number) => { const x = clamp01(t); return x < 0.5 ? 4 * x * x * x : 1 - (-2 * x + 2) ** 3 / 2; };
+
+// The frame at which each character of `text` appears when typed at `cps` characters a second from frame `start`: the first at `start`. Length is text.length.
+export function typedFrames(text: string, cps: number, fps: number, start = 0): number[] {
+  const step = fps / Math.max(0.1, cps);
+  return Array.from({ length: [...text].length }, (_, i) => start + Math.floor(i * step));
+}
+// How many characters are showing at `frame`.
+export function typedCount(frame: number, text: string, cps: number, fps: number, start = 0): number {
+  const f = typedFrames(text, cps, fps, start);
+  let n = 0;
+  while (n < f.length && f[n]! <= frame) n++;
+  return n;
+}
+
+export type PromptTiming = { text: string; cps?: number; delay?: number; reply?: string; replyCps?: number; sendPause?: number; replyDelay?: number };
+export type PromptEvents = { type: number[]; typedEnd: number; send: number; replyStart: number; reply: number[]; end: number };
+export const PROMPT_DEFAULTS = { cps: 22, delay: 6, replyCps: 70, sendPause: 9, replyDelay: 12 } as const;
+// The events of a PromptBox, from the same props: the frame of every typed character, the frame typing is over, the frame the send button presses, the frame
+// the reply starts and the frame of each of its characters, and the last frame of it all.
+export function promptFrames(p: PromptTiming, fps: number): PromptEvents {
+  const cps = p.cps ?? PROMPT_DEFAULTS.cps, delay = p.delay ?? PROMPT_DEFAULTS.delay;
+  const type = typedFrames(p.text, cps, fps, delay);
+  const typedEnd = (type[type.length - 1] ?? delay) + 1;
+  const send = typedEnd + (p.sendPause ?? PROMPT_DEFAULTS.sendPause);
+  const replyStart = send + (p.replyDelay ?? PROMPT_DEFAULTS.replyDelay);
+  const reply = p.reply ? typedFrames(p.reply, p.replyCps ?? PROMPT_DEFAULTS.replyCps, fps, replyStart) : [];
+  return { type, typedEnd, send, replyStart, reply, end: Math.max(send + 8, (reply[reply.length - 1] ?? 0) + 1) };
+}
+
+export type LineKind = "cmd" | "out" | "ok" | "warn" | "edit";
+export type TerminalLine = { kind: LineKind; text: string; add?: number; del?: number; wait?: number };
+// The frame each line of a TerminalLog appears: `rate` lines a second (default 3) from `delay` (default 6); a line's `wait` adds frames before it.
+export function lineFrames(lines: readonly TerminalLine[], rate = 3, fps = 30, delay = 6): number[] {
+  const step = fps / Math.max(0.1, rate);
+  let t = delay;
+  return lines.map((l, i) => { t += (i === 0 ? 0 : step) + (l.wait ?? 0); return Math.round(t); });
+}
+export type TerminalTiming = { lines: readonly TerminalLine[]; rate?: number; delay?: number; checklist?: readonly string[]; checkEvery?: number };
+// The events of a TerminalLog: each line's frame, each checklist item's frame (the strike-through, one every `checkEvery` frames, default 16, starting a beat
+// after the last line), and the frame the work is done.
+export function terminalFrames(p: TerminalTiming, fps: number): { lines: number[]; checks: number[]; done: number } {
+  const lines = lineFrames(p.lines, p.rate, fps, p.delay);
+  const first = (lines[lines.length - 1] ?? p.delay ?? 6) + 6, every = p.checkEvery ?? 16;
+  const checks = (p.checklist ?? []).map((_, i) => first + i * every);
+  return { lines, checks, done: Math.max(lines[lines.length - 1] ?? 0, checks[checks.length - 1] ?? 0) + 10 };
+}
+// "m:ss" for `seconds`.
+export const clock = (seconds: number): string => `${Math.floor(Math.max(0, seconds) / 60)}:${String(Math.floor(Math.max(0, seconds) % 60)).padStart(2, "0")}`;
+
+export type CursorPoint = { x: number; y: number; click?: boolean; hold?: number };
+export const CURSOR_MOVE_FRAMES = 22;
+// The frame the cursor reaches each point: the first at `delay` (default 4), then `moveFrames` (default 22) after leaving the one before, which it does
+// after `hold` frames (default 10 on a click, 5 otherwise).
+export function cursorArrivals(points: readonly CursorPoint[], o: { delay?: number; moveFrames?: number } = {}): number[] {
+  const move = o.moveFrames ?? CURSOR_MOVE_FRAMES;
+  let t = o.delay ?? 4;
+  return points.map((p, i) => { if (i > 0) t += (points[i - 1]!.hold ?? (points[i - 1]!.click ? 10 : 5)) + move; return t; });
+}
+// The frame of each click: 3 frames after the cursor reaches a point marked `click`.
+export function clickFrames(points: readonly CursorPoint[], o: { delay?: number; moveFrames?: number } = {}): number[] {
+  const at = cursorArrivals(points, o);
+  return points.flatMap((p, i) => (p.click ? [at[i]! + 3] : []));
+}
+// Where the cursor is at `frame`, as fractions of the frame: it travels each leg on an ease with a gentle arc, never a straight line, and rests on the points.
+export function cursorAt(points: readonly CursorPoint[], frame: number, o: { delay?: number; moveFrames?: number } = {}): { x: number; y: number } {
+  const at = cursorArrivals(points, o), move = o.moveFrames ?? CURSOR_MOVE_FRAMES;
+  if (points.length === 0) return { x: 0.5, y: 0.5 };
+  for (let i = points.length - 1; i > 0; i--) {
+    if (frame < at[i]! - move) continue;
+    const a = points[i - 1]!, b = points[i]!, t = inOutCubic((frame - (at[i]! - move)) / move);
+    const dx = b.x - a.x, dy = b.y - a.y, bend = 0.14 * (i % 2 ? 1 : -1);
+    const cx = (a.x + b.x) / 2 - dy * bend, cy = (a.y + b.y) / 2 + dx * bend;
+    return { x: (1 - t) ** 2 * a.x + 2 * (1 - t) * t * cx + t * t * b.x, y: (1 - t) ** 2 * a.y + 2 * (1 - t) * t * cy + t * t * b.y };
+  }
+  return { x: points[0]!.x, y: points[0]!.y };
+}
+
+// The frame at which a spring of the given kind has settled (within 1% of its end): the frame a panel or a badge is seen to land.
+export const settledAfter = (config: { stiffness: number; damping: number }, fps: number): number => measureSpring({ fps, config, threshold: 0.01 });
+export const PANEL_SPRING = { stiffness: 170, damping: 19 };
+// The frame a GlassPanel has settled, from its `delay` (default 0).
+export const panelSettleFrame = (delay = 0, fps = 30): number => delay + settledAfter(PANEL_SPRING, fps);
+
+export type ChapterTiming = { delay?: number; badges?: number };
+// The events of a ChapterFrame: the frame each badge pops (the first 14 frames in, then 6 apart) and the frame the progress rule has filled.
+export function chapterFrames(p: ChapterTiming = {}): { badges: number[]; progressDone: number } {
+  const d = p.delay ?? 0;
+  return { badges: Array.from({ length: Math.min(3, p.badges ?? 0) }, (_, i) => d + 14 + i * 6), progressDone: d + 24 };
+}
+
+export const headlineWords = (text: string): string[] => text.trim().split(/\s+/).filter(Boolean);
+const bare = (w: string) => w.replace(/[^\p{L}\p{N}]/gu, "").toLowerCase();
+// The index of `keyword` among the words of `text`, ignoring case and punctuation; throws, listing the words, when it is not one of them.
+export function keywordIndex(text: string, keyword: string): number {
+  const words = headlineWords(text), i = words.findIndex((w) => bare(w) === bare(keyword));
+  if (i < 0) throw new Error(`Headline: the keyword "${keyword}" is not one of the words of "${text}". The words are: ${words.join(", ")}.`);
+  return i;
+}
+// The events of a Headline: the frame each word lands (`per` frames apart, 4 unless set, from `delay`) and the frame its emphasis finishes.
+export function headlineFrames(text: string, o: { delay?: number; per?: number } = {}): { words: number[]; emphasisDone: number } {
+  const n = headlineWords(text).length, d = o.delay ?? 0, per = o.per ?? 4;
+  const words = Array.from({ length: n }, (_, i) => d + i * per + 6);
+  return { words, emphasisDone: (words[n - 1] ?? d) + 14 };
+}
+// Splits the words into the fewest lines that keep the longest near `maxChars`, in order, and returns the lines' word indices.
+export function headlineLines(words: readonly string[], maxChars = 12): number[][] {
+  const lines: number[][] = [[]];
+  let len = 0;
+  words.forEach((w, i) => {
+    const cur = lines[lines.length - 1]!;
+    if (cur.length && len + 1 + w.length > maxChars) { lines.push([i]); len = w.length; } else { cur.push(i); len += (cur.length > 1 ? 1 : 0) + w.length; }
+  });
+  return lines;
+}
+
+// The value of a CounterRoll at `frame`: it eases out over `frames` frames from `delay` and holds `to`.
+export function rollValue(frame: number, o: { from?: number; to: number; frames?: number; delay?: number }): number {
+  const from = o.from ?? 0, t = (frame - (o.delay ?? 0)) / Math.max(1, o.frames ?? 45);
+  return from + (o.to - from) * (1 - (1 - clamp01(t)) ** 4);
+}
+// The frame a CounterRoll lands on its number (`delay` + `frames`, defaults 0 and 45): put the settle chime here.
+export const settleFrame = (o: { delay?: number; frames?: number } = {}): number => (o.delay ?? 0) + (o.frames ?? 45);
+// The frame of the last tick of the roll: it starts at `delay`.
+export const rollStart = (o: { delay?: number } = {}): number => o.delay ?? 0;
+
+// A timecode "mm:ss:ff" of `frame`.
+export const timecode = (frame: number, fps: number): string => {
+  const s = Math.floor(frame / fps);
+  return `${String(Math.floor(s / 60)).padStart(2, "0")}:${String(s % 60).padStart(2, "0")}:${String(Math.floor(frame % fps)).padStart(2, "0")}`;
+};
+
+// The frames of a BrowserFrame: the frame it has settled, and the frames the sheen starts and ends.
+export function browserFrames(o: { delay?: number; fps?: number } = {}): { settled: number; sheenStart: number; sheenEnd: number } {
+  const d = o.delay ?? 0;
+  return { settled: d + settledAfter(PANEL_SPRING, o.fps ?? 30), sheenStart: d + 18, sheenEnd: d + 44 };
+}

package/src/hyperframes/kit/ui-theme.ts

@@ -0,0 +1,25 @@
+import { inkOn, luminance, mixHex } from "./three-math";
+
+// What the product-surface components (PromptBox, TerminalLog, GlassPanel, ...) share: the three looks, the colours each one gives, and the helpers that
+// say where a component sits. Nothing here needs React.
+export type UiTheme = "light" | "dark" | "glass";
+export const DEFAULT_HERO = "#7C3AED";
+
+// "light" on a light ground and "dark" on a dark one: the theme a component should take when its ground is `bg`.
+export const themeFor = (bg: string): UiTheme => (luminance(bg) > 0.5 ? "light" : "dark");
+
+export type UiColors = { panel: string; stroke: string; ink: string; dim: string; field: string; chip: string; shadow: string; heroInk: string; ok: string; warn: string; bad: string };
+
+// One set of colours per theme. `glass` is the dark slab with a lit hairline: it is meant to sit over a coloured glow and is a little see-through.
+export function uiColors(theme: UiTheme, hero: string): UiColors {
+  const heroInk = inkOn(hero);
+  if (theme === "light") return { panel: "#ffffff", stroke: "rgba(20,20,30,0.12)", ink: "#16161d", dim: "#6b6b78", field: "#f1f1f5", chip: "#e9e9f0", shadow: "rgba(20,20,40,0.22)", heroInk, ok: "#16a34a", warn: "#d97706", bad: "#dc2626" };
+  if (theme === "glass") return { panel: "rgba(14,14,22,0.62)", stroke: "rgba(255,255,255,0.20)", ink: "#f4f4f5", dim: "#a8a8b6", field: "rgba(255,255,255,0.07)", chip: "rgba(255,255,255,0.12)", shadow: "rgba(0,0,0,0.5)", heroInk, ok: "#4ade80", warn: "#fbbf24", bad: "#f87171" };
+  return { panel: "#121219", stroke: "rgba(255,255,255,0.10)", ink: "#f4f4f5", dim: "#9a9aa6", field: "#1b1b26", chip: "#262634", shadow: "rgba(0,0,0,0.55)", heroInk, ok: "#4ade80", warn: "#fbbf24", bad: "#f87171" };
+}
+
+export const rgba = (hex: string, a: number): string => {
+  const m = /^#?([0-9a-f]{6})$/i.exec(mixHex(hex, hex, 0));
+  const n = parseInt(m ? m[1]! : "000000", 16);
+  return `rgba(${(n >> 16) & 255},${(n >> 8) & 255},${n & 255},${a})`;
+};

package/src/hyperframes/kit/word-anchor.ts

@@ -0,0 +1,107 @@
+// Word anchors: where in the film a spoken word falls, so that what illustrates a word can be placed on it.
+// Everything here is a pure function over a manifest scene (`manifest.scenes[i]`, with its `words`), so it is the same in the studio, in a test and in a render.
+// Frames are counted from the start of the scene (what its own useCurrentFrame() gives) unless `absolute: true` adds the scene's startFrame.
+import type { WordTiming } from "../../pipeline/schema";
+
+// The manifest's frame rate is always this one; pass `fps` only for a scene that came from somewhere else.
+export const WORD_FPS = 30;
+// An entrance needs a few frames to become visible, so it starts this many frames before its word.
+export const DEFAULT_LEAD = 3;
+// A beat counts as "at the word" when it is no more than this many frames from the word's start.
+export const DEFAULT_BEAT_WINDOW = 3;
+// The thing a word names is never seen more than this many frames before the word starts.
+export const MAX_EARLY_FRAMES = 3;
+
+export type WordScene = { id?: string; startFrame: number; durationFrames?: number; words: WordTiming[] };
+
+export type WordFrameOptions = {
+  // The 1-based occurrence of the word when the scene says it more than once (default 1).
+  nth?: number;
+  // "start" (default): the frame the word starts. "end": the frame it ends (for a phrase, the end of its last word).
+  edge?: "start" | "end";
+  // Add the scene's startFrame, giving a frame of the whole film.
+  absolute?: boolean;
+  fps?: number;
+};
+
+// A word as it is compared: lower case, with everything but letters and digits removed ("Meetings," is "meetings", "don't" is "dont").
+export const normalizeWord = (w: string): string => w.toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+
+const spoken = (scene: WordScene): { norm: string; word: WordTiming }[] =>
+  scene.words.map((word) => ({ norm: normalizeWord(word.word), word })).filter((w) => w.norm !== "");
+
+// The words that make up `phrase`, matched against the scene's words, with where the phrase's `nth` occurrence is.
+function findPhrase(scene: WordScene, phrase: string, nth: number): { first: WordTiming; last: WordTiming } {
+  const parts = phrase.split(/\s+/).map(normalizeWord).filter(Boolean);
+  const list = spoken(scene);
+  const where = scene.id ? `scene "${scene.id}"` : "the scene";
+  if (!parts.length) throw new Error(`wordFrame: the word is empty. ${where} says: ${list.map((w) => w.word.word).join(" ")}`);
+  if (!Number.isInteger(nth) || nth < 1) throw new Error(`wordFrame: nth must be 1 or more, got ${nth}.`);
+  let seen = 0;
+  for (let i = 0; i + parts.length <= list.length; i++) {
+    if (parts.every((p, k) => list[i + k]!.norm === p) && ++seen === nth) return { first: list[i]!.word, last: list[i + parts.length - 1]!.word };
+  }
+  const had = seen ? ` (it is said ${seen} time${seen === 1 ? "" : "s"}, not ${nth})` : "";
+  throw new Error(`wordFrame: "${phrase}"${nth > 1 ? ` (occurrence ${nth})` : ""} is not in ${where}${had}. Its words are: ${list.map((w) => w.word.word).join(" ")}`);
+}
+
+// The frame, inside the scene, at which `word` starts (or ends, with edge: "end"). `word` ignores case and punctuation; a phrase of several words
+// ("whole week") matches consecutive words and gives the first one's start. A word the scene does not say throws an Error that lists the scene's
+// words, so a misspelt word stops the render instead of silently timing to frame 0.
+export function wordFrame(scene: WordScene, word: string, opts: WordFrameOptions = {}): number {
+  const { first, last } = findPhrase(scene, word, opts.nth ?? 1);
+  const fps = opts.fps ?? WORD_FPS;
+  const sec = opts.edge === "end" ? last.endSec : first.startSec;
+  let frame = Math.max(0, Math.round(sec * fps));
+  if (scene.durationFrames !== undefined) frame = Math.min(frame, Math.max(0, scene.durationFrames - 1));
+  return frame + (opts.absolute ? scene.startFrame : 0);
+}
+
+// Several words at once, in the order given.
+export const wordFrames = (scene: WordScene, words: string[], opts: WordFrameOptions = {}): number[] => words.map((w) => wordFrame(scene, w, opts));
+
+// The scene with this id. Throws an Error that lists the ids when there is none.
+export function sceneById<S extends { id: string }>(manifest: { scenes: S[] }, id: string): S {
+  const found = manifest.scenes.find((s) => s.id === id);
+  if (!found) throw new Error(`sceneById: there is no scene "${id}". The scenes are: ${manifest.scenes.map((s) => s.id).join(", ")}`);
+  return found;
+}
+
+export type OnWordOptions = WordFrameOptions & {
+  // How many frames before the word the entrance starts (default 3).
+  lead?: number;
+};
+
+// The frame at which to START an entrance (a `delay`, a `from`, an `at`) so that it is seen landing on its word: the word's frame minus `lead`
+// (default 3), never below 0.
+export function onWord(scene: WordScene, word: string, opts: OnWordOptions = {}): number {
+  const lead = opts.lead ?? DEFAULT_LEAD;
+  const at = wordFrame(scene, word, { ...opts, absolute: false });
+  return Math.max(0, at - lead) + (opts.absolute ? scene.startFrame : 0);
+}
+
+export type OnWordBeatOptions = OnWordOptions & {
+  // A beat counts only when it is at most this many frames from the word's start (default 3).
+  window?: number;
+};
+
+// Beat and word together. The voice is the clock for what illustrates a word, so the word wins; the beat is used only when one lies within `window`
+// frames of the word (default 3), and then only to let the entrance land on it. The result is never earlier than onWord's, so what a word names
+// is never seen more than 3 frames before the word starts. `music` is manifest.music (its beatFrames are frames of the whole film); without a
+// track it is onWord.
+export function onWordBeat(scene: WordScene, word: string, music: { beatFrames: number[] } | undefined, opts: OnWordBeatOptions = {}): number {
+  const lead = opts.lead ?? DEFAULT_LEAD;
+  const window = opts.window ?? DEFAULT_BEAT_WINDOW;
+  const at = wordFrame(scene, word, { ...opts, absolute: false });
+  const wordAbs = scene.startFrame + at;
+  const base = Math.max(0, at - lead);
+  let start = base;
+  let best: number | undefined;
+  for (const b of music?.beatFrames ?? []) {
+    // A beat before the word is never used: it would show the thing early.
+    if (b < wordAbs || b - wordAbs > window) continue;
+    if (best === undefined || b - wordAbs < best - wordAbs) best = b;
+  }
+  if (best !== undefined) start = Math.max(base, best - scene.startFrame - lead);
+  return start + (opts.absolute ? scene.startFrame : 0);
+}

package/src/hyperframes/math.ts

@@ -0,0 +1,62 @@
+// Seekable animation math. These functions have no browser or React dependency.
+export type SpringConfig = { damping?: number; stiffness?: number; mass?: number; overshootClamping?: boolean };
+export function spring({ frame, fps, config = {}, from = 0, to = 1, delay = 0, durationInFrames, durationRestThreshold = 0.005, reverse = false }: { frame: number; fps: number; config?: SpringConfig; from?: number; to?: number; delay?: number; durationInFrames?: number; durationRestThreshold?: number; reverse?: boolean }): number {
+  const length = durationInFrames ?? measureSpring({ fps, config, threshold: durationRestThreshold });
+  let f = frame - delay;
+  if (reverse) f = length - f;
+  if (f <= 0) return from;
+  if (durationInFrames && f >= durationInFrames) return to;
+  const t = f / fps * (durationInFrames ? measureSpring({ fps, config, threshold: durationRestThreshold }) / durationInFrames : 1);
+  const m = config.mass ?? 1, k = config.stiffness ?? 100, c = config.damping ?? 10;
+  const w = Math.sqrt(k / m), z = c / (2 * Math.sqrt(k * m));
+  let p: number;
+  if (z < 1) { const wd = w * Math.sqrt(1 - z * z); p = 1 - Math.exp(-z * w * t) * (Math.cos(wd * t) + z * w / wd * Math.sin(wd * t)); }
+  else if (z === 1) p = 1 - (1 + w * t) * Math.exp(-w * t);
+  else { const r = Math.sqrt(z * z - 1), a = -w * (z - r), b = -w * (z + r); p = 1 - (b * Math.exp(a * t) - a * Math.exp(b * t)) / (b - a); }
+  return from + (to - from) * (config.overshootClamping ? Math.min(1, p) : p);
+}
+export function measureSpring({ fps, config = {}, threshold = 0.005 }: { fps: number; config?: SpringConfig; threshold?: number }): number {
+  const m = config.mass ?? 1, k = config.stiffness ?? 100, c = config.damping ?? 10;
+  const w = Math.sqrt(k / m), z = c / (2 * Math.sqrt(k * m));
+  // Require a full second inside the rest band so an oscillation's zero crossing cannot end the spring.
+  let last = 0;
+  for (let f = 0; f < fps * 60; f++) {
+    const t = f / fps;
+    let error: number;
+    if (z < 1) { const wd = w * Math.sqrt(1 - z * z); error = Math.exp(-z * w * t) * (Math.cos(wd * t) + z * w / wd * Math.sin(wd * t)); }
+    else if (z === 1) error = (1 + w * t) * Math.exp(-w * t);
+    else { const r = Math.sqrt(z * z - 1), a = -w * (z - r), b = -w * (z + r); error = (b * Math.exp(a * t) - a * Math.exp(b * t)) / (b - a); }
+    if (Math.abs(error) > threshold) last = f;
+    if (f - last >= fps) return last + 1;
+  }
+  throw new Error("Spring did not settle within 60 seconds.");
+}
+type Extrapolate = "extend" | "clamp" | "identity" | "wrap";
+export function interpolate(value: number, input: readonly number[], output: readonly number[], options: { easing?: (t: number) => number; extrapolateLeft?: Extrapolate; extrapolateRight?: Extrapolate } = {}): number {
+  if (input.length !== output.length || input.length < 2 || input.some((n, i) => i > 0 && n <= input[i - 1]!)) throw new Error("Interpolation ranges must have equal length and increasing input values.");
+  const lo = input[0]!, hi = input[input.length - 1]!;
+  if (value < lo || value > hi) { const mode = value < lo ? options.extrapolateLeft : options.extrapolateRight; if (mode === "identity") return value; if (mode === "clamp") value = Math.min(hi, Math.max(lo, value)); if (mode === "wrap") value = lo + ((value - lo) % (hi - lo) + hi - lo) % (hi - lo); }
+  let i = 0; while (i < input.length - 2 && value > input[i + 1]!) i++;
+  const t = (value - input[i]!) / (input[i + 1]! - input[i]!);
+  return output[i]! + (output[i + 1]! - output[i]!) * (options.easing ?? Easing.linear)(t);
+}
+export const Easing = {
+  linear: (t: number) => t, quad: (t: number) => t * t, cubic: (t: number) => t ** 3,
+  sin: (t: number) => 1 - Math.cos(t * Math.PI / 2), exp: (t: number) => t === 0 ? 0 : 2 ** (10 * (t - 1)),
+  in: (fn: (t: number) => number) => fn,
+  out: (fn: (t: number) => number) => (t: number) => 1 - fn(1 - t),
+  inOut: (fn: (t: number) => number) => (t: number) => t < 0.5 ? fn(t * 2) / 2 : 1 - fn((1 - t) * 2) / 2,
+  bezier: (x1: number, y1: number, x2: number, y2: number) => (t: number) => {
+    if (t <= 0 || t >= 1) return t;
+    const curve = (u: number, a: number, b: number) => 3 * (1 - u) ** 2 * u * a + 3 * (1 - u) * u * u * b + u ** 3;
+    let lo = 0, hi = 1;
+    for (let i = 0; i < 40; i++) { const u = (lo + hi) / 2; if (curve(u, x1, x2) < t) lo = u; else hi = u; }
+    return curve((lo + hi) / 2, y1, y2);
+  },
+};
+export function random(seed: string | number): number {
+  let h = 2166136261;
+  for (const c of String(seed)) h = Math.imul(h ^ c.charCodeAt(0), 16777619);
+  h ^= h >>> 16; h = Math.imul(h, 0x7feb352d); h ^= h >>> 15; h = Math.imul(h, 0x846ca68b);
+  return ((h ^ h >>> 16) >>> 0) / 4294967296;
+}

package/src/hyperframes/three.tsx

@@ -0,0 +1,10 @@
+import React from "react";
+import { Canvas, useThree, type CanvasProps } from "@react-three/fiber";
+import { FrameContext, useCurrentFrame, delayRender, continueRender } from "./frame";
+const Draw: React.FC = () => { const f = useCurrentFrame(), s = useThree(); React.useLayoutEffect(() => { s.invalidate(); }, [f, s]); return null; };
+export const ThreeCanvas: React.FC<CanvasProps & { width: number; height: number }> = ({ width, height, children, style, ...props }) => {
+  const state = React.useContext(FrameContext);
+  const [handle] = React.useState(() => delayRender("3D canvas"));
+  React.useEffect(() => () => continueRender(handle), [handle]);
+  return <Canvas {...props} onCreated={() => continueRender(handle)} frameloop="demand" gl={{ preserveDrawingBuffer: true, alpha: true }} style={{ width, height, ...style }}><FrameContext.Provider value={state}>{children}<Draw /></FrameContext.Provider></Canvas>;
+};

package/src/pipeline/beatsnap.ts

@@ -12,6 +12,9 @@ export type SnapInput = {
   // Beats as frame numbers, ascending. They should reach past the end of the video.
   beatFrames: number[];
   fps: number;
+  // "next" holds a scene to the next whole beat (narration cannot be cut). "nearest" moves each end to the closest point on a finer grid
+  // (a film with no voice can be shortened as well as lengthened, so its total stays near the plan).
+  grid?: "next" | "nearest";
 };
 
 const firstAtOrAfter = (beats: number[], frame: number): number | undefined => beats.find((b) => b >= frame);
@@ -21,6 +24,7 @@ const firstAtOrAfter = (beats: number[], frame: number): number | undefined => b
 export function snapToBeats(input: SnapInput): number[] {
   const { naturalFrames, beatFrames, fps } = input;
   if (beatFrames.length < 2) return [...naturalFrames];
+  if (input.grid === "nearest") return snapToNearest(naturalFrames, beatFrames);
   const gaps = beatFrames.slice(1).map((b, i) => b - beatFrames[i]!).sort((a, b) => a - b);
   const period = Math.max(1, gaps[Math.floor(gaps.length / 2)]!);
   let cursor = 0;
@@ -40,6 +44,74 @@ export function snapToBeats(input: SnapInput): number[] {
   });
 }
 
+// How far a scene change of a narrated film may move to reach a beat, in frames, either way.
+export const NARRATED_SNAP_FRAMES = 4;
+// A boundary never comes closer than this to the last word of the scene it ends, in frames.
+export const NARRATED_WORD_CLEARANCE = 2;
+
+// Scene changes for a narrated film. The voice sets where a scene ends; a boundary is moved to the nearest beat only when that is at most
+// `maxMove` frames away either way and leaves at least `clearance` frames after the scene's last word (a boundary never cuts into a word). The
+// next scene's audio starts on its first frame, so it moves with the boundary. Every other boundary stays where the narration puts it, and the
+// last scene is not touched: the film's end is not a scene change. Each boundary is judged from where its scene actually starts, so
+// nothing adds up. `lastWordEndFrames[i]` is when scene i's last word ends, in frames from its own start.
+export function snapNarrated(input: { naturalFrames: number[]; lastWordEndFrames: number[]; beatFrames: number[]; maxMove?: number; clearance?: number }): { frames: number[]; onBeat: boolean[] } {
+  const { naturalFrames, lastWordEndFrames, beatFrames } = input;
+  const maxMove = input.maxMove ?? NARRATED_SNAP_FRAMES, clearance = input.clearance ?? NARRATED_WORD_CLEARANCE;
+  let cursor = 0;
+  const onBeat: boolean[] = [];
+  const frames = naturalFrames.map((natural, i) => {
+    let end = cursor + natural;
+    if (i < naturalFrames.length - 1) {
+      const floor = cursor + (lastWordEndFrames[i] ?? 0) + clearance;
+      let best: number | undefined;
+      for (const b of beatFrames) {
+        if (Math.abs(b - end) > maxMove || b < floor) continue;
+        if (best === undefined || Math.abs(b - end) < Math.abs(best - end) || (Math.abs(b - end) === Math.abs(best - end) && b > best)) best = b;
+      }
+      if (best !== undefined) end = best;
+      onBeat.push(beatFrames.includes(end));
+    }
+    const length = end - cursor;
+    cursor = end;
+    return length;
+  });
+  return { frames, onBeat };
+}
+
+// The beat frames with `divisions - 1` evenly spaced points between each pair, rounded to frames. The last beat is followed by one more
+// at the median spacing, so a point just after it exists too.
+export function gridPoints(beatFrames: number[], divisions: number): number[] {
+  if (beatFrames.length < 2) return [...beatFrames];
+  const gaps = beatFrames.slice(1).map((b, i) => b - beatFrames[i]!).sort((a, b) => a - b);
+  const period = Math.max(1, gaps[Math.floor(gaps.length / 2)]!);
+  const all = [...beatFrames, beatFrames[beatFrames.length - 1]! + period];
+  const out = new Set<number>();
+  for (let i = 0; i + 1 < all.length; i++) for (let k = 0; k < divisions; k++) out.add(Math.round(all[i]! + ((all[i + 1]! - all[i]!) * k) / divisions));
+  out.add(all[all.length - 1]!);
+  return [...out].sort((a, b) => a - b);
+}
+
+// A scene of at least 1.5 beats ends on the nearest whole beat; a shorter one on the nearest half beat, and under half a beat the nearest
+// quarter. The target is the planned end (the sum of the natural lengths), so rounding errors do not add up; a scene is never made empty.
+function snapToNearest(naturalFrames: number[], beatFrames: number[]): number[] {
+  const gaps = beatFrames.slice(1).map((b, i) => b - beatFrames[i]!).sort((a, b) => a - b);
+  const period = Math.max(1, gaps[Math.floor(gaps.length / 2)]!);
+  const grids = new Map<number, number[]>();
+  const grid = (d: number) => grids.get(d) ?? (grids.set(d, gridPoints(beatFrames, d)), grids.get(d)!);
+  let cursor = 0, planned = 0;
+  return naturalFrames.map((natural) => {
+    planned += natural;
+    const beats = natural / period;
+    const points = grid(beats >= 1.5 ? 1 : beats >= 0.5 ? 2 : 4).filter((f) => f > cursor);
+    let target = planned;
+    if (points.length) target = points.reduce((best, f) => (Math.abs(f - planned) < Math.abs(best - planned) ? f : best));
+    else target = Math.max(planned, cursor + 1);
+    const frames = target - cursor;
+    cursor = target;
+    return frames;
+  });
+}
+
 // Beats in seconds, continued at the tempo's own spacing until `untilSec`, for a video longer than the track (the track loops).
 export function extendBeats(beats: number[], bpm: number, untilSec: number): number[] {
   if (!beats.length) return [];

package/src/pipeline/review.ts

@@ -1,16 +1,23 @@
-import { WORDS_PER_SEC, type AssetRecord, type ScenePlan } from "./schema";
+import { gapSec, isVoiceless, LAST_TAIL_SEC, PACE_SPEED, VOICE_WORDS_PER_SEC, type AssetRecord, type ScenePlan } from "./schema";
 
 const words = (s: string) => s.trim().split(/\s+/).filter(Boolean).length;
 
-// The same estimate the length advice below is based on: narration words at the voice's usual pace.
+// What the voice speaks at, in words a second, for this plan's pace.
+const speechRate = (plan: ScenePlan) => VOICE_WORDS_PER_SEC * PACE_SPEED[plan.pace ?? "normal"];
+
+// The estimate the length advice below is based on: each scene's words at the voice's real speed (2.25 words a second at the normal pace, the
+// pauses within a sentence included), the plan's silence between sentences after every scene but the last, and the last scene's tail after its
+// last word. It matches the manifest `reelkit assets voiceover` builds. A video with no voice has no words to count: its length is the sum of the
+// scenes' own seconds.
 export function estimateLength(plan: ScenePlan): { words: number; seconds: number } {
+  if (isVoiceless(plan)) return { words: 0, seconds: plan.scenes.reduce((n, s) => n + (s.seconds ?? 0), 0) };
   const total = plan.scenes.reduce((n, s) => n + words(s.narration), 0);
-  return { words: total, seconds: total / WORDS_PER_SEC };
+  return { words: total, seconds: total / speechRate(plan) + (plan.scenes.length - 1) * gapSec(plan) + LAST_TAIL_SEC };
 }
 
-// Each scene's estimated length in seconds, from its narration at the same pace as the whole-video estimate above.
+// Each scene's estimated length in seconds: its speech and what follows it (the gap, or the tail for the last scene), so they add up to the whole estimate.
 export function sceneSeconds(plan: ScenePlan): { id: string; seconds: number }[] {
-  return plan.scenes.map((s) => ({ id: s.id, seconds: words(s.narration) / WORDS_PER_SEC }));
+  return plan.scenes.map((s, i) => ({ id: s.id, seconds: isVoiceless(plan) ? (s.seconds ?? 0) : words(s.narration) / speechRate(plan) + (i === plan.scenes.length - 1 ? LAST_TAIL_SEC : gapSec(plan)) }));
 }
 
 // How uneven the scene lengths are: the standard deviation over the mean (0 when they are all the same).
@@ -29,12 +36,14 @@ export function rhythmNote(plan: ScenePlan): string | undefined {
   const cv = lengthVariation(values);
   if (cv >= 0.25 && values.some((v) => v < mean / 2)) return undefined;
   const shortest = lengths.reduce((a, b) => (b.seconds < a.seconds ? b : a)), longest = lengths.reduce((a, b) => (b.seconds > a.seconds ? b : a));
-  return `The scenes are too even in length (the shortest, ${shortest.id}, is about ${shortest.seconds.toFixed(1)}s and the longest, ${longest.id}, about ${longest.seconds.toFixed(1)}s). Make one or two scenes much shorter (a hit of a few words) and let one run long.`;
+  const fix = isVoiceless(plan) ? "Make one or two scenes much shorter (under a second) and let one run long." : "Make one or two scenes much shorter (a hit of a few words) and let one run long.";
+  return `The scenes are too even in length (the shortest, ${shortest.id}, is about ${shortest.seconds.toFixed(1)}s and the longest, ${longest.id}, about ${longest.seconds.toFixed(1)}s). ${fix}`;
 }
 
 // Soft quality checks on a plan that already passes the hard rules in validatePlan.
 // These are things worth improving in the script; they never fail a video on their own.
 export function reviewPlan(plan: ScenePlan, ctx: { footage?: AssetRecord }): string[] {
+  if (isVoiceless(plan)) return reviewVoicelessPlan(plan, ctx);
   const issues: string[] = [];
   const { words: total, seconds } = estimateLength(plan);
 
@@ -53,7 +62,30 @@ export function reviewPlan(plan: ScenePlan, ctx: { footage?: AssetRecord }): str
     // A hit of a few words is wanted in the rhythm of a video, so only a scene with almost nothing to say is flagged.
     if (!ctx.footage && n < 3) issues.push(`Scene ${s.id} has only ${n} word${n === 1 ? "" : "s"} of narration; give it at least a short phrase.`);
     if (n > 45) issues.push(`Scene ${s.id} has ${n} words of narration; split it or cut it to under 45.`);
-    if (s.onScreenText.length > 3) issues.push(`Scene ${s.id} has ${s.onScreenText.length} on-screen text items; use at most 3.`);
+    if (s.onScreenText.length > 5) issues.push(`Scene ${s.id} has ${s.onScreenText.length} on-screen text items; use at most 5 (the items of one list on screen count as one text, but the plan cannot say which they are).`);
+    for (const t of s.onScreenText) if (words(t) > 7) issues.push(`Scene ${s.id}: on-screen text "${t}" is too long; keep each item to 7 words or fewer.`);
+  }
+  const rhythm = rhythmNote(plan);
+  if (rhythm) issues.push(rhythm);
+  issues.push(...structureNotes(plan, ctx));
+  return issues;
+}
+
+// The same kind of advice for a video with no voice: no words to count, so length and rhythm come from `seconds`, and every word the
+// viewer reads is on screen. A video of this kind needs at least one quick hit, so a plan with no scene under a second is flagged.
+function reviewVoicelessPlan(plan: ScenePlan, ctx: { footage?: AssetRecord }): string[] {
+  const issues: string[] = [];
+  const { seconds } = estimateLength(plan);
+  if (seconds < 10) issues.push(`The video runs ${seconds.toFixed(1)}s. A video with no voice needs at least 10 seconds to get across; aim for 15 to 45.`);
+  if (seconds > 60) issues.push(`The video runs ${seconds.toFixed(1)}s. Cut it to 60 seconds or less; aim for 15 to 45.`);
+  if (!plan.scenes.some((s) => (s.seconds ?? 0) < 1)) issues.push("No scene is under 1 second. A film like this needs at least one quick hit; shorten one or two scenes to under a second.");
+  if (!ctx.footage) {
+    const illustrations = plan.scenes.filter((s) => s.treatment === "illustration").length;
+    if (illustrations > Math.ceil(plan.scenes.length / 2)) issues.push(`${illustrations} of ${plan.scenes.length} scenes are illustrations. Use illustrations for at most half the scenes.`);
+  }
+  for (const s of plan.scenes) {
+    if (!s.onScreenText.length && !s.notes.trim()) issues.push(`Scene ${s.id} has neither onScreenText nor notes. Say what is on screen, since no voice explains it.`);
+    if (s.onScreenText.length > 5) issues.push(`Scene ${s.id} has ${s.onScreenText.length} on-screen text items; use at most 5 (the items of one list on screen count as one text, but the plan cannot say which they are).`);
     for (const t of s.onScreenText) if (words(t) > 7) issues.push(`Scene ${s.id}: on-screen text "${t}" is too long; keep each item to 7 words or fewer.`);
   }
   const rhythm = rhythmNote(plan);
@@ -75,14 +107,16 @@ export function firstSentence(text: string): string {
 export function structureNotes(plan: ScenePlan, ctx: { footage?: AssetRecord }): string[] {
   const notes: string[] = [];
   if (ctx.footage) return notes;
-  if (plan.scenes.length >= 4 && !plan.scenes.some(hasPicture)) {
+  // A film with no voice is made of type and interface pieces on purpose (reference/launch-film.md), so it is not asked for a picture.
+  const voiceless = isVoiceless(plan);
+  if (!voiceless && plan.scenes.length >= 4 && !plan.scenes.some(hasPicture)) {
     notes.push("Every scene is type and shapes: no illustration, no clip and none of the user's own files. Give at least one scene a picture so the video has something to look at; see reference/scene-treatments.md.");
   }
   const first = plan.scenes[0]!;
-  if (!hasPicture(first)) {
+  if (!voiceless && !hasPicture(first)) {
     notes.push(`The opening has no picture, clip or user asset (scene ${first.id}). The first second decides whether the video is watched, so open on something to look at; see reference/scriptwriting.md.`);
   }
-  const n = words(firstSentence(first.narration));
+  const n = isVoiceless(plan) ? 0 : words(firstSentence(first.narration));
   if (n > 12) notes.push(`The first sentence of the opening is ${n} words. Open with a sentence of 12 words or fewer; see reference/scriptwriting.md.`);
   return notes;
 }