Skip to content

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

3.6 KB
Raw Blame
import { createRequire, registerHooks } from "node:module";
import path from "node:path";
import { pathToFileURL } from "node:url";

/** Query parameter that scopes workspace source modules to one job. */
export const JOB_PARAM = "ff-job";

let roots: string[] = [];
let rootDirs: string[] = [];
let engineEntry: string | undefined;
let installed = false;

const isEngine = (s: string) =>
	s === "framefields" ||
	s.startsWith("framefields/") ||
	s.startsWith("@framefields/");
const inWorkspace = (url: string) => roots.some((r) => url.startsWith(r));
const isDependency = (url: string) => url.includes("/node_modules/");
/** Project source files that load as ESM even without "type": "module". */
const FORCE_ESM = /\.(ts|tsx|js|jsx)$/;

function jobOf(url: string | undefined): string | undefined {
	if (!url?.includes("?")) return undefined;
	try {
		return new URL(url).searchParams.get(JOB_PARAM) ?? undefined;
	} catch {
		return undefined;
	}
}

/** Routes framefields imports to the bound engine (see engine.ts). */
export function setEngineEntry(url: string): void {
	engineEntry = url;
}

/**
 * Installs the loader hooks once per process (PLAN.md §7, §8.1). Uses
 * synchronous in-thread hooks, which apply to both `import` and `require()`.
 *
 * - Once an engine is bound, `framefields` / `@framefields/*` imported from
 *   any workspace resolve from the bound engine's package (always its ESM
 *   build), so every project on the same version shares one GPU stack.
 * - Project source files (outside node_modules) inherit a per-job query, so
 *   a job never reuses source modules cached by a previous one, and load as
 *   ESM: in CommonJS mode tsx would transpile a second copy of the engine.
 * - Dependencies in node_modules load as they are and stay cached by path,
 *   shared with the engine. A dependency change restarts the worker instead
 *   (installer.ts).
 */
export function installEngineAlias(workspaceRoots: string[]): void {
	if (installed) return;
	installed = true;
	rootDirs = workspaceRoots.map((r) => path.resolve(r) + path.sep);
	roots = rootDirs.map((r) => pathToFileURL(r).href);

	registerHooks({
		resolve(specifier, context, next) {
			const parent = context.parentURL;
			if (engineEntry && isEngine(specifier) && parent && inWorkspace(parent)) {
				try {
					const conditions = (context.conditions ?? []).map((c) =>
						c === "require" ? "import" : c,
					);
					if (!conditions.includes("import")) conditions.push("import");
					return next(specifier, {
						...context,
						conditions,
						parentURL: engineEntry,
					});
				} catch {
					// Not part of the engine (e.g. a project-local @framefields/* package).
				}
			}
			const result = next(specifier, context);
			if (
				!result.url.startsWith("file:") ||
				!inWorkspace(result.url) ||
				isDependency(result.url)
			) {
				return result;
			}
			let { url, format } = result;
			if (format === "commonjs" && FORCE_ESM.test(new URL(url).pathname))
				format = "module";
			const job = jobOf(parent);
			if (job && !jobOf(url)) {
				const scoped = new URL(url);
				scoped.searchParams.set(JOB_PARAM, job);
				url = scoped.href;
			}
			return { ...result, url, format };
		},
	});
}

/**
 * Drops CommonJS project sources loaded from the workspaces (ES modules are
 * scoped by the job query instead). Called when a job ends.
 */
export function clearWorkspaceRequireCache(): void {
	const cache = createRequire(import.meta.url).cache;
	for (const key of Object.keys(cache)) {
		if (
			rootDirs.some((r) => key.startsWith(r)) &&
			!key.includes(`${path.sep}node_modules${path.sep}`)
		) {
			delete cache[key];
		}
	}
}