reelkit-cli 0.5.0 → 0.6.0

package/src/contract/index.ts

@@ -13,7 +13,12 @@
 // - A voiceover `text` must contain at least one non-space character: whitespace alone is 400 invalid_request.
 // - A library item `id` (pull, commit) matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`; a `deviceCode` is 1 to 200 characters of plain text.
 // - A `voiceId` is 1 to 64 letters and digits and must be one of the voices the server lists (`voices`), otherwise 400 invalid_request.
-// - Components are added to the library only by the owner's scripts, never through this API (UploadKindSchema has no `component`).
+// - A user's component is uploaded for review through the same two calls as any other file (`kind: "component"`). The server checks its source
+//   at commit with the same static check a pulled component gets (only react, remotion and reelkit/kit imports, no network, no globals that reach
+//   outside the video) and refuses a source that fails it with 400 `invalid_request` and the first problem. It stays in `review`, is never found
+//   by search or the public listing, and is published only by the owner. A component upload is: `contentType` `text/plain`, `bytes` up to 65,536,
+//   `shareable` true, `filename` matching `^[A-Z][A-Za-z0-9]*\.tsx$`, a `description` of at least 20 characters, and `meta.example` a string of at most
+//   2,000 characters that starts with `<` and the file's name (`<StatCard value="42" />` for StatCard.tsx). Anything else is 400 `invalid_request`.
 // - Upload is a single `PUT` to `uploadUrl` with exactly the declared content type and byte length, and no auth header.
 //   Anything else is refused with a non-2xx status and stores nothing. That refusal comes from the storage service, so its body
 //   is not an API error and a client must not parse it.
@@ -105,6 +110,11 @@ const Meta = z.record(z.string(), z.unknown()).refine((m) => new TextEncoder().e
 
 // The most a single upload may be: 200 MB.
 export const MAX_UPLOAD_BYTES = 209_715_200;
+// A component's source is at most 64 KB, its file name is PascalCase, and its description and example have the sizes below.
+export const MAX_COMPONENT_BYTES = 65_536;
+export const COMPONENT_FILE = /^[A-Z][A-Za-z0-9]*\.tsx$/;
+export const MIN_COMPONENT_DESCRIPTION = 20;
+export const MAX_COMPONENT_EXAMPLE = 2000;
 // The video types a cutout takes.
 export const CutoutTypeSchema = z.enum(["video/mp4", "video/quicktime", "video/webm"]);
 export type CutoutType = z.infer<typeof CutoutTypeSchema>;
@@ -124,8 +134,8 @@ export const ApiErrorSchema = z.object({ error: z.object({ code: z.string(), mes
 
 export const LibraryKindSchema = z.enum(["image", "overlay", "sfx", "music", "component", "clip"]);
 export type LibraryKind = z.infer<typeof LibraryKindSchema>;
-// What a user may upload: everything except components, which are code and come only from Reelkit.
-export const UploadKindSchema = LibraryKindSchema.exclude(["component"]);
+// What a user may upload: every kind. A component is code and is held for review (see the rules at the top).
+export const UploadKindSchema = LibraryKindSchema;
 export type UploadKind = z.infer<typeof UploadKindSchema>;
 
 export const LibraryItemSchema = z.object({
@@ -183,6 +193,16 @@ export const routes = {
       kind: UploadKindSchema, title: text(200).min(1), description: text(2000), tags: z.array(text(40)).max(20),
       meta: Meta, filename: text(200).min(1), contentType: text(100), bytes: z.number().int().positive().max(MAX_UPLOAD_BYTES),
       shareable: z.boolean(),
+    }).superRefine((r, ctx) => {
+      if (r.kind !== "component") return;
+      const bad = (path: string, message: string) => ctx.addIssue({ code: "custom", path: [path], message });
+      if (r.contentType.toLowerCase() !== "text/plain") bad("contentType", "a component must be text/plain");
+      if (r.bytes > MAX_COMPONENT_BYTES) bad("bytes", `a component is at most ${MAX_COMPONENT_BYTES} bytes`);
+      if (!COMPONENT_FILE.test(r.filename)) bad("filename", "a component file is named like StatCard.tsx");
+      if (!r.shareable) bad("shareable", "a component is only uploaded to be shared for review");
+      if (r.description.trim().length < MIN_COMPONENT_DESCRIPTION) bad("description", `a component needs a description of at least ${MIN_COMPONENT_DESCRIPTION} characters`);
+      const example = r.meta.example;
+      if (typeof example !== "string" || example.length > MAX_COMPONENT_EXAMPLE || !example.startsWith(`<${r.filename.replace(/\.tsx$/, "")}`)) bad("meta.example", `a component needs meta.example, at most ${MAX_COMPONENT_EXAMPLE} characters, that starts with <Name`);
     }),
     z.object({ id: z.string(), uploadUrl: z.string() })),
   libraryCommit: route("POST", "/library/upload/commit", true, z.object({ id: ItemId }), z.object({ item: LibraryItemSchema })),

package/src/pipeline/review.ts

@@ -58,5 +58,31 @@ export function reviewPlan(plan: ScenePlan, ctx: { footage?: AssetRecord }): str
   }
   const rhythm = rhythmNote(plan);
   if (rhythm) issues.push(rhythm);
+  issues.push(...structureNotes(plan, ctx));
   return issues;
 }
+
+const hasPicture = (s: ScenePlan["scenes"][number]) => s.treatment === "illustration" || s.treatment === "clip" || s.userAssetIds.length > 0;
+
+// The first sentence of some narration, up to . ! ? … or their Hebrew and Arabic forms.
+export function firstSentence(text: string): string {
+  const m = /^[\s\S]*?[.!?…؟׃。！？]+(?=\s|$)/.exec(text.trim());
+  return (m ? m[0] : text).trim();
+}
+
+// What the plan alone says about whether the video will look like something: pictures, an opening that shows, an opening that gets to the point.
+// Used by `plan check` and, because the composition is built from the plan, by `check` too.
+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)) {
+    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)) {
+    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));
+  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;
+}

package/src/project/loudness.ts

@@ -0,0 +1,68 @@
+import { audioDuration, tool } from "./refmeasure";
+
+// How loud a sound is, measured on this machine, and how much to turn it up or down so that the same `volume` number sounds equally loud
+// for every file.
+//   A one-shot (a sound effect under 3 s) is levelled by its loudest moment: its peak is brought to -3 dBFS.
+//   A longer sound (music, a long effect) is levelled by how loud it is overall: about -18 LUFS, integrated.
+// The gain is limited to 18 dB either way, so a nearly silent or a broken file is not blown up into noise.
+export const ONE_SHOT_SECONDS = 3;
+export const ONE_SHOT_PEAK_DB = -3;
+export const LONG_TARGET_LUFS = -18;
+export const MAX_GAIN_DB = 18;
+
+export type SoundLevel = { durationSec: number; peakDb?: number; lufs?: number };
+
+const round = (n: number, digits: number) => Math.round(n * 10 ** digits) / 10 ** digits;
+
+// The gain in dB that brings a measured sound to its target, or 0 when it could not be measured (silence).
+export function gainDbFor(level: SoundLevel): number {
+  const oneShot = level.durationSec < ONE_SHOT_SECONDS;
+  const measured = oneShot ? level.peakDb : level.lufs ?? level.peakDb;
+  if (measured === undefined || !Number.isFinite(measured)) return 0;
+  const target = oneShot || level.lufs === undefined ? ONE_SHOT_PEAK_DB : LONG_TARGET_LUFS;
+  return round(Math.max(-MAX_GAIN_DB, Math.min(MAX_GAIN_DB, target - measured)), 1);
+}
+
+export const dbToLinear = (db: number) => round(10 ** (db / 20), 4);
+
+// ffmpeg's volumedetect: the loudest sample, in dBFS. Undefined for digital silence.
+export async function peakOf(path: string): Promise<number | undefined> {
+  const { stderr } = await tool("ffmpeg", ["-hide_banner", "-nostats", "-i", path, "-vn", "-af", "volumedetect", "-f", "null", "-"]);
+  const peak = Number(/max_volume:\s*(-?[0-9.]+)\s*dB/.exec(stderr)?.[1]);
+  return Number.isFinite(peak) ? peak : undefined;
+}
+
+// What loudnorm's first pass reports; its numbers are text in the JSON it prints, and "-inf" for silence.
+export type LoudnormReport = { input_i: string; input_tp: string; input_lra: string; input_thresh: string; target_offset: string };
+
+export function parseLoudnorm(stderr: string): LoudnormReport | undefined {
+  const end = stderr.lastIndexOf("}");
+  const start = stderr.lastIndexOf("{", end);
+  if (start < 0 || end < start) return undefined;
+  try {
+    const r = JSON.parse(stderr.slice(start, end + 1)) as LoudnormReport;
+    return typeof r.input_i === "string" ? r : undefined;
+  } catch { return undefined; }
+}
+
+export async function measureLoudnorm(path: string, target: { i: number; tp: number }): Promise<LoudnormReport | undefined> {
+  const { stderr } = await tool("ffmpeg", ["-hide_banner", "-nostats", "-i", path, "-vn", "-af", `loudnorm=I=${target.i}:TP=${target.tp}:LRA=11:print_format=json`, "-f", "null", "-"]);
+  return parseLoudnorm(stderr);
+}
+
+// Measures a sound for levelling. A failure to measure is not the caller's failure: it returns undefined and the sound is used as it is.
+export async function levelOf(path: string): Promise<(SoundLevel & { gainDb: number }) | undefined> {
+  try {
+    const durationSec = await audioDuration(path);
+    if (!(durationSec > 0)) return undefined;
+    const peakDb = await peakOf(path);
+    let lufs: number | undefined;
+    if (durationSec >= ONE_SHOT_SECONDS) {
+      const r = await measureLoudnorm(path, { i: LONG_TARGET_LUFS, tp: -1.5 });
+      const v = Number(r?.input_i);
+      if (Number.isFinite(v)) lufs = round(v, 1);
+    }
+    const level: SoundLevel = { durationSec, ...(peakDb !== undefined ? { peakDb } : {}), ...(lufs !== undefined ? { lufs } : {}) };
+    return { ...level, gainDb: gainDbFor(level) };
+  } catch { return undefined; }
+}

package/src/project/manifest.ts

@@ -1,6 +1,7 @@
 import { PACE_SPEED, type AssetManifest, type ScenePlan, type WordTiming } from "../pipeline/schema";
 import { extendBeats, snapToBeats, toBeatFrames } from "../pipeline/beatsnap";
 import { dimensionsFor, FPS, layoutScenes } from "../pipeline/timing";
+import { dbToLinear } from "./loudness";
 import type { MusicRecord } from "./music";
 import { FILES, type Project } from "./project";
 
@@ -51,11 +52,19 @@ export function buildManifest(project: Project, plan: ScenePlan): AssetManifest
     totalFrames = footageFrames;
   }
 
+  // The levelling of every sound that was measured when it was pulled, as linear gains by path.
+  const soundGain: Record<string, number> = {};
+  for (const e of Object.values(project.readJsonOr<Record<string, { path: string; kind: string; gainDb?: number }>>(FILES.library, {}))) {
+    if ((e.kind === "sfx" || e.kind === "music") && typeof e.gainDb === "number") soundGain[e.path] = dbToLinear(e.gainDb);
+  }
+  if (music) soundGain[music.key] = dbToLinear(music.gainDb);
+
   const manifest: AssetManifest = {
     fps: FPS,
     ...dimensionsFor(plan.aspect, footage),
     totalFrames,
     captions: plan.captions ?? "phrase",
+    ...(Object.keys(soundGain).length ? { soundGain } : {}),
     ...(footage ? { footageKey: footage.key } : {}),
     ...(music ? { music: { key: music.key, ...(music.bpm ? { bpm: music.bpm } : {}), beatFrames: music.bpm ? beatFrames.filter((f) => f < totalFrames) : [] } } : {}),
     scenes: plan.scenes.map((scene, i) => ({

package/src/project/project.ts

@@ -5,14 +5,16 @@ import { AspectSchema, type AssetRecord } from "../pipeline/schema";
 
 export const FILES = {
   config: "reelkit.json", plan: "plan.json", manifest: "manifest.json",
-  assetIndex: "assets/index.json", voiceovers: "assets/voiceovers.json", images: "assets/images.json", clips: "assets/clips.json", library: "assets/library.json", music: "assets/music.json",
+  assetIndex: "assets/index.json", voiceovers: "assets/voiceovers.json", images: "assets/images.json", clips: "assets/clips.json", library: "assets/library.json", music: "assets/music.json", searches: "assets/searches.json", shared: "assets/shared.json",
 } as const;
 
 // "path: message", or just the message for a problem at the root of the file.
 export const issueLines = (e: { issues: { path: PropertyKey[]; message: string }[] }) =>
   e.issues.map((i) => (i.path.length ? `${i.path.map(String).join(".")}: ${i.message}` : i.message));
 
-export const ProjectConfigSchema = z.object({ aspect: AspectSchema, name: z.string().optional(), footage: z.string().optional() });
+export const ProjectConfigSchema = z.object({ aspect: AspectSchema, name: z.string().optional(), footage: z.string().optional(),
+  // false when the project was made with --private: nothing is shared with the library automatically.
+  shareComponents: z.boolean().optional() });
 export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
 
 // One video's working folder. Every command reads and writes its state here.

package/src/project/refmeasure.ts

@@ -9,7 +9,7 @@ const exec = promisify(execFile);
 export const REF_ASPECTS = ["9:16", "16:9", "1:1", "4:5"] as const;
 export type RefAspect = (typeof REF_ASPECTS)[number];
 
-async function tool(cmd: "ffmpeg" | "ffprobe", args: string[]): Promise<{ stdout: Buffer; stderr: string }> {
+export async function tool(cmd: "ffmpeg" | "ffprobe", args: string[]): Promise<{ stdout: Buffer; stderr: string }> {
   try {
     const r = await exec(cmd, args, { maxBuffer: 256 * 1024 * 1024, encoding: "buffer" });
     return { stdout: r.stdout, stderr: r.stderr.toString("utf8") };

package/src/remotion/kit/Sfx.tsx

@@ -1,11 +1,17 @@
 import React from "react";
-import { useMedia } from "./media";
+import { useGain, useMedia } from "./media";
 import { Audio, Sequence } from "remotion";
 
 // Plays one sound effect starting at a frame. at is counted from the start of the enclosing scene, or of the video
 // when placed outside the scenes. Keep volume well under the voiceover.
-export const Sfx: React.FC<{ src: string; at?: number; volume?: number }> = ({ src, at = 0, volume = 0.35 }) => (
-  <Sequence from={Math.max(0, Math.round(at))} layout="none">
-    <Audio src={useMedia(src)} volume={volume} />
-  </Sequence>
-);
+// A sound pulled from the library is levelled when it is pulled (the manifest's soundGain), and that is applied here by itself, so the same
+// volume sounds equally loud for every file: 0.2 to 0.45 is the range for an effect.
+export const Sfx: React.FC<{ src: string; at?: number; volume?: number }> = ({ src, at = 0, volume = 0.35 }) => {
+  const url = useMedia(src);
+  const gain = useGain(src);
+  return (
+    <Sequence from={Math.max(0, Math.round(at))} layout="none">
+      <Audio src={url} volume={volume * gain} />
+    </Sequence>
+  );
+};

package/src/remotion/kit/docs.ts

@@ -107,6 +107,7 @@ ScreenOverlay { src: string; durationSec?: number; opacity?: number }
 
 Sfx { src: string; at?: number; volume?: number }
   Plays one sound effect from the shared library, starting at the frame given by "at", counted from the start of the enclosing scene. Pull one with: reelkit assets search "<description>" --kind sfx, then reelkit assets pull <id>.
+  A pulled sound is levelled when it is pulled (the manifest's soundGain), and Sfx and Music apply that by themselves: the same volume sounds equally loud for every file. Nothing to pass.
   <Sfx src={urls["assets/lib/<id>/clip.mp3"]} at={10} volume={0.35} />
 
 Music { src: string; volume?: number; duckTo?: number }

package/src/remotion/kit/media.ts

@@ -15,11 +15,13 @@ export function useMedia(src: string): string {
 export const useManifest = () => useContext(ManifestContext);
 
 // The linear gain that levels a sound, from the manifest's soundGain. The sound may be named by its project path or by its link.
-export function useGain(src: string): number {
-  const urls = useContext(UrlsContext);
-  const gains = useContext(ManifestContext)?.soundGain;
+export function gainFor(gains: Record<string, number> | undefined, urls: Record<string, string>, src: string): number {
   if (!gains) return 1;
   if (gains[src] !== undefined) return gains[src]!;
   const path = Object.keys(gains).find((k) => urls[k] === src);
   return path ? gains[path]! : 1;
 }
+
+export function useGain(src: string): number {
+  return gainFor(useContext(ManifestContext)?.soundGain, useContext(UrlsContext), src);
+}

package/src/render/master.ts

@@ -0,0 +1,31 @@
+import { renameSync, rmSync } from "node:fs";
+import { loudnessLufs, tool } from "../project/refmeasure";
+import { measureLoudnorm } from "../project/loudness";
+
+// The loudness a finished video is brought to: -14 LUFS integrated, the level the big video platforms play at, with the loudest instant
+// kept under -1 dBTP so that re-encoding on upload cannot clip.
+export const MASTER_LUFS = -14;
+export const MASTER_TRUE_PEAK_DB = -1;
+
+export type Mastered = { inputLufs: number; outputLufs: number };
+// What a test may replace: the whole pass.
+export type Master = (path: string) => Promise<Mastered>;
+
+// Two-pass loudnorm: the first pass measures, the second applies exactly the gain that measurement asks for (linear, so the dynamics stay).
+// The video stream is copied untouched. The result replaces the file only when everything worked; otherwise the original stays as it was.
+export const masterLoudness: Master = async (path) => {
+  const first = await measureLoudnorm(path, { i: MASTER_LUFS, tp: MASTER_TRUE_PEAK_DB });
+  const inputLufs = Number(first?.input_i);
+  if (!first || !Number.isFinite(inputLufs)) throw new Error("the video has no sound to measure");
+  const out = path.replace(/(\.[^./]+)?$/, ".mastered$1");
+  const filter = `loudnorm=I=${MASTER_LUFS}:TP=${MASTER_TRUE_PEAK_DB}:LRA=11:measured_I=${first.input_i}:measured_TP=${first.input_tp}:measured_LRA=${first.input_lra}:measured_thresh=${first.input_thresh}:offset=${first.target_offset}:linear=true`;
+  try {
+    await tool("ffmpeg", ["-v", "error", "-y", "-i", path, "-c:v", "copy", "-af", filter, "-ar", "48000", "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart", out]);
+    const outputLufs = await loudnessLufs(out);
+    if (outputLufs === undefined) throw new Error("the mastered file has no readable loudness");
+    renameSync(out, path);
+    return { inputLufs: Math.round(inputLufs * 10) / 10, outputLufs };
+  } finally {
+    rmSync(out, { force: true });
+  }
+};

package/src/render/static-check.ts

@@ -0,0 +1,156 @@
+import ts from "typescript";
+
+// The check a component's source gets before it is used or shared: which modules it may import, which names it may not touch, and that
+// it exports what its file name says. Kept apart from the rest of validation because it needs nothing from this package's own folder
+// or from the machine: it is pure text in, problems out, so a server can bundle it.
+export const MAIN_FILE = "Video.tsx";
+export const FILE_NAME = /^[A-Z][A-Za-z0-9]*\.tsx$/;
+export const componentName = (file: string) => file.replace(/\.tsx$/, "");
+
+export const KIT = "reelkit/kit";
+const BASE_IMPORTS = new Set(["react", "remotion", KIT]);
+
+// This check keeps honest compositions deterministic and self-contained. It is NOT a security boundary:
+// code in src/ runs on the user's machine when it is bundled and rendered, and anyone determined can get around a list of names.
+// It looks at the code (the TypeScript syntax tree), never at text, so words in on-screen copy, strings and comments are not flagged.
+// Only a reference to the global counts: `style.process`, `{ fetch: 1 }`, and a name the file declares itself (a component called
+// `Worker`, a parameter called `window`) are fine. Scope comes from the TypeScript binder, so a declaration only covers where it is in scope.
+const FORBIDDEN_NAMES: Record<string, string> = {
+  require: "require()", eval: "eval()", fetch: "fetch()",
+  process: "process", globalThis: "globalThis", window: "window", self: "self",
+  XMLHttpRequest: "XMLHttpRequest", WebSocket: "WebSocket", EventSource: "EventSource",
+  navigator: "navigator", localStorage: "localStorage", sessionStorage: "sessionStorage", indexedDB: "indexedDB",
+  Function: "Function", Worker: "Worker", SharedWorker: "SharedWorker", importScripts: "importScripts", child_process: "child_process",
+};
+
+export const sourceFile = (source: string, file = "Video.tsx") => ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+
+// True when this identifier names a property, a label or a JSX attribute rather than referring to a variable.
+function isNamePosition(node: ts.Identifier): boolean {
+  const p = node.parent;
+  if (!p) return false;
+  if ((ts.isPropertyAccessExpression(p) || ts.isQualifiedName(p)) && (ts.isQualifiedName(p) ? p.right : p.name) === node) return true;
+  if ((ts.isPropertyAssignment(p) || ts.isPropertyDeclaration(p) || ts.isPropertySignature(p) || ts.isMethodDeclaration(p) || ts.isMethodSignature(p)
+    || ts.isGetAccessorDeclaration(p) || ts.isSetAccessorDeclaration(p) || ts.isEnumMember(p) || ts.isJsxAttribute(p)) && p.name === node) return true;
+  if (ts.isBindingElement(p) && p.propertyName === node) return true;
+  if ((ts.isImportSpecifier(p) || ts.isExportSpecifier(p)) && p.propertyName === node) return true;
+  if ((ts.isLabeledStatement(p) || ts.isBreakOrContinueStatement(p)) && p.label === node) return true;
+  return false;
+}
+
+// Looks through the wrappers that do not change what an expression is: (x), x as T, x!, x satisfies T, <T>x.
+export function unwrap(e: ts.Expression): ts.Expression {
+  while (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isNonNullExpression(e) || ts.isSatisfiesExpression(e) || ts.isTypeAssertionExpression(e)) e = e.expression;
+  return e;
+}
+
+// A one-file program with no libraries: a name the file declares has a symbol with a declaration in it; a global has none.
+function declaredHere(sf: ts.SourceFile): (id: ts.Identifier) => boolean {
+  const host: ts.CompilerHost = {
+    getSourceFile: (name) => (name === sf.fileName ? sf : undefined),
+    getDefaultLibFileName: () => "lib.d.ts", writeFile: () => {}, getCurrentDirectory: () => "", getCanonicalFileName: (f) => f,
+    useCaseSensitiveFileNames: () => true, getNewLine: () => "\n", fileExists: (f) => f === sf.fileName, readFile: () => undefined, getDirectories: () => [],
+  };
+  const program = ts.createProgram([sf.fileName], { noLib: true, noResolve: true, jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest }, host);
+  const checker = program.getTypeChecker();
+  return (id) => {
+    const p = id.parent;
+    const symbol = p && ts.isShorthandPropertyAssignment(p) && p.name === id ? checker.getShorthandAssignmentValueSymbol(p) : checker.getSymbolAtLocation(id);
+    return Boolean(symbol?.declarations?.some((d) => d.getSourceFile() === sf));
+  };
+}
+
+const textOf = (n: ts.Node | undefined) => (n && (ts.isStringLiteralLike(n)) ? n.text : undefined);
+
+type Finding = { specifiers: string[]; forbidden: string[] };
+
+function inspectSource(source: string, file?: string): Finding {
+  const specifiers: string[] = [];
+  const forbidden = new Set<string>();
+  const add = (s: string | undefined) => { if (s !== undefined) specifiers.push(s); };
+
+  const sf = sourceFile(source, file);
+  const declared = declaredHere(sf);
+  // True when the expression is the global with this name, not a variable the file declares.
+  const isGlobal = (e: ts.Expression | undefined, name: string) => {
+    const x = e && unwrap(e);
+    return Boolean(x && ts.isIdentifier(x) && x.text === name && !declared(x));
+  };
+  const flagMember = (object: ts.Expression | undefined, member: string | undefined) => {
+    if (isGlobal(object, "Math") && member === "random") forbidden.add("Math.random (use random(seed) from remotion)");
+    if (isGlobal(object, "Date") && member === "now") forbidden.add("the clock (Date)");
+  };
+  // The key a destructuring element reads: `random` in `{ random }` and in `{ random: r }`, "random" in `{ ["random"]: r }`.
+  const keyOf = (name: ts.PropertyName | undefined) =>
+    name && (ts.isIdentifier(name) || ts.isStringLiteralLike(name) ? name.text : ts.isComputedPropertyName(name) ? textOf(name.expression) : undefined);
+
+  const visit = (node: ts.Node, inType: boolean) => {
+    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) add(textOf(node.moduleSpecifier));
+    else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) add(textOf(node.moduleReference.expression));
+    else if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) add(textOf(node.argument.literal));
+    else if (ts.isCallExpression(node)) {
+      const callee = node.expression;
+      if (callee.kind === ts.SyntaxKind.ImportKeyword) { forbidden.add("dynamic import()"); add(textOf(node.arguments[0])); }
+      else if (isGlobal(callee, "require")) add(textOf(node.arguments[0]));
+      else if (ts.isPropertyAccessExpression(callee) && isGlobal(callee.expression, "require")) add(textOf(node.arguments[0]));
+      if (isGlobal(callee, "Function")) forbidden.add("Function()");
+      if (isGlobal(callee, "Date")) forbidden.add("the clock (Date)");
+    } else if (ts.isNewExpression(node)) {
+      if (isGlobal(node.expression, "Function")) forbidden.add("new Function");
+      if (isGlobal(node.expression, "Date")) forbidden.add("the clock (Date)");
+    }
+
+    // Math.random and Date.now, also written Math["random"], (Math).random, or taken out by destructuring.
+    if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+      flagMember(node.expression, ts.isPropertyAccessExpression(node) ? node.name.text : textOf(node.argumentExpression));
+    } else if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && node.initializer) {
+      for (const el of node.name.elements) flagMember(node.initializer, keyOf(el.propertyName) ?? (ts.isIdentifier(el.name) ? el.name.text : undefined));
+    } else if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isObjectLiteralExpression(unwrap(node.left))) {
+      for (const prop of (unwrap(node.left) as ts.ObjectLiteralExpression).properties) {
+        if (ts.isShorthandPropertyAssignment(prop)) flagMember(node.right, prop.name.text);
+        else if (ts.isPropertyAssignment(prop)) flagMember(node.right, keyOf(prop.name));
+      }
+    }
+    if (!inType && ts.isIdentifier(node) && !isNamePosition(node) && Object.hasOwn(FORBIDDEN_NAMES, node.text) && !declared(node)) {
+      // A plain call or `new` of Function is already reported as Function() or new Function.
+      const p = node.parent;
+      const reported = node.text === "Function" && (ts.isCallExpression(p) || ts.isNewExpression(p)) && p.expression === node;
+      if (!reported) forbidden.add(FORBIDDEN_NAMES[node.text]);
+    }
+
+    const nextInType = inType || (ts.isTypeNode(node) && !ts.isExpressionWithTypeArguments(node));
+    ts.forEachChild(node, (c) => visit(c, nextInType));
+  };
+  visit(sf, false);
+  return { specifiers, forbidden: [...forbidden] };
+}
+
+// Every module a file pulls in: import and export declarations, import(), require() and require.x(), however they are spaced or commented.
+export function importSpecifiers(source: string): string[] {
+  return inspectSource(source).specifiers;
+}
+
+// Video.tsx may import sibling component files; a component must be self-contained so it can be reused on its own.
+export function staticCheck(source: string, file: string, siblings: string[]): string[] {
+  const errors: string[] = [];
+  const isMain = file === MAIN_FILE;
+  const allowedSiblings = new Set(isMain ? siblings.filter((s) => s !== MAIN_FILE).map((s) => `./${componentName(s)}`) : []);
+  const found = inspectSource(source, file);
+  for (const s of found.specifiers) {
+    if (BASE_IMPORTS.has(s) || allowedSiblings.has(s)) continue;
+    errors.push(
+      isMain
+        ? `${file}: import not allowed: "${s}". Use react, remotion, ${KIT}, or a component file that exists ("./Name").`
+        : `${file}: import not allowed: "${s}". A component may only import react, remotion and ${KIT}.`,
+    );
+  }
+  for (const name of found.forbidden) errors.push(`${file}: not allowed: ${name}.`);
+  const exported = isMain ? "Video" : componentName(file);
+  const exportsIt = sourceFile(source, file).statements.some((s) =>
+    ts.isVariableStatement(s) && s.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+    && s.declarationList.flags & ts.NodeFlags.Const && s.declarationList.declarations.some((d) => ts.isIdentifier(d.name) && d.name.text === exported));
+  if (!exportsIt) errors.push(`${file} must contain \`export const ${exported}\`.`);
+  return errors;
+}
+
+// The project folder has no node_modules. These map its imports to the copies installed with this package.

package/src/render/validate.ts

@@ -7,157 +7,10 @@ export const PKG_ROOT = fileURLToPath(new URL("../..", import.meta.url));
 export const KIT_INDEX = join(PKG_ROOT, "src", "remotion", "kit", "index.ts");
 export const ROOT_FILE = join(PKG_ROOT, "src", "remotion", "Root.tsx");
 
-export const MAIN_FILE = "Video.tsx";
-export const FILE_NAME = /^[A-Z][A-Za-z0-9]*\.tsx$/;
-export const componentName = (file: string) => file.replace(/\.tsx$/, "");
+// The static check lives in its own module, which a server can bundle; everything it exports is available from here as before.
+export { FILE_NAME, MAIN_FILE, componentName, importSpecifiers, staticCheck } from "./static-check";
+import { KIT, sourceFile, unwrap } from "./static-check";
 
-const KIT = "reelkit/kit";
-const BASE_IMPORTS = new Set(["react", "remotion", KIT]);
-
-// This check keeps honest compositions deterministic and self-contained. It is NOT a security boundary:
-// code in src/ runs on the user's machine when it is bundled and rendered, and anyone determined can get around a list of names.
-// It looks at the code (the TypeScript syntax tree), never at text, so words in on-screen copy, strings and comments are not flagged.
-// Only a reference to the global counts: `style.process`, `{ fetch: 1 }`, and a name the file declares itself (a component called
-// `Worker`, a parameter called `window`) are fine. Scope comes from the TypeScript binder, so a declaration only covers where it is in scope.
-const FORBIDDEN_NAMES: Record<string, string> = {
-  require: "require()", eval: "eval()", fetch: "fetch()",
-  process: "process", globalThis: "globalThis", window: "window", self: "self",
-  XMLHttpRequest: "XMLHttpRequest", WebSocket: "WebSocket", EventSource: "EventSource",
-  navigator: "navigator", localStorage: "localStorage", sessionStorage: "sessionStorage", indexedDB: "indexedDB",
-  Function: "Function", Worker: "Worker", SharedWorker: "SharedWorker", importScripts: "importScripts", child_process: "child_process",
-};
-
-const sourceFile = (source: string, file = "Video.tsx") => ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
-
-// True when this identifier names a property, a label or a JSX attribute rather than referring to a variable.
-function isNamePosition(node: ts.Identifier): boolean {
-  const p = node.parent;
-  if (!p) return false;
-  if ((ts.isPropertyAccessExpression(p) || ts.isQualifiedName(p)) && (ts.isQualifiedName(p) ? p.right : p.name) === node) return true;
-  if ((ts.isPropertyAssignment(p) || ts.isPropertyDeclaration(p) || ts.isPropertySignature(p) || ts.isMethodDeclaration(p) || ts.isMethodSignature(p)
-    || ts.isGetAccessorDeclaration(p) || ts.isSetAccessorDeclaration(p) || ts.isEnumMember(p) || ts.isJsxAttribute(p)) && p.name === node) return true;
-  if (ts.isBindingElement(p) && p.propertyName === node) return true;
-  if ((ts.isImportSpecifier(p) || ts.isExportSpecifier(p)) && p.propertyName === node) return true;
-  if ((ts.isLabeledStatement(p) || ts.isBreakOrContinueStatement(p)) && p.label === node) return true;
-  return false;
-}
-
-// Looks through the wrappers that do not change what an expression is: (x), x as T, x!, x satisfies T, <T>x.
-function unwrap(e: ts.Expression): ts.Expression {
-  while (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isNonNullExpression(e) || ts.isSatisfiesExpression(e) || ts.isTypeAssertionExpression(e)) e = e.expression;
-  return e;
-}
-
-// A one-file program with no libraries: a name the file declares has a symbol with a declaration in it; a global has none.
-function declaredHere(sf: ts.SourceFile): (id: ts.Identifier) => boolean {
-  const host: ts.CompilerHost = {
-    getSourceFile: (name) => (name === sf.fileName ? sf : undefined),
-    getDefaultLibFileName: () => "lib.d.ts", writeFile: () => {}, getCurrentDirectory: () => "", getCanonicalFileName: (f) => f,
-    useCaseSensitiveFileNames: () => true, getNewLine: () => "\n", fileExists: (f) => f === sf.fileName, readFile: () => undefined, getDirectories: () => [],
-  };
-  const program = ts.createProgram([sf.fileName], { noLib: true, noResolve: true, jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest }, host);
-  const checker = program.getTypeChecker();
-  return (id) => {
-    const p = id.parent;
-    const symbol = p && ts.isShorthandPropertyAssignment(p) && p.name === id ? checker.getShorthandAssignmentValueSymbol(p) : checker.getSymbolAtLocation(id);
-    return Boolean(symbol?.declarations?.some((d) => d.getSourceFile() === sf));
-  };
-}
-
-const textOf = (n: ts.Node | undefined) => (n && (ts.isStringLiteralLike(n)) ? n.text : undefined);
-
-type Finding = { specifiers: string[]; forbidden: string[] };
-
-function inspectSource(source: string, file?: string): Finding {
-  const specifiers: string[] = [];
-  const forbidden = new Set<string>();
-  const add = (s: string | undefined) => { if (s !== undefined) specifiers.push(s); };
-
-  const sf = sourceFile(source, file);
-  const declared = declaredHere(sf);
-  // True when the expression is the global with this name, not a variable the file declares.
-  const isGlobal = (e: ts.Expression | undefined, name: string) => {
-    const x = e && unwrap(e);
-    return Boolean(x && ts.isIdentifier(x) && x.text === name && !declared(x));
-  };
-  const flagMember = (object: ts.Expression | undefined, member: string | undefined) => {
-    if (isGlobal(object, "Math") && member === "random") forbidden.add("Math.random (use random(seed) from remotion)");
-    if (isGlobal(object, "Date") && member === "now") forbidden.add("the clock (Date)");
-  };
-  // The key a destructuring element reads: `random` in `{ random }` and in `{ random: r }`, "random" in `{ ["random"]: r }`.
-  const keyOf = (name: ts.PropertyName | undefined) =>
-    name && (ts.isIdentifier(name) || ts.isStringLiteralLike(name) ? name.text : ts.isComputedPropertyName(name) ? textOf(name.expression) : undefined);
-
-  const visit = (node: ts.Node, inType: boolean) => {
-    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) add(textOf(node.moduleSpecifier));
-    else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) add(textOf(node.moduleReference.expression));
-    else if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) add(textOf(node.argument.literal));
-    else if (ts.isCallExpression(node)) {
-      const callee = node.expression;
-      if (callee.kind === ts.SyntaxKind.ImportKeyword) { forbidden.add("dynamic import()"); add(textOf(node.arguments[0])); }
-      else if (isGlobal(callee, "require")) add(textOf(node.arguments[0]));
-      else if (ts.isPropertyAccessExpression(callee) && isGlobal(callee.expression, "require")) add(textOf(node.arguments[0]));
-      if (isGlobal(callee, "Function")) forbidden.add("Function()");
-      if (isGlobal(callee, "Date")) forbidden.add("the clock (Date)");
-    } else if (ts.isNewExpression(node)) {
-      if (isGlobal(node.expression, "Function")) forbidden.add("new Function");
-      if (isGlobal(node.expression, "Date")) forbidden.add("the clock (Date)");
-    }
-
-    // Math.random and Date.now, also written Math["random"], (Math).random, or taken out by destructuring.
-    if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
-      flagMember(node.expression, ts.isPropertyAccessExpression(node) ? node.name.text : textOf(node.argumentExpression));
-    } else if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && node.initializer) {
-      for (const el of node.name.elements) flagMember(node.initializer, keyOf(el.propertyName) ?? (ts.isIdentifier(el.name) ? el.name.text : undefined));
-    } else if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isObjectLiteralExpression(unwrap(node.left))) {
-      for (const prop of (unwrap(node.left) as ts.ObjectLiteralExpression).properties) {
-        if (ts.isShorthandPropertyAssignment(prop)) flagMember(node.right, prop.name.text);
-        else if (ts.isPropertyAssignment(prop)) flagMember(node.right, keyOf(prop.name));
-      }
-    }
-    if (!inType && ts.isIdentifier(node) && !isNamePosition(node) && Object.hasOwn(FORBIDDEN_NAMES, node.text) && !declared(node)) {
-      // A plain call or `new` of Function is already reported as Function() or new Function.
-      const p = node.parent;
-      const reported = node.text === "Function" && (ts.isCallExpression(p) || ts.isNewExpression(p)) && p.expression === node;
-      if (!reported) forbidden.add(FORBIDDEN_NAMES[node.text]);
-    }
-
-    const nextInType = inType || (ts.isTypeNode(node) && !ts.isExpressionWithTypeArguments(node));
-    ts.forEachChild(node, (c) => visit(c, nextInType));
-  };
-  visit(sf, false);
-  return { specifiers, forbidden: [...forbidden] };
-}
-
-// Every module a file pulls in: import and export declarations, import(), require() and require.x(), however they are spaced or commented.
-export function importSpecifiers(source: string): string[] {
-  return inspectSource(source).specifiers;
-}
-
-// Video.tsx may import sibling component files; a component must be self-contained so it can be reused on its own.
-export function staticCheck(source: string, file: string, siblings: string[]): string[] {
-  const errors: string[] = [];
-  const isMain = file === MAIN_FILE;
-  const allowedSiblings = new Set(isMain ? siblings.filter((s) => s !== MAIN_FILE).map((s) => `./${componentName(s)}`) : []);
-  const found = inspectSource(source, file);
-  for (const s of found.specifiers) {
-    if (BASE_IMPORTS.has(s) || allowedSiblings.has(s)) continue;
-    errors.push(
-      isMain
-        ? `${file}: import not allowed: "${s}". Use react, remotion, ${KIT}, or a component file that exists ("./Name").`
-        : `${file}: import not allowed: "${s}". A component may only import react, remotion and ${KIT}.`,
-    );
-  }
-  for (const name of found.forbidden) errors.push(`${file}: not allowed: ${name}.`);
-  const exported = isMain ? "Video" : componentName(file);
-  const exportsIt = sourceFile(source, file).statements.some((s) =>
-    ts.isVariableStatement(s) && s.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
-    && s.declarationList.flags & ts.NodeFlags.Const && s.declarationList.declarations.some((d) => ts.isIdentifier(d.name) && d.name.text === exported));
-  if (!exportsIt) errors.push(`${file} must contain \`export const ${exported}\`.`);
-  return errors;
-}
-
-// The project folder has no node_modules. These map its imports to the copies installed with this package.
 const typesReact = packageDir("@types/react");
 export const remotionDir = packageDir("remotion");