framefields 2.5.5 → 2.6.0

package/dist/cli.mjs

@@ -1,17 +1,15 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, join, posix, relative, resolve, sep } from "node:path";
+import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 
-//#region src/cli/add.ts
+//#region src/cli/config.ts
 /**
-* `framefields add`: copy components' source into a project, the way a
-* shadcn-style registry does. The code becomes the project's own; it
-* imports only `framefields` and `framefields/components` (the toolkit),
-* plus any component it builds on, which is installed alongside it.
-*
-* Where they go is remembered in `framefields.json` at the project root.
+* `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`. */
@@ -20,6 +18,7 @@ function readConfig(cwd) {
 	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
@@ -30,6 +29,236 @@ function readConfig(cwd) {
 		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,
+* size, SHA-256, license), the installer `framefields add` and
+* `framefields fonts add` share, and the generated `fonts.ts` module that
+* registers whatever is installed.
+*
+* framefields ships no fonts in its package (a color emoji font alone is
+* ~10 MB); they're fetched when a project needs one, verified byte for byte,
+* and saved with their license next to them.
+*/
+const NOTO_EMOJI = "https://raw.githubusercontent.com/googlefonts/noto-emoji/v2.051";
+/** google/fonts at one commit: Inter and JetBrains Mono. */
+const GOOGLE_FONTS = "https://raw.githubusercontent.com/google/fonts/e7db6ca603fd4862010383ff17ffd6cc4ffac1c0";
+/** Installable fonts by role. */
+const FONTS = {
+	emoji: {
+		label: "Noto Color Emoji 2.051: color emoji in any text (🎉 ❤️ 👍)",
+		file: "NotoColorEmoji.ttf",
+		font: {
+			url: `${NOTO_EMOJI}/fonts/NotoColorEmoji.ttf`,
+			sha256: "72a635cb3d2f3524c51620cdde406b217204e8a6a06c6a096ff8ed4b5fd6e27b",
+			bytes: 10673480
+		},
+		license: {
+			id: "OFL-1.1",
+			file: "NotoColorEmoji-OFL.txt",
+			url: `${NOTO_EMOJI}/fonts/LICENSE`,
+			sha256: "6a73f9541c2de74158c0e7cf6b0a58ef774f5a780bf191f2d7ec9cc53efe2bf2",
+			bytes: 4301
+		},
+		register: { emoji: true }
+	},
+	sans: googleFont({
+		label: "Inter 4: the built-in themes' display and body face",
+		file: "Inter.ttf",
+		family: "Inter",
+		path: "ofl/inter/Inter%5Bopsz,wght%5D.ttf",
+		sha256: "29160a80ff49ddcab2c97711247e08b1fab27a484a329ce8b813d820dc559031",
+		bytes: 876576,
+		license: {
+			path: "ofl/inter/OFL.txt",
+			sha256: "5b9321a4298cfeb6b34354164a1c3afc3db114569984c502b9b35d988fd58c57",
+			bytes: 4377
+		}
+	}),
+	mono: googleFont({
+		label: "JetBrains Mono 2: the built-in themes' code and terminal face",
+		file: "JetBrainsMono.ttf",
+		family: "JetBrains Mono",
+		path: "ofl/jetbrainsmono/JetBrainsMono%5Bwght%5D.ttf",
+		sha256: "48715a42ec242c21e9f02692891e147d022299a52e48d5e413e1a942193ffeda",
+		bytes: 187208,
+		license: {
+			path: "ofl/jetbrainsmono/OFL.txt",
+			sha256: "b2fe5e8987594e9ffd1d2ca52a2f5d73eb8335243893c5d6254b5ad69269591d",
+			bytes: 4399
+		}
+	})
+};
+/** google/fonts, pinned to one commit. */
+function googleFont(o) {
+	const at = (path$1) => `${GOOGLE_FONTS}/${path$1}`;
+	return {
+		label: o.label,
+		file: o.file,
+		font: {
+			url: at(o.path),
+			sha256: o.sha256,
+			bytes: o.bytes
+		},
+		license: {
+			url: at(o.license.path),
+			sha256: o.license.sha256,
+			bytes: o.license.bytes,
+			id: "OFL-1.1",
+			file: o.file.replace(/\.ttf$/, "-OFL.txt")
+		},
+		register: { family: o.family }
+	};
+}
+/** Where fonts go when `framefields.json` names no place: the setup skill's layout. */
+const DEFAULT_FONTS_DIR = "assets/fonts";
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** A project-relative path with forward slashes, as `framefields.json` keeps it. */
+const projectPath = (cwd, path$1) => relative(cwd, path$1).split(sep).join(posix.sep);
+/** Install the font for `role` into the project and record it in `framefields.json`. */
+async function installFont(role, options) {
+	const catalog = options.catalog ?? FONTS;
+	const spec = catalog[role];
+	if (!spec) throw new Error(`Unknown font "${role}". Fonts framefields can install: ${Object.keys(catalog).join(", ")}.`);
+	const { cwd } = options;
+	const { config } = readConfig(cwd);
+	const configured = config.fonts?.[role];
+	if (configured && existsSync(resolve(cwd, configured))) return {
+		role,
+		path: configured,
+		status: "configured"
+	};
+	const target = resolve(cwd, options.dir ?? DEFAULT_FONTS_DIR, spec.file);
+	const path$1 = projectPath(cwd, target);
+	let status = "present";
+	const current = existsSync(target) ? readFileSync(target) : null;
+	if (!current || sha256(current) !== spec.font.sha256) {
+		if (current && !options.overwrite) throw new Error(`${path$1} exists but isn't the pinned ${spec.file}. Pass --overwrite to replace it, or point "fonts.${role}" in framefields.json at it to keep using yours.`);
+		options.onDownload?.(spec);
+		const get = options.fetch ?? fetch;
+		const [font, license] = await Promise.all([download(spec.font, get), download(spec.license, get)]);
+		mkdirSync(dirname(target), { recursive: true });
+		writeFileSync(target, font);
+		writeFileSync(join(dirname(target), spec.license.file), license);
+		status = "installed";
+	}
+	writeConfig(cwd, {
+		...config,
+		fonts: {
+			...config.fonts,
+			[role]: path$1
+		}
+	});
+	return {
+		role,
+		path: path$1,
+		status
+	};
+}
+async function download(file, get) {
+	let res;
+	try {
+		res = await get(file.url);
+	} catch (error) {
+		throw new Error(`Couldn't download ${file.url} (${error instanceof Error ? error.message : String(error)}). Check the connection, or download it yourself and point framefields.json "fonts" at it.`);
+	}
+	if (!res.ok) throw new Error(`${file.url}: ${res.status} ${res.statusText}`);
+	const bytes = new Uint8Array(await res.arrayBuffer());
+	const hash = sha256(bytes);
+	if (bytes.length !== file.bytes || hash !== file.sha256) throw new Error(`${file.url} isn't the pinned file (got ${bytes.length} bytes, sha256 ${hash}; expected ${file.bytes}, ${file.sha256}). Nothing was written.`);
+	return bytes;
+}
+/** First line of the generated module: files without it are the user's and left alone. */
+const FONTS_MODULE_MARKER = "// Generated by framefields from framefields.json.";
+/**
+* Write `<components>/fonts.ts`, which registers every font in
+* `framefields.json`. Call it once before building or rendering:
+* `await registerFonts()`.
+*/
+function writeFontsModule(cwd, componentsDir, catalog = FONTS) {
+	const { config } = readConfig(cwd);
+	const target = join(componentsDir, "fonts.ts");
+	const path$1 = projectPath(cwd, target);
+	const fonts$1 = Object.entries(config.fonts ?? {}).filter(([role]) => catalog[role]).sort(([a], [b]) => a.localeCompare(b)).map(([role, file]) => {
+		const from = relative(componentsDir, resolve(cwd, file)).split(sep).join(posix.sep);
+		const url = from.startsWith(".") ? from : `./${from}`;
+		return {
+			register: catalog[role].register,
+			url
+		};
+	});
+	const call = (r, source) => "family" in r ? `register({ family: ${JSON.stringify(r.family)}, source: ${source} })` : `registerEmojiFont(${source})`;
+	const calls = fonts$1.map((f) => `await FontManager.${call(f.register, `asset("${f.url}")`)};`);
+	const content = `${FONTS_MODULE_MARKER}
+// \`framefields add\` and \`framefields fonts add\` rewrite it when fonts
+// change; register any other fonts in your own code.
+import { FontManager } from "framefields";
+
+/** A path next to this file as a URL: works in Node and in the browser preview. */
+const asset = (path: string) => new URL(path, import.meta.url).href;
+
+/**
+ * Register the fonts this project installed with framefields. Call it
+ * once, before building any text or rendering:
+ *
+ * \`\`\`ts
+ * await registerFonts();
+ * \`\`\`
+ */
+export async function registerFonts(): Promise<void> {
+${fonts$1.map((f) => "family" in f.register ? `\tawait FontManager.register({\n\t\tfamily: ${JSON.stringify(f.register.family)},\n\t\tsource: asset("${f.url}"),\n\t});` : `\tawait FontManager.registerEmojiFont(\n\t\tasset("${f.url}"),\n\t);`).join("\n")}
+}
+`;
+	if (existsSync(target)) {
+		const current = readFileSync(target, "utf8");
+		if (current === content) return {
+			path: path$1,
+			status: "unchanged",
+			calls
+		};
+		if (!current.startsWith(FONTS_MODULE_MARKER)) return {
+			path: path$1,
+			status: "skipped",
+			calls
+		};
+	}
+	mkdirSync(componentsDir, { recursive: true });
+	writeFileSync(target, content);
+	return {
+		path: path$1,
+		status: "written",
+		calls
+	};
+}
+/**
+* A hint when fonts land in a Git repo whose `.gitattributes` doesn't send
+* them to LFS (a 10 MB binary bloats every clone), or null.
+*/
+function lfsHint(cwd, fontPath) {
+	if (!existsSync(join(cwd, ".git"))) return null;
+	const attrs = join(cwd, ".gitattributes");
+	const text = existsSync(attrs) ? readFileSync(attrs, "utf8") : "";
+	if (/\.ttf\b[^\n]*filter=lfs/.test(text)) return null;
+	return `Fonts are large binaries: track them with Git LFS, e.g. \`git lfs track "${posix.dirname(fontPath)}/**/*.ttf"\`.`;
+}
+
+//#endregion
+//#region src/cli/add.ts
+/**
+* `framefields add`: copy components' source into a project, the way a
+* shadcn-style registry does. The code becomes the project's own; it
+* imports only `framefields` and `framefields/components` (the toolkit),
+* plus any component it builds on, which is installed alongside it.
+*
+* Where they go is remembered in `framefields.json` at the project root.
+* Components that draw with fonts beyond the theme's (emoji) get them
+* installed too, plus a generated `fonts.ts` that registers them.
+*/
 /** Resolve `names` (and what they import) and write their files. */
 async function add(names, options) {
 	const { cwd, registry } = options;
@@ -54,7 +283,9 @@ async function add(names, options) {
 		written: [],
 		unchanged: [],
 		skipped: [],
-		configWritten: false
+		configWritten: false,
+		fonts: [],
+		fontsSkipped: []
 	};
 	for (const item of order) for (const file of item.files) {
 		const target = join(dir, file.path);
@@ -74,11 +305,499 @@ async function add(names, options) {
 		report.written.push(shown);
 	}
 	if (!saved) {
-		writeFileSync(join(cwd, CONFIG_FILE), `${JSON.stringify({ components: relative(cwd, dir) || "." }, null, "	")}\n`);
+		writeConfig(cwd, { components: relative(cwd, dir) || "." });
 		report.configWritten = true;
 	}
+	const needs = /* @__PURE__ */ new Map();
+	for (const item of order) for (const f of item.fonts ?? []) if (!needs.has(f.font)) needs.set(f.font, {
+		why: f.why,
+		by: item.name
+	});
+	for (const [role, need] of needs) {
+		if (options.fonts === false) {
+			report.fontsSkipped.push({
+				role,
+				...need
+			});
+			continue;
+		}
+		const done = await installFont(role, {
+			cwd,
+			dir: options.fontsDir,
+			overwrite: options.overwrite,
+			fetch: options.fetch,
+			catalog: options.fontCatalog,
+			onDownload: options.onDownload
+		});
+		report.fonts.push({
+			...done,
+			...need
+		});
+	}
+	if (report.fonts.length > 0 || readConfig(cwd).config.fonts) report.fontsModule = writeFontsModule(cwd, dir, options.fontCatalog);
+	return report;
+}
+
+//#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.
+*/
+const ALLOWED_SCRIPTS = ["skia-canvas"];
+const DENIED_SCRIPTS = [
+	"sharp",
+	"webgpu",
+	"onnxruntime-node",
+	"node-av",
+	"esbuild",
+	"protobufjs"
+];
+/** Dev tools the scripts use, at versions the scaffold is tested with. */
+const DEV_DEPENDENCIES = {
+	"@types/node": "^24.1.0",
+	tsx: "^4.20.3",
+	typescript: "^5.8.3"
+};
+const SCRIPTS = {
+	typecheck: "tsc --noEmit -p .",
+	frames: "tsx src/render.ts frames",
+	grid: "tsx src/render.ts grid",
+	preview: "tsx src/render.ts preview",
+	render: "tsx src/render.ts"
+};
+/**
+* The `package.json` fields a framefields project needs. npm reads
+* `allowScripts`, pnpm its `pnpm` block, bun `trustedDependencies`.
+*/
+function packageFields(o) {
+	return {
+		type: "module",
+		...o.packageManager && { packageManager: o.packageManager },
+		scripts: SCRIPTS,
+		dependencies: { framefields: `^${o.framefieldsVersion}` },
+		devDependencies: DEV_DEPENDENCIES,
+		allowScripts: Object.fromEntries([...ALLOWED_SCRIPTS.map((p) => [p, true]), ...DENIED_SCRIPTS.map((p) => [p, false])]),
+		pnpm: {
+			onlyBuiltDependencies: ALLOWED_SCRIPTS,
+			ignoredBuiltDependencies: DENIED_SCRIPTS
+		},
+		trustedDependencies: ALLOWED_SCRIPTS
+	};
+}
+const TSCONFIG = `${JSON.stringify({
+	compilerOptions: {
+		module: "NodeNext",
+		moduleResolution: "NodeNext",
+		target: "ES2022",
+		strict: true,
+		skipLibCheck: true,
+		noEmit: true,
+		types: ["node"]
+	},
+	include: ["src/**/*"]
+}, null, "	")}\n`;
+/** Lines `init` makes sure `.gitignore` has. */
+const GITIGNORE = [
+	"node_modules/",
+	"output/",
+	"scratch/",
+	".DS_Store",
+	".env"
+];
+/** Where the AI gateway's keys come from. */
+const AI_DASHBOARD = "https://framefields.dev/dashboard";
+/** Optional settings; `render.ts` loads `.env` when there is one. Commit this, not `.env`. */
+const ENV_EXAMPLE = `# Copy to .env (git-ignored). Everything here is optional.
+
+# framefields AI gateway: generate images, video, music, voice and 3D from code.
+# Create a key at ${AI_DASHBOARD}
+FRAMEFIELDS_API_KEY=
+`;
+/** Media, LUTs and fonts go to Git LFS; renders stay out of Git. */
+const GITATTRIBUTES = [
+	"assets/**/*.mp4 filter=lfs diff=lfs merge=lfs -text",
+	"assets/**/*.mov filter=lfs diff=lfs merge=lfs -text",
+	"assets/**/*.webm filter=lfs diff=lfs merge=lfs -text",
+	"assets/**/*.mp3 filter=lfs diff=lfs merge=lfs -text",
+	"assets/**/*.wav filter=lfs diff=lfs merge=lfs -text",
+	"assets/**/*.cube filter=lfs diff=lfs merge=lfs -text",
+	"assets/**/*.lottie filter=lfs diff=lfs merge=lfs -text",
+	"assets/fonts/**/*.ttf filter=lfs diff=lfs merge=lfs -text",
+	"assets/fonts/**/*.otf filter=lfs diff=lfs merge=lfs -text"
+];
+const THEME_TS = `import { registerFonts as registerInstalledFonts } from "./components/fonts.js";
+
+export const W = 1920;
+export const H = 1080;
+export const FPS = 30;
+export const INK = "#0E0D0C";
+export const PAPER = "#EEE9E0";
+/** Installed by \`framefields init\` (assets/fonts), registered below. */
+export const SANS = "Inter";
+export const MONO = "JetBrains Mono";
+
+/**
+ * Register the film's fonts. Fonts framefields installed
+ * (\`npx framefields fonts add <role>\`) come from the generated
+ * components/fonts.ts; register any others here with \`FontManager.register\`.
+ */
+export async function registerFonts(): Promise<void> {
+	await registerInstalledFonts();
+}
+`;
+const FILM_TS = `import { Composition, Layer, LayerAnimation } from "framefields";
+import { FPS, H, INK, PAPER, registerFonts, SANS, W } from "./theme.js";
+
+const DURATION = 3 * FPS; // frames
+
+/** Builds the film. Only builds: no rendering or writes, so tests, the preview and renders share it. */
+export async function buildFilm(): Promise<Composition> {
+	// Fonts must be registered before any text layer is built.
+	await registerFonts();
+
+	const film = new Composition({
+		width: W,
+		height: H,
+		fps: FPS,
+		durationMs: (DURATION / FPS) * 1000,
+		backgroundColor: INK,
+	});
+
+	film.add(
+		Layer.text("Hello, framefields", {
+			id: "title",
+			position: "absolute",
+			x: 0,
+			y: H / 2 - 60,
+			width: W,
+			height: 120,
+			fontFamily: SANS,
+			fontSize: 96,
+			fontWeight: 700,
+			fill: PAPER,
+			align: "center",
+		}).animate(
+			LayerAnimation.create()
+				.fadeIn(0, 20, "power2.out")
+				.fromTo("y", H / 2 - 20, H / 2 - 60, {
+					start: 0,
+					end: 30,
+					ease: "expo.out",
+				}),
+		),
+	);
+
+	return film;
+}
+`;
+const RENDER_TS = `import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { HeadlessMediaRenderer, startPreview } from "framefields";
+import { buildFilm } from "./film.js";
+
+// 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
+	.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") {
+	const png = await film.renderFrameGrid({
+		frames: args.length ? args.map(Number) : [0, 10, 20, 30, 45, 60, 75, 89],
+		columns: 4,
+		cellWidth: 480,
+		showLabels: true,
+	});
+	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}\`);
+}
+
+// Native GPU and encoder threads keep Node alive; always exit explicitly.
+process.exit(0);
+`;
+function readme(name, run) {
+	return `# ${name}
+
+A film built with [framefields](https://www.npmjs.com/package/framefields).
+
+\`\`\`bash
+${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
+\`\`\`
+
+- \`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
+  one into \`src/components/\`.
+- Optional: the AI gateway generates images, video, music, voice and 3D from code. Copy
+  \`.env.example\` to \`.env\` and set \`FRAMEFIELDS_API_KEY\` (keys at ${AI_DASHBOARD}).
+- Footage, audio and fonts live in \`assets/\` and are tracked with Git LFS
+  (\`git lfs install\` once per machine, \`git lfs pull\` after cloning).
+`;
+}
+
+//#endregion
+//#region src/cli/init.ts
+/**
+* `framefields init [dir]`: a new framefields project, or framefields added
+* to an existing one. Writes the layout the setup skill describes
+* (`package.json` with the install-script approvals framefields needs,
+* `tsconfig.json`, `src/theme.ts` / `film.ts` / `render.ts`, `assets/`,
+* LFS `.gitattributes`, `.gitignore`), installs the themes' fonts and keeps
+* them registered in `src/components/fonts.ts`.
+*
+* It never overwrites: files that exist are left alone, and `package.json`,
+* `.gitignore` and `.gitattributes` gain only what they're missing.
+*/
+const PACKAGE_MANAGERS = [
+	"npm",
+	"pnpm",
+	"yarn",
+	"bun"
+];
+/** The package manager in `npm_config_user_agent` (`pnpm/10.13.1 npm/? node/v22 …`). */
+function detectPackageManager(userAgent) {
+	const m = userAgent?.match(/^(npm|pnpm|yarn|bun)\/(\d[\w.+-]*)/);
+	if (!m) return null;
+	return {
+		name: m[1],
+		version: m[2]
+	};
+}
+const runScriptFor = (pm) => (script) => pm === "npm" || pm === "bun" ? `${pm} run ${script}` : `${pm} ${script}`;
+/** `My Film!` → `my-film`. */
+function packageName(folder) {
+	return folder.toLowerCase().replace(/[^a-z0-9._~-]+/g, "-").replace(/^[-._]+|[-._]+$/g, "") || "framefields-film";
+}
+async function init(options) {
+	const root = resolve(options.cwd, options.dir ?? ".");
+	mkdirSync(root, { recursive: true });
+	const detected = detectPackageManager(options.userAgent);
+	const pm = options.packageManager ?? detected?.name ?? "npm";
+	const pmVersion = detected?.name === pm ? detected.version : void 0;
+	const run = options.run ?? spawnRunner;
+	const report = {
+		root,
+		name: "",
+		packageManager: pm,
+		written: [],
+		merged: [],
+		unchanged: [],
+		fonts: [],
+		fontsModule: {
+			path: "",
+			status: "unchanged",
+			calls: []
+		},
+		git: "skipped",
+		lfs: null,
+		installed: false,
+		runScript: runScriptFor(pm)
+	};
+	const fields = packageFields({
+		framefieldsVersion: options.framefieldsVersion ?? ownVersion(),
+		...pmVersion && { packageManager: `${pm}@${pmVersion}` }
+	});
+	const pkgPath = join(root, "package.json");
+	if (existsSync(pkgPath)) {
+		const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+		if (pkg.type === "commonjs") throw new Error("package.json has \"type\": \"commonjs\". framefields projects are ES modules: set \"type\": \"module\" (and convert any require() files) first.");
+		report.name = typeof pkg.name === "string" ? pkg.name : packageName(basename(root));
+		record(report, "package.json", writeIfChanged(pkgPath, mergePackage(pkg, fields), pkg));
+	} else {
+		report.name = options.name ?? packageName(basename(root));
+		writeJson(pkgPath, {
+			name: report.name,
+			version: "0.0.0",
+			private: true,
+			...fields
+		});
+		report.written.push("package.json");
+	}
+	const files = [
+		["tsconfig.json", TSCONFIG],
+		["src/theme.ts", THEME_TS],
+		["src/film.ts", FILM_TS],
+		["src/render.ts", RENDER_TS],
+		["assets/footage/.gitkeep", ""],
+		[".env.example", ENV_EXAMPLE],
+		["README.md", readme(report.name, report.runScript)]
+	];
+	for (const [path$1, content] of files) {
+		const target = join(root, path$1);
+		if (existsSync(target)) report.unchanged.push(path$1);
+		else {
+			mkdirSync(dirname(target), { recursive: true });
+			writeFileSync(target, content);
+			report.written.push(path$1);
+		}
+	}
+	for (const [path$1, lines] of [[".gitignore", GITIGNORE], [".gitattributes", GITATTRIBUTES]]) record(report, path$1, appendLines(join(root, path$1), lines));
+	const { config, saved } = readConfig(root);
+	if (!saved) {
+		writeConfig(root, config);
+		report.written.push("framefields.json");
+	}
+	const roles = [...options.fonts === false ? [] : ["sans", "mono"], ...options.emoji ? ["emoji"] : []];
+	for (const role of roles) report.fonts.push(await installFont(role, {
+		cwd: root,
+		fetch: options.fetch,
+		catalog: options.fontCatalog,
+		onDownload: options.onDownload
+	}));
+	report.fontsModule = writeFontsModule(root, resolve(root, readConfig(root).config.components), options.fontCatalog);
+	if (options.git !== false) {
+		if (await run("git", ["rev-parse", "--is-inside-work-tree"], {
+			cwd: root,
+			quiet: true
+		}) === 0) report.git = "existing";
+		else if (await run("git", ["init", "-q"], {
+			cwd: root,
+			quiet: true
+		}) === 0) report.git = "initialized";
+		else report.git = "unavailable";
+		if (report.git !== "unavailable") report.lfs = await run("git", ["lfs", "version"], {
+			cwd: root,
+			quiet: true
+		}) === 0;
+	}
+	if (options.install) {
+		const code = await run(pm, ["install"], { cwd: root });
+		if (code !== 0) throw new Error(`\`${pm} install\` failed (exit ${code}). The project files are written; fix the error and run it again.`);
+		report.installed = true;
+	}
 	return report;
 }
+/** Add every field of `fields` the package lacks; existing values win. */
+function mergePackage(pkg, fields) {
+	const out = { ...pkg };
+	const obj = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : {};
+	const union = (a, b) => [...new Set([...Array.isArray(a) ? a : [], ...b])];
+	out.type ??= fields.type;
+	if (fields.packageManager) out.packageManager ??= fields.packageManager;
+	for (const key of [
+		"scripts",
+		"dependencies",
+		"devDependencies",
+		"allowScripts"
+	]) {
+		const theirs = obj(pkg[key]);
+		const present = key === "dependencies" || key === "devDependencies" ? {
+			...obj(pkg.dependencies),
+			...obj(pkg.devDependencies)
+		} : theirs;
+		const missing = Object.entries(fields[key]).filter(([k]) => !(k in present));
+		if (missing.length > 0) out[key] = {
+			...theirs,
+			...Object.fromEntries(missing)
+		};
+	}
+	const pnpm = obj(pkg.pnpm);
+	out.pnpm = {
+		...pnpm,
+		onlyBuiltDependencies: union(pnpm.onlyBuiltDependencies, fields.pnpm.onlyBuiltDependencies),
+		ignoredBuiltDependencies: union(pnpm.ignoredBuiltDependencies, fields.pnpm.ignoredBuiltDependencies)
+	};
+	out.trustedDependencies = union(pkg.trustedDependencies, fields.trustedDependencies);
+	return out;
+}
+function writeJson(path$1, value) {
+	writeFileSync(path$1, `${JSON.stringify(value, null, "	")}\n`);
+}
+function writeIfChanged(path$1, next, prev) {
+	if (JSON.stringify(next) === JSON.stringify(prev)) return false;
+	writeJson(path$1, next);
+	return true;
+}
+/** Create `path` with `lines` ("written"), or append the ones it lacks (true if any). */
+function appendLines(path$1, lines) {
+	if (!existsSync(path$1)) {
+		writeFileSync(path$1, `${lines.join("\n")}\n`);
+		return "written";
+	}
+	const text = readFileSync(path$1, "utf8");
+	const have = new Set(text.split(/\r?\n/).map((l) => l.trim()));
+	const missing = lines.filter((l) => !have.has(l));
+	if (missing.length === 0) return false;
+	writeFileSync(path$1, `${text}${text.endsWith("\n") || text === "" ? "" : "\n"}${missing.join("\n")}\n`);
+	return true;
+}
+/** File it under written (new), merged (changed) or unchanged. */
+function record(report, path$1, result) {
+	if (result === "written") report.written.push(path$1);
+	else if (result) report.merged.push(path$1);
+	else report.unchanged.push(path$1);
+}
+/** This package's version, from the nearest `package.json` named framefields. */
+function ownVersion() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (;;) {
+		const file = join(dir, "package.json");
+		if (existsSync(file)) {
+			const pkg = JSON.parse(readFileSync(file, "utf8"));
+			if (pkg.name === "framefields" && pkg.version) return pkg.version;
+		}
+		const up = dirname(dir);
+		if (up === dir) throw new Error("Can't find framefields' own package.json");
+		dir = up;
+	}
+}
+const spawnRunner = (command, args, { cwd, quiet }) => new Promise((done) => {
+	const child = spawn(command, args, {
+		cwd,
+		stdio: quiet ? "ignore" : "inherit",
+		shell: process.platform === "win32"
+	});
+	child.on("error", () => done(127));
+	child.on("close", (code) => done(code ?? 1));
+});
+/** Where the project is, as the user would `cd` to it. */
+function shownPath(cwd, root) {
+	return relative(cwd, root) || ".";
+}
 
 //#endregion
 //#region src/cli/registry.ts
@@ -125,29 +844,55 @@ function openRegistry(source, cwd = process.cwd()) {
 /**
 * The `framefields` command.
 *
-*   npx framefields add <name...>   copy components into this project
-*   npx framefields list            the components you can add
+*   npx framefields init [dir]           start a project (or add framefields to one)
+*   npx framefields add <name...>        copy components into this project
+*   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
 */
 const HELP = `Usage: framefields <command> [options]
 
 Commands:
+  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,
+                  LFS .gitattributes, and the themes' fonts. Never
+                  overwrites; existing files only gain what they lack.
   add <name...>   Copy components' source into this project (and the
                   components they build on). The code is yours to edit.
   list            List the components you can add.
+  fonts add <role...>
+                  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.
+
+Options for init:
+  --name <name>     Package name (default: the folder's name).
+  --pm <manager>    npm, pnpm, yarn or bun (default: the one running this).
+  --install         Install dependencies afterwards.
+  --emoji           Also install the color emoji font.
+  --no-fonts        Skip Inter and JetBrains Mono.
+  --no-git          Don't run \`git init\`.
 
 Options for add:
   --all             Add every component.
   --dir <path>      Components directory (default: from framefields.json,
                     else src/components or components). Saved the first time.
   --overwrite       Replace files you have changed.
+  --no-fonts        Don't install the fonts components ask for (emoji).
+
+Options for add and fonts add:
+  --fonts-dir <path>  Where downloaded fonts go (default assets/fonts).
 
-Options for both:
+Options for add and list:
   --registry <src>  A registry folder or http(s) URL instead of the one
                     shipped with this version of framefields.
   -h, --help        Show this help.
 
-Example:
+Examples:
+  npx framefields init my-film --install
   npx framefields add mouse-pointer focus-zoom
+  npx framefields fonts add emoji
 `;
 async function main(argv) {
 	const { values, positionals } = parseArgs({
@@ -157,6 +902,13 @@ async function main(argv) {
 			all: { type: "boolean" },
 			dir: { type: "string" },
 			overwrite: { type: "boolean" },
+			"no-fonts": { type: "boolean" },
+			"fonts-dir": { type: "string" },
+			name: { type: "string" },
+			pm: { type: "string" },
+			install: { type: "boolean" },
+			emoji: { type: "boolean" },
+			"no-git": { type: "boolean" },
 			registry: { type: "string" },
 			help: {
 				type: "boolean",
@@ -170,6 +922,31 @@ async function main(argv) {
 		return command || values.help ? 0 : 1;
 	}
 	const cwd = process.cwd();
+	const log = (line) => process.stdout.write(`${line}\n`);
+	if (command === "fonts") return fonts(names, cwd, values, log);
+	if (command === "init") {
+		if (names.length > 1) {
+			process.stderr.write("init takes one folder: `framefields init my-film`.\n");
+			return 1;
+		}
+		if (values.pm && !PACKAGE_MANAGERS.includes(values.pm)) {
+			process.stderr.write(`--pm must be one of ${PACKAGE_MANAGERS.join(", ")}.\n`);
+			return 1;
+		}
+		logInit(await init({
+			cwd,
+			dir: names[0],
+			name: values.name,
+			packageManager: values.pm,
+			userAgent: process.env.npm_config_user_agent,
+			fonts: !values["no-fonts"],
+			emoji: values.emoji,
+			git: !values["no-git"],
+			install: values.install,
+			onDownload
+		}), cwd, log);
+		return 0;
+	}
 	const registry = openRegistry(values.registry, cwd);
 	if (command === "list") {
 		const index = await registry.index();
@@ -190,13 +967,16 @@ async function main(argv) {
 		cwd,
 		registry,
 		dir: values.dir,
-		overwrite: values.overwrite
+		overwrite: values.overwrite,
+		fonts: !values["no-fonts"],
+		fontsDir: values["fonts-dir"],
+		onDownload
 	});
-	const log = (line) => process.stdout.write(`${line}\n`);
 	for (const f of report.written) log(`  wrote      ${f}`);
 	for (const f of report.unchanged) log(`  unchanged  ${f}`);
 	for (const f of report.skipped) log(`  skipped    ${f} (yours differs; --overwrite replaces it)`);
 	if (report.configWritten) log("  wrote      framefields.json");
+	logFonts(report, cwd, log);
 	const extra = report.components.filter((c) => !wanted.includes(c.name));
 	if (extra.length > 0) log(`\nWith what they build on: ${extra.map((c) => c.name).join(", ")}.`);
 	warnIfMissingFramefields(cwd, log);
@@ -204,6 +984,76 @@ async function main(argv) {
 	if (first) log(`\nimport { ${first.title} } from "./${first.name}/index.js"; // from ${relative(cwd, report.dir) || "."}`);
 	return 0;
 }
+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. */
+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}\`.`);
+	if (report.fontsModule) logFontsModule(report.fontsModule, log);
+	const installed = report.fonts.find((f) => f.status === "installed");
+	const hint = installed && lfsHint(cwd, installed.path);
+	if (hint) log(`\n${hint}`);
+	if (report.fonts.some((f) => f.status !== "configured") && report.fontsModule) log(`\nRegister them once before rendering: \`await registerFonts()\` from ${report.fontsModule.path.replace(/\.ts$/, ".js")}.`);
+}
+function logFontsModule(m, log) {
+	if (m.status === "written") log(`  wrote      ${m.path}`);
+	else if (m.status === "unchanged") log(`  unchanged  ${m.path}`);
+	else log(`  skipped    ${m.path} (not generated by framefields). Register the fonts yourself:\n${m.calls.map((c) => `    ${c}`).join("\n")}`);
+}
+/** `framefields fonts add <role...>` and `framefields fonts list`. */
+async function fonts([sub, ...roles], cwd, values, log) {
+	if (sub === "list") {
+		const { config: config$1 } = readConfig(cwd);
+		for (const [role, spec] of Object.entries(FONTS)) log(`${role.padEnd(6)}  ${spec.label}${config$1.fonts?.[role] ? `  (installed: ${config$1.fonts[role]})` : ""}`);
+		return 0;
+	}
+	if (sub !== "add" || roles.length === 0) {
+		process.stderr.write(`Usage: framefields fonts add <role...>   (roles: ${Object.keys(FONTS).join(", ")})\n       framefields fonts list\n`);
+		return 1;
+	}
+	const unknown = roles.filter((r) => !FONTS[r]);
+	if (unknown.length > 0) {
+		process.stderr.write(`Unknown font ${unknown.map((r) => `"${r}"`).join(", ")}. Fonts framefields can install: ${Object.keys(FONTS).join(", ")}.\n`);
+		return 1;
+	}
+	const { config, saved } = readConfig(cwd);
+	const installs = [];
+	for (const role of roles) installs.push(await installFont(role, {
+		cwd,
+		dir: values["fonts-dir"],
+		overwrite: values.overwrite,
+		onDownload
+	}));
+	for (const f of installs) log(`  ${f.status === "installed" ? "font      " : "font ok   "} ${f.path} (${f.role})`);
+	if (!saved) log("  wrote      framefields.json");
+	const module = writeFontsModule(cwd, resolve(cwd, values.dir ?? config.components));
+	logFontsModule(module, log);
+	const installed = installs.find((f) => f.status === "installed");
+	const hint = installed && lfsHint(cwd, installed.path);
+	if (hint) log(`\n${hint}`);
+	log(`\nRegister them once before rendering: \`await registerFonts()\` from ${module.path.replace(/\.ts$/, ".js")}.`);
+	return 0;
+}
+function logInit(report, cwd, log) {
+	const at = shownPath(cwd, report.root);
+	for (const f of report.written) log(`  wrote      ${f}`);
+	for (const f of report.merged) log(`  merged     ${f} (added what it lacked)`);
+	for (const f of report.unchanged) log(`  unchanged  ${f}`);
+	for (const f of report.fonts) log(`  ${f.status === "installed" ? "font      " : "font ok   "} ${f.path} (${f.role})`);
+	logFontsModule(report.fontsModule, log);
+	if (report.git === "initialized") log("  git        initialized a repository");
+	if (report.git === "unavailable") log("  git        not found: skipped `git init`");
+	if (report.lfs === false) log("\nGit LFS isn't installed. Footage and fonts are tracked with it: install it (https://git-lfs.com), then run `git lfs install` once.");
+	else if (report.lfs) log("\nRun `git lfs install` once on this machine if you haven't yet.");
+	const steps = [
+		...at === "." ? [] : [`cd ${/\s/.test(at) ? JSON.stringify(at) : at}`],
+		...report.installed ? [] : [`${report.packageManager} install`],
+		`${report.runScript("frames")} -- 0 30 60`
+	];
+	log(`\n${report.name} is ready. Next:\n${steps.map((s) => `  ${s}`).join("\n")}`);
+	log("\nThen edit src/film.ts, and run `npx framefields list` for ready-made components.");
+	log(`\nOptional: to generate images, video, music, voice and 3D with the framefields AI gateway, get a key at ${AI_DASHBOARD} and put it in .env as FRAMEFIELDS_API_KEY (see .env.example).`);
+}
 /** Installed components import `framefields`; say so if the project lacks it. */
 function warnIfMissingFramefields(cwd, log) {
 	try {