Skip to content

Code-first video & image, rendered natively on WebGPU.

10.7 KB
Raw Blame
/**
 * 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.
 */
import { createHash } from "node:crypto";
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { dirname, join, posix, relative, resolve, sep } from "node:path";
import { readConfig, writeConfig } from "./config.js";

/** A downloadable file, pinned by size and hash. */
interface PinnedFile {
	url: string;
	sha256: string;
	bytes: number;
}

export interface FontSpec {
	/** What it's for, in a sentence: shown by `fonts list`. */
	label: string;
	/** File name it's saved under. */
	file: string;
	font: PinnedFile;
	license: PinnedFile & {
		/** SPDX id. */
		id: string;
		/** File name it's saved under, next to the font. */
		file: string;
	};
	/**
	 * How it registers: as the color emoji font, or as a text family under
	 * this name (the name themes use: `Inter`, `JetBrains Mono`).
	 */
	register: { emoji: true } | { family: string };
}

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. */
export const FONTS: Record<string, FontSpec> = {
	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: 10_673_480,
		},
		license: {
			id: "OFL-1.1",
			file: "NotoColorEmoji-OFL.txt",
			url: `${NOTO_EMOJI}/fonts/LICENSE`,
			sha256:
				"6a73f9541c2de74158c0e7cf6b0a58ef774f5a780bf191f2d7ec9cc53efe2bf2",
			bytes: 4_301,
		},
		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: 876_576,
		license: {
			path: "ofl/inter/OFL.txt",
			sha256:
				"5b9321a4298cfeb6b34354164a1c3afc3db114569984c502b9b35d988fd58c57",
			bytes: 4_377,
		},
	}),
	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: 187_208,
		license: {
			path: "ofl/jetbrainsmono/OFL.txt",
			sha256:
				"b2fe5e8987594e9ffd1d2ca52a2f5d73eb8335243893c5d6254b5ad69269591d",
			bytes: 4_399,
		},
	}),
};

/** google/fonts, pinned to one commit. */
function googleFont(o: {
	label: string;
	file: string;
	family: string;
	path: string;
	sha256: string;
	bytes: number;
	license: { path: string; sha256: string; bytes: number };
}): FontSpec {
	const at = (path: string) => `${GOOGLE_FONTS}/${path}`;
	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. */
export const DEFAULT_FONTS_DIR = "assets/fonts";

export type Fetch = (url: string) => Promise<{
	ok: boolean;
	status: number;
	statusText: string;
	arrayBuffer(): Promise<ArrayBuffer>;
}>;

export interface FontInstallOptions {
	cwd: string;
	/** Folder for new font files, relative to `cwd`. Default `assets/fonts`. */
	dir?: string;
	/** Replace a different file already at the target path. */
	overwrite?: boolean;
	/** For tests; default the global `fetch`. */
	fetch?: Fetch;
	/** For tests; default {@link FONTS}. */
	catalog?: Record<string, FontSpec>;
	/** Called before a download starts (for progress messages). */
	onDownload?: (spec: FontSpec) => void;
}

export interface FontInstall {
	role: string;
	/** Relative to the project root. */
	path: string;
	/**
	 * `installed`: downloaded now. `present`: the pinned file was already
	 * there. `configured`: `framefields.json` already names a font for the role.
	 */
	status: "installed" | "present" | "configured";
}

const sha256 = (bytes: Uint8Array) =>
	createHash("sha256").update(bytes).digest("hex");

/** A project-relative path with forward slashes, as `framefields.json` keeps it. */
const projectPath = (cwd: string, path: string) =>
	relative(cwd, path).split(sep).join(posix.sep);

/** Install the font for `role` into the project and record it in `framefields.json`. */
export async function installFont(
	role: string,
	options: FontInstallOptions,
): Promise<FontInstall> {
	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 = projectPath(cwd, target);
	let status: FontInstall["status"] = "present";
	const current = existsSync(target) ? readFileSync(target) : null;
	if (!current || sha256(current) !== spec.font.sha256) {
		if (current && !options.overwrite)
			throw new Error(
				`${path} 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 as unknown as 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 },
	});
	return { role, path, status };
}

async function download(file: PinnedFile, get: Fetch): Promise<Uint8Array> {
	let res: Awaited<ReturnType<Fetch>>;
	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. */
export const FONTS_MODULE_MARKER =
	"// Generated by framefields from framefields.json.";

export interface FontsModule {
	/** Relative to the project root. */
	path: string;
	/** `skipped`: the file exists without the marker, so it's the user's. */
	status: "written" | "unchanged" | "skipped";
	/** The registration calls, one line each, for printing when `skipped`. */
	calls: string[];
}

/**
 * Write `<components>/fonts.ts`, which registers every font in
 * `framefields.json`. Call it once before building or rendering:
 * `await registerFonts()`.
 */
export function writeFontsModule(
	cwd: string,
	componentsDir: string,
	catalog: Record<string, FontSpec> = FONTS,
): FontsModule {
	const { config } = readConfig(cwd);
	const target = join(componentsDir, "fonts.ts");
	const path = projectPath(cwd, target);
	const fonts = Object.entries(config.fonts ?? {})
		.filter(([role]) => catalog[role])
		.sort(([a], [b]) => a.localeCompare(b))
		.map(([role, file]) => {
			const from = relative(componentsDir, resolve(cwd, file as string))
				.split(sep)
				.join(posix.sep);
			const url = from.startsWith(".") ? from : `./${from}`;
			return { register: (catalog[role] as FontSpec).register, url };
		});
	const call = (r: FontSpec["register"], source: string) =>
		"family" in r
			? `register({ family: ${JSON.stringify(r.family)}, source: ${source} })`
			: `registerEmojiFont(${source})`;
	const calls = fonts.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
	// Wrapped the way Biome / Prettier would at 80 columns.
	.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, status: "unchanged", calls };
		if (!current.startsWith(FONTS_MODULE_MARKER))
			return { path, status: "skipped", calls };
	}
	mkdirSync(componentsDir, { recursive: true });
	writeFileSync(target, content);
	return { path, 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.
 */
export function lfsHint(cwd: string, fontPath: string): string | null {
	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;
	const dir = posix.dirname(fontPath);
	return `Fonts are large binaries: track them with Git LFS, e.g. \`git lfs track "${dir}/**/*.ttf"\`.`;
}