framefields 2.12.0 → 2.13.0

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { c as CONFIG_FILE, d as writeConfig, i as renderCloud, l as findRender, t as CloudRenderError, u as readConfig } from "./cloud-COid1Ipa.mjs";
-import { t as failedCheck } from "./check-result-Culfu7Nx.mjs";
+import { c as AssetsError, d as runAssets, f as CONFIG_FILE, h as writeConfig, i as renderCloud, l as megabytes, m as readConfig, p as findRender, t as CloudRenderError, u as pullAssets } from "./cloud-Cj1TIme8.mjs";
+import { t as failedCheck } from "./check-result-DZWx73V8.mjs";
 import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path, { basename, dirname, join, posix, relative, resolve, sep } from "node:path";
@@ -343,8 +343,8 @@ const SCRIPTS = {
 	"check:render": "tsc --noEmit -p . && framefields check film --render --json",
 	frames: "tsx src/render.ts frames",
 	grid: "tsx src/render.ts grid",
-	preview: "tsx src/render.ts preview",
-	render: "tsx src/render.ts",
+	preview: "framefields preview film",
+	render: "framefields render film",
 	"render:cloud": "framefields render film --cloud"
 };
 /** The named render `init` records in framefields.json. */
@@ -485,44 +485,30 @@ export async function buildFilm(): Promise<Composition> {
 const RENDER_TS = `import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { HeadlessMediaRenderer, frameCount, startPreview } from "framefields";
+import { HeadlessMediaRenderer, frameCount } from "framefields";
 import { buildFilm } from "./film.js";
 
+// Quick looks at the film: \`npm run frames -- 0 30 60\` and \`npm run grid\`.
+// \`npm run render\` and \`npm run preview\` use the "film" render in
+// framefields.json instead (\`framefields render film\`, \`framefields preview film\`).
+
 // Optional settings such as FRAMEFIELDS_API_KEY (see .env.example).
 const ENV = path.resolve(import.meta.dirname, "../.env");
 if (existsSync(ENV)) process.loadEnvFile(ENV);
 
 const OUT = path.resolve(import.meta.dirname, "../output");
 // \`npm run frames -- 0 30\` needs the \`--\`; pnpm passes it through: drop it.
-const [mode = "video", ...args] = process.argv
+const [mode = "frames", ...args] = process.argv
 	.slice(2)
 	.filter((a) => a !== "--");
 
-if (mode === "preview") {
-	// The page runs film.ts itself and renders it with WebGPU in the browser.
-	const session = await startPreview({
-		entry: new URL("./film.ts", import.meta.url),
-		export: "buildFilm",
-	});
-	console.log(\`Preview at \${session.url}\`);
-	await session.closed; // until its tab closes or the next preview replaces it
-	process.exit(0);
-}
-
 const film = await buildFilm();
 await fs.mkdir(OUT, { recursive: true });
 
-if (mode === "frames") {
-	const renderer = new HeadlessMediaRenderer();
-	for (const frame of (args.length ? args : ["0"]).map(Number)) {
-		const png = await film.renderFrame({ frame, renderer });
-		const file = path.join(OUT, \`f\${String(frame).padStart(4, "0")}.png\`);
-		await fs.writeFile(file, png);
-		console.log(\`Wrote \${path.relative(process.cwd(), file)}\`);
-	}
-} else if (mode === "grid") {
+if (mode === "grid") {
+	const last = frameCount(film.durationMs ?? (await film.computeDuration()), film.fps) - 1;
 	const png = await film.renderFrameGrid({
-		frames: args.length ? args.map(Number) : [...new Set([0, Math.floor((frameCount(film.durationMs ?? await film.computeDuration(), film.fps) - 1) / 2), frameCount(film.durationMs ?? await film.computeDuration(), film.fps) - 1])],
+		frames: args.length ? args.map(Number) : [...new Set([0, Math.floor(last / 2), last])],
 		columns: 4,
 		cellWidth: 480,
 		showLabels: true,
@@ -530,12 +516,13 @@ if (mode === "frames") {
 	await fs.writeFile(path.join(OUT, "grid.png"), png);
 	console.log("Wrote output/grid.png");
 } else {
-	const result = await film.renderVideo({
-		outputPath: path.join(OUT, "output.mp4"),
-		quality: "high",
-	});
-	await result.cleanup?.();
-	console.log(\`Exported \${result.filePath}\`);
+	const renderer = new HeadlessMediaRenderer();
+	for (const frame of (args.length ? args : ["0"]).map(Number)) {
+		const png = await film.renderFrame({ frame, renderer });
+		const file = path.join(OUT, \`f\${String(frame).padStart(4, "0")}.png\`);
+		await fs.writeFile(file, png);
+		console.log(\`Wrote \${path.relative(process.cwd(), file)}\`);
+	}
 }
 
 // Native GPU and encoder threads keep Node alive; always exit explicitly.
@@ -551,7 +538,7 @@ ${run("typecheck")}
 ${run("frames")} -- 0 30 60   # PNGs in output/
 ${run("grid")}                # a contact sheet of the motion
 ${run("preview")}             # play it in the browser
-${run("render")}              # output/output.mp4
+${run("render")}              # output/film.mp4
 ${run("render:cloud")}        # on cloud GPUs, from the pushed commit
 \`\`\`
 
@@ -799,6 +786,27 @@ function shownPath(cwd, root) {
 	return relative(cwd, root) || ".";
 }
 
+//#endregion
+//#region src/cli/project-node.ts
+/**
+* Node arguments to run a CLI worker against the user's project: the
+* project's own tsx loader for a TypeScript entry (TypeScript belongs to the
+* consumer project; init's scaffold has it), and the worker script, from
+* source when the CLI runs from source.
+*/
+function projectNodeArgs(entry, worker) {
+	const source = import.meta.url.endsWith(".ts");
+	const args = source ? ["--conditions=development"] : [];
+	if (source || /\.[cm]?tsx?$/.test(entry)) try {
+		const require = createRequire(resolve("package.json"));
+		args.push("--import", pathToFileURL(require.resolve("tsx")).href);
+	} catch {
+		return { error: "Install the project's tsx dev dependency to load a TypeScript entry." };
+	}
+	args.push(fileURLToPath(new URL(source ? `./${worker}.ts` : `./cli/${worker}.mjs`, import.meta.url)));
+	return args;
+}
+
 //#endregion
 //#region src/cli/check.ts
 /** The worker's IPC result is separate from arbitrary builder stdout/stderr. */
@@ -809,15 +817,8 @@ async function runCheck(options) {
 	const timeout = options.timeoutMs ?? 6e4;
 	if (!Number.isSafeInteger(timeout) || timeout <= 0) throw new Error("--timeout must be a positive integer in milliseconds");
 	const fail = (code, message) => failedCheck(entry, exportName, sdkVersion, code, message);
-	const source = import.meta.url.endsWith(".ts");
-	const args = source ? ["--conditions=development"] : [];
-	if (source || /\.[cm]?tsx?$/.test(entry)) try {
-		const require = createRequire(resolve("package.json"));
-		args.push("--import", pathToFileURL(require.resolve("tsx")).href);
-	} catch {
-		return fail("missing_ts_loader", "Install the project's tsx dev dependency to check a TypeScript entry.");
-	}
-	args.push(fileURLToPath(new URL(source ? "./check-worker.ts" : "./cli/check-worker.mjs", import.meta.url)));
+	const args = projectNodeArgs(entry, "check-worker");
+	if ("error" in args) return fail("missing_ts_loader", args.error);
 	return new Promise((done) => {
 		const child = spawn(process.execPath, args, { stdio: [
 			"ignore",
@@ -883,8 +884,7 @@ async function runCloudRender(o, log, render = renderCloud) {
 		return 2;
 	}
 	const spec = target.name ? findRender(cwd, target.name) : void 0;
-	const codec = o.codec ?? spec?.codec ?? "h264";
-	const outputPath = o.output ?? spec?.output ?? path.join("output", `${target.name ?? path.basename(target.entry ?? "").replace(/\.[^.]+$/, "")}.${codec === "vp9" ? "webm" : "mp4"}`);
+	const outputPath = renderOutput(target, spec, o.codec ?? spec?.codec ?? "h264", o.output);
 	const planWorkers = o.plan && (workers ?? spec?.workers ?? 1) === 1 ? "auto" : workers;
 	const controller = new AbortController();
 	const onSigint = () => {
@@ -909,7 +909,8 @@ async function runCloudRender(o, log, render = renderCloud) {
 			outputPath: o.plan ? void 0 : outputPath,
 			signal: controller.signal,
 			onProgress: narrate,
-			onWarning: (m) => log(`warning: ${m}`)
+			onWarning: (m) => log(`warning: ${m}`),
+			onLog: log
 		});
 		if (o.json) {
 			log(JSON.stringify(result));
@@ -952,6 +953,11 @@ function renderCommand(o) {
 	];
 	return [`framefields render ${o.entry ?? ""} --cloud`.replace("  ", " "), ...flags.filter(([, v]) => v !== void 0).map(([f, v]) => `${f} ${v}`)].join(" ");
 }
+/** What a render named `name` (or the module `entry`) produces, wherever it runs. */
+function renderOutput(target, spec, codec, output) {
+	const base = target.name ?? path.basename(target.entry ?? "").replace(/\.[^.]+$/, "");
+	return output ?? spec?.output ?? path.join("output", `${base}.${codec === "vp9" ? "webm" : "mp4"}`);
+}
 /**
 * What `framefields render [arg]` renders: a render named in framefields.json,
 * or a module path; with no argument, the project's only named render.
@@ -961,7 +967,7 @@ function pickRender(arg, cwd) {
 	const names = Object.keys(renders);
 	if (arg === void 0) {
 		if (names.length === 1) return { name: names[0] };
-		return { error: names.length ? `Name the render: ${names.join(", ")}. \`framefields renders\` lists them.` : `Name a module, e.g. \`framefields render src/film.ts --cloud\`, or add "renders" to ${CONFIG_FILE}.` };
+		return { error: names.length ? `Name the render: ${names.join(", ")}. \`framefields renders\` lists them.` : `Name a module, e.g. \`framefields render src/film.ts\`, or add "renders" to ${CONFIG_FILE}.` };
 	}
 	if (renders[arg]) return { name: arg };
 	if (existsSync(path.resolve(cwd, arg))) return { entry: arg };
@@ -1027,6 +1033,121 @@ function usd(value) {
 	return value > 0 && value < .01 ? "<$0.01" : `$${value.toFixed(2)}`;
 }
 
+//#endregion
+//#region src/cli/local.ts
+/**
+* `framefields render [name|entry]` and `framefields preview [name|entry]`
+* on this machine. They read the same named renders in framefields.json as
+* `--cloud`, so a render goes to the same file wherever it runs.
+*
+* A local render first downloads pinned assets that are missing here; a
+* preview doesn't need to: the page streams them from their bucket.
+*/
+async function runLocal(mode, o, log) {
+	const cwd = o.cwd ?? process.cwd();
+	const target = pickRender(o.entry, cwd);
+	if ("error" in target) {
+		log(target.error);
+		return 2;
+	}
+	const spec = target.name ? findRender(cwd, target.name) : void 0;
+	const entry = path.resolve(cwd, spec?.entry ?? target.entry);
+	const codec = o.codec ?? spec?.codec ?? "h264";
+	if (codec !== "h264" && codec !== "vp9") {
+		log(`--codec must be h264 or vp9, not "${codec}".`);
+		return 2;
+	}
+	const engine = projectEngine(entry);
+	if (!engine) {
+		log("framefields isn't installed in this project: `npm i framefields`.");
+		return 2;
+	}
+	const job = {
+		mode,
+		entry,
+		engine,
+		export: o.export ?? spec?.export ?? "buildFilm",
+		args: spec?.args,
+		select: o.select ?? spec?.select,
+		codec,
+		quality: o.quality ?? spec?.quality,
+		outputPath: path.resolve(cwd, renderOutput(target, spec, codec, o.output)),
+		title: spec?.title ?? target.name
+	};
+	if (mode === "preview" && (job.args !== void 0 || job.select)) log("The preview calls the export without args or select; it shows what the export returns by default.");
+	if (mode === "render" && !await ensureAssets(cwd, log)) return 1;
+	const result = await runWorker(job, cwd);
+	if (!result.ok) {
+		log(result.message);
+		return 1;
+	}
+	if (result.filePath) log(`Rendered ${path.relative(cwd, result.filePath) || result.filePath}`);
+	return result.qaPassed === false ? 1 : 0;
+}
+/** The framefields the film imports, resolved from its module. */
+function projectEngine(entry) {
+	try {
+		return pathToFileURL(createRequire(entry).resolve("framefields")).href;
+	} catch {
+		return;
+	}
+}
+/** Downloads pinned assets missing here; false (after saying why) when it can't. */
+async function ensureAssets(cwd, log) {
+	const assets = readConfig(cwd).config.assets ?? {};
+	if (Object.keys(assets).length === 0) return true;
+	try {
+		const { downloaded, changed } = await pullAssets({
+			cwd,
+			log
+		});
+		if (downloaded.length) {
+			const bytes = downloaded.reduce((n, p) => n + (assets[p]?.size ?? 0), 0);
+			log(`Downloaded ${downloaded.length} pinned assets (${megabytes(bytes)}).`);
+		}
+		if (changed.length) log(`Rendering local edits of pinned assets: ${changed.join(", ")}. \`framefields assets add\` pins them for the cloud.`);
+		return true;
+	} catch (err) {
+		if (!(err instanceof AssetsError)) throw err;
+		log(err.message);
+		return false;
+	}
+}
+function runWorker(job, cwd) {
+	const args = projectNodeArgs(job.entry, "local-worker");
+	if ("error" in args) return Promise.resolve({
+		ok: false,
+		message: args.error
+	});
+	return new Promise((done) => {
+		const child = spawn(process.execPath, args, {
+			cwd,
+			stdio: [
+				"inherit",
+				"inherit",
+				"inherit",
+				"ipc"
+			]
+		});
+		let result;
+		child.on("message", (message) => {
+			result = message;
+		});
+		child.on("error", (error) => done({
+			ok: false,
+			message: error.message
+		}));
+		child.on("close", (code, signal) => done(result ?? (signal === "SIGINT" || code === 130 ? {
+			ok: false,
+			message: "Stopped."
+		} : {
+			ok: false,
+			message: `The ${job.mode} exited without a result (code ${code}, signal ${signal}).`
+		})));
+		child.send(job);
+	});
+}
+
 //#endregion
 //#region src/cli/registry.ts
 /**
@@ -1077,8 +1198,11 @@ function openRegistry(source, cwd = process.cwd()) {
 *   npx framefields list                 the components you can add
 *   npx framefields fonts add <role...>  install fonts (emoji)
 *   npx framefields fonts list           the fonts you can install
+*   npx framefields assets add|push|pull|status   media on your own bucket
 *   npx framefields renders              the renders named in framefields.json
+*   npx framefields render <name>        render on this machine's GPU
 *   npx framefields render <name> --cloud    render on api.framefields.dev
+*   npx framefields preview <name>       play it in the browser
 */
 const HELP = `Usage: framefields <command> [options]
 
@@ -1101,14 +1225,27 @@ Commands:
                   Install fonts (pinned, hash-checked, with their license)
                   and register them in the generated <components>/fonts.ts.
   fonts list      List the fonts you can install.
+  assets add <path...>
+                  Keep media out of git: hash files (or every file in a
+                  folder), upload them to the project's bucket (R2, S3, any
+                  S3-compatible storage) and pin them in framefields.json.
+  assets push     Upload recorded assets the bucket lacks.
+  assets pull     Download missing assets, checked against their sha256.
+  assets status   Which assets are here, missing or changed.
   renders         List the renders named in framefields.json.
-  render [name|entry] --cloud
-                  Render on api.framefields.dev from the pushed commit of
-                  this git repo, and download the video. Needs
-                  FRAMEFIELDS_API_KEY. A render named in framefields.json
+  render [name|entry]
+                  Render on this machine: a render named in framefields.json
                   (its fields are the defaults; flags override them), or a
                   module (--export defaults to buildFilm). Without either,
-                  the project's only named render.
+                  the project's only named render. Pinned assets missing
+                  here are downloaded first.
+  render [name|entry] --cloud
+                  The same render on api.framefields.dev, from the pushed
+                  commit of this git repo, downloaded to the same file.
+                  Needs FRAMEFIELDS_API_KEY.
+  preview [name|entry]
+                  Play it in the browser (localhost, WebGPU). Pinned assets
+                  that aren't here stream from their bucket.
 
 Options for check:
   --export <name>   Composition or builder export (default buildFilm).
@@ -1118,6 +1255,10 @@ Options for check:
   --warnings-as-errors  Fail on lint warnings.
   --json            Machine-readable check, component list, or font list result.
 
+Options for render and preview:
+  --export, --select, --codec, --quality and --output (render) override the
+  named render's fields, locally and with --cloud.
+
 Options for render --cloud:
   --workers <n|auto>  1 (default) renders on one GPU. auto measures the film
                     first and splits it across as many GPUs as stay
@@ -1132,6 +1273,14 @@ Options for render --cloud:
   --json            Print the final status as JSON.
   Ctrl-C cancels the render; GPU time already used is charged.
 
+Options for assets:
+  --remote <name>   The remote in framefields.json "storage" (default: its
+                    default, or its only one).
+  --overwrite       pull: replace files changed locally.
+  Keys: FRAMEFIELDS_STORAGE_<REMOTE>_ACCESS_KEY_ID and _SECRET_ACCESS_KEY,
+  or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Reads need none when the
+  remote has a publicUrl (a custom domain or CDN in front of the bucket).
+
 Options for init:
   --name <name>     Package name (default: the folder's name).
   --pm <manager>    npm, pnpm, yarn or bun (default: the one running this).
@@ -1159,6 +1308,9 @@ Examples:
   npx framefields init my-film --install
   npx framefields add mouse-pointer focus-zoom
   npx framefields fonts add emoji
+  npx framefields assets add assets/footage
+  npx framefields preview film
+  npx framefields render film
   npx framefields render film --cloud --plan
 `;
 async function main(argv) {
@@ -1191,6 +1343,7 @@ async function main(argv) {
 			codec: { type: "string" },
 			quality: { type: "string" },
 			select: { type: "string" },
+			remote: { type: "string" },
 			help: {
 				type: "boolean",
 				short: "h"
@@ -1203,6 +1356,7 @@ async function main(argv) {
 		return command || values.help ? 0 : 1;
 	}
 	const cwd = process.cwd();
+	if (existsSync(join(cwd, ".env"))) process.loadEnvFile(join(cwd, ".env"));
 	const log = (line) => process.stdout.write(`${line}\n`);
 	if (command === "api") {
 		const catalog = JSON.parse(readFileSync(fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "../dist/api.json" : "./api.json", import.meta.url)), "utf8"));
@@ -1214,9 +1368,30 @@ async function main(argv) {
 	}
 	if (command === "check") return check(names, cwd, values, log);
 	if (command === "renders") return listRenders(cwd, values.json, log);
+	if (command === "assets") return runAssets(names, {
+		cwd,
+		log,
+		remote: values.remote,
+		overwrite: values.overwrite,
+		json: values.json
+	});
+	if (command === "preview" || command === "render" && !values.cloud) {
+		if (names.length > 1) {
+			process.stderr.write(`Usage: framefields ${command} [name|entry] [--export <name>]\n`);
+			return 2;
+		}
+		return runLocal(command === "preview" ? "preview" : "render", {
+			entry: names[0],
+			export: values.export,
+			select: values.select,
+			codec: values.codec,
+			quality: values.quality,
+			output: values.output
+		}, log);
+	}
 	if (command === "render") {
-		if (names.length > 1 || !values.cloud) {
-			process.stderr.write("Usage: framefields render [name|entry] --cloud [--workers auto] [--plan]\nLocal renders run your project's render script (`npm run render`).\n");
+		if (names.length > 1) {
+			process.stderr.write("Usage: framefields render [name|entry] --cloud [--workers auto] [--plan]\n");
 			return 2;
 		}
 		return runCloudRender({