@moku-labs/game 0.7.1 → 0.9.0

package/dist/project.mjs

@@ -874,13 +874,465 @@ function readModule(typescript, source) {
 	return draft;
 }
 //#endregion
+//#region src/project/paths.ts
+/**
+* @file project — which files the index reads, and the guard on every path it reads. Paths in and
+* out are root-relative POSIX. A read resolves the path against the real root with `realpath`, so
+* a `..` or a symlink that leaves the root is refused by name instead of read.
+*/
+/** The folders a game never edits by hand: dependencies, builds, generated code and tests. */
+const SKIPPED_FOLDER = /^(?:node_modules|dist|generated|\.moku|\.git|__tests__|tests)$/;
+/** The source files the index reads. */
+const SOURCE_FILE = /\.tsx?$/;
+/** Test files, skipped wherever they sit. */
+const TEST_FILE = /\.(?:test|spec)\.tsx?$/;
+/** The hint under every root error. */
+const ROOT_HINT = "Pass the folder of the game as root.";
+/**
+* Whether a folder name is one the index never walks into.
+*
+* @param name - One folder name.
+* @returns True for `node_modules`, `dist`, `generated`, `.moku`, `.git`, `__tests__` and `tests`.
+* @example
+* ```ts
+* isSkippedFolder("generated"); // true
+* ```
+*/
+function isSkippedFolder(name) {
+	return SKIPPED_FOLDER.test(name);
+}
+/**
+* Whether a root-relative path sits under a skipped folder.
+*
+* @param file - A path with `/` or `\` separators.
+* @returns True when one of its folders is skipped.
+* @example
+* ```ts
+* isSkippedPath("node_modules/pixi.js/index.ts"); // true
+* ```
+*/
+function isSkippedPath(file) {
+	return file.split(/[/\\]/).slice(0, -1).some((folder) => isSkippedFolder(folder));
+}
+/**
+* Whether the index reads a root-relative path: a `.ts` or `.tsx` file outside the skipped
+* folders that is not a test.
+*
+* @param file - A root-relative POSIX path.
+* @returns True for a source file of the index.
+* @example
+* ```ts
+* isIndexedFile("features/ui/kit.tsx"); // true
+* ```
+*/
+function isIndexedFile(file) {
+	return SOURCE_FILE.test(file) && !TEST_FILE.test(file) && !isSkippedPath(file);
+}
+/**
+* Turns a path into its root-relative POSIX form.
+*
+* @param file - A path with any separators.
+* @returns The path with `/` separators, `.` segments resolved.
+* @example
+* ```ts
+* toPosix("./features\\ui\\kit.tsx"); // "features/ui/kit.tsx"
+* ```
+*/
+function toPosix(file) {
+	return path.posix.normalize(file.replaceAll("\\", "/"));
+}
+/**
+* Whether a file system error says nothing is at the path.
+*
+* @param error - What was thrown.
+* @returns True for `ENOENT` and `ENOTDIR`.
+*/
+function isMissing(error) {
+	const code = error instanceof Error && "code" in error ? error.code : void 0;
+	return code === "ENOENT" || code === "ENOTDIR";
+}
+/**
+* Whether an absolute path lies inside a folder.
+*
+* @param folder - The absolute folder.
+* @param file - The absolute path.
+* @returns True for the folder itself and anything below it.
+*/
+function isInside(folder, file) {
+	const relative = path.relative(folder, file);
+	return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+/**
+* The error of a path that leaves the root.
+*
+* @param file - The path as it was given.
+* @param root - The real root.
+* @returns The error to throw.
+*/
+function leavesRoot(file, root) {
+	return /* @__PURE__ */ new Error(`[game] The path "${file}" leaves the project root.\n  Pass a path inside "${root}", relative to it.`);
+}
+/**
+* Checks the root of a project and resolves it: it exists, it is a directory, and its real path
+* is the one every read is held to.
+*
+* @param root - The root as given, absolute or relative to the working directory.
+* @returns The real absolute path of the root.
+* @throws {Error} When the root does not exist or is not a directory.
+*/
+async function openRoot(root) {
+	const absolute = path.resolve(root);
+	if (!(await stat(absolute).catch((error) => {
+		if (!isMissing(error)) throw error;
+		throw new Error(`[game] The project root "${absolute}" does not exist.\n  ${ROOT_HINT}`);
+	})).isDirectory()) throw new Error(`[game] The project root "${absolute}" is not a directory.\n  ${ROOT_HINT}`);
+	return realpath(absolute);
+}
+/**
+* Resolves a root-relative path to the real file, refusing any path that leaves the root.
+*
+* @param root - The real root.
+* @param file - The root-relative path.
+* @returns The real absolute path, or `undefined` when nothing is there.
+* @throws {Error} When the path leaves the root, by `..`, as an absolute path or by a symlink.
+*/
+async function resolveInside(root, file) {
+	const absolute = path.resolve(root, file);
+	if (!isInside(root, absolute)) throw leavesRoot(file, root);
+	let real;
+	try {
+		real = await realpath(absolute);
+	} catch (error) {
+		if (isMissing(error)) return;
+		throw error;
+	}
+	if (!isInside(root, real)) throw leavesRoot(file, root);
+	return real;
+}
+/**
+* Reads the bytes of a root-relative file through the guard. A path that leaves the root reads as
+* nothing here; `changed` refuses it by name with `resolveInside` first.
+*
+* @param root - The real root.
+* @param file - The root-relative path.
+* @returns The bytes, or `undefined` when the file is gone or lies outside the root.
+*/
+async function readInside(root, file) {
+	try {
+		const real = await resolveInside(root, file);
+		if (real !== void 0) return await readFile(real);
+	} catch {}
+}
+//#endregion
+//#region src/project/aliases.ts
+/**
+* @file project — the tsconfig `paths` of a game, the one alias resolver of the index. A v15 game
+* imports across its layers through aliases (`@core/kit`, `@features/home`, `@shared`). The
+* tsconfig is read with TypeScript, so JSONC and the `extends` chain are TypeScript's own; a
+* specifier is matched the way TypeScript matches it: an exact key first, then the `*` key with
+* the longest prefix. The engine is a package by definition and is never matched. Paths in and
+* out are root-relative POSIX.
+*/
+/** A specifier relative to the importing file, or an absolute path: never an alias. */
+const NOT_BARE = /^(?:\.{1,2}(?:\/|$)|\/)/;
+/** The hint under a tsconfig that does not parse. */
+const PARSE_HINT = "Fix the file, or name another one with the tsconfig option or --tsconfig.";
+/** TypeScript numbers its syntax diagnostics from 1000 to 1999. */
+const SYNTAX_CODES = {
+	from: 1e3,
+	below: 2e3
+};
+/**
+* Whether a specifier names the engine, which is a package even when the paths map it.
+*
+* @param specifier - A module specifier.
+* @returns True for `@moku-labs/game` and its subpaths.
+* @example
+* ```ts
+* isEngine("@moku-labs/game/testing"); // true
+* ```
+*/
+function isEngine(specifier) {
+	return specifier === "@moku-labs/game" || specifier.startsWith(`@moku-labs/game/`);
+}
+/**
+* How many `*` a key or a target holds.
+*
+* @param text - A key or a target of `paths`.
+* @returns The count.
+* @example
+* ```ts
+* starsOf("@features/*"); // 1
+* ```
+*/
+function starsOf(text) {
+	return text.split("*").length - 1;
+}
+/**
+* Whether a diagnostic of a tsconfig says a file does not parse: a syntax error in the tsconfig
+* or in a file it extends. TypeScript also reports an unknown option, a missing `extends` and
+* the empty file list of a read that lists no files; none of them hides the `paths`.
+*
+* @param diagnostic - A diagnostic of the read.
+* @returns True for a syntax error of a file.
+*/
+function isSyntaxError(diagnostic) {
+	return diagnostic.file !== void 0 && diagnostic.code >= SYNTAX_CODES.from && diagnostic.code < SYNTAX_CODES.below;
+}
+/**
+* The error of a tsconfig that does not parse, naming the file and the place as
+* `path:line:col message`.
+*
+* @param typescript - The TypeScript module.
+* @param root - The real root.
+* @param file - The tsconfig, root-relative.
+* @param diagnostic - The syntax error.
+* @returns The error to throw.
+*/
+function doesNotParse(typescript, root, file, diagnostic) {
+	const text = typescript.flattenDiagnosticMessageText(diagnostic.messageText, " ");
+	const message = text.endsWith(".") ? text : `${text}.`;
+	const source = diagnostic.file;
+	let place = "";
+	if (source !== void 0) {
+		const { line, character } = source.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
+		place = `${toPosix(path.relative(root, source.fileName))}:${line + 1}:${character + 1} `;
+	}
+	return /* @__PURE__ */ new Error(`[game] The tsconfig "${file}" does not parse: ${place}${message}\n  ${PARSE_HINT}`);
+}
+/**
+* The targets of one key of `paths`, root-relative: each string target with one `*` at most,
+* resolved against the base folder. TypeScript does not check the shape of `paths`, so the value
+* is read as the JSON it is.
+*
+* @param root - The real root.
+* @param base - The absolute folder the targets are relative to.
+* @param value - The value of the key.
+* @returns The targets, `*` kept.
+*/
+function targetsOf(root, base, value) {
+	if (!Array.isArray(value)) return [];
+	return value.filter((target) => typeof target === "string" && starsOf(target) <= 1).map((target) => toPosix(path.relative(root, path.resolve(base, target))));
+}
+/**
+* The patterns of a `paths` block: one per key with one `*` at most and a target. A key or a
+* target with two `*` never matches in TypeScript, so it is dropped here.
+*
+* @param root - The real root.
+* @param base - The absolute folder the targets are relative to.
+* @param paths - The `paths` of the merged options.
+* @returns The patterns, in the order of the keys.
+*/
+function patternsOf(root, base, paths) {
+	const patterns = [];
+	for (const [key, value] of Object.entries(paths)) {
+		const targets = targetsOf(root, base, value);
+		const star = key.indexOf("*");
+		if (targets.length === 0 || starsOf(key) > 1) continue;
+		patterns.push(star === -1 ? {
+			prefix: key,
+			targets
+		} : {
+			prefix: key.slice(0, star),
+			suffix: key.slice(star + 1),
+			targets
+		});
+	}
+	return patterns;
+}
+/**
+* The files TypeScript read for a tsconfig that lie inside the root, outside `node_modules`,
+* root-relative and each once. A file it tried and did not find is kept: its arrival changes the
+* aliases.
+*
+* @param root - The real root.
+* @param read - The absolute paths TypeScript asked for, in order.
+* @returns The root-relative paths.
+*/
+function sourcesInside(root, read) {
+	const inside = read.map((file) => toPosix(path.relative(root, file))).filter((file) => !file.startsWith("../") && !path.isAbsolute(file)).filter((file) => !file.split("/").includes("node_modules"));
+	return [...new Set(inside)];
+}
+/**
+* Parses a tsconfig with TypeScript: comments and trailing commas included, its `extends` chain
+* merged, and every file TypeScript reads for that chain noted. No file is listed, so the parse
+* stays cheap.
+*
+* @param typescript - The TypeScript module.
+* @param root - The real root.
+* @param file - The tsconfig, root-relative POSIX.
+* @param text - The text of the tsconfig.
+* @returns The merged options and the files TypeScript read.
+* @throws {Error} When the tsconfig or a file it extends does not parse.
+*/
+function parseTsconfigOptions(typescript, root, file, text) {
+	const absolute = path.join(root, file);
+	const parsed = typescript.parseConfigFileTextToJson(absolute, text);
+	if (parsed.error !== void 0) throw doesNotParse(typescript, root, file, parsed.error);
+	const read = [];
+	const host = {
+		...typescript.sys,
+		readDirectory: () => [],
+		readFile: (name) => {
+			read.push(name);
+			return typescript.sys.readFile(name);
+		}
+	};
+	const { options, errors } = typescript.parseJsonConfigFileContent(parsed.config, host, path.dirname(absolute), void 0, absolute);
+	const syntax = errors.find((diagnostic) => isSyntaxError(diagnostic));
+	if (syntax !== void 0) throw doesNotParse(typescript, root, file, syntax);
+	return {
+		options,
+		read
+	};
+}
+/**
+* The folder TypeScript resolves `paths` against when no `baseUrl` is set: the folder of the
+* config that declares them, which may be a file the tsconfig extends. TypeScript keeps it on the
+* merged options as `pathsBasePath`, outside its published types.
+*
+* @param options - The merged options.
+* @returns The absolute folder, or `undefined` when no config declares `paths`.
+*/
+function pathsBaseOf(options) {
+	const base = options.pathsBasePath;
+	return typeof base === "string" ? base : void 0;
+}
+/**
+* Reads the tsconfig `paths` of a game. TypeScript parses the file and merges its `extends`
+* chain. The targets resolve against `baseUrl` when one is set, else against the folder of the
+* config that declares `paths`, as TypeScript resolves them: the folder of the tsconfig, or of the
+* file it extends that holds the block.
+*
+* @param typescript - The TypeScript module.
+* @param root - The real root.
+* @param file - The tsconfig, root-relative POSIX.
+* @returns The aliases, or `undefined` when the file is missing. A tsconfig without `paths` has
+*   no patterns and still lists its sources, so a `paths` block added to a file it extends is seen.
+* @throws {Error} When the tsconfig or a file it extends does not parse.
+*/
+async function readAliases(typescript, root, file) {
+	const bytes = await readInside(root, file);
+	if (bytes === void 0) return void 0;
+	const { options, read } = parseTsconfigOptions(typescript, root, file, new TextDecoder().decode(bytes));
+	const patterns = patternsOf(root, options.baseUrl ?? pathsBaseOf(options) ?? path.dirname(path.join(root, file)), options.paths ?? {});
+	return {
+		file,
+		sources: [.../* @__PURE__ */ new Set([file, ...sourcesInside(root, read)])],
+		patterns
+	};
+}
+/**
+* Whether a `*` key matches a specifier.
+*
+* @param pattern - A key with `*`.
+* @param suffix - Its suffix.
+* @param specifier - The module specifier.
+* @returns True when the specifier starts with the prefix and ends with the suffix.
+* @example
+* ```ts
+* matchesStar({ prefix: "@core/", suffix: "", targets: ["core/*"] }, "", "@core/kit"); // true
+* ```
+*/
+function matchesStar(pattern, suffix, specifier) {
+	return specifier.length >= pattern.prefix.length + suffix.length && specifier.startsWith(pattern.prefix) && specifier.endsWith(suffix);
+}
+/**
+* Whether a specifier is never an alias: a path relative to the importing file, an absolute path,
+* or the engine.
+*
+* @param specifier - The module specifier as written.
+* @returns True when no key of `paths` may match it.
+* @example
+* ```ts
+* isNeverAlias("@moku-labs/game/testing"); // true
+* ```
+*/
+function isNeverAlias(specifier) {
+	return NOT_BARE.test(specifier) || isEngine(specifier);
+}
+/**
+* Whether a key of `paths` is a `*` key that matches a specifier with a longer prefix than the
+* best match so far.
+*
+* @param pattern - A key of `paths`.
+* @param best - The best `*` match so far, if any.
+* @param specifier - The module specifier.
+* @returns True when the key is the better match.
+* @example
+* ```ts
+* isBetterMatch({ prefix: "@core/", suffix: "", targets: ["core/*"] }, undefined, "@core/kit"); // true
+* ```
+*/
+function isBetterMatch(pattern, best, specifier) {
+	const isLonger = best === void 0 || pattern.prefix.length > best.prefix.length;
+	return pattern.suffix !== void 0 && isLonger && matchesStar(pattern, pattern.suffix, specifier);
+}
+/**
+* The targets a specifier maps to, the way TypeScript maps it: a key without `*` equal to the
+* specifier wins; else the `*` key with the longest prefix, its `*` filled into every target. A
+* relative or absolute specifier, the engine (`@moku-labs/game` and its subpaths) and a specifier
+* no key matches map to nothing.
+*
+* @param aliases - The aliases of the game, if it declares some.
+* @param specifier - The module specifier as written.
+* @returns The root-relative targets in the order of the tsconfig; `[]` for no match.
+* @example
+* ```ts
+* // map: the aliases of tests/fixtures/layout-game/tsconfig.json
+* aliasTargets(map, "@features/orders"); // ["features/orders/index.ts"]
+* aliasTargets(map, "@moku-labs/game/testing"); // []
+* ```
+*/
+function aliasTargets(aliases, specifier) {
+	if (aliases === void 0 || isNeverAlias(specifier)) return [];
+	const exact = aliases.patterns.find((pattern) => pattern.suffix === void 0 && pattern.prefix === specifier);
+	if (exact !== void 0) return [...exact.targets];
+	let best;
+	for (const pattern of aliases.patterns) if (isBetterMatch(pattern, best, specifier)) best = pattern;
+	if (best === void 0) return [];
+	const hole = specifier.slice(best.prefix.length, specifier.length - best.suffix.length);
+	return best.targets.map((target) => target.replace("*", () => hole));
+}
+/**
+* Whether two keys of `paths` are the same key with the same targets.
+*
+* @param first - One pattern.
+* @param second - The other, if any.
+* @returns True when prefix, suffix and targets are equal.
+* @example
+* ```ts
+* samePattern({ prefix: "@kit", targets: ["kit.ts"] }, { prefix: "@kit", targets: ["kit.ts"] }); // true
+* ```
+*/
+function samePattern(first, second) {
+	return second !== void 0 && first.prefix === second.prefix && first.suffix === second.suffix && first.targets.length === second.targets.length && first.targets.every((target, at) => target === second.targets[at]);
+}
+/**
+* Whether two reads of the aliases resolve alike: the same tsconfig and the same patterns in the
+* same order. The sources are left out: they feed the stamps, not the resolution.
+*
+* @param first - The aliases before, or `undefined` for none.
+* @param second - The aliases after, or `undefined` for none.
+* @returns True when the index built with either is the same.
+* @example
+* ```ts
+* sameAliases(undefined, undefined); // true
+* ```
+*/
+function sameAliases(first, second) {
+	if (first === void 0 || second === void 0) return first === second;
+	return first.file === second.file && first.patterns.length === second.patterns.length && first.patterns.every((pattern, at) => samePattern(pattern, second.patterns[at]));
+}
+//#endregion
 //#region src/project/extract/resolve.ts
 /**
 * @file project, extract — following a name across files with the module facts only: an import
-* to the module it names, a re-export to the module behind it, a star export to the first module
-* that has the name, until the name is declared, handed out by the kit, or comes from a package.
-* This is how a definer is recognised by binding (a renamed import still is the definer) and how
-* a node of a flow table reaches the file that declares it.
+* to the module it names, through a tsconfig alias when the game declares one, a re-export to the
+* module behind it, a star export to the first module that has the name, until the name is
+* declared, handed out by the kit, or comes from a package. This is how a definer is recognised
+* by binding (a renamed import still is the definer) and how a node of a flow table reaches the
+* file that declares it.
 */
 /** How many imports and re-exports a name is followed through before giving up. */
 const MAX_HOPS = 12;
@@ -900,20 +1352,18 @@ function isRelative(specifier) {
 	return specifier === "." || specifier === ".." || specifier.startsWith("./") || specifier.startsWith("../");
 }
 /**
-* Resolves a relative module specifier to an indexed file, the way a bundler does: the path as
-* written, then with `.ts`, `.tsx`, `/index.ts` and `/index.tsx`.
+* The indexed file a root-relative path names, the way a bundler finds it: the path as written,
+* then with `.ts`, `.tsx`, `/index.ts` and `/index.tsx`.
 *
 * @param modules - The module facts by path.
-* @param from - The importing file.
-* @param specifier - The module specifier.
-* @returns The root-relative path, or `undefined` for a package or a file the index does not hold.
+* @param base - A root-relative path.
+* @returns The path the index holds, or `undefined`.
 */
-function resolveModulePath(modules, from, specifier) {
-	if (!isRelative(specifier)) return void 0;
-	const base = path.posix.normalize(path.posix.join(path.posix.dirname(from), specifier));
-	const stem = base.replace(SCRIPT_EXTENSION, "");
+function indexedFile(modules, base) {
+	const normal = path.posix.normalize(base);
+	const stem = normal.replace(SCRIPT_EXTENSION, "");
 	return [
-		base,
+		normal,
 		`${stem}.ts`,
 		`${stem}.tsx`,
 		`${stem}/index.ts`,
@@ -921,40 +1371,69 @@ function resolveModulePath(modules, from, specifier) {
 	].find((candidate) => modules.has(candidate));
 }
 /**
+* Resolves a module specifier to an indexed file: a relative one against the importing file, any
+* other through the targets of the tsconfig alias it matches, the first target the index holds
+* winning. Each candidate is tried as written, then with `.ts`, `.tsx`, `/index.ts` and
+* `/index.tsx`.
+*
+* @param resolution - The module facts and the aliases.
+* @param from - The importing file.
+* @param specifier - The module specifier.
+* @returns The root-relative path, or `undefined` for a package or a file the index does not hold.
+*/
+function resolveModulePath(resolution, from, specifier) {
+	const { modules } = resolution;
+	if (isRelative(specifier)) return indexedFile(modules, path.posix.join(path.posix.dirname(from), specifier));
+	for (const target of aliasTargets(resolution.aliases, specifier)) {
+		const found = indexedFile(modules, target);
+		if (found !== void 0) return found;
+	}
+}
+/**
+* Whether a specifier names a package: it is not relative and no tsconfig alias matches it.
+*
+* @param resolution - The module facts and the aliases.
+* @param specifier - The module specifier.
+* @returns True for a package.
+*/
+function isPackage(resolution, specifier) {
+	return !isRelative(specifier) && aliasTargets(resolution.aliases, specifier).length === 0;
+}
+/**
 * Follows an imported name into the module that the specifier names.
 *
-* @param modules - The module facts by path.
+* @param resolution - The module facts and the aliases.
 * @param from - The importing file.
 * @param ref - The specifier and the name.
 * @param hops - How many hops were taken so far.
 * @returns Where the name ends up.
 */
-function followImport(modules, from, ref, hops) {
-	if (!isRelative(ref.specifier)) return {
+function followImport(resolution, from, ref, hops) {
+	if (isPackage(resolution, ref.specifier)) return {
 		kind: "package",
 		...ref
 	};
 	if (ref.imported === "*") return void 0;
-	const target = resolveModulePath(modules, from, ref.specifier);
-	return target === void 0 ? void 0 : resolveExport(modules, target, ref.imported, hops + 1);
+	const target = resolveModulePath(resolution, from, ref.specifier);
+	return target === void 0 ? void 0 : resolveExport(resolution, target, ref.imported, hops + 1);
 }
 /**
 * Follows an exported name of a module: a local binding, a re-export, or a star export.
 *
-* @param modules - The module facts by path.
+* @param resolution - The module facts and the aliases.
 * @param file - The module.
 * @param name - The exported name.
 * @param hops - How many hops were taken so far.
 * @returns Where the name ends up.
 */
-function resolveExport(modules, file, name, hops = 0) {
-	const facts = modules.get(file);
+function resolveExport(resolution, file, name, hops = 0) {
+	const facts = resolution.modules.get(file);
 	if (facts === void 0 || hops > MAX_HOPS) return void 0;
 	const ref = facts.exports.get(name);
-	if (ref !== void 0 && "local" in ref) return resolveBinding(modules, file, ref.local, hops + 1);
-	if (ref !== void 0) return followImport(modules, file, ref, hops);
+	if (ref !== void 0 && "local" in ref) return resolveBinding(resolution, file, ref.local, hops + 1);
+	if (ref !== void 0) return followImport(resolution, file, ref, hops);
 	for (const specifier of facts.stars) {
-		const found = followImport(modules, file, {
+		const found = followImport(resolution, file, {
 			specifier,
 			imported: name
 		}, hops);
@@ -965,14 +1444,14 @@ function resolveExport(modules, file, name, hops = 0) {
 * Follows a name used in a file to where it ends up: the kit hands it out, the file declares it,
 * or an import brings it.
 *
-* @param modules - The module facts by path.
+* @param resolution - The module facts and the aliases.
 * @param file - The file that uses the name.
 * @param local - The name as the file writes it.
 * @param hops - How many hops were taken so far.
 * @returns Where the name ends up, or `undefined` when it cannot be followed.
 */
-function resolveBinding(modules, file, local, hops = 0) {
-	const facts = modules.get(file);
+function resolveBinding(resolution, file, local, hops = 0) {
+	const facts = resolution.modules.get(file);
 	if (facts === void 0 || hops > MAX_HOPS) return void 0;
 	const definer = facts.kit.get(local);
 	if (definer !== void 0) return {
@@ -985,7 +1464,21 @@ function resolveBinding(modules, file, local, hops = 0) {
 		binding: local
 	};
 	const ref = facts.imports.get(local);
-	return ref === void 0 ? void 0 : followImport(modules, file, ref, hops);
+	return ref === void 0 ? void 0 : followImport(resolution, file, ref, hops);
+}
+/**
+* The alias a name of a file is imported through when that alias reaches no indexed file: a
+* tsconfig key matched the specifier, and none of its targets is a file of the root.
+*
+* @param resolution - The module facts and the aliases.
+* @param file - The file that imports the name.
+* @param local - The name as the file writes it.
+* @returns The specifier as written, or `undefined` when the import is not such an alias.
+*/
+function missedAlias(resolution, file, local) {
+	const ref = resolution.modules.get(file)?.imports.get(local);
+	if (!(ref !== void 0 && !isRelative(ref.specifier) && !isPackage(resolution, ref.specifier))) return void 0;
+	return resolveModulePath(resolution, file, ref.specifier) === void 0 ? ref.specifier : void 0;
 }
 /**
 * The definer a target is, if any: one the kit hands out, or one imported from the engine.
@@ -1005,21 +1498,21 @@ function definerOf(target) {
 /**
 * Adds the definers a namespace import reaches as `ns.name`.
 *
-* @param modules - The module facts by path.
+* @param resolution - The module facts and the aliases.
 * @param file - The importing file.
 * @param namespace - The local name of the namespace.
 * @param specifier - The module it imports.
 * @param definers - The map to add to.
 */
-function addNamespace(modules, file, namespace, specifier, definers) {
+function addNamespace(resolution, file, namespace, specifier, definers) {
 	if (specifier === "@moku-labs/game") {
 		for (const definer of DEFINERS) definers.set(`${namespace}.${definer}`, definer);
 		return;
 	}
-	const target = resolveModulePath(modules, file, specifier);
-	const names = target === void 0 ? [] : [...modules.get(target)?.exports.keys() ?? []];
+	const target = resolveModulePath(resolution, file, specifier);
+	const names = target === void 0 ? [] : [...resolution.modules.get(target)?.exports.keys() ?? []];
 	for (const name of names) {
-		const definer = definerOf(resolveExport(modules, target ?? "", name));
+		const definer = definerOf(resolveExport(resolution, target ?? "", name));
 		if (definer !== void 0) definers.set(`${namespace}.${name}`, definer);
 	}
 }
@@ -1027,19 +1520,19 @@ function addNamespace(modules, file, namespace, specifier, definers) {
 * The definers a file can call, by the callee as the file writes it: `defineFlow`, a renamed
 * `scene`, or `kit.defineScene` through a namespace.
 *
-* @param modules - The module facts by path.
+* @param resolution - The module facts and the aliases.
 * @param file - The file.
 * @returns The callee text to the definer.
 */
-function definersOf(modules, file) {
-	const facts = modules.get(file);
+function definersOf(resolution, file) {
+	const facts = resolution.modules.get(file);
 	const definers = new Map(facts?.kit);
 	for (const [local, ref] of facts?.imports ?? []) {
 		if (ref.imported === "*") {
-			addNamespace(modules, file, local, ref.specifier, definers);
+			addNamespace(resolution, file, local, ref.specifier, definers);
 			continue;
 		}
-		const definer = definerOf(resolveBinding(modules, file, local));
+		const definer = definerOf(resolveBinding(resolution, file, local));
 		if (definer !== void 0) definers.set(local, definer);
 	}
 	return definers;
@@ -1121,6 +1614,20 @@ function entryOf(symbols, key) {
 	return entry;
 }
 /**
+* Why a name of a flow table cannot be followed: the alias it is imported through reaches no
+* file, or it is declared in no file of the root.
+*
+* @param resolution - The module facts and the aliases.
+* @param file - The flow file.
+* @param node - The key of the entry, `main/home`.
+* @param ref - The name the entry holds.
+* @returns The reason for the unresolved list.
+*/
+function unfollowed(resolution, file, node, ref) {
+	const alias = missedAlias(resolution, file, ref);
+	return alias === void 0 ? `node "${node}": "${ref}" is not declared in a file of the root` : `node "${node}": "${ref}" is imported from "${alias}", which names no file of the root`;
+}
+/**
 * Adds the `node:` keys of one flow table. A plain name is followed to the file that declares
 * it, and the table is its use; a slot or an inline node is anchored at the table. A name that
 * cannot be followed is anchored at the table and listed as unresolved.
@@ -1136,13 +1643,17 @@ function addTable(assembly, symbols, unresolved, file, table) {
 		path: file,
 		binding: table.binding
 	};
+	const resolution = {
+		modules: assembly.modules,
+		aliases: assembly.aliases
+	};
 	for (const { name, ref } of table.entries) {
 		const entry = entryOf(symbols, `${NODE}${table.flow}/${name}`);
 		const atTable = {
 			...use,
 			key: name
 		};
-		const target = ref === void 0 ? void 0 : resolveBinding(assembly.modules, file, ref);
+		const target = ref === void 0 ? void 0 : resolveBinding(resolution, file, ref);
 		if (target?.kind === "declared") {
 			entry.def.push({
 				path: target.path,
@@ -1152,13 +1663,10 @@ function addTable(assembly, symbols, unresolved, file, table) {
 			continue;
 		}
 		entry.def.push(atTable);
-		if (ref !== void 0) {
-			const reason = `node "${table.flow}/${name}": "${ref}" is not declared in a file of the root`;
-			unresolved.push({
-				path: file,
-				reason
-			});
-		}
+		if (ref !== void 0) unresolved.push({
+			path: file,
+			reason: unfollowed(resolution, file, `${table.flow}/${name}`, ref)
+		});
 	}
 }
 /**
@@ -1168,8 +1676,12 @@ function addTable(assembly, symbols, unresolved, file, table) {
 * @param symbols - The keys so far.
 */
 function addStyleUses(assembly, symbols) {
+	const resolution = {
+		modules: assembly.modules,
+		aliases: assembly.aliases
+	};
 	for (const [file, record] of assembly.files) for (const [local, ref] of record.good?.module.imports ?? []) {
-		const target = ref.imported === "*" ? void 0 : resolveBinding(assembly.modules, file, local);
+		const target = ref.imported === "*" ? void 0 : resolveBinding(resolution, file, local);
 		(target?.kind === "declared" ? symbols.get(`style:${target.path}#${target.binding}`) : void 0)?.uses.push({
 			path: file,
 			binding: local
@@ -1258,9 +1770,9 @@ function deepFreeze(value) {
 	return value;
 }
 /**
-* Assembles the index of a catalog.
+* Assembles the index of a catalog. The index names the tsconfig when the assembly has aliases.
 *
-* @param assembly - The records sorted by path, and the module facts of the good files.
+* @param assembly - The records sorted by path, the module facts of the good files, the aliases.
 * @param manifest - The root-relative manifest path when the file exists.
 * @returns The index, frozen.
 */
@@ -1292,6 +1804,7 @@ function assembleIndex(assembly, manifest) {
 		schemaVersion: 1,
 		revision: revisionOf(files),
 		...manifest === void 0 ? {} : { manifest },
+		...assembly.aliases === void 0 ? {} : { tsconfig: assembly.aliases.file },
 		symbols: finishSymbols(symbols),
 		files,
 		unresolved
@@ -1736,13 +2249,6 @@ function parseFile(typescript, path, text) {
 }
 //#endregion
 //#region src/project/catalog.ts
-/**
-* @file project — the catalog: one record per indexed file and a cache of parses. A file is
-* parsed once per version of its bytes; a file that stops parsing keeps its last good parse, so
-* its keys stay in the index while it is broken. Building the index reads the module facts of
-* every good file, re-extracts only the files whose bytes or reachable definers changed, and
-* assembles the result.
-*/
 /** How many parses the cache keeps; the oldest goes first. */
 const PARSE_CACHE_SIZE = 512;
 /**
@@ -1828,16 +2334,17 @@ function dropFile(catalog, path) {
 }
 /**
 * Brings the keys of every good file up to date: a file is read again when its good version or
-* the definers it reaches changed since it was last read.
+* the definers it reaches changed since it was last read. An alias change that moves the
+* definers of a file moves its stamp, so a tsconfig edit re-reads exactly the files it affects.
 *
 * @param catalog - The catalog.
-* @param modules - The module facts of every good file.
+* @param resolution - The module facts of every good file, and the aliases.
 */
-function refreshExtractions(catalog, modules) {
+function refreshExtractions(catalog, resolution) {
 	for (const [path, record] of catalog.records) {
 		const good = record.good;
 		if (good === void 0) continue;
-		const definers = definersOf(modules, path);
+		const definers = definersOf(resolution, path);
 		const signature = [...definers].map(([callee, definer]) => `${callee}=${definer}`).join(";");
 		const stamp = `${good.hash}|${signature}`;
 		if (record.extracted?.definers === stamp) continue;
@@ -1853,16 +2360,21 @@ function refreshExtractions(catalog, modules) {
 *
 * @param catalog - The catalog.
 * @param manifest - The root-relative manifest path when the file exists.
+* @param aliases - The tsconfig aliases when the game declares some.
 * @returns The index, frozen.
 */
-function buildIndex(catalog, manifest) {
+function buildIndex(catalog, manifest, aliases) {
 	const files = [...catalog.records].toSorted(([first], [second]) => first < second ? -1 : 1);
 	const modules = /* @__PURE__ */ new Map();
 	for (const [path, record] of files) if (record.good !== void 0) modules.set(path, record.good.module);
-	refreshExtractions(catalog, modules);
+	refreshExtractions(catalog, {
+		modules,
+		aliases
+	});
 	return assembleIndex({
 		files,
-		modules
+		modules,
+		aliases
 	}, manifest);
 }
 //#endregion
@@ -1977,183 +2489,33 @@ function locateFactory(typescript, source, anchor, context) {
 	if (anchor.key !== void 0) {
 		const property = propertyIn(typescript, factory.node, anchor.key);
 		if (property === void 0 || !typescript.isPropertyAssignment(property)) return [];
-		return [placeOf(source, property, unwrap(typescript, property.initializer))];
-	}
-	const definers = context.definers?.() ?? /* @__PURE__ */ new Map();
-	return styleCallsIn(typescript, factory.node, definers).map((call) => placeOf(source, call, call));
-}
-/**
-* Reads an anchor on one parse of its file.
-*
-* @param typescript - The TypeScript module.
-* @param source - The parsed file.
-* @param anchor - The anchor.
-* @param context - The kind of its key, the JSX hits of the parse and the definers of the file.
-* @returns Every place of the anchor in the file; none when the file no longer holds it.
-*/
-function locate(typescript, source, anchor, context = {}) {
-	if (anchor.kind !== void 0) return (context.jsxHits?.() ?? collectJsx(typescript, source)).filter((hit) => hit.key === anchor.key && hit.kind === anchor.kind && hit.component === anchor.component && hit.prop === anchor.prop).map((hit) => placeOf(source, hit.attribute, hit.element));
-	if (anchor.binding === void 0) {
-		const place = anchor.key === void 0 ? void 0 : writtenAt(typescript, source, anchor.key);
-		return place === void 0 ? [] : [place];
-	}
-	const built = context.keyKind === STYLE_KIND ? locateFactory(typescript, source, anchor, context) : [];
-	if (built.length > 0) return built;
-	const binding = anchor.binding;
-	const statement = source.statements.find((item) => declares(typescript, item, binding));
-	if (statement === void 0) return [];
-	const node = (anchor.key === void 0 ? void 0 : propertyIn(typescript, statement, anchor.key)) ?? statement;
-	return [placeOf(source, node, node)];
-}
-//#endregion
-//#region src/project/paths.ts
-/**
-* @file project — which files the index reads, and the guard on every path it reads. Paths in and
-* out are root-relative POSIX. A read resolves the path against the real root with `realpath`, so
-* a `..` or a symlink that leaves the root is refused by name instead of read.
-*/
-/** The folders a game never edits by hand: dependencies, builds, generated code and tests. */
-const SKIPPED_FOLDER = /^(?:node_modules|dist|generated|\.moku|\.git|__tests__|tests)$/;
-/** The source files the index reads. */
-const SOURCE_FILE = /\.tsx?$/;
-/** Test files, skipped wherever they sit. */
-const TEST_FILE = /\.(?:test|spec)\.tsx?$/;
-/** The hint under every root error. */
-const ROOT_HINT = "Pass the folder of the game as root.";
-/**
-* Whether a folder name is one the index never walks into.
-*
-* @param name - One folder name.
-* @returns True for `node_modules`, `dist`, `generated`, `.moku`, `.git`, `__tests__` and `tests`.
-* @example
-* ```ts
-* isSkippedFolder("generated"); // true
-* ```
-*/
-function isSkippedFolder(name) {
-	return SKIPPED_FOLDER.test(name);
-}
-/**
-* Whether a root-relative path sits under a skipped folder.
-*
-* @param file - A path with `/` or `\` separators.
-* @returns True when one of its folders is skipped.
-* @example
-* ```ts
-* isSkippedPath("node_modules/pixi.js/index.ts"); // true
-* ```
-*/
-function isSkippedPath(file) {
-	return file.split(/[/\\]/).slice(0, -1).some((folder) => isSkippedFolder(folder));
-}
-/**
-* Whether the index reads a root-relative path: a `.ts` or `.tsx` file outside the skipped
-* folders that is not a test.
-*
-* @param file - A root-relative POSIX path.
-* @returns True for a source file of the index.
-* @example
-* ```ts
-* isIndexedFile("features/ui/kit.tsx"); // true
-* ```
-*/
-function isIndexedFile(file) {
-	return SOURCE_FILE.test(file) && !TEST_FILE.test(file) && !isSkippedPath(file);
-}
-/**
-* Turns a path into its root-relative POSIX form.
-*
-* @param file - A path with any separators.
-* @returns The path with `/` separators, `.` segments resolved.
-* @example
-* ```ts
-* toPosix("./features\\ui\\kit.tsx"); // "features/ui/kit.tsx"
-* ```
-*/
-function toPosix(file) {
-	return path.posix.normalize(file.replaceAll("\\", "/"));
-}
-/**
-* Whether a file system error says nothing is at the path.
-*
-* @param error - What was thrown.
-* @returns True for `ENOENT` and `ENOTDIR`.
-*/
-function isMissing(error) {
-	const code = error instanceof Error && "code" in error ? error.code : void 0;
-	return code === "ENOENT" || code === "ENOTDIR";
-}
-/**
-* Whether an absolute path lies inside a folder.
-*
-* @param folder - The absolute folder.
-* @param file - The absolute path.
-* @returns True for the folder itself and anything below it.
-*/
-function isInside(folder, file) {
-	const relative = path.relative(folder, file);
-	return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
-}
-/**
-* The error of a path that leaves the root.
-*
-* @param file - The path as it was given.
-* @param root - The real root.
-* @returns The error to throw.
-*/
-function leavesRoot(file, root) {
-	return /* @__PURE__ */ new Error(`[game] The path "${file}" leaves the project root.\n  Pass a path inside "${root}", relative to it.`);
-}
-/**
-* Checks the root of a project and resolves it: it exists, it is a directory, and its real path
-* is the one every read is held to.
-*
-* @param root - The root as given, absolute or relative to the working directory.
-* @returns The real absolute path of the root.
-* @throws {Error} When the root does not exist or is not a directory.
-*/
-async function openRoot(root) {
-	const absolute = path.resolve(root);
-	if (!(await stat(absolute).catch((error) => {
-		if (!isMissing(error)) throw error;
-		throw new Error(`[game] The project root "${absolute}" does not exist.\n  ${ROOT_HINT}`);
-	})).isDirectory()) throw new Error(`[game] The project root "${absolute}" is not a directory.\n  ${ROOT_HINT}`);
-	return realpath(absolute);
-}
-/**
-* Resolves a root-relative path to the real file, refusing any path that leaves the root.
-*
-* @param root - The real root.
-* @param file - The root-relative path.
-* @returns The real absolute path, or `undefined` when nothing is there.
-* @throws {Error} When the path leaves the root, by `..`, as an absolute path or by a symlink.
-*/
-async function resolveInside(root, file) {
-	const absolute = path.resolve(root, file);
-	if (!isInside(root, absolute)) throw leavesRoot(file, root);
-	let real;
-	try {
-		real = await realpath(absolute);
-	} catch (error) {
-		if (isMissing(error)) return;
-		throw error;
+		return [placeOf(source, property, unwrap(typescript, property.initializer))];
 	}
-	if (!isInside(root, real)) throw leavesRoot(file, root);
-	return real;
+	const definers = context.definers?.() ?? /* @__PURE__ */ new Map();
+	return styleCallsIn(typescript, factory.node, definers).map((call) => placeOf(source, call, call));
 }
 /**
-* Reads the bytes of a root-relative file through the guard. A path that leaves the root reads as
-* nothing here; `changed` refuses it by name with `resolveInside` first.
+* Reads an anchor on one parse of its file.
 *
-* @param root - The real root.
-* @param file - The root-relative path.
-* @returns The bytes, or `undefined` when the file is gone or lies outside the root.
+* @param typescript - The TypeScript module.
+* @param source - The parsed file.
+* @param anchor - The anchor.
+* @param context - The kind of its key, the JSX hits of the parse and the definers of the file.
+* @returns Every place of the anchor in the file; none when the file no longer holds it.
 */
-async function readInside(root, file) {
-	try {
-		const real = await resolveInside(root, file);
-		if (real !== void 0) return await readFile(real);
-	} catch {}
+function locate(typescript, source, anchor, context = {}) {
+	if (anchor.kind !== void 0) return (context.jsxHits?.() ?? collectJsx(typescript, source)).filter((hit) => hit.key === anchor.key && hit.kind === anchor.kind && hit.component === anchor.component && hit.prop === anchor.prop).map((hit) => placeOf(source, hit.attribute, hit.element));
+	if (anchor.binding === void 0) {
+		const place = anchor.key === void 0 ? void 0 : writtenAt(typescript, source, anchor.key);
+		return place === void 0 ? [] : [place];
+	}
+	const built = context.keyKind === STYLE_KIND ? locateFactory(typescript, source, anchor, context) : [];
+	if (built.length > 0) return built;
+	const binding = anchor.binding;
+	const statement = source.statements.find((item) => declares(typescript, item, binding));
+	if (statement === void 0) return [];
+	const node = (anchor.key === void 0 ? void 0 : propertyIn(typescript, statement, anchor.key)) ?? statement;
+	return [placeOf(source, node, node)];
 }
 //#endregion
 //#region src/project/find.ts
@@ -2302,17 +2664,20 @@ async function viewOf(session, file) {
 	};
 }
 /**
-* The definers a file can call, recognised by binding on the module facts of the catalog, as
-* extraction does.
+* The definers a file can call, recognised by binding on the module facts of the catalog and the
+* tsconfig aliases of the session, as extraction does.
 *
-* @param catalog - The catalog of the project.
+* @param session - The open project.
 * @param file - The root-relative path.
 * @returns The callee text to the definer.
 */
-function definersAt(catalog, file) {
+function definersAt(session, file) {
 	const modules = /* @__PURE__ */ new Map();
-	for (const [path, record] of catalog.records) if (record.good !== void 0) modules.set(path, record.good.module);
-	return definersOf(modules, file);
+	for (const [path, record] of session.catalog.records) if (record.good !== void 0) modules.set(path, record.good.module);
+	return definersOf({
+		modules,
+		aliases: session.aliases
+	}, file);
 }
 /**
 * The kind of a key: the text before its first colon.
@@ -2361,7 +2726,7 @@ async function findKey(session, key) {
 		const answers = locate(session.catalog.typescript, view.source, anchor, {
 			keyKind,
 			jsxHits: view.jsx,
-			definers: () => definersAt(session.catalog, anchor.path)
+			definers: () => definersAt(session, anchor.path)
 		}).map((place) => ({
 			...anchor,
 			...place,
@@ -2517,13 +2882,16 @@ async function walkRoot(root) {
 //#region src/project/session.ts
 /**
 * @file project — an open project: the real root, the catalog of its files, the stamps of the last
-* walk, the current index and a queue that runs one update at a time. `syncWithDisk` is the batch
-* walk of a watch batch: it walks the root, hashes the files whose stamp moved and every new one,
-* drops the vanished ones and rebuilds the index when bytes changed. `reindexPath` reads one path
-* now for `changed`.
+* walk, the tsconfig aliases with the stamps of the config files they came from, the current index
+* and a queue that runs one update at a time. `syncWithDisk` is the batch walk of a watch batch:
+* it walks the root, hashes the files whose stamp moved and every new one, drops the vanished
+* ones, reads the aliases again when a config file moved, and rebuilds the index when bytes or
+* aliases changed. `reindexPath` reads one path now for `changed`.
 */
 /** The manifest the asset scanner writes by default. */
 const MANIFEST_FILE = "manifest.json";
+/** The tsconfig whose `paths` are read by default. */
+const TSCONFIG_FILE = "tsconfig.json";
 /**
 * The manifest path to report, when the file exists.
 *
@@ -2537,6 +2905,93 @@ async function presentManifest(root, manifest) {
 	} catch {}
 }
 /**
+* The stamp of a config file, read through the guard.
+*
+* @param root - The real root.
+* @param file - The root-relative path.
+* @returns The stamp, or `undefined` when nothing is there or the path left the root.
+*/
+async function configStampOf(root, file) {
+	try {
+		const real = await resolveInside(root, file);
+		return real === void 0 ? void 0 : await stampOf(real);
+	} catch {
+		return;
+	}
+}
+/**
+* The stamps of config files.
+*
+* @param root - The real root.
+* @param files - The root-relative config files.
+* @returns Path to stamp, `undefined` for a file that is not there.
+*/
+async function stampConfigs(root, files) {
+	const stamps = /* @__PURE__ */ new Map();
+	for (const file of files) stamps.set(file, await configStampOf(root, file));
+	return stamps;
+}
+/**
+* The config files a read of the tsconfig touched: its sources, or the tsconfig alone when it is
+* missing.
+*
+* @param tsconfig - The root-relative tsconfig path.
+* @param read - The read, `undefined` for a missing tsconfig.
+* @returns The root-relative files to stamp.
+* @example
+* ```ts
+* configsOf("tsconfig.json", undefined); // ["tsconfig.json"]
+* ```
+*/
+function configsOf(tsconfig, read) {
+	return read?.sources ?? [tsconfig];
+}
+/**
+* The aliases the index follows: a tsconfig without patterns maps nothing, as no tsconfig does.
+*
+* @param read - The read, `undefined` for a missing tsconfig.
+* @returns The read when it holds a pattern, else `undefined`.
+* @example
+* ```ts
+* followedAliases({ file: "tsconfig.json", sources: ["tsconfig.json"], patterns: [] }); // undefined
+* ```
+*/
+function followedAliases(read) {
+	return read === void 0 || read.patterns.length === 0 ? void 0 : read;
+}
+/**
+* Whether a config file moved, appeared or vanished since its stamp.
+*
+* @param session - The project.
+* @returns True when a stamp of `configStamps` is not the one on disk now.
+*/
+async function configsMoved(session) {
+	for (const [file, known] of session.configStamps) {
+		const now = await configStampOf(session.root, file);
+		if (known === void 0 || now === void 0 ? known !== now : !sameStamp(known, now)) return true;
+	}
+	return false;
+}
+/**
+* Reads the aliases again and stamps the config files the read touched. A tsconfig that stops
+* parsing keeps the aliases it had until it parses again, as a broken source file keeps its keys,
+* and the files of the last good read are stamped again.
+*
+* @param session - The project.
+* @returns True when the aliases resolve differently now.
+*/
+async function rereadAliases(session) {
+	const before = session.aliases;
+	let configs = [...session.configStamps.keys()];
+	try {
+		const read = await readAliases(session.catalog.typescript, session.root, session.tsconfig);
+		session.aliases = followedAliases(read);
+		configs = configsOf(session.tsconfig, read);
+	} catch {}
+	session.configStamps = await stampConfigs(session.root, configs);
+	return !sameAliases(before, session.aliases);
+}
+/**
 * Reads one file into the catalog, or drops it when it is gone or cannot be read.
 *
 * @param session - The project.
@@ -2561,37 +3016,44 @@ async function readIntoCatalog(session, file) {
 async function rebuild(session, files) {
 	const before = session.index;
 	const manifest = await presentManifest(session.root, session.manifest);
-	session.index = buildIndex(session.catalog, manifest);
+	session.index = buildIndex(session.catalog, manifest, session.aliases);
 	return diffIndexes(before, session.index, files);
 }
 /**
-* Opens a project: checks the root, loads TypeScript, reads every source file and builds the
-* index.
+* Opens a project: checks the root, loads TypeScript, reads the tsconfig aliases and every source
+* file, and builds the index.
 *
-* @param options - The root, the manifest and the debounce.
+* @param options - The root, the manifest, the tsconfig and the debounce.
 * @returns The open project.
-* @throws {Error} When the root is missing or not a directory, the manifest path leaves the root,
-*   or TypeScript is not installed.
+* @throws {Error} When the root is missing or not a directory, the manifest or the tsconfig path
+*   leaves the root, the tsconfig does not parse, or TypeScript is not installed.
 */
 async function openSession(options) {
 	const root = await openRoot(options.root);
 	const typescript = await loadTypeScript();
 	const manifest = toPosix(options.manifest ?? MANIFEST_FILE);
+	const tsconfig = toPosix(options.tsconfig ?? TSCONFIG_FILE);
 	await resolveInside(root, manifest);
+	await resolveInside(root, tsconfig);
+	const read = await readAliases(typescript, root, tsconfig);
+	const aliases = followedAliases(read);
 	const walk = await walkRoot(root);
 	const catalog = createCatalog(typescript);
 	const session = {
 		root,
 		manifest,
+		tsconfig,
+		aliases,
+		configStamps: await stampConfigs(root, configsOf(tsconfig, read)),
 		catalog,
 		stamps: walk.files,
 		folders: walk.folders,
-		index: buildIndex(catalog),
+		index: buildIndex(catalog, void 0, aliases),
 		shapes: /* @__PURE__ */ new WeakMap(),
 		queue: Promise.resolve()
 	};
 	for (const file of [...walk.files.keys()].toSorted()) await readIntoCatalog(session, file);
-	session.index = buildIndex(catalog, await presentManifest(root, manifest));
+	session.index = buildIndex(catalog, await presentManifest(root, manifest), aliases);
 	return session;
 }
 /**
@@ -2607,47 +3069,282 @@ function serialize(session, task) {
 	return result;
 }
 /**
-* The batch walk: walks the root, hashes each file whose stamp moved and each new one, drops the
-* vanished ones, and rebuilds the index when bytes changed. A save with the same bytes changes
-* nothing.
+* The batch walk: walks the root, hashes each file whose stamp moved and each new one, drops the
+* vanished ones, reads the aliases again when a config file moved, appeared or vanished, and
+* rebuilds the index when bytes or aliases changed. A save with the same bytes, or a tsconfig
+* edit that leaves the aliases as they were, changes nothing. New aliases list the tsconfig
+* among the changed files.
+*
+* @param session - The project.
+* @returns The change, or `undefined` when the index stayed the same.
+*/
+async function syncWithDisk(session) {
+	const walk = await walkRoot(session.root);
+	const files = [];
+	for (const file of session.catalog.records.keys()) if (!walk.files.has(file) && dropFile(session.catalog, file)) files.push(file);
+	const previous = session.stamps;
+	session.stamps = walk.files;
+	session.folders = walk.folders;
+	for (const [file, stamp] of walk.files) {
+		const known = previous.get(file);
+		if (known !== void 0 && sameStamp(known, stamp)) continue;
+		if (await readIntoCatalog(session, file)) files.push(file);
+	}
+	if (await configsMoved(session) && await rereadAliases(session)) files.push(session.tsconfig);
+	const manifest = await presentManifest(session.root, session.manifest);
+	if (files.length === 0 && manifest === session.index.manifest) return void 0;
+	return rebuild(session, files);
+}
+/**
+* Reads one root-relative path now: a changed or new source file is parsed, a deleted one is
+* dropped, the tsconfig or a file it extends reads the aliases again, and anything else changes
+* nothing.
+*
+* @param session - The project.
+* @param file - The root-relative path.
+* @returns The index after the read.
+* @throws {Error} When the path leaves the root.
+*/
+async function reindexPath(session, file) {
+	const relative = toPosix(file);
+	const real = await resolveInside(session.root, relative);
+	if (path.isAbsolute(relative)) return session.index;
+	if (session.configStamps.has(relative)) {
+		if (await rereadAliases(session)) await rebuild(session, [session.tsconfig]);
+		return session.index;
+	}
+	if (real !== void 0 && real !== path.join(session.root, relative) || !isIndexedFile(relative)) return session.index;
+	const stamp = real === void 0 ? void 0 : await stampOf(real);
+	if (stamp !== void 0) session.stamps.set(relative, stamp);
+	if (!await readIntoCatalog(session, relative)) return session.index;
+	await rebuild(session, [relative]);
+	return session.index;
+}
+//#endregion
+//#region src/project/cli.ts
+/**
+* @file project — the command line `moku-game-index`. It opens the project of `--root` and runs one
+* command: `--json` prints the index, `where <key>` prints one `path:line` per place, `--check`
+* reports broken files and conflicts (exit 1), names the tsconfig aliases and lists the
+* unresolved items as info. A run answers once and watches nothing, so it opens a session, not a
+* handle. Output goes through the branded console of `@moku-labs/common`; `runCli` returns the
+* exit code instead of taking it.
+*/
+/** The usage line under every flag error. */
+const USAGE = "Run: moku-game-index --root <dir> [--manifest <path>] [--tsconfig <path>] --json | --check | where <key>.";
+/** Pretty JSON indent of `--json`. */
+const JSON_INDENT = 2;
+/**
+* Wraps a command line problem in the message shape of the framework.
+*
+* @param message - One sentence naming the flag.
+* @returns The error to throw.
+*/
+function problem(message) {
+	return /* @__PURE__ */ new Error(`[game] index: ${message}\n  ${USAGE}`);
+}
+/**
+* Reads the message of anything that was thrown.
+*
+* @param failure - What the `catch` caught.
+* @returns The message.
+*/
+function messageOf(failure) {
+	return failure instanceof Error ? failure.message : String(failure);
+}
+/**
+* The value after a flag that takes one.
+*
+* @param argv - The arguments.
+* @param at - The index of the flag.
+* @param what - What the flag needs, for the error.
+* @returns The value.
+* @throws {Error} When the value is missing.
+*/
+function valueAfter(argv, at, what) {
+	const flag = argv[at] ?? "";
+	const value = argv[at + 1];
+	if (value === void 0 || value.startsWith("--")) throw problem(`"${flag}" needs ${what}.`);
+	return value;
+}
+/**
+* Reads one flag or command into the flags.
+*
+* @param argv - The arguments.
+* @param at - The index of the flag.
+* @param flags - The flags so far.
+* @returns How many arguments the flag took.
+* @throws {Error} When the flag is unknown or misses its value.
+*/
+function readFlag(argv, at, flags) {
+	const flag = argv[at];
+	switch (flag) {
+		case "--json":
+			flags.commands.push({ kind: "json" });
+			return 1;
+		case "--check":
+			flags.commands.push({ kind: "check" });
+			return 1;
+		case "where":
+			flags.commands.push({
+				kind: "where",
+				key: valueAfter(argv, at, "a key, such as node:board/merge")
+			});
+			return 2;
+		case "--root":
+			flags.root = valueAfter(argv, at, "a path");
+			return 2;
+		case "--manifest":
+			flags.manifest = valueAfter(argv, at, "a path");
+			return 2;
+		case "--tsconfig":
+			flags.tsconfig = valueAfter(argv, at, "a path");
+			return 2;
+		default: throw problem(`unknown option "${String(flag)}".`);
+	}
+}
+/**
+* Reads the arguments.
+*
+* @param argv - The arguments after the script name.
+* @returns The root, the manifest, the tsconfig and the one command.
+* @throws {Error} When a flag is unknown, a value is missing, `--root` is missing or the commands
+*   are not exactly one.
+*/
+function parseArgv(argv) {
+	const flags = { commands: [] };
+	for (let at = 0; at < argv.length;) at += readFlag(argv, at, flags);
+	if (flags.root === void 0) throw new Error("[game] index: \"--root\" is required.\n  Name the game folder: moku-game-index --root <dir> where <key>.");
+	const [command] = flags.commands;
+	if (command === void 0 || flags.commands.length > 1) throw problem("name one command: --json, --check or where <key>.");
+	return {
+		root: flags.root,
+		command,
+		...flags.manifest === void 0 ? {} : { manifest: flags.manifest },
+		...flags.tsconfig === void 0 ? {} : { tsconfig: flags.tsconfig }
+	};
+}
+/**
+* One line of a `where` answer.
+*
+* @param found - One place of the key.
+* @returns `path:line`, with ` (broken)` when the line comes from the last good parse.
+* @example
+* ```ts
+* whereLine({ path: "nodes/merge.ts", line: 17, range: [17, 1, 38, 4], hash: "ab" }); // "nodes/merge.ts:17"
+* ```
+*/
+function whereLine(found) {
+	return `${found.path}:${found.line}${found.broken === true ? " (broken)" : ""}`;
+}
+/**
+* Counts a thing in words, so the summary reads as a sentence.
+*
+* @param count - How many.
+* @param word - The singular.
+* @returns The count and the word.
+* @example
+* ```ts
+* plural(1, "key"); // "1 key"
+* ```
+*/
+function plural(count, word) {
+	return `${count} ${word}${count === 1 ? "" : "s"}`;
+}
+/**
+* The line of `--check` that names the aliases: the tsconfig and how many keys of `paths` it
+* holds, or `none` for a tsconfig without them. A root with no tsconfig gets no line.
+*
+* @param session - The open project.
+* @returns The line, or `undefined`.
+*/
+function aliasesLine(session) {
+	const { aliases } = session;
+	if (aliases !== void 0) return `aliases: ${aliases.file}, ${plural(aliases.patterns.length, "pattern")}`;
+	return session.configStamps.get(session.tsconfig) !== void 0 ? "aliases: none (no tsconfig paths)" : void 0;
+}
+/**
+* The `--check` report: a summary, the aliases, every broken file and conflict as an error, every
+* unresolved item as info.
+*
+* @param session - The open project.
+* @param ui - Where the lines go.
+* @returns `1` when a file is broken or a key is in conflict, else `0`.
+*/
+function printCheck(session, ui) {
+	const { index } = session;
+	const aliases = aliasesLine(session);
+	const files = Object.entries(index.files);
+	const symbols = Object.entries(index.symbols);
+	const broken = files.filter(([, file]) => file.state === "broken");
+	const conflicts = symbols.filter(([, symbol]) => symbol.conflict === true);
+	ui.info(`${plural(files.length, "file")}, ${plural(symbols.length, "key")}: ${broken.length} broken, ${conflicts.length} in conflict, ${index.unresolved.length} unresolved.`);
+	if (aliases !== void 0) ui.info(aliases);
+	for (const [file, entry] of broken) ui.error(`broken ${file}: ${entry.error ?? ""}`);
+	for (const [key, symbol] of conflicts) ui.error(`conflict ${key}: ${symbol.def.map((anchor) => anchor.path).join(", ")}`);
+	for (const item of index.unresolved) ui.info(`unresolved ${item.path}: ${item.reason}`);
+	return broken.length + conflicts.length > 0 ? 1 : 0;
+}
+/**
+* The `where` answer: one line per place of the key.
 *
-* @param session - The project.
-* @returns The change, or `undefined` when the index stayed the same.
+* @param session - The open project.
+* @param key - The key.
+* @param root - The root as given, for the message.
+* @param ui - Where the lines go.
+* @returns `1` when the key is unknown, else `0`.
 */
-async function syncWithDisk(session) {
-	const walk = await walkRoot(session.root);
-	const files = [];
-	for (const file of session.catalog.records.keys()) if (!walk.files.has(file) && dropFile(session.catalog, file)) files.push(file);
-	const previous = session.stamps;
-	session.stamps = walk.files;
-	session.folders = walk.folders;
-	for (const [file, stamp] of walk.files) {
-		const known = previous.get(file);
-		if (!(known !== void 0 && sameStamp(known, stamp)) && await readIntoCatalog(session, file)) files.push(file);
+async function printWhere(session, key, root, ui) {
+	const found = await findKey(session, key);
+	if (found.length === 0) {
+		ui.error(`[game] The key "${key}" is not in the index of "${root}".\n  Run "moku-game-index --root ${root} --json" to list the keys.`);
+		return 1;
 	}
-	const manifest = await presentManifest(session.root, session.manifest);
-	if (files.length === 0 && manifest === session.index.manifest) return void 0;
-	return rebuild(session, files);
+	for (const place of found) ui.line(whereLine(place));
+	return 0;
 }
 /**
-* Reads one root-relative path now: a changed or new source file is parsed, a deleted one is
-* dropped, and anything the index does not read changes nothing.
+* Runs the one command of the line on an open project.
 *
-* @param session - The project.
-* @param file - The root-relative path.
-* @returns The index after the read.
-* @throws {Error} When the path leaves the root.
+* @param session - The open project.
+* @param options - What the flags asked for.
+* @param ui - Where the lines go.
+* @returns The exit code.
 */
-async function reindexPath(session, file) {
-	const relative = toPosix(file);
-	const real = await resolveInside(session.root, relative);
-	const isLinked = real !== void 0 && real !== path.join(session.root, relative);
-	if (path.isAbsolute(relative) || isLinked || !isIndexedFile(relative)) return session.index;
-	const stamp = real === void 0 ? void 0 : await stampOf(real);
-	if (stamp !== void 0) session.stamps.set(relative, stamp);
-	if (!await readIntoCatalog(session, relative)) return session.index;
-	await rebuild(session, [relative]);
-	return session.index;
+async function runCommand(session, options, ui) {
+	const { command } = options;
+	if (command.kind === "where") return printWhere(session, command.key, options.root, ui);
+	if (command.kind === "check") return printCheck(session, ui);
+	ui.line(JSON.stringify(session.index, void 0, JSON_INDENT));
+	return 0;
+}
+/**
+* Runs `moku-game-index`: opens the project of `--root` and runs one command. Nothing here calls
+* `process.exit`; the caller does.
+*
+* @param argv - The arguments after the script name.
+* @param ui - Where the lines go. The branded console by default.
+* @returns The exit code: `1` for a bad flag, a root that cannot be opened, an unknown key, or a
+*   `--check` that found a broken file or a conflict; else `0`.
+* @example
+* ```ts
+* // An agent asks where a node of the mini game lives.
+* await runCli(["--root", "tests/fixtures/mini-game", "where", "node:infoPopup/count"]);
+* // 0, and the console printed "nodes/count.ts:7"
+* ```
+*/
+async function runCli(argv, ui = createBrandConsole()) {
+	try {
+		const options = parseArgv(argv);
+		return await runCommand(await openSession({
+			root: options.root,
+			...options.manifest === void 0 ? {} : { manifest: options.manifest },
+			...options.tsconfig === void 0 ? {} : { tsconfig: options.tsconfig }
+		}), options, ui);
+	} catch (error) {
+		ui.error(messageOf(error));
+		return 1;
+	}
 }
 //#endregion
 //#region src/project/watch.ts
@@ -2856,16 +3553,17 @@ const DEFAULT_DEBOUNCE_MS = 75;
 * path), loads TypeScript, parses every source file and builds the index. Nothing is written to
 * disk and nothing is inferred from the working directory but the root itself.
 *
-* @param options - The game root, the manifest path and the quiet period of `watch`.
+* @param options - The game root, the manifest path, the tsconfig whose `paths` the index follows
+*   (`tsconfig`, root-relative, `tsconfig.json` by default) and the quiet period of `watch`.
 * @returns The handle; close it when the game closes.
 * @throws {Error} When the root is missing or not a directory, or the `typescript` package is not
 *   installed: `[game] The project index needs the "typescript" package.`
 * @example
 * ```ts
-* // The editor opens the fixture game and answers where a node and a text style live.
-* const project = await openProject({ root: "tests/integration/merge-game" });
-* Object.keys(project.index.files).length; // 111
-* (await project.find("textStyle:ui.title"))[0]?.line; // 39, in "features/ui/styles.ts"
+* // The editor opens the mini game and answers where a node and a text style live.
+* const project = await openProject({ root: "tests/fixtures/mini-game" });
+* Object.keys(project.index.files).length; // 21
+* (await project.find("textStyle:ui.counter"))[0]?.line; // 16, in "features/home/styles.ts"
 * project.close();
 * ```
 */
@@ -2888,222 +3586,13 @@ async function openProject(options) {
 	};
 }
 //#endregion
-//#region src/project/cli.ts
-/**
-* @file project — the command line `moku-game-index`. It opens the project of `--root` and runs one
-* command: `--json` prints the index, `where <key>` prints one `path:line` per place, `--check`
-* reports broken files and conflicts (exit 1) and lists the unresolved items as info. Output goes
-* through the branded console of `@moku-labs/common`; `runCli` returns the exit code instead of
-* taking it.
-*/
-/** The usage line under every flag error. */
-const USAGE = "Run: moku-game-index --root <dir> [--manifest <path>] --json | --check | where <key>.";
-/** Pretty JSON indent of `--json`. */
-const JSON_INDENT = 2;
-/**
-* Wraps a command line problem in the message shape of the framework.
-*
-* @param message - One sentence naming the flag.
-* @returns The error to throw.
-*/
-function problem(message) {
-	return /* @__PURE__ */ new Error(`[game] index: ${message}\n  ${USAGE}`);
-}
-/**
-* Reads the message of anything that was thrown.
-*
-* @param failure - What the `catch` caught.
-* @returns The message.
-*/
-function messageOf(failure) {
-	return failure instanceof Error ? failure.message : String(failure);
-}
-/**
-* The value after a flag that takes one.
-*
-* @param argv - The arguments.
-* @param at - The index of the flag.
-* @param what - What the flag needs, for the error.
-* @returns The value.
-* @throws {Error} When the value is missing.
-*/
-function valueAfter(argv, at, what) {
-	const flag = argv[at] ?? "";
-	const value = argv[at + 1];
-	if (value === void 0 || value.startsWith("--")) throw problem(`"${flag}" needs ${what}.`);
-	return value;
-}
-/**
-* Reads one flag or command into the flags.
-*
-* @param argv - The arguments.
-* @param at - The index of the flag.
-* @param flags - The flags so far.
-* @returns How many arguments the flag took.
-* @throws {Error} When the flag is unknown or misses its value.
-*/
-function readFlag(argv, at, flags) {
-	const flag = argv[at];
-	switch (flag) {
-		case "--json":
-			flags.commands.push({ kind: "json" });
-			return 1;
-		case "--check":
-			flags.commands.push({ kind: "check" });
-			return 1;
-		case "where":
-			flags.commands.push({
-				kind: "where",
-				key: valueAfter(argv, at, "a key, such as node:board/merge")
-			});
-			return 2;
-		case "--root":
-			flags.root = valueAfter(argv, at, "a path");
-			return 2;
-		case "--manifest":
-			flags.manifest = valueAfter(argv, at, "a path");
-			return 2;
-		default: throw problem(`unknown option "${String(flag)}".`);
-	}
-}
-/**
-* Reads the arguments.
-*
-* @param argv - The arguments after the script name.
-* @returns The root, the manifest and the one command.
-* @throws {Error} When a flag is unknown, a value is missing, `--root` is missing or the commands
-*   are not exactly one.
-*/
-function parseArgv(argv) {
-	const flags = { commands: [] };
-	for (let at = 0; at < argv.length;) at += readFlag(argv, at, flags);
-	if (flags.root === void 0) throw new Error("[game] index: \"--root\" is required.\n  Name the game folder: moku-game-index --root <dir> where <key>.");
-	const [command] = flags.commands;
-	if (command === void 0 || flags.commands.length > 1) throw problem("name one command: --json, --check or where <key>.");
-	return {
-		root: flags.root,
-		command,
-		...flags.manifest === void 0 ? {} : { manifest: flags.manifest }
-	};
-}
-/**
-* One line of a `where` answer.
-*
-* @param found - One place of the key.
-* @returns `path:line`, with ` (broken)` when the line comes from the last good parse.
-* @example
-* ```ts
-* whereLine({ path: "nodes/merge.ts", line: 17, range: [17, 1, 38, 4], hash: "ab" }); // "nodes/merge.ts:17"
-* ```
-*/
-function whereLine(found) {
-	return `${found.path}:${found.line}${found.broken === true ? " (broken)" : ""}`;
-}
-/**
-* Counts a thing in words, so the summary reads as a sentence.
-*
-* @param count - How many.
-* @param word - The singular.
-* @returns The count and the word.
-* @example
-* ```ts
-* plural(1, "key"); // "1 key"
-* ```
-*/
-function plural(count, word) {
-	return `${count} ${word}${count === 1 ? "" : "s"}`;
-}
-/**
-* The `--check` report: a summary, every broken file and conflict as an error, every unresolved
-* item as info.
-*
-* @param index - The index.
-* @param ui - Where the lines go.
-* @returns `1` when a file is broken or a key is in conflict, else `0`.
-*/
-function printCheck(index, ui) {
-	const files = Object.entries(index.files);
-	const symbols = Object.entries(index.symbols);
-	const broken = files.filter(([, file]) => file.state === "broken");
-	const conflicts = symbols.filter(([, symbol]) => symbol.conflict === true);
-	ui.info(`${plural(files.length, "file")}, ${plural(symbols.length, "key")}: ${broken.length} broken, ${conflicts.length} in conflict, ${index.unresolved.length} unresolved.`);
-	for (const [file, entry] of broken) ui.error(`broken ${file}: ${entry.error ?? ""}`);
-	for (const [key, symbol] of conflicts) ui.error(`conflict ${key}: ${symbol.def.map((anchor) => anchor.path).join(", ")}`);
-	for (const item of index.unresolved) ui.info(`unresolved ${item.path}: ${item.reason}`);
-	return broken.length + conflicts.length > 0 ? 1 : 0;
-}
-/**
-* The `where` answer: one line per place of the key.
-*
-* @param project - The open project.
-* @param key - The key.
-* @param root - The root as given, for the message.
-* @param ui - Where the lines go.
-* @returns `1` when the key is unknown, else `0`.
-*/
-async function printWhere(project, key, root, ui) {
-	const found = await project.find(key);
-	if (found.length === 0) {
-		ui.error(`[game] The key "${key}" is not in the index of "${root}".\n  Run "moku-game-index --root ${root} --json" to list the keys.`);
-		return 1;
-	}
-	for (const place of found) ui.line(whereLine(place));
-	return 0;
-}
-/**
-* Runs the one command of the line on an open project.
-*
-* @param project - The open project.
-* @param options - What the flags asked for.
-* @param ui - Where the lines go.
-* @returns The exit code.
-*/
-async function runCommand(project, options, ui) {
-	const { command } = options;
-	if (command.kind === "where") return printWhere(project, command.key, options.root, ui);
-	if (command.kind === "check") return printCheck(project.index, ui);
-	ui.line(JSON.stringify(project.index, void 0, JSON_INDENT));
-	return 0;
-}
-/**
-* Runs `moku-game-index`: opens the project of `--root` and runs one command. Nothing here calls
-* `process.exit`; the caller does.
-*
-* @param argv - The arguments after the script name.
-* @param ui - Where the lines go. The branded console by default.
-* @returns The exit code: `1` for a bad flag, a root that cannot be opened, an unknown key, or a
-*   `--check` that found a broken file or a conflict; else `0`.
-* @example
-* ```ts
-* // An agent asks where a node of the fixture game lives.
-* await runCli(["--root", "tests/integration/merge-game", "where", "node:board/merge"]);
-* // 0, and the console printed "nodes/merge.ts:17"
-* ```
-*/
-async function runCli(argv, ui = createBrandConsole()) {
-	try {
-		const options = parseArgv(argv);
-		const project = await openProject({
-			root: options.root,
-			...options.manifest === void 0 ? {} : { manifest: options.manifest }
-		});
-		try {
-			return await runCommand(project, options, ui);
-		} finally {
-			project.close();
-		}
-	} catch (error) {
-		ui.error(messageOf(error));
-		return 1;
-	}
-}
-//#endregion
 //#region src/project.ts
 /**
 * @file The project door of the engine (subpath `./project`, node and bun only): the static index
 * of a game's sources. `openProject` parses the game with TypeScript (an optional peer, loaded on
 * the first open) and maps every engine id (flows, nodes, features, scenes, projections, emitters,
-* text styles, styles and JSX keys) to anchors; `find` reads the line of a key from the file on
+* text styles, styles and JSX keys) to anchors, following names through relative imports and the
+* tsconfig `paths` aliases of the game; `find` reads the line of a key from the file on
 * disk at the call, `watch` keeps the index fresh while agents edit files. The package bin
 * `moku-game-index` runs `runCli`. Re-exports only: the code lives in `project/`, and this is the
 * one door to it in `src/`.