framefields 2.11.0 → 2.13.0

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { i as renderCloud, t as CloudRenderError } from "./cloud-xcfV4J03.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";
@@ -9,34 +9,6 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 
-//#region src/cli/config.ts
-/**
-* `framefields.json` at the project root: where installed components live,
-* and which fonts `framefields add` / `framefields fonts add` installed.
-*/
-const CONFIG_FILE = "framefields.json";
-/** The project's config, or the default it would get: `src/components` when there is a `src`. */
-function readConfig(cwd) {
-	const file = join(cwd, CONFIG_FILE);
-	if (existsSync(file)) {
-		const config = JSON.parse(readFileSync(file, "utf8"));
-		if (typeof config.components !== "string") throw new Error(`${CONFIG_FILE}: "components" must be a directory path`);
-		if (config.fonts !== void 0 && (typeof config.fonts !== "object" || Object.values(config.fonts).some((v) => typeof v !== "string"))) throw new Error(`${CONFIG_FILE}: "fonts" must map roles to font file paths, e.g. { "emoji": "assets/fonts/NotoColorEmoji.ttf" }`);
-		return {
-			config,
-			saved: true
-		};
-	}
-	return {
-		config: { components: existsSync(join(cwd, "src")) ? "src/components" : "components" },
-		saved: false
-	};
-}
-function writeConfig(cwd, config) {
-	writeFileSync(join(cwd, CONFIG_FILE), `${JSON.stringify(config, null, "	")}\n`);
-}
-
-//#endregion
 //#region src/cli/fonts.ts
 /**
 * Fonts the CLI installs into a project: a catalog of pinned files (URL,
@@ -308,7 +280,10 @@ async function add(names, options) {
 		report.written.push(shown);
 	}
 	if (!saved) {
-		writeConfig(cwd, { components: relative(cwd, dir) || "." });
+		writeConfig(cwd, {
+			...config,
+			components: relative(cwd, dir) || "."
+		});
 		report.configWritten = true;
 	}
 	const needs = /* @__PURE__ */ new Map();
@@ -344,11 +319,6 @@ async function add(names, options) {
 //#endregion
 //#region src/cli/templates.ts
 /**
-* The files `framefields init` writes: the project layout the framefields
-* setup skill describes. `film.ts` only builds; `render.ts` renders frames,
-* a grid, the live preview or the video; `theme.ts` holds the numbers.
-*/
-/**
 * Packages with install scripts. framefields needs exactly one (skia-canvas
 * downloads its native binary); the others work without theirs.
 */
@@ -369,14 +339,24 @@ const DEV_DEPENDENCIES = {
 };
 const SCRIPTS = {
 	typecheck: "tsc --noEmit -p .",
-	check: "tsc --noEmit -p . && framefields check src/film.ts --json",
-	"check:render": "tsc --noEmit -p . && framefields check src/film.ts --render --json",
+	check: "tsc --noEmit -p . && framefields check film --json",
+	"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",
-	"render:cloud": "framefields render src/film.ts --cloud --workers auto"
+	preview: "framefields preview film",
+	render: "framefields render film",
+	"render:cloud": "framefields render film --cloud"
 };
+/** The named render `init` records in framefields.json. */
+function defaultRenders(name) {
+	return { film: {
+		title: name,
+		entry: "src/film.ts",
+		export: "buildFilm",
+		workers: "auto",
+		output: "output/film.mp4"
+	} };
+}
 /**
 * The `package.json` fields a framefields project needs. npm reads
 * `allowScripts`, pnpm its `pnpm` block, bun `trustedDependencies`.
@@ -505,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,
@@ -550,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.
@@ -571,10 +538,13 @@ ${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
 \`\`\`
 
+- \`framefields.json\` names the renders: \`film\` is \`buildFilm\` in \`src/film.ts\`. Add an
+  entry under \`renders\` for each cut (a teaser, a vertical edit) and render or check it by
+  name: \`npx framefields render teaser --cloud\`, \`npx framefields check teaser\`.
 - \`src/film.ts\` builds the composition, \`src/theme.ts\` holds sizes, colors and fonts,
   \`src/render.ts\` renders it.
 - \`npx framefields list\` shows ready-made components; \`npx framefields add <name>\` copies
@@ -687,10 +657,14 @@ async function init(options) {
 		}
 	}
 	for (const [path$1, lines] of [[".gitignore", GITIGNORE], [".gitattributes", GITATTRIBUTES]]) record(report, path$1, appendLines(join(root, path$1), lines));
+	const configExisted = existsSync(join(root, CONFIG_FILE));
 	const { config, saved } = readConfig(root);
-	if (!saved) {
-		writeConfig(root, config);
-		report.written.push("framefields.json");
+	if (!saved || !config.renders) {
+		writeConfig(root, {
+			...config,
+			renders: config.renders ?? defaultRenders(basename(root))
+		});
+		record(report, CONFIG_FILE, configExisted || "written");
 	}
 	const installFonts = options.fonts !== false;
 	const installEmoji = options.emoji ?? installFonts;
@@ -812,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. */
@@ -822,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",
@@ -872,14 +860,17 @@ function isCheckReport(value) {
 //#endregion
 //#region src/cli/cloud.ts
 /**
-* `framefields render <entry> --cloud`: renders the project on
-* api.framefields.dev and downloads the video. Prints one plain line per
-* phase, and a progress line at most every 10 seconds while frames render.
+* `framefields render <name|entry> --cloud`: renders the project on
+* api.framefields.dev and downloads the video. `name` is a render in
+* framefields.json; a module path renders without one. Prints one plain
+* line per phase, and a progress line at most every 10 seconds while
+* frames render.
 */
 const PROGRESS_EVERY_MS = 1e4;
 async function runCloudRender(o, log, render = renderCloud) {
+	const cwd = o.cwd ?? process.cwd();
 	const workers = parseWorkers(o.workers);
-	if (workers === void 0) {
+	if (workers === null) {
 		log(`--workers must be "auto" or a positive whole number, not "${o.workers}".`);
 		return 2;
 	}
@@ -887,8 +878,14 @@ async function runCloudRender(o, log, render = renderCloud) {
 		log(`--codec must be h264 or vp9, not "${o.codec}".`);
 		return 2;
 	}
-	const codec = o.codec ?? "h264";
-	const outputPath = o.output ?? path.join("output", `${path.basename(o.entry).replace(/\.[^.]+$/, "")}.${codec === "vp9" ? "webm" : "mp4"}`);
+	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 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 = () => {
 		log("Cancelling the cloud render…");
@@ -899,25 +896,33 @@ async function runCloudRender(o, log, render = renderCloud) {
 	const narrate = narrator(o.json ? () => {} : log, Date.now);
 	try {
 		const result = await render({
-			entry: o.entry,
+			cwd,
+			render: target.name,
+			entry: target.entry,
 			export: o.export,
 			select: o.select,
-			workers: o.plan && workers === 1 ? "auto" : workers,
+			workers: planWorkers,
 			maxWorkers: o.maxWorkers ? Number(o.maxWorkers) : void 0,
-			codec,
+			codec: o.codec,
 			quality: o.quality,
 			dryRun: o.plan,
 			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));
 			return 0;
 		}
 		if (result.status === "planned") {
-			log(`Render it: framefields render ${o.entry} --cloud --workers ${o.workers ?? "auto"}`);
+			const planned = planWorkers === "auto" && spec?.workers !== "auto";
+			log(`Render it: ${renderCommand({
+				...o,
+				entry: target.name ?? target.entry,
+				workers: o.workers ?? (planned ? "auto" : void 0)
+			})}`);
 			return 0;
 		}
 		const bytes = result.output?.bytes;
@@ -935,11 +940,45 @@ async function runCloudRender(o, log, render = renderCloud) {
 		process.removeListener("SIGINT", onSigint);
 	}
 }
+/** The command that renders what `--plan` just planned: the same options, without `--plan`. */
+function renderCommand(o) {
+	const flags = [
+		["--export", o.export],
+		["--select", o.select],
+		["--workers", o.workers],
+		["--max-workers", o.maxWorkers],
+		["--codec", o.codec],
+		["--quality", o.quality],
+		["--output", o.output]
+	];
+	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.
+*/
+function pickRender(arg, cwd) {
+	const renders = readConfig(cwd).config.renders ?? {};
+	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\`, or add "renders" to ${CONFIG_FILE}.` };
+	}
+	if (renders[arg]) return { name: arg };
+	if (existsSync(path.resolve(cwd, arg))) return { entry: arg };
+	return { error: names.length ? `"${arg}" is neither a render in ${CONFIG_FILE} (${names.join(", ")}) nor a file.` : `"${arg}" is not a file, and ${CONFIG_FILE} names no renders.` };
+}
+/** --workers: undefined when not given, null when invalid. */
 function parseWorkers(value) {
-	if (value === void 0) return 1;
+	if (value === void 0) return void 0;
 	if (value === "auto") return "auto";
 	const n = Number(value);
-	return Number.isInteger(n) && n >= 1 ? n : void 0;
+	return Number.isInteger(n) && n >= 1 ? n : null;
 }
 /** Turns status polls into log lines: one per phase, throttled frame progress. */
 function narrator(log, now) {
@@ -994,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
 /**
@@ -1044,14 +1198,21 @@ 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 render <entry> --cloud   render on api.framefields.dev
+*   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]
 
 Commands:
   api             JSON reference generated from timing, grid and check types.
-  check <entry>   Build, validate and lint a composition; --render also writes a
-                  representative frame and grid. --export defaults to buildFilm.
+  check [name|entry]
+                  Build, validate and lint a composition; --render also writes a
+                  representative frame and grid. A render named in
+                  framefields.json, or a module (--export defaults to
+                  buildFilm); with neither, every named render.
   init [dir]      Start a framefields project in dir (default: here), or add
                   framefields to the project there: package.json, tsconfig,
                   src/theme.ts, film.ts, render.ts, assets/, .gitignore,
@@ -1064,10 +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.
-  render <entry> --cloud
-                  Render on api.framefields.dev from the pushed commit of
-                  this git repo, and download the video. Needs
-                  FRAMEFIELDS_API_KEY. --export defaults to buildFilm.
+  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]
+                  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. 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).
@@ -1077,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
@@ -1084,13 +1266,21 @@ Options for render --cloud:
   --max-workers <n> Upper bound for auto.
   --plan            Measure and plan only: prints workers, time and the
                     estimated cost, renders nothing.
-  --output <file>   Where the video goes (default output/<entry>.mp4).
+  --output <file>   Where the video goes (default output/<name>.mp4).
   --codec <codec>   h264 (default) or vp9.
   --quality <q>     very_low, low, high or very_high (default).
   --select <name>   When the export returns several compositions.
   --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).
@@ -1118,7 +1308,10 @@ Examples:
   npx framefields init my-film --install
   npx framefields add mouse-pointer focus-zoom
   npx framefields fonts add emoji
-  npx framefields render src/film.ts --cloud --workers auto --plan
+  npx framefields assets add assets/footage
+  npx framefields preview film
+  npx framefields render film
+  npx framefields render film --cloud --plan
 `;
 async function main(argv) {
 	const { values, positionals } = parseArgs({
@@ -1150,6 +1343,7 @@ async function main(argv) {
 			codec: { type: "string" },
 			quality: { type: "string" },
 			select: { type: "string" },
+			remote: { type: "string" },
 			help: {
 				type: "boolean",
 				short: "h"
@@ -1162,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"));
@@ -1171,30 +1366,32 @@ async function main(argv) {
 		}));
 		return 0;
 	}
-	if (command === "check") {
-		if (names.length !== 1) {
-			process.stderr.write("Usage: framefields check <entry> [--export buildFilm] [--render] [--json]\n");
+	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;
 		}
-		const report$1 = await runCheck({
+		return runLocal(command === "preview" ? "preview" : "render", {
 			entry: names[0],
-			exportName: values.export,
-			render: values.render,
-			outputDir: values.output,
-			timeoutMs: values.timeout === void 0 ? void 0 : Number(values.timeout),
-			warningsAsErrors: values["warnings-as-errors"]
-		});
-		if (values.json) log(JSON.stringify(report$1));
-		else {
-			log(`Check ${report$1.status}: ${report$1.entry} (${report$1.exportName})`);
-			for (const d of report$1.diagnostics) log(`${d.severity} ${d.code}${d.path ? ` at ${d.path}` : ""}: ${d.message}`);
-			for (const file of report$1.artifacts) log(`Wrote ${file}`);
-		}
-		return report$1.status === "passed" ? 0 : 1;
+			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 <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({
@@ -1284,6 +1481,75 @@ async function main(argv) {
 }
 const onDownload = (spec) => process.stdout.write(`  fetching   ${spec.file} (${(spec.font.bytes / 1e6).toFixed(1)} MB, ${spec.license.id})\n`);
 /** What `add` did about fonts, and how to use them. */
+/** `check [name|entry]`: a named render, a module, or every named render. */
+async function check(names, cwd, values, log) {
+	const renders = readConfig(cwd).config.renders ?? {};
+	const usage = () => {
+		process.stderr.write("Usage: framefields check [name|entry] [--export buildFilm] [--render] [--json]\n");
+		return 2;
+	};
+	if (names.length > 1) return usage();
+	const targets = names.length === 0 ? Object.entries(renders).map(([name, spec]) => ({
+		name,
+		entry: spec.entry,
+		exportName: spec.export
+	})) : renders[names[0]] ? [{
+		name: names[0],
+		entry: renders[names[0]].entry,
+		exportName: values.export ?? renders[names[0]].export
+	}] : [{
+		entry: names[0],
+		exportName: values.export
+	}];
+	if (targets.length === 0) return usage();
+	const reports = [];
+	for (const t of targets) {
+		const report = await runCheck({
+			entry: t.entry,
+			exportName: t.exportName,
+			render: values.render,
+			outputDir: values.output ?? (targets.length > 1 ? join("output", "check", t.name ?? "") : void 0),
+			timeoutMs: values.timeout === void 0 ? void 0 : Number(values.timeout),
+			warningsAsErrors: values["warnings-as-errors"]
+		});
+		reports.push({
+			...t.name && { name: t.name },
+			...report
+		});
+		if (values.json) continue;
+		log(`Check ${report.status}: ${t.name ? `${t.name} (${t.entry}, ${report.exportName})` : `${report.entry} (${report.exportName})`}`);
+		for (const d of report.diagnostics) log(`${d.severity} ${d.code}${d.path ? ` at ${d.path}` : ""}: ${d.message}`);
+		for (const file of report.artifacts) log(`Wrote ${file}`);
+	}
+	const passed = reports.every((r) => r.status === "passed");
+	if (values.json) log(JSON.stringify(names.length === 0 ? {
+		status: passed ? "passed" : "failed",
+		checks: reports
+	} : reports[0]));
+	return passed ? 0 : 1;
+}
+/** `renders`: what framefields.json names, as the dashboard shows it. */
+function listRenders(cwd, json, log) {
+	const renders = readConfig(cwd).config.renders ?? {};
+	if (json) {
+		log(JSON.stringify({
+			schemaVersion: 1,
+			renders
+		}));
+		return 0;
+	}
+	const entries = Object.entries(renders);
+	if (entries.length === 0) {
+		log("framefields.json names no renders. Add one: \"renders\": { \"film\": { \"entry\": \"src/film.ts\", \"export\": \"buildFilm\" } }");
+		return 0;
+	}
+	for (const [name, spec] of entries) {
+		const title = spec.title && spec.title !== name ? `  ${spec.title}` : "";
+		const opts = [spec.workers !== void 0 && `workers ${spec.workers}`, spec.codec].filter(Boolean);
+		log(`${name}${title}\n  ${spec.entry} · ${spec.export ?? "buildFilm"}${spec.select ? ` · ${spec.select}` : ""}${opts.length ? ` · ${opts.join(", ")}` : ""}${spec.description ? `\n  ${spec.description}` : ""}`);
+	}
+	return 0;
+}
 function logFonts(report, cwd, log) {
 	for (const f of report.fonts) log(`  ${f.status === "installed" ? "font      " : "font ok   "} ${f.path} (${f.role}, for ${f.by}: ${f.why})`);
 	for (const f of report.fontsSkipped) log(`  no font    ${f.role} for ${f.by} (--no-fonts): ${f.why} Install later with \`framefields fonts add ${f.role}\`.`);