Skip to content

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

13.7 KB
Raw Blame
import fs from "node:fs/promises";
import path from "node:path";
import {
	registerHeadlessFont,
	SlugFontCache,
	SlugGeometry,
	setRegisteredFontSource,
} from "@framefields/webgpu-renderers";
import * as fontkit from "fontkit";

export interface RegisterFontOptions {
	family?: string;
	source: string | Uint8Array;
	weight?: number | string;
	style?: "normal" | "italic" | "oblique";
}

export interface RegisteredFont {
	family: string;
	source: string | Uint8Array;
	filePath?: string;
	format: "truetype" | "opentype";
	postscriptName?: string;
	unitsPerEm?: number;
	weight?: number | string;
	style?: string;
}

interface ResolvedSource {
	buffer: Uint8Array;
	filePath?: string;
}

const SFNT_TRUETYPE_1 = 0x00010000;
const SFNT_TRUETYPE_TRUE = 0x74727565; // 'true'
const SFNT_TRUETYPE_TYP1 = 0x74797031; // 'typ1'
const SFNT_OPENTYPE_CFF = 0x4f54544f; // 'OTTO'
const SFNT_COLLECTION = 0x74746366; // 'ttcf'

function validateFontBinaryHeader(
	bytes: Uint8Array,
	sourceLabel: string,
): "truetype" | "opentype" {
	if (bytes.length < 12) {
		throw new Error(
			`Invalid font binary for "${sourceLabel}": File size (${bytes.length} bytes) is too small to be a valid TrueType or OpenType font.`,
		);
	}

	const tag =
		((bytes[0] ?? 0) << 24) |
		((bytes[1] ?? 0) << 16) |
		((bytes[2] ?? 0) << 8) |
		(bytes[3] ?? 0);

	if (
		tag === SFNT_TRUETYPE_1 ||
		tag === SFNT_TRUETYPE_TRUE ||
		tag === SFNT_TRUETYPE_TYP1 ||
		tag === SFNT_COLLECTION
	) {
		return "truetype";
	}

	if (tag === SFNT_OPENTYPE_CFF) {
		return "opentype";
	}

	const hexTag = (tag >>> 0).toString(16).padStart(8, "0");
	throw new Error(
		`Invalid font format for "${sourceLabel}": Expected a valid TrueType (.ttf) or OpenType (.otf) font binary. Found header tag: 0x${hexTag}.`,
	);
}

async function resolveSourceBuffer(
	source: string | Uint8Array,
): Promise<ResolvedSource> {
	if (source instanceof Uint8Array) {
		return { buffer: source };
	}

	if (typeof source !== "string") {
		throw new TypeError(
			`Font source must be a file path string or Uint8Array, received: ${typeof source}`,
		);
	}

	let cleanPath = source;
	if (cleanPath.startsWith("http://") || cleanPath.startsWith("https://")) {
		const res = await fetch(cleanPath);
		if (!res.ok) {
			throw new Error(
				`Failed to download font from "${cleanPath}": HTTP ${res.status} ${res.statusText}`,
			);
		}
		const arrayBuffer = await res.arrayBuffer();
		return {
			buffer: new Uint8Array(arrayBuffer),
			filePath: cleanPath,
		};
	}

	if (cleanPath.startsWith("file://")) {
		try {
			// A URL path is percent-encoded ("My%20Film"); files aren't. On
			// Windows "/C:/…" loses its leading slash.
			cleanPath = decodeURIComponent(new URL(cleanPath).pathname).replace(
				/^\/([A-Za-z]:)/,
				"$1",
			);
		} catch {
			cleanPath = cleanPath.replace(/^file:\/\//, "");
		}
	}

	const candidates: string[] = [
		cleanPath,
		path.resolve(process.cwd(), cleanPath),
		path.resolve(process.cwd(), "assets/fonts", cleanPath),
		path.resolve(process.cwd(), "assets/fonts", path.basename(cleanPath)),
	];

	// Upward traversal to locate fonts in parent monorepo roots
	let currentDir = process.cwd();
	for (let i = 0; i < 5; i++) {
		candidates.push(path.resolve(currentDir, cleanPath));
		candidates.push(
			path.resolve(currentDir, "assets/fonts", path.basename(cleanPath)),
		);
		const parent = path.dirname(currentDir);
		if (parent === currentDir) break;
		currentDir = parent;
	}

	let resolvedPath: string | null = null;
	let fileBuffer: Buffer | null = null;

	for (const candidate of candidates) {
		try {
			const stat = await fs.stat(candidate);
			if (stat.isFile()) {
				resolvedPath = candidate;
				fileBuffer = await fs.readFile(candidate);
				break;
			}
		} catch {
			// Continue searching next candidate
		}
	}

	if (!resolvedPath || !fileBuffer) {
		throw new Error(
			`Font file not found: "${source}". Checked candidate locations:\n  - ${candidates.join("\n  - ")}`,
		);
	}

	return {
		buffer: new Uint8Array(
			fileBuffer.buffer,
			fileBuffer.byteOffset,
			fileBuffer.byteLength,
		),
		filePath: resolvedPath,
	};
}

/**
 * Central singleton manager for font registration, TTF validation, and compositor typography binding.
 */
export interface MeasureTextOptions {
	fontFamily: string;
	fontSize?: number;
	fontWeight?: string | number;
	/** Variable font axes, as on `Layer.text` (`{ wdth: 68 }`). */
	fontVariations?: Record<string, number>;
	/** Extra px between characters, as on `Layer.text`. */
	letterSpacing?: number;
	/** Multiplier of fontSize when < 10, else px. Default 1.2. */
	lineHeight?: number;
	/** Wrap width in px; omit for one line per `\n`. */
	width?: number;
	align?: "left" | "center" | "right";
	/** Paragraph base direction, as on `Layer.text`. Default "auto". */
	direction?: "ltr" | "rtl" | "auto";
}

export interface MeasuredGlyph {
	char: string;
	/** Index into the string (code units), matching `text.slice`. */
	index: number;
	/** Left edge of the glyph, relative to the text box. */
	x: number;
	/** Baseline-relative top of the line box. */
	y: number;
	/** Advance width in px. */
	width: number;
	line: number;
	/** Part of a right-to-left run: reading continues to the left. */
	rtl?: boolean;
}

export interface TextMetrics {
	width: number;
	height: number;
	lines: number;
	/** Line box height in px. */
	lineHeight: number;
	glyphs: MeasuredGlyph[];
	/**
	 * X of a caret placed after `count` characters (0 = before the first),
	 * relative to the text box. In right-to-left text the caret sits on the
	 * left of the last character. Pair with a `.keys("text", …)` reveal to make
	 * a cursor follow typing exactly.
	 */
	caretX(count: number): number;
	/** Width of the first `count` characters (same as `caretX` on one line). */
	widthOf(count: number): number;
}

export class FontManager {
	private static instance: FontManager | null = null;
	private readonly fonts = new Map<string, RegisteredFont>();

	private constructor() {}

	/**
	 * Returns the singleton FontManager instance.
	 */
	public static getInstance(): FontManager {
		if (!FontManager.instance) {
			FontManager.instance = new FontManager();
		}
		return FontManager.instance;
	}

	/**
	 * Registers a TrueType/OpenType font into the Framefields engine with validation.
	 */
	public static async register(
		optionsOrFamilyOrSource: RegisterFontOptions | string,
		source?: string | Uint8Array,
	): Promise<RegisteredFont> {
		return FontManager.getInstance().register(optionsOrFamilyOrSource, source);
	}

	/**
	 * Sets the color emoji font text draws emoji with, for the preview and the
	 * export alike: a CBDT/CBLC bitmap font such as Noto Color Emoji, as a file
	 * path, URL or bytes. framefields ships none; without one, exports draw
	 * nothing for emoji.
	 */
	public static async registerEmojiFont(
		source: string | Uint8Array,
	): Promise<void> {
		const { buffer, filePath } = await resolveSourceBuffer(source);
		const label =
			filePath ?? (typeof source === "string" ? source : "Uint8Array");
		validateFontBinaryHeader(buffer, label);
		SlugFontCache.setEmojiFont(buffer, filePath);
	}

	/** Whether a color emoji font is registered (or set to load from a path / URL). */
	public static hasEmojiFont(): boolean {
		return SlugFontCache.hasEmojiFont();
	}

	/**
	 * Measures text with the real font, exactly as `Layer.text` lays it out:
	 * box size, line count, per-glyph positions and caret offsets. Use it to
	 * size containers, place cursors, underline a word or center by ink
	 * instead of guessing advances. The family must be registered first.
	 *
	 * ```ts
	 * const m = FontManager.measure("Hello", { fontFamily: "Inter", fontSize: 60 });
	 * m.width; m.caretX(3); m.glyphs[1].x
	 * ```
	 */
	public static measure(
		text: string,
		options: MeasureTextOptions,
	): TextMetrics {
		const fontSize = options.fontSize ?? 48;
		const font = SlugFontCache.getFont(
			options.fontFamily,
			options.fontWeight,
			null,
			undefined,
			fontSize,
			options.fontVariations,
		);
		if (!font) {
			throw new Error(
				`FontManager.measure: font "${options.fontFamily}" is not registered. ` +
					"Call `await FontManager.register(...)` first.",
			);
		}
		const lineHeight =
			options.lineHeight !== undefined && options.lineHeight < 10
				? options.lineHeight * fontSize
				: (options.lineHeight ?? fontSize * 1.2);
		const letterSpacing = options.letterSpacing ?? 0;
		const { width, height, layout } = SlugGeometry.measure(
			text,
			font,
			fontSize,
			letterSpacing,
			lineHeight,
			options.width,
			undefined,
			options.direction,
		);
		const scale = fontSize / font.unitsPerEm;
		// One entry per cluster (a letter with its marks, or a ligature), in
		// reading order; textIndex maps it back to the string.
		const glyphs: MeasuredGlyph[] = [];
		const seen = new Set<number>();
		let cursor = 0;
		for (const g of layout.glyphs) {
			let index = g.textIndex;
			if (index === undefined) {
				const at = text.indexOf(g.char, cursor);
				index = at >= 0 ? at : cursor;
			}
			if (seen.has(index)) continue;
			seen.add(index);
			cursor = index + g.char.length;
			const advance =
				g.clusterAdvance ?? g.cp.advanceWidth * (g.fontScale ?? scale);
			glyphs.push({
				char: g.char,
				index,
				x: g.clusterX ?? g.x,
				y: g.y,
				width: advance + letterSpacing,
				line: g.lineIndex,
				...(g.rtl && { rtl: true }),
			});
		}
		const caretX = (count: number): number => {
			if (count <= 0 || glyphs.length === 0) {
				const first = glyphs[0];
				if (!first) return 0;
				return first.rtl ? first.x + first.width - letterSpacing : first.x;
			}
			const before = glyphs.filter((g) => g.index < count);
			const last = before[before.length - 1];
			if (!last) return 0;
			return last.rtl ? last.x : last.x + last.width - letterSpacing;
		};
		return {
			width,
			height,
			lines: layout.linesCount,
			lineHeight,
			glyphs,
			caretX,
			widthOf: (count: number) => caretX(count) - (glyphs[0]?.x ?? 0),
		};
	}

	/**
	 * Retrieves registered font metadata by family name.
	 */
	public static get(family: string): RegisteredFont | undefined {
		return FontManager.getInstance().get(family);
	}

	/**
	 * Checks if a font family has been registered.
	 */
	public static has(family: string): boolean {
		return FontManager.getInstance().has(family);
	}

	/**
	 * Returns all currently registered fonts.
	 */
	public static getAll(): RegisteredFont[] {
		return FontManager.getInstance().getAll();
	}

	/**
	 * Returns relative or absolute file paths of all registered fonts for composition spec serialization.
	 */
	public static getRegisteredFontPaths(): string[] {
		return FontManager.getInstance().getRegisteredFontPaths();
	}

	/**
	 * Clears all registered fonts from the manager.
	 */
	public static clear(): void {
		FontManager.getInstance().clear();
	}

	/**
	 * Instance registration method with format validation and Slug WebGPU cache population.
	 */
	public async register(
		optionsOrFamilyOrSource: RegisterFontOptions | string,
		source?: string | Uint8Array,
	): Promise<RegisteredFont> {
		let family: string | undefined;
		let rawSource: string | Uint8Array;
		let weight: number | string | undefined;
		let style: "normal" | "italic" | "oblique" | undefined;

		if (
			typeof optionsOrFamilyOrSource === "object" &&
			optionsOrFamilyOrSource !== null
		) {
			family = optionsOrFamilyOrSource.family;
			rawSource = optionsOrFamilyOrSource.source;
			weight = optionsOrFamilyOrSource.weight;
			style = optionsOrFamilyOrSource.style;
		} else if (
			typeof optionsOrFamilyOrSource === "string" &&
			source !== undefined
		) {
			family = optionsOrFamilyOrSource;
			rawSource = source;
		} else if (typeof optionsOrFamilyOrSource === "string") {
			family = undefined;
			rawSource = optionsOrFamilyOrSource;
		} else {
			throw new TypeError("Invalid arguments passed to FontManager.register");
		}

		const { buffer, filePath } = await resolveSourceBuffer(rawSource);
		const sourceLabel =
			filePath ?? (typeof rawSource === "string" ? rawSource : "Uint8Array");
		const format = validateFontBinaryHeader(buffer, sourceLabel);

		let parsedFontkit: fontkit.Font;
		try {
			const parsed = fontkit.create(buffer as unknown as Buffer);
			if (
				parsed &&
				"fonts" in parsed &&
				Array.isArray(parsed.fonts) &&
				parsed.fonts.length > 0
			) {
				parsedFontkit = parsed.fonts[0] as fontkit.Font;
			} else {
				parsedFontkit = parsed as fontkit.Font;
			}
		} catch (err) {
			const msg = err instanceof Error ? err.message : String(err);
			throw new Error(
				`Failed to parse TrueType/OpenType font binary for "${sourceLabel}": ${msg}`,
			);
		}

		const detectedFamily =
			parsedFontkit.familyName ||
			parsedFontkit.postscriptName ||
			path.parse(sourceLabel).name;
		const resolvedFamily = family?.trim() || detectedFamily;

		const registered: RegisteredFont = {
			family: resolvedFamily,
			source: rawSource,
			filePath,
			format,
			postscriptName: parsedFontkit.postscriptName,
			unitsPerEm: parsedFontkit.unitsPerEm,
			weight,
			style,
		};

		this.fonts.set(resolvedFamily, registered);

		setRegisteredFontSource(resolvedFamily, filePath ?? rawSource);
		// Populate headless font registries
		if (filePath) {
			await registerHeadlessFont(resolvedFamily, filePath);
		}
		SlugFontCache.setParsed(resolvedFamily, parsedFontkit);

		return registered;
	}

	public get(family: string): RegisteredFont | undefined {
		return this.fonts.get(family);
	}

	public has(family: string): boolean {
		return this.fonts.has(family);
	}

	public getAll(): RegisteredFont[] {
		return Array.from(this.fonts.values());
	}

	public getRegisteredFontPaths(): string[] {
		const paths: string[] = [];
		for (const font of this.fonts.values()) {
			if (font.filePath) {
				paths.push(font.filePath);
			} else if (typeof font.source === "string") {
				paths.push(font.source);
			}
		}
		return paths;
	}

	public clear(): void {
		this.fonts.clear();
	}
}