reelkit-cli 0.1.0

package/src/remotion/kit/docs.ts

@@ -0,0 +1,98 @@
+export const KIT_DOCS = `
+Import from "reelkit/kit". Media props (src) take urls[key]; the kit components also accept the bare project path. For your own <Img>, <Audio> or <OffthreadVideo>, always pass urls[key]. Inside a SceneFrame, useCurrentFrame() starts at 0 for that scene.
+
+SceneFrame { from: number; durationInFrames: number; children }
+  Wraps one scene. Places children on the timeline and fades them in and out.
+  <SceneFrame from={s.startFrame} durationInFrames={s.durationFrames}>...</SceneFrame>
+
+TitleCard { text: string; subtitle?: string; color?: string; background?: string }
+  Large centred title that springs in.
+  <TitleCard text="Ship faster" subtitle="in three steps" background="#101020" />
+
+LowerThird { title: string; subtitle?: string; accent?: string }
+  Name/label strip that slides in from the left, low on the screen.
+  <LowerThird title="Step 1" subtitle="Connect your account" />
+
+Captions { words: WordTiming[]; mode?: "highlight" | "pop" | "karaoke"; highlight?: string; color?: string; perLine?: number; uppercase?: boolean; bottom?: number; face?: string; rtl?: boolean }
+  Word-timed captions near the bottom. Pass the scene's words from the manifest. Pick one mode for the whole video:
+  "highlight" (a line, spoken word coloured), "pop" (1-3 words popping in as spoken), "karaoke" (a line filling with colour).
+  bottom is the distance from the bottom edge as a fraction of the height (default 0.16).
+  For Hebrew narration pass face={font("heebo")} and rtl.
+  <Captions words={s.words} mode="pop" highlight={palette.hero} uppercase />
+
+Counter { from?: number; to: number; durationFrames?: number; prefix?: string; suffix?: string; color?: string }
+  Centred number that counts up.
+  <Counter to={10000} suffix="+" durationFrames={45} />
+
+KenBurnsImage { src: string; zoom?: number; direction?: "in" | "out" }
+  Full-frame image with a slow zoom and pan. src must come from urls[...]. Alternate direction between consecutive image scenes.
+  <KenBurnsImage src={urls[s.imageKey]} />
+
+FootageLayer { src: string; muted?: boolean; dim?: number }
+  Full-frame user footage. Place it once, outside the scenes, as the bottom layer. dim (0-1) darkens it for legibility.
+  <FootageLayer src={urls[manifest.footageKey]} dim={0.25} />
+
+BgMesh { bg: string; hero: string; accent?: string }
+  The bottom layer of the video: the base colour with two slow-drifting soft colour fields. Use it instead of a flat background.
+  <BgMesh bg={palette.bg} hero={palette.hero} accent={palette.accent} />
+
+Grade { color: string; strength?: number }   Grain { opacity?: number; blend?: "multiply" | "overlay" }   Vignette { strength?: number }
+  Finishing layers, placed once at the very top of the video in this order: Grade, Grain, Vignette.
+  Grade tints everything toward the hero colour so images and graphics read as one look (strength 0.10-0.15 on light themes, 0.18-0.25 on dark).
+  Grain uses blend "multiply" on light themes and "overlay" on dark ones.
+  <Grade color={palette.hero} /><Grain blend="overlay" /><Vignette />
+
+Entrance { delay?: number; exitAt?: number; rise?: number; breathe?: boolean; style?; children }
+  The standard way to bring anything in: fade + rise + scale on a spring, then a slow idle breathe. delay and exitAt are frames from the scene start; exitAt adds a faster exit.
+  <Entrance delay={8} exitAt={s.durationFrames - 14}><Card /></Entrance>
+
+WordReveal { text: string; delay?: number; per?: number; highlight?: string; highlightColor?: string; style? }
+  Headline that rises in word by word from behind a mask. highlight colours one word.
+  <WordReveal text="Stretch first, phone second" highlight="first" highlightColor={palette.hero} style={{ fontFamily: fonts.display, fontWeight: 800, fontSize: width * 0.09, color: palette.ink }} />
+
+fonts { display: string; body: string }
+  Loaded font families. Use fonts.display (weights 600-800) for headlines and numbers, fonts.body for supporting text. Never leave hero text on a default font.
+
+Icon { name: IconName; size: number; color?: string }     brandColor(name): string
+  A platform's real logo mark, or a plain interface glyph. size is in pixels. color "brand" uses the platform's own colour.
+  Brands: instagram, tiktok, youtube, x, facebook, whatsapp, telegram, twitch, discord, spotify, snapchat, pinterest, messenger, threads,
+  reddit, github, gmail, soundcloud, behance, vimeo, dribbble, imessage, apple, googlemessages, signal, googlecalendar, stripe, paypal,
+  applepay, shopify, notion, zoom.  Glyphs: message, mail, bell, phone, calendar, cart, heart, star, user, play.
+  Use Icon for any platform logo. Never draw a logo yourself, never use a letter or an emoji in its place, and only show a
+  platform's mark when the video really refers to that platform.
+  <Icon name="instagram" size={width * 0.06} color="brand" />
+
+font(name): string
+  Loads one extra typeface and returns its family name. Call it once at the top of a file: const heavy = font("montserrat").
+  montserrat (300, 800, 900), montserratItalic (800, 900), kanit (600), roboto (300, 500, 700, 900), robotoSlab (700),
+  bebasNeue (tall condensed caps), archivoBlack (very heavy), unbounded (wide heavy display, 800, 900), modak (chunky rounded),
+  greatVibes (formal script), sacramento (monoline script), outfit (geometric sans 100, 300, 500, 900), syne (wide heavy 800),
+  lilitaOne (heavy rounded), kaushanScript (bold brush script), yellowtail (flowing brush script), mrsSaintDelafield (signature script),
+  permanentMarker (marker lettering), bungeeShade (outlined sign capitals), cinzel (Roman capitals 700, 900: epic),
+  playfairDisplay (elegant serif 700, 900), orbitron (sci-fi 700, 900), rye (western), creepster (horror).
+  Hebrew text must use a Hebrew face; every face above is Latin only and Hebrew would fall back to a default font. Hebrew faces
+  (all also cover Latin): heebo, rubik, notoSansHebrew (400, 700, 900: neutral sans), assistant (400, 700, 800), alef (400, 700),
+  secularOne (strong headline), varelaRound (soft rounded), fredoka (playful rounded 500, 700), karantina (tall condensed 400, 700),
+  suezOne (heavy serif headline), frankRuhlLibre (book serif 400, 700, 900), davidLibre (traditional serif 400, 700),
+  amaticSC (hand-lettered 400, 700).
+  Use at most two typefaces in one video.
+
+springs { snappy, smooth, heavy }    ease { out, in, inOut }
+  Spring configs for spring({ frame, fps, config: springs.smooth }) and easings for interpolate(..., { easing: ease.out, extrapolateLeft: "clamp", extrapolateRight: "clamp" }).
+
+palettes { darkTech, warmEditorial, warmPremium, cleanLight }   each is a Palette { bg, ink, hero, accent, dim }
+  Proven starting palettes. Pick one that suits the topic, or define your own Palette object. Declare it once at the top of Video.tsx and take every colour from it.
+
+ScreenOverlay { src: string; durationSec?: number; opacity?: number }
+  Lays a shared overlay clip (film marks, HUD frames) over the video with a screen blend. Pull one with: reelkit assets search "<description>" --kind overlay, then reelkit assets pull <id>; the clip's durationSec is in its entry in assets/library.json.
+  Place it once, above the scenes and below Grade. Works best on dark themes.
+  <ScreenOverlay src={urls["assets/lib/<id>/clip.mp4"]} durationSec={5} opacity={0.5} />
+
+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>.
+  <Sfx src={urls["assets/lib/<id>/clip.mp3"]} at={10} volume={0.35} />
+
+Voiceover { src: string; volume?: number }
+  The scene's narration audio. One per narrated scene, inside its SceneFrame. Guard it with s.voiceoverKey so a scene without a recording still renders.
+  {s.voiceoverKey ? <Voiceover src={urls[s.voiceoverKey]} /> : null}
+`.trim();

package/src/remotion/kit/index.ts

@@ -0,0 +1,20 @@
+export { Captions } from "./Captions";
+export { Counter } from "./Counter";
+export { Entrance, WordReveal } from "./Entrance";
+export { FootageLayer } from "./FootageLayer";
+export { brandColor, Icon } from "./Icon";
+export type { GlyphName, IconName } from "./Icon";
+export type { BrandName } from "./brand-icons";
+export { KenBurnsImage } from "./KenBurnsImage";
+export { BgMesh, Grade, Grain, Vignette } from "./Layers";
+export { LowerThird } from "./LowerThird";
+export { SceneFrame } from "./SceneFrame";
+export { ScreenOverlay } from "./ScreenOverlay";
+export { useMedia } from "./media";
+export { Sfx } from "./Sfx";
+export { TitleCard } from "./TitleCard";
+export { Voiceover } from "./Voiceover";
+export type { VideoProps } from "../types";
+export { ease, font, fonts, palettes, springs } from "./theme";
+export type { CaptionMode } from "./Captions";
+export type { KitFont, Palette } from "./theme";

package/src/remotion/kit/media.ts

@@ -0,0 +1,10 @@
+import { createContext, useContext } from "react";
+
+// The project's media links, keyed by project path (assets/...). Root provides them, so a kit component works whether it is
+// given a link (urls[key]) or just the project path (key).
+export const UrlsContext = createContext<Record<string, string>>({});
+
+export function useMedia(src: string): string {
+  const urls = useContext(UrlsContext);
+  return urls[src] ?? src;
+}

package/src/remotion/kit/theme.ts

@@ -0,0 +1,131 @@
+import { loadFont as loadBody } from "@remotion/google-fonts/Inter";
+import { loadFont as loadDisplay } from "@remotion/google-fonts/Sora";
+import { loadFont as loadArchivoBlack } from "@remotion/google-fonts/ArchivoBlack";
+import { loadFont as loadBebasNeue } from "@remotion/google-fonts/BebasNeue";
+import { loadFont as loadGreatVibes } from "@remotion/google-fonts/GreatVibes";
+import { loadFont as loadKanit } from "@remotion/google-fonts/Kanit";
+import { loadFont as loadModak } from "@remotion/google-fonts/Modak";
+import { loadFont as loadMontserrat } from "@remotion/google-fonts/Montserrat";
+import { loadFont as loadRoboto } from "@remotion/google-fonts/Roboto";
+import { loadFont as loadRobotoSlab } from "@remotion/google-fonts/RobotoSlab";
+import { loadFont as loadSacramento } from "@remotion/google-fonts/Sacramento";
+import { loadFont as loadUnbounded } from "@remotion/google-fonts/Unbounded";
+import { loadFont as loadBungeeShade } from "@remotion/google-fonts/BungeeShade";
+import { loadFont as loadCinzel } from "@remotion/google-fonts/Cinzel";
+import { loadFont as loadCreepster } from "@remotion/google-fonts/Creepster";
+import { loadFont as loadHeebo } from "@remotion/google-fonts/Heebo";
+import { loadFont as loadKaushanScript } from "@remotion/google-fonts/KaushanScript";
+import { loadFont as loadLilitaOne } from "@remotion/google-fonts/LilitaOne";
+import { loadFont as loadMrsSaintDelafield } from "@remotion/google-fonts/MrsSaintDelafield";
+import { loadFont as loadOrbitron } from "@remotion/google-fonts/Orbitron";
+import { loadFont as loadOutfit } from "@remotion/google-fonts/Outfit";
+import { loadFont as loadPermanentMarker } from "@remotion/google-fonts/PermanentMarker";
+import { loadFont as loadPlayfairDisplay } from "@remotion/google-fonts/PlayfairDisplay";
+import { loadFont as loadRubik } from "@remotion/google-fonts/Rubik";
+import { loadFont as loadRye } from "@remotion/google-fonts/Rye";
+import { loadFont as loadSyne } from "@remotion/google-fonts/Syne";
+import { loadFont as loadYellowtail } from "@remotion/google-fonts/Yellowtail";
+import { loadFont as loadAlef } from "@remotion/google-fonts/Alef";
+import { loadFont as loadAmaticSC } from "@remotion/google-fonts/AmaticSC";
+import { loadFont as loadAssistant } from "@remotion/google-fonts/Assistant";
+import { loadFont as loadDavidLibre } from "@remotion/google-fonts/DavidLibre";
+import { loadFont as loadFrankRuhlLibre } from "@remotion/google-fonts/FrankRuhlLibre";
+import { loadFont as loadFredoka } from "@remotion/google-fonts/Fredoka";
+import { loadFont as loadKarantina } from "@remotion/google-fonts/Karantina";
+import { loadFont as loadNotoSansHebrew } from "@remotion/google-fonts/NotoSansHebrew";
+import { loadFont as loadSecularOne } from "@remotion/google-fonts/SecularOne";
+import { loadFont as loadSuezOne } from "@remotion/google-fonts/SuezOne";
+import { loadFont as loadVarelaRound } from "@remotion/google-fonts/VarelaRound";
+import { Easing } from "remotion";
+
+// Loaded once for every video. Hero text must never fall back to a system default font.
+const display = loadDisplay("normal", { weights: ["600", "700", "800"], subsets: ["latin"] });
+const body = loadBody("normal", { weights: ["400", "500", "700"], subsets: ["latin"] });
+
+// Heebo is loaded for every video and appended to every family as a fallback, so Hebrew text set in a Latin-only
+// face still renders in a proper Hebrew typeface instead of a system default.
+const hebrewFallback = loadHeebo("normal", { weights: ["400", "700", "900"], subsets: ["hebrew"] }).fontFamily;
+const withHebrew = (family: string) => (family === hebrewFallback ? family : `${family}, ${hebrewFallback}`);
+
+export const fonts = { display: withHebrew(display.fontFamily), body: withHebrew(body.fontFamily) };
+
+// Extra typefaces, loaded only by the videos that ask for them. Call font("montserrat") at the top of a file
+// and use the returned family name. Each loads just the weights listed here.
+const latin = { subsets: ["latin" as const] };
+const hebrew = { subsets: ["hebrew" as const, "latin" as const] };
+const loaders = {
+  montserrat: () => loadMontserrat("normal", { weights: ["300", "800", "900"], ...latin }), // 300 light, 800/900 heavy titles
+  montserratItalic: () => loadMontserrat("italic", { weights: ["800", "900"], ...latin }),
+  kanit: () => loadKanit("normal", { weights: ["600"], ...latin }), // semi-bold, social handles
+  roboto: () => loadRoboto("normal", { weights: ["300", "500", "700", "900"], ...latin }), // interface text
+  robotoSlab: () => loadRobotoSlab("normal", { weights: ["700"], ...latin }), // slab serif titles
+  bebasNeue: () => loadBebasNeue("normal", { weights: ["400"], ...latin }), // tall condensed caps
+  archivoBlack: () => loadArchivoBlack("normal", { weights: ["400"], ...latin }), // very heavy grotesque
+  unbounded: () => loadUnbounded("normal", { weights: ["800", "900"], ...latin }), // wide heavy display
+  modak: () => loadModak("normal", { weights: ["400"], ...latin }), // chunky rounded display
+  greatVibes: () => loadGreatVibes("normal", { weights: ["400"], ...latin }), // formal script
+  sacramento: () => loadSacramento("normal", { weights: ["400"], ...latin }), // monoline script, neon signs
+  // Free stand-ins for commercial or demo faces that cannot be bundled:
+  outfit: () => loadOutfit("normal", { weights: ["100", "300", "500", "900"], ...latin }), // geometric sans, thin to black (for Objective)
+  syne: () => loadSyne("normal", { weights: ["800"], ...latin }), // wide, characterful heavy sans (for Hanson, with unbounded)
+  lilitaOne: () => loadLilitaOne("normal", { weights: ["400"], ...latin }), // heavy rounded sans (for Peace Sans)
+  kaushanScript: () => loadKaushanScript("normal", { weights: ["400"], ...latin }), // bold brush script (for Blacksword)
+  yellowtail: () => loadYellowtail("normal", { weights: ["400"], ...latin }), // flowing brush script (for Brushwell)
+  mrsSaintDelafield: () => loadMrsSaintDelafield("normal", { weights: ["400"], ...latin }), // fine signature script (for Antro Vectra)
+  permanentMarker: () => loadPermanentMarker("normal", { weights: ["400"], ...latin }), // dry marker lettering
+  bungeeShade: () => loadBungeeShade("normal", { weights: ["400"], ...latin }), // outlined, shadowed sign capitals
+  // Genre faces for film-style titles (original designs, not imitations of any film's logo):
+  cinzel: () => loadCinzel("normal", { weights: ["700", "900"], ...latin }), // Roman inscription capitals: epic, historical
+  playfairDisplay: () => loadPlayfairDisplay("normal", { weights: ["700", "900"], ...latin }), // high-contrast serif: elegant, editorial
+  orbitron: () => loadOrbitron("normal", { weights: ["700", "900"], ...latin }), // geometric sci-fi
+  rye: () => loadRye("normal", { weights: ["400"], ...latin }), // western poster
+  creepster: () => loadCreepster("normal", { weights: ["400"], ...latin }), // horror
+  // Hebrew (these also cover Latin):
+  heebo: () => loadHeebo("normal", { weights: ["400", "700", "900"], subsets: ["hebrew", "latin"] }),
+  rubik: () => loadRubik("normal", { weights: ["400", "700", "900"], subsets: ["hebrew", "latin"] }),
+  alef: () => loadAlef("normal", { weights: ["400", "700"], ...hebrew }), // clean, friendly sans
+  assistant: () => loadAssistant("normal", { weights: ["400", "700", "800"], ...hebrew }), // modern sans for interface and body
+  notoSansHebrew: () => loadNotoSansHebrew("normal", { weights: ["400", "700", "900"], ...hebrew }), // neutral sans, full weight range
+  secularOne: () => loadSecularOne("normal", { weights: ["400"], ...hebrew }), // strong headline sans
+  varelaRound: () => loadVarelaRound("normal", { weights: ["400"], ...hebrew }), // soft rounded sans
+  fredoka: () => loadFredoka("normal", { weights: ["500", "700"], ...hebrew }), // playful rounded
+  karantina: () => loadKarantina("normal", { weights: ["400", "700"], ...hebrew }), // tall condensed display
+  suezOne: () => loadSuezOne("normal", { weights: ["400"], ...hebrew }), // heavy serif headline
+  frankRuhlLibre: () => loadFrankRuhlLibre("normal", { weights: ["400", "700", "900"], ...hebrew }), // classic book serif
+  davidLibre: () => loadDavidLibre("normal", { weights: ["400", "700"], ...hebrew }), // traditional serif
+  amaticSC: () => loadAmaticSC("normal", { weights: ["400", "700"], ...hebrew }), // hand-lettered capitals
+};
+export type KitFont = keyof typeof loaders;
+const loaded = new Map<KitFont, string>();
+export function font(name: KitFont): string {
+  let family = loaded.get(name);
+  if (!family) {
+    family = withHebrew(loaders[name]().fontFamily);
+    loaded.set(name, family);
+  }
+  return family;
+}
+
+// Spring presets (stiffness / damping). A tiny overshoot at most: never a cartoon bounce.
+export const springs = {
+  snappy: { stiffness: 320, damping: 30 },
+  smooth: { stiffness: 170, damping: 26 },
+  heavy: { stiffness: 120, damping: 24 },
+};
+
+// Use one of these on every interpolate(). Linear motion looks cheap.
+export const ease = {
+  out: Easing.bezier(0.16, 1, 0.3, 1),
+  in: Easing.bezier(0.7, 0, 0.84, 0),
+  inOut: Easing.bezier(0.65, 0, 0.35, 1),
+};
+
+export type Palette = { bg: string; ink: string; hero: string; accent: string; dim: string };
+
+// One base, one hero colour, one accent. The hero colour goes on at most one element per frame.
+export const palettes: Record<"darkTech" | "warmEditorial" | "warmPremium" | "cleanLight", Palette> = {
+  darkTech: { bg: "#0A0A0F", ink: "#F4F4F5", hero: "#7C3AED", accent: "#22D3EE", dim: "#A1A1AA" },
+  warmEditorial: { bg: "#FAF7F2", ink: "#1F1E1B", hero: "#D97757", accent: "#8A6A4F", dim: "#6B6660" },
+  warmPremium: { bg: "#1A120B", ink: "#F4E9DA", hero: "#E8A33D", accent: "#C9B79C", dim: "#A8977F" },
+  cleanLight: { bg: "#F7F5F2", ink: "#1A1A1A", hero: "#2563EB", accent: "#0EA5E9", dim: "#6B7280" },
+};

package/src/remotion/types.ts

@@ -0,0 +1,2 @@
+import type { AssetManifest } from "../pipeline/schema";
+export type VideoProps = { manifest: AssetManifest; urls: Record<string, string> };

package/src/render/component-preview.ts

@@ -0,0 +1,65 @@
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { renderMedia, selectComposition } from "@remotion/renderer";
+import { bundleProject, disposeBundle } from "./render";
+
+const run = promisify(execFile);
+const NAME = /^[A-Z][A-Za-z0-9]*$/;
+
+export const PREVIEW = { width: 960, height: 600, fps: 30, frames: 105 } as const;
+
+// The generated entry: the kit's default dark background with the example filling the frame. Importing the kit also loads
+// its fonts, which is what makes text render in the kit fonts. `name` is checked against NAME and `example` starts with `<name`,
+// because both are interpolated into this code; the example is trusted seed text from the owner's own repository.
+const entrySource = (name: string, example: string) => `import React from "react";
+import { AbsoluteFill, Composition, registerRoot } from "remotion";
+import { palettes } from "reelkit/kit";
+import { ${name} } from "./${name}";
+
+void ${name};
+const Preview: React.FC = () => (
+  <AbsoluteFill style={{ background: palettes.darkTech.bg }}>
+    ${example}
+  </AbsoluteFill>
+);
+
+registerRoot(() => (
+  <Composition id="Preview" component={Preview} durationInFrames={${PREVIEW.frames}} fps={${PREVIEW.fps}} width={${PREVIEW.width}} height={${PREVIEW.height}} />
+));
+`;
+
+// Renders one component with its example to a short silent MP4 (960x600, 30 fps, 3.5 s, H.264, yuv420p, CRF 28).
+// Everything it creates besides outPath (the temp folder and the bundle) is removed again, also when it fails.
+export async function renderComponentPreview(input: { name: string; source: string; example: string }, outPath: string): Promise<void> {
+  const { name, source, example } = input;
+  if (!NAME.test(name)) throw new Error(`Component name "${name}" must be PascalCase letters and digits.`);
+  if (!example.trimStart().startsWith(`<${name}`)) throw new Error(`The example for ${name} must start with <${name}.`);
+
+  const work = await mkdtemp(join(tmpdir(), "rk-cmp-preview-"));
+  let serveUrl: string | undefined;
+  try {
+    await writeFile(join(work, `${name}.tsx`), source);
+    const entry = join(work, "index.tsx");
+    await writeFile(entry, entrySource(name, example.trim()));
+    serveUrl = await bundleProject(entry);
+    const composition = await selectComposition({ serveUrl, id: "Preview" });
+    const rendered = join(work, "rendered.mp4");
+    await renderMedia({
+      composition, serveUrl, codec: "h264", outputLocation: rendered, crf: 28, pixelFormat: "yuv420p", colorSpace: "bt709", muted: true, logLevel: "error",
+    });
+    // The last pass guarantees no audio stream and the index at the front, whatever Remotion wrote; the video is copied, not re-encoded.
+    const finished = join(work, "final.mp4");
+    await run("ffmpeg", ["-y", "-v", "error", "-i", rendered, "-an", "-movflags", "+faststart", "-c:v", "copy", finished]);
+    await mkdir(dirname(outPath), { recursive: true });
+    await rename(finished, outPath).catch(async () => {
+      // A different file system than the temp folder: copy instead.
+      await run("ffmpeg", ["-y", "-v", "error", "-i", finished, "-c", "copy", "-movflags", "+faststart", outPath]);
+    });
+  } finally {
+    if (serveUrl) await disposeBundle(serveUrl).catch(() => {});
+    await rm(work, { recursive: true, force: true });
+  }
+}

package/src/render/deps.ts

@@ -0,0 +1,8 @@
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+
+const require = createRequire(import.meta.url);
+
+// The directory of an installed dependency of this package, found through its package.json so it does not depend on
+// where the package keeps its main file or on how the package manager lays out node_modules.
+export const packageDir = (name: string): string => dirname(require.resolve(`${name}/package.json`));

package/src/render/render.ts

@@ -0,0 +1,67 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { bundle } from "@remotion/bundler";
+import { renderMedia, renderStill, selectComposition } from "@remotion/renderer";
+import type { VideoProps } from "../remotion/types";
+import { packageDir } from "./deps";
+import { KIT_INDEX, ROOT_FILE } from "./validate";
+
+const ENTRY_SOURCE = `import { registerRoot } from "remotion";
+import { makeRoot } from "reelkit/root";
+import { Video } from "../../src/Video";
+
+registerRoot(makeRoot(Video));
+`;
+
+// The project folder has no node_modules. Each dependency is pinned to the one copy installed with this package, so the
+// kit, Root and the user's composition all share a single react and remotion (a second react breaks hooks).
+export function dependencyAliases(): Record<string, string> {
+  return Object.fromEntries(["react", "react-dom", "remotion"].map((n) => [n, packageDir(n)]));
+}
+
+// Writes the bundler's entry file into the project. The composition itself stays where the user's Claude wrote it.
+export async function writeEntry(projectDir: string): Promise<string> {
+  const dir = join(projectDir, ".reelkit", "build");
+  await rm(dir, { recursive: true, force: true });
+  await mkdir(dir, { recursive: true });
+  const entry = join(dir, "index.ts");
+  await writeFile(entry, ENTRY_SOURCE);
+  return entry;
+}
+
+// Webpack's on-disk cache would only grow, by tens of megabytes per render. It is switched off, and each bundle
+// is deleted by disposeBundle once it has been used.
+export async function bundleProject(entry: string): Promise<string> {
+  return bundle({
+    entryPoint: entry,
+    enableCaching: false,
+    webpackOverride: (config) => ({
+      ...config,
+      resolve: {
+        ...config.resolve,
+        alias: { ...(config.resolve?.alias as Record<string, string> | undefined), ...dependencyAliases(), "reelkit/kit": KIT_INDEX, "reelkit/root": ROOT_FILE },
+      },
+    }),
+  });
+}
+
+export async function disposeBundle(serveUrl: string): Promise<void> {
+  // Only ever remove a folder that is one of Remotion's own temporary bundles.
+  if (/remotion-webpack-bundle-/.test(serveUrl)) await rm(serveUrl, { recursive: true, force: true });
+}
+
+const asInput = (props: VideoProps) => props as unknown as Record<string, unknown>;
+
+export async function renderStills(serveUrl: string, props: VideoProps, frames: number[], outDir: string) {
+  await mkdir(outDir, { recursive: true });
+  const composition = await selectComposition({ serveUrl, id: "Video", inputProps: asInput(props) });
+  for (const frame of frames) {
+    await renderStill({ composition, serveUrl, frame, output: join(outDir, `still-${frame}.png`), inputProps: asInput(props) });
+  }
+}
+
+export async function renderVideo(serveUrl: string, props: VideoProps, outPath: string) {
+  await mkdir(dirname(outPath), { recursive: true });
+  const composition = await selectComposition({ serveUrl, id: "Video", inputProps: asInput(props) });
+  await renderMedia({ composition, serveUrl, codec: "h264", outputLocation: outPath, inputProps: asInput(props) });
+}

package/src/render/validate.ts

@@ -0,0 +1,191 @@
+import { basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import { packageDir } from "./deps";
+
+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$/, "");
+
+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");
+
+export function typecheck(files: string[]): string[] {
+  const program = ts.createProgram(files, {
+    target: ts.ScriptTarget.ES2022,
+    module: ts.ModuleKind.ES2022,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    jsx: ts.JsxEmit.ReactJSX,
+    strict: true,
+    noEmit: true,
+    skipLibCheck: true,
+    esModuleInterop: true,
+    allowImportingTsExtensions: true,
+    baseUrl: PKG_ROOT,
+    paths: {
+      [KIT]: [KIT_INDEX],
+      react: [typesReact],
+      "react/*": [join(typesReact, "*")],
+      remotion: [remotionDir],
+    },
+  });
+  const wanted = new Set(files);
+  return ts
+    .getPreEmitDiagnostics(program)
+    .filter((d) => d.file && wanted.has(d.file.fileName))
+    .map((d) => {
+      const pos = d.file!.getLineAndCharacterOfPosition(d.start ?? 0);
+      return `${basename(d.file!.fileName)} line ${pos.line + 1}: ${ts.flattenDiagnosticMessageText(d.messageText, "\n")}`;
+    });
+}