reelkit-cli 0.8.0 → 0.10.0

package/src/render/render.ts

@@ -1,81 +1,79 @@
-import { mkdir, rm, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { bundle } from "@remotion/bundler";
-import { ensureBrowser, renderMedia, renderStill, selectComposition } from "@remotion/renderer";
-import type { VideoProps } from "../remotion/types";
+import { execFile } from "node:child_process";
+import { cp, mkdir, mkdtemp, rm, writeFile, readdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, basename } from "node:path";
+import { promisify } from "node:util";
+import { build } from "esbuild";
+import type { VideoProps } from "../hyperframes/types";
+import { fontFamilies } from "../hyperframes/fonts";
 import { packageDir } from "./deps";
-import { KIT_INDEX, ROOT_FILE } from "./validate";
+import { KIT_INDEX, PKG_ROOT } 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), and the 3D layer a single three
-// (two copies of three break instanceof checks). User code still may not import them: only the kit does.
+const run = promisify(execFile);
+const HOST = join(PKG_ROOT, "src/hyperframes/host.tsx");
+const FRAME = join(PKG_ROOT, "src/hyperframes/frame.tsx");
 export function dependencyAliases(): Record<string, string> {
-  return Object.fromEntries(["react", "react-dom", "remotion", "three", "@react-three/fiber", "@remotion/three"].map((n) => [n, packageDir(n)]));
+  return Object.fromEntries(["react", "react-dom", "three", "@react-three/fiber"].map((name) => [name, packageDir(name)]));
 }
-
-// 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 });
+  await rm(dir, { recursive: true, force: true }); await mkdir(dir, { recursive: true });
   const entry = join(dir, "index.ts");
-  await writeFile(entry, ENTRY_SOURCE);
+  await writeFile(entry, 'import { mountVideo } from "reelkit/host";\nimport { Video } from "../../src/Video";\nmountVideo(Video);\n');
   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.
+// A self-contained HyperFrames page using the package's copies of React and Three.
 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 },
-      },
-    }),
-  });
+  const dir = await mkdtemp(join(tmpdir(), "reelkit-hyperframes-"));
+  try {
+    await build({ entryPoints: [entry], bundle: true, outfile: join(dir, "composition.js"), platform: "browser", format: "iife", jsx: "automatic", logLevel: "silent", loader: { ".woff2": "file", ".woff": "file", ".ttf": "file" }, define: { "process.env.NODE_ENV": '"production"' }, alias: { ...dependencyAliases(), "reelkit/kit": KIT_INDEX, "reelkit/frame": FRAME, "reelkit/host": HOST } });
+    await mkdir(join(dir, "fonts"));
+    for (const slug of Object.values(fontFamilies)) {
+      const source = packageDir(`@fontsource/${slug}`);
+      await cp(join(source, "files"), join(dir, "fonts", "files"), { recursive: true });
+      const sheets = (await readdir(source)).filter((name) => /^\d+(?:-italic)?\.css$/.test(name));
+      await writeFile(join(dir, "fonts", `${slug}.css`), (await Promise.all(sheets.map((name) => readFile(join(source, name), "utf8")))).join("\n"));
+    }
+    await writeFile(join(dir, "index.html"), '<!doctype html><html><head><meta charset="utf-8"><style>html,body{margin:0;overflow:hidden}#stage{position:relative;overflow:hidden}</style></head><body><div id="stage"></div><script src="props.js"></script><script src="composition.js"></script></body></html>');
+    return dir;
+  } catch (error) { await rm(dir, { recursive: true, force: true }); throw error; }
 }
-
-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 });
+export async function disposeBundle(dir: string): Promise<void> {
+  if (dirname(dir) === tmpdir() && basename(dir).startsWith("reelkit-hyperframes-")) await rm(dir, { recursive: true, force: true });
 }
-
-// Makes sure Remotion's headless browser is installed. onDownload is called once, only when a download is about to begin.
-// Remotion's own progress bar is replaced because it writes to stdout, which --json keeps for the result alone.
 export type EnsureBrowser = (onDownload: () => void) => Promise<void>;
+export const GL_BACKEND = "software" as const;
+export type RenderOptions = { uses3D?: boolean; silent?: boolean; crf?: number };
+export function browserPath(): string | undefined {
+  if (process.env.REELKIT_CHROME_PATH) return process.env.REELKIT_CHROME_PATH;
+  const paths = process.platform === "darwin" ? ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium"] : process.platform === "linux" ? ["/usr/bin/chromium", "/usr/bin/chromium-browser", "/usr/bin/google-chrome"] : [];
+  return paths.find(existsSync);
+}
 export const ensureRenderBrowser: EnsureBrowser = async (onDownload) => {
-  await ensureBrowser({ onBrowserDownload: () => { onDownload(); return { version: null, onProgress: () => {} }; } });
+  if (browserPath()) return;
+  const { resolveHeadlessShellPath } = await import("@hyperframes/engine");
+  const cached = resolveHeadlessShellPath({}) ?? resolveHeadlessShellPath({ chromePath: undefined });
+  if (cached) { process.env.REELKIT_CHROME_PATH = cached; return; }
+  const { install, Browser, resolveBuildId, detectBrowserPlatform, getInstalledBrowsers } = await import("@puppeteer/browsers");
+  const installed = (await getInstalledBrowsers({ cacheDir: join(PKG_ROOT, ".browser") })).find((b) => b.browser === Browser.CHROMEHEADLESSSHELL && existsSync(b.executablePath));
+  if (installed) { process.env.REELKIT_CHROME_PATH = installed.executablePath; return; }
+  const platform = detectBrowserPlatform(); if (!platform) throw new Error("No supported Chrome platform. Set REELKIT_CHROME_PATH.");
+  onDownload();
+  const browser = await install({ browser: Browser.CHROMEHEADLESSSHELL, buildId: await resolveBuildId(Browser.CHROMEHEADLESSSHELL, platform, "stable"), cacheDir: join(PKG_ROOT, ".browser"), platform });
+  process.env.REELKIT_CHROME_PATH = browser.executablePath;
 };
-
-// Remotion's headless browser has no GPU, so three.js needs a software GL. "angle" is the setting that draws WebGL here; it is used only for a film that
-// has a 3D scene, so every 2D render keeps the browser's own defaults and looks exactly as before. This is the one place that says it.
-export const GL_BACKEND = "angle" as const;
-export type RenderOptions = { uses3D?: boolean };
-const chromium = (o?: RenderOptions) => (o?.uses3D ? { chromiumOptions: { gl: GL_BACKEND } } : {});
-
-const asInput = (props: VideoProps) => props as unknown as Record<string, unknown>;
-
-export async function renderStills(serveUrl: string, props: VideoProps, frames: number[], outDir: string, options?: RenderOptions) {
-  await mkdir(outDir, { recursive: true });
-  const composition = await selectComposition({ serveUrl, id: "Video", inputProps: asInput(props), ...chromium(options) });
-  for (const frame of frames) {
-    await renderStill({ composition, serveUrl, frame, output: join(outDir, `still-${frame}.png`), inputProps: asInput(props), ...chromium(options) });
-  }
+async function render(dir: string, props: VideoProps, mode: "stills" | "video", output: string, frames: number[], options?: RenderOptions) {
+  await ensureRenderBrowser(() => {});
+  await writeFile(join(dir, "props.js"), `window.__reelkitProps=${JSON.stringify(props).replace(/</g, "\\u003c")};`);
+  // Isolate engine diagnostics from the CLI's JSON stdout.
+  const request = join(dir, "render-request.json");
+  await writeFile(request, JSON.stringify({ dir, props, mode, output, frames, options, chromePath: browserPath() }));
+  await run(process.execPath, ["--import", join(packageDir("tsx"), "dist/loader.mjs"), join(PKG_ROOT, "src/render/worker.ts"), request], { maxBuffer: 16 * 1024 * 1024 });
 }
-
-export async function renderVideo(serveUrl: string, props: VideoProps, outPath: string, options?: RenderOptions) {
-  await mkdir(dirname(outPath), { recursive: true });
-  const composition = await selectComposition({ serveUrl, id: "Video", inputProps: asInput(props), ...chromium(options) });
-  await renderMedia({ composition, serveUrl, codec: "h264", outputLocation: outPath, inputProps: asInput(props), ...chromium(options) });
+export async function renderStills(dir: string, props: VideoProps, frames: number[], outDir: string, options?: RenderOptions) {
+  await mkdir(outDir, { recursive: true }); await render(dir, props, "stills", outDir, frames, options);
+}
+export async function renderVideo(dir: string, props: VideoProps, outPath: string, options?: RenderOptions) {
+  await mkdir(dirname(outPath), { recursive: true }); await render(dir, props, "video", outPath, [], options);
 }

package/src/render/serve.ts

@@ -0,0 +1,31 @@
+import { randomBytes } from "node:crypto";
+import { createReadStream, statSync } from "node:fs";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { extname, resolve, sep } from "node:path";
+
+const TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8", ".js": "application/javascript", ".css": "text/css",
+  ".json": "application/json", ".woff2": "font/woff2", ".woff": "font/woff", ".ttf": "font/ttf",
+  ".png": "image/png", ".jpg": "image/jpeg", ".svg": "image/svg+xml",
+};
+
+// Serve the generated composition only to localhost, under an unguessable per-render prefix.
+// The generic HyperFrames file server listens on all interfaces; project copy and media URLs stay private here.
+export async function serveComposition(dir: string): Promise<{ url: string; close(): Promise<void> }> {
+  const root = resolve(dir), prefix = `/${randomBytes(16).toString("hex")}/`;
+  const server = createServer((req, res) => {
+    let path: string;
+    try { path = decodeURIComponent((req.url ?? "").split("?")[0]!); } catch { res.writeHead(400).end(); return; }
+    if (!path.startsWith(prefix)) { res.writeHead(404).end(); return; }
+    const file = resolve(root, path.slice(prefix.length) || "index.html");
+    try {
+      if (!file.startsWith(root + sep) || !statSync(file).isFile()) { res.writeHead(404).end(); return; }
+      res.writeHead(200, { "content-type": TYPES[extname(file)] ?? "application/octet-stream", "cache-control": "no-store" });
+      const stream = createReadStream(file); stream.on("error", () => res.destroy()); stream.pipe(res);
+    } catch { res.writeHead(404).end(); }
+  });
+  await new Promise<void>((ready, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", ready); });
+  const port = (server.address() as AddressInfo).port;
+  return { url: `http://127.0.0.1:${port}${prefix}`, close: () => new Promise<void>((ready) => { server.closeAllConnections(); server.close(() => ready()); }) };
+}

package/src/render/static-check.ts

@@ -7,8 +7,19 @@ 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$/, "");
 
+// Upgrade previously published library components without touching on-screen copy or comments.
+export function migrateFrameImports(source: string): string {
+  const parsed = sourceFile(source);
+  const edits: { start: number; end: number }[] = [];
+  for (const node of parsed.statements) {
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "remotion") edits.push({ start: node.moduleSpecifier.getStart(parsed), end: node.moduleSpecifier.getEnd() });
+  }
+  for (const edit of edits.reverse()) source = source.slice(0, edit.start) + '"reelkit/frame"' + source.slice(edit.end);
+  return source;
+}
+
 export const KIT = "reelkit/kit";
-const BASE_IMPORTS = new Set(["react", "remotion", KIT]);
+const BASE_IMPORTS = new Set(["react", "reelkit/frame", 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.
@@ -77,7 +88,7 @@ function inspectSource(source: string, file?: string): Finding {
     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, "Math") && member === "random") forbidden.add("Math.random (use random(seed) from reelkit/frame)");
     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 }`.
@@ -140,8 +151,8 @@ export function staticCheck(source: string, file: string, siblings: string[]): s
     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}.`,
+        ? `${file}: import not allowed: "${s}". Use react, reelkit/frame, ${KIT}, or a component file that exists ("./Name").`
+        : `${file}: import not allowed: "${s}". A component may only import react, reelkit/frame and ${KIT}.`,
     );
   }
   for (const name of found.forbidden) errors.push(`${file}: not allowed: ${name}.`);

package/src/render/validate.ts

@@ -4,15 +4,15 @@ 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 KIT_INDEX = join(PKG_ROOT, "src", "hyperframes", "kit", "index.ts");
+export const ROOT_FILE = join(PKG_ROOT, "src", "hyperframes", "Root.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 typesReact = packageDir("@types/react");
-export const remotionDir = packageDir("remotion");
+export const frameFile = join(PKG_ROOT, "src", "hyperframes", "frame.tsx");
 
 export function typecheck(files: string[]): string[] {
   const program = ts.createProgram(files, {
@@ -30,7 +30,7 @@ export function typecheck(files: string[]): string[] {
       [KIT]: [KIT_INDEX],
       react: [typesReact],
       "react/*": [join(typesReact, "*")],
-      remotion: [remotionDir],
+      "reelkit/frame": [frameFile],
     },
   });
   const wanted = new Set(files);

package/src/render/word-check.ts

@@ -2,7 +2,7 @@
 // the word is in that scene's narration. Pure text in, findings out (the TypeScript syntax tree, never regular expressions on code), so `check`
 // and `preview` can both use it.
 import ts from "typescript";
-import { normalizeWord, wordFrame, type WordScene } from "../remotion/kit/word-anchor";
+import { normalizeWord, wordFrame, type WordScene } from "../hyperframes/kit/word-anchor";
 import { sourceFile, unwrap } from "./static-check";
 
 export const WORD_HELPERS = ["wordFrame", "wordFrames", "onWord", "onWordBeat"] as const;

package/src/render/worker.ts

@@ -0,0 +1,71 @@
+// Internal subprocess: HyperFrames owns capture, encoding and audio mixing.
+import { execFile } from "node:child_process";
+import { cp, mkdir, mkdtemp, rm, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, extname } from "node:path";
+import { promisify } from "node:util";
+import { createCaptureSession, initializeSession, captureFrame, closeCaptureSession, encodeFramesFromDir, processCompositionAudio, muxVideoWithAudio, applyFaststart, type AudioElement } from "@hyperframes/engine";
+import { serveComposition } from "./serve";
+import type { VideoProps } from "../hyperframes/types";
+import type { AudioRecord } from "../hyperframes/frame";
+import type { RenderOptions } from "./render";
+
+const run = promisify(execFile);
+const input = JSON.parse(await readFile(process.argv[2]!, "utf8")) as { dir: string; props: VideoProps; mode: "stills" | "video"; output: string; frames: number[]; options?: RenderOptions; chromePath?: string };
+const m = input.props.manifest, fps = { num: m.fps, den: 1 };
+const work = await mkdtemp(join(tmpdir(), "reelkit-capture-"));
+const server = await serveComposition(input.dir);
+let session: Awaited<ReturnType<typeof createCaptureSession>> | undefined;
+try {
+  session = await createCaptureSession(server.url.replace(/\/$/, ""), work, { width: m.width, height: m.height, fps, format: "png", compositionDurationSeconds: m.totalFrames / m.fps }, async (page) => {
+    await page.evaluate(async () => { await (window as unknown as { __reelkitReady: Promise<void> }).__reelkitReady; });
+  }, { chromePath: input.chromePath, forceScreenshot: true, useDrawElement: false, staticFrameDedup: false, enableBrowserPool: false, browserGpuMode: input.options?.uses3D ? "software" : "auto" });
+  await initializeSession(session);
+  await session.page.evaluate(async () => { await (window as unknown as { __reelkitReady: Promise<void> }).__reelkitReady; });
+  const frames = input.mode === "stills" ? input.frames : Array.from({ length: m.totalFrames }, (_, i) => i);
+  for (const frame of frames) {
+    if (!Number.isInteger(frame) || frame < 0 || frame >= m.totalFrames) throw new Error(`Frame ${frame} is outside the composition.`);
+    const captured = await captureFrame(session, frame, frame / m.fps);
+    if (input.mode === "stills") await cp(captured.path, join(input.output, `still-${frame}.png`));
+  }
+  if (input.mode === "video") {
+    const silent = join(work, "silent.mp4");
+    const encoded = await encodeFramesFromDir(work, "frame_%06d.png", silent, { fps, width: m.width, height: m.height, codec: "h264", pixelFormat: "yuv420p", quality: input.options?.crf ?? 18, preset: "fast" });
+    if (!encoded.success) throw new Error(encoded.error ?? "HyperFrames encoding failed.");
+    const records = input.options?.silent ? [] : await session.page.evaluate(() => [...(window as unknown as { __reelkitAudio: Map<string, AudioRecord> }).__reelkitAudio.values()]);
+    const audio: AudioElement[] = [];
+    const localSources = new Map<string, string>();
+    for (const record of records) {
+      let src = localSources.get(record.src);
+      if (!src) {
+        const response = await fetch(record.src); if (!response.ok) throw new Error(`Audio source returned ${response.status}.`);
+        src = join(work, `source-${localSources.size}${extname(new URL(record.src).pathname) || ".media"}`);
+        await writeFile(src, new Uint8Array(await response.arrayBuffer())); localSources.set(record.src, src);
+      }
+      const info = JSON.parse((await run("ffprobe", ["-v", "error", "-show_format", "-of", "json", src])).stdout) as { format: { duration: string } };
+      let end = Math.min(record.end, record.start + Number(info.format.duration) - record.mediaStart);
+      if (record.loop) {
+        const looped = join(work, `loop-${audio.length}.wav`);
+        await run("ffmpeg", ["-y", "-v", "error", "-stream_loop", "-1", "-i", src, "-t", String(record.end - record.start + record.mediaStart), "-vn", looped]);
+        src = looped; end = record.end;
+      }
+      if (end <= record.start) continue;
+      const keys = [...new Map(record.volumeKeyframes.map((k) => [k.time, k])).values()].sort((a, b) => a.time - b.time);
+      audio.push({ ...record, src, end, volumeKeyframes: keys.length ? keys : undefined });
+    }
+    if (audio.length) {
+      const mixed = join(work, "audio.m4a");
+      const result = await processCompositionAudio(audio, work, join(work, "audio-work"), mixed, m.totalFrames / m.fps);
+      if (!result.success) throw new Error(result.error ?? "HyperFrames audio mixing failed.");
+      const muxed = await muxVideoWithAudio(silent, mixed, input.output, undefined, { audioCodec: "aac" });
+      if (!muxed.success) throw new Error(muxed.error ?? "HyperFrames audio mux failed.");
+    } else {
+      await mkdir(join(work, "faststart"));
+      const result = await applyFaststart(silent, input.output);
+      if (!result.success) throw new Error(result.error ?? "Faststart failed.");
+    }
+  }
+} finally {
+  if (session) await closeCaptureSession(session);
+  await server.close(); await rm(work, { recursive: true, force: true });
+}

package/src/testing/fixtures.ts

@@ -12,7 +12,7 @@ export const PIXEL_PNG = new Uint8Array(Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAE
 
 // A known-good composition, used as the worked example for composition authors.
 export const FIXTURE_COMPOSITION = `import React from "react";
-import { AbsoluteFill, useVideoConfig } from "remotion";
+import { AbsoluteFill, useVideoConfig } from "reelkit/frame";
 import { BgMesh, Captions, FootageLayer, fonts, Grade, Grain, KenBurnsImage, palettes, SceneFrame, Vignette, Voiceover, WordReveal } from "reelkit/kit";
 import type { VideoProps } from "reelkit/kit";
 

package/src/remotion/Root.tsx

@@ -1,31 +0,0 @@
-import React from "react";
-import { Composition } from "remotion";
-import { ManifestContext, UrlsContext } from "./kit/media";
-import type { VideoProps } from "./types";
-
-const EMPTY: VideoProps = { manifest: { fps: 30, width: 1080, height: 1920, totalFrames: 1, scenes: [] }, urls: {} };
-
-export const makeRoot = (Video: React.FC<VideoProps>): React.FC => {
-  const WithMedia: React.FC<VideoProps> = (props) => (
-    <UrlsContext.Provider value={props.urls}>
-      <ManifestContext.Provider value={props.manifest}>
-        <Video {...props} />
-      </ManifestContext.Provider>
-    </UrlsContext.Provider>
-  );
-  return () => (
-  <Composition
-    id="Video"
-    component={WithMedia as unknown as React.FC<Record<string, unknown>>}
-    durationInFrames={1}
-    fps={30}
-    width={1080}
-    height={1920}
-    defaultProps={EMPTY as unknown as Record<string, unknown>}
-    calculateMetadata={({ props }) => {
-      const m = (props as unknown as VideoProps).manifest;
-      return { durationInFrames: m.totalFrames, fps: m.fps, width: m.width, height: m.height };
-    }}
-  />
-);
-};