@ringozz/godot 4.7.2-664 → 4.7.2-676

package/README.md

@@ -54,7 +54,7 @@ await import('./app.ts'); // may now import @ringozz/godot / react-godot freely
 | `@ringozz/godot/boot` | Platform boot: `getNativeModule()`; web `preloadGodot()` (awaited before importing the app; no-op on desktop) |
 | `@ringozz/godot/load` | Async resource loading: `loadResourceAsync`, `loadAsset`, `loadAssetPack` (native `.pck` packs), `configurePacks`/`loadPackEntry` (content packs) |
 | `@ringozz/godot/bake` | `buildAssetPacks(opts, run?)` + the `godot pack` subcommand: bake the project's boot `.pck` plus one per declared content pack, with their loose-texture documents. `opts.cwd` picks the project root and `run` replaces the editor, so a test can bake a temp project |
-| `@ringozz/godot/pack` | The pack protocol the bake writes and the plugin/runtime read: `PACK_DOC`/`RELEASE`/`FILES_DIR` and the boot's names, `parseDoc`/`serializeDoc`/`parseRelease`, `packEntries`/`godotEntry`/`entryId`/`packPath`/`pckOf`, and `resolveEntry` (what to mount and stage for one entry) |
+| `@ringozz/godot/pack` | The pack protocol the bake writes and the plugin/runtime read: `PACK_DOC`/`RELEASE`/`FILES_DIR` and the boot's names, `parseDoc`/`serializeDoc`/`parseRelease`, `packEntries`/`godotEntry`/`entryId`/`pckOf`, and `resolveEntry` (what to mount and stage for one entry) |
 | `@ringozz/godot/debug` | `initDebug()`, `dumpStr`, `snapshot`, `inspect`, `click`, `find`, `gc` |
 
 Class-scoped enums use bare names (import `ProcessMode` from `@ringozz/godot/Node`, not `NodeProcessMode`).
@@ -111,7 +111,11 @@ A content pack is deployed apart from the app, so nothing about it is in the bun
 
 ```ts
 import { configurePacks } from '@ringozz/godot/load';
-configurePacks({ at: (path) => `https://cdn.example/packs/${path}` });   // '<name>/<version>/<file>'
+// The host owns the base: a pack's name, its version and one of its files, addressed its own way.
+configurePacks({
+	at: (name, version, file) => `https://cdn.example/packs/${name}@${version}/${file}`,
+	release: 'https://cdn.example/packs/release.json',   // or the map itself: `{ '@tiv/beach': { version, deps } }`
+});
 ```
 
 The boot pack — the app's own sources, which ship beside it — needs no config: the bake renders it into a module (`.godot/packs/boot-pack.js`: its `.pck`, plus a bundled URL per loose product it owns), which every imported asset pulls in, and `configurePacks` merges, so the app's `at` and the boot's config may land in either order. A pack declares its entries (`exports` → the `godot` condition, the `res://` path) and ships **no entry module**: the preload plugin serves one, built from the bake's documents, with one named export per entry. So importing a pack is an ordinary import — and the bake emits the types it resolves to (`package.d.ts`, named by the pack's `types`):

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/godot",
   "author": "Vladimir Davidovich",
-  "version": "4.7.2-664",
+  "version": "4.7.2-676",
   "description": "Node-API bindings for Godot Engine — call Godot classes from JavaScript",
   "publishConfig": {
     "access": "public"
@@ -67,9 +67,9 @@
     "precision": "single"
   },
   "optionalDependencies": {
-    "@ringozz/godot-macos-arm64": "^4.7.2-664",
-    "@ringozz/godot-windows-x86_64": "^4.7.2-664",
-    "@ringozz/godot-web-wasm32": "^4.7.2-664"
+    "@ringozz/godot-macos-arm64": "^4.7.2-676",
+    "@ringozz/godot-windows-x86_64": "^4.7.2-676",
+    "@ringozz/godot-web-wasm32": "^4.7.2-676"
   },
   "peerDependencies": {
     "@types/bun": "*"

package/src/bake.ts

@@ -3,8 +3,9 @@
 ***********************************************************************/
 
 import { spawnSync } from 'node:child_process';
+import { createHash, type Hash } from 'node:crypto';
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, extname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveEditor } from './editor.ts';
 import { packedExtensions, scannedExtensions } from './formats.ts';
@@ -50,6 +51,27 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 /** The dump's one build-time output, rewritten by every bake. */
 const DUMP = '.godot/pack-dump.json';
 
+/** The digest of every bake input, beside the packs: written by a bake that finished, read by the next. */
+const STAMP = '.stamp.json';
+
+/**
+ * Removes everything a bake derives — the import cache, the documents, the packs — and never a source.
+ * `godot clean` is the answer to the two states a bake cannot repair by itself: orphaned products left
+ * by sources that moved or were renamed, and a derived file whose import was never forced.
+ */
+export function cleanProject(cwd = process.cwd()): void {
+	rmSync(resolve(cwd, '.godot'), { recursive: true, force: true });
+	console.log('[pack] cleaned .godot');
+}
+
+/**
+ * Source the engine never imports or packs — the app's own code, sitting in the same tree as its
+ * assets. Editing it cannot change a pack, and it is the most common edit there is, so the digest
+ * skips it. The list is a deny-list on purpose: an unknown extension re-bakes (harmless) rather than
+ * going stale (a pack that silently lags its sources).
+ */
+const SOURCE = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.md', '.yaml', '.yml', '.css']);
+
 export interface BuildAssetPackOptions {
 	/** The project root the bake reads and writes (default: `process.cwd()`). */
 	cwd?: string;
@@ -63,6 +85,8 @@ export interface BuildAssetPackOptions {
 	preset?: string;
 	/** Editor executable override (default: `resolveEditor()`). */
 	godot?: string;
+	/** Bake even when nothing the bake reads has changed since the last one (default: false). */
+	force?: boolean;
 }
 
 /** A content pack: a directory that declares itself with a `package.json`. */
@@ -96,19 +120,37 @@ export async function buildAssetPacks(opts: BuildAssetPackOptions = {}, run?: Ru
 	const bootRoots = opts.roots ?? ['res://src'];
 	const out = opts.out ?? PACK_DIR;
 	const preset = opts.preset ?? 'Pack';
-	const exec = run ?? runner(opts.godot ?? (await resolveEditor()), cwd);
+	const editor = opts.godot ?? (run ? null : await resolveEditor());
+	const exec = run ?? runner(editor!, cwd);
 	mkdirSync(resolve(cwd, out), { recursive: true });
 
+	const dlc = rel(opts.dlc ?? 'res://dlc');
+	const packs = discoverPacks(cwd, dlc);
+
+	const presets = resolve(cwd, 'export_presets.cfg');
+	const cfg = readFileSync(presets, 'utf8');
+
+	// Nothing the bake reads has changed since the last one that finished: an import scan, a dump and
+	// one export per pack are the whole cost of a dev server start, and none of it is worth repeating
+	// for a project nobody touched. The stamp is the digest of every input, not a timestamp of the
+	// outputs — a pack's `.pck` is rewritten on every export, so it can't answer this.
+	const stamp = resolve(cwd, out, STAMP);
+	const inputs = inputsOf({ cwd, dirs: [...bootRoots.map(rel), ...packs.map((pack) => pack.dir)], cfg, editor });
+	if (!opts.force && readStamp(stamp) === inputs) {
+		console.log(`[pack] up to date (${out})`);
+		return;
+	}
+
 	// The editor's import scan must not walk the installed dependency tree: a workspace-linked pack
 	// would be imported a second time through the link, at a depth its relative paths (a terrain
 	// `.webparray`'s layer refs) do not survive. `.gdignore` is the editor's own skip marker; the
 	// bundler never looks at it, and the sources are imported once at their real `res://` paths.
-	const installed = resolve(cwd, 'node_modules');
-	if (existsSync(installed)) writeFileSync(join(installed, '.gdignore'), '');
+	// A pack that declares another pack gets that link *inside itself* (`node_modules` beside its
+	// `package.json`), so each pack's tree needs the marker as well as the root one.
+	const installed = [resolve(cwd, 'node_modules'), ...packs.map((pack) => resolve(cwd, pack.dir, 'node_modules'))];
+	for (const dir of installed.filter((dir) => existsSync(dir))) writeFileSync(join(dir, '.gdignore'), '');
 	exec(['--headless', '--path', '.', '--import']);
 
-	const dlc = rel(opts.dlc ?? 'res://dlc');
-	const packs = discoverPacks(cwd, dlc);
 	assertScopes(bootRoots.map(rel), packs);
 	const dirOf = new Map(packs.map((pack) => [pack.name, pack.dir]));
 	const release = releaseOf(packs);
@@ -117,8 +159,6 @@ export async function buildAssetPacks(opts: BuildAssetPackOptions = {}, run?: Ru
 	const bootDirs = bootRoots.map(rel);
 	const all = [...bootDirs, ...packs.map((pack) => pack.dir)];
 
-	const presets = resolve(cwd, 'export_presets.cfg');
-	const cfg = readFileSync(presets, 'utf8');
 	// A plan's routes are relative to the converter's output root, which is where the packs live.
 	const ctx: Bake = { run: exec, cwd, cfg, preset, base: excludeFilter(cfg), all, planBase: resPath(dlc) };
 	try {
@@ -126,18 +166,22 @@ export async function buildAssetPacks(opts: BuildAssetPackOptions = {}, run?: Ru
 		// that *owns* it, whoever needs it). One dump is also one editor run instead of one per pack.
 		const dump = runDump(ctx, [...bootRoots, ...packs.map((pack) => resPath(pack.dir))]);
 
-		const boot = manifestOf(dump, cwd, out, bootDirs);
-		assertRefs('the boot pack', boot.external, bootRoots);
-		exportPack(ctx, bootDirs, `${out}/${BOOT_PCK}`);
-		writeFileSync(resolve(cwd, out, BOOT_MANIFEST), serializeDoc({ needs: boot.needs, stage: boot.stage }));
-		writeFileSync(resolve(cwd, out, BOOT_MODULE), bootModule(boot));
-		console.log(`[pack] ${BOOT_PCK} over ${Object.keys(boot.needs).length} sources`);
+		if (bootDirs.length) {
+			const boot = manifestOf(dump, cwd, out, bootDirs);
+			assertRefs('the boot pack', boot.external, bootRoots);
+			exportPack(ctx, bootDirs, `${out}/${BOOT_PCK}`);
+			writeFileSync(resolve(cwd, out, BOOT_MANIFEST), serializeDoc({ needs: boot.needs, stage: boot.stage }));
+			writeFileSync(resolve(cwd, out, BOOT_MODULE), bootModule(boot));
+			console.log(`[pack] ${BOOT_PCK} over ${Object.keys(boot.needs).length} sources`);
+		}
 
 		for (const pack of packs) {
 			const version = release[pack.name].version;
-			// Version-addressed, exactly as a client fetches it — a local bake then exercises the same
-			// URLs a CDN serves (`packPath`), and nothing is ever rewritten in place.
-			const dir = `${out}/${pack.name}/${version}`;
+			// One directory per pack, holding exactly what its npm package holds: the `.pck`, its
+			// document, the loose products, the types and a manifest. So a bake's output and an installed
+			// pack have the same layout, and a host serves either with one static root. The version is
+			// the release's (`release.json`), not a directory's — a bake builds one per pack.
+			const dir = `${out}/${pack.name}`;
 			mkdirSync(resolve(cwd, dir), { recursive: true });
 			const own = manifestOf(dump, cwd, dir, [pack.dir]);
 			const entries = packEntries(pack.exports);
@@ -158,20 +202,43 @@ export async function buildAssetPacks(opts: BuildAssetPackOptions = {}, run?: Ru
 					stage: own.stage,
 				}),
 			);
-			// The pack's types, emitted beside its own `package.json` (whose `types` names them): a
-			// build-time plugin can serve the module, not its types, so the one declaration it already
-			// carries becomes a declaration file too.
-			const types = resolve(cwd, pack.dir, 'package.d.ts');
-			if (entries.length) {
-				writeFileSync(types, packTypes(pack.exports));
+			// The pack's types, beside its own `package.json` (whose `types` names them) and in its
+			// output directory: a client installs the pack by name, so the types have to travel with it.
+			const types = entries.length ? packTypes(pack.exports) : null;
+			if (types) {
+				writeFileSync(resolve(cwd, pack.dir, 'package.d.ts'), types);
+				writeFileSync(resolve(cwd, dir, 'package.d.ts'), types);
 			} else {
-				rmSync(types, { force: true });
+				rmSync(resolve(cwd, pack.dir, 'package.d.ts'), { force: true });
 			}
+			// The output directory *is* the deployable artifact: `npm publish` of it ships the `.pck`,
+			// its document, the loose products and the types, and its declared dependencies — so a
+			// level pulls its shared pack in on install, and nothing is assembled later.
+			writeFileSync(
+				resolve(cwd, dir, 'package.json'),
+				`${JSON.stringify(
+					{
+						name: pack.name,
+						version,
+						dependencies: Object.keys(pack.dependencies).length ? pack.dependencies : undefined,
+						types: types ? './package.d.ts' : undefined,
+						files: [PACK_DOC, pckOf(pack.name), `${FILES_DIR}/**`, ...(types ? ['package.d.ts'] : [])],
+					},
+					null,
+					'\t',
+				)}\n`,
+			);
 			console.log(`[pack] ${pack.name}@${version} over ${Object.keys(own.needs).length} sources`);
 		}
 		if (packs.length) {
 			writeFileSync(resolve(cwd, out, RELEASE), serializeDoc(release));
+		} else {
+			// Nothing to release: a release document left by a previous bake would name packs this
+			// project no longer builds.
+			rmSync(resolve(cwd, out, RELEASE), { force: true });
 		}
+		// Only a bake that got this far can say the project is up to date next time.
+		writeFileSync(stamp, `${inputs}\n`);
 	} finally {
 		// The preset is scoped per pack, so it is rewritten per export and put back once.
 		writeFileSync(presets, cfg);
@@ -453,6 +520,56 @@ function withExcludes(cfg: string, preset: string, exclude: string[]): string {
 	return `${cfg.slice(0, start)}exclude_filter=${JSON.stringify(exclude.join(','))}${cfg.slice(start + line[0].length)}`;
 }
 
+/**
+ * Everything a bake reads, as one digest: each resource tree's files (`path/size/mtime` — content is the
+ * editor's to read, and a checkout that only moves timestamps re-bakes, which is the safe direction),
+ * the preset, the dump script, the tool, and the editor it runs.
+ */
+function inputsOf({ cwd, dirs, cfg, editor }: {
+	cwd: string;
+	dirs: string[];
+	cfg: string;
+	editor: string | null;
+}): string {
+	const hash = createHash('sha1')
+		.update(cfg)
+		.update(readFileSync(join(HERE, 'dump-deps.gd')))
+		.update(readFileSync(join(HERE, '..', 'package.json')));
+	// The executable itself, not its `--version`: asking would spawn it, which is the cost the stamp
+	// exists to avoid.
+	hash.update(editor ? `${statSync(editor).size}:${statSync(editor).mtimeMs}` : 'injected');
+	for (const dir of dirs) digestTree(resolve(cwd, dir), '', hash);
+	return hash.digest('hex');
+}
+
+/** Feeds a tree's files into `hash`: the bake's own outputs and the app's own sources are not inputs. */
+function digestTree(abs: string, rel: string, hash: Hash): void {
+	let names: string[];
+	try {
+		names = readdirSync(abs);
+	} catch {
+		return;
+	}
+	for (const name of names.sort()) {
+		// The bake's own output beside a pack's manifest, the app's own sources, and dependencies are
+		// not inputs: editing them cannot change a pack.
+		if (name === 'node_modules' || name.startsWith('.') || name === 'package.d.ts' || SOURCE.has(extname(name))) continue;
+		const child = join(abs, name);
+		const stat = statSync(child);
+		if (stat.isDirectory()) digestTree(child, `${rel}/${name}`, hash);
+		else hash.update(`${rel}/${name}:${stat.size}:${stat.mtimeMs}\n`);
+	}
+}
+
+/** The stamp a bake left, or `null` — a stamp this can't read is a project that gets baked. */
+function readStamp(file: string): string | null {
+	try {
+		return readFileSync(file, 'utf8').trim();
+	} catch {
+		return null;
+	}
+}
+
 /** Parses `godot pack` CLI args into {@link BuildAssetPackOptions}. */
 export function parsePackArgs(args: string[]): BuildAssetPackOptions {
 	const opt = (flag: string): string | undefined => {
@@ -460,10 +577,11 @@ export function parsePackArgs(args: string[]): BuildAssetPackOptions {
 		return i >= 0 ? args[i + 1] : undefined;
 	};
 	return {
-		roots: opt('--roots')?.split(',').filter(Boolean),
+		roots: args.includes('--no-boot') ? [] : opt('--roots')?.split(',').filter(Boolean),
 		dlc: opt('--dlc'),
 		out: opt('--out'),
 		preset: opt('--preset'),
 		godot: opt('--godot'),
+		force: args.includes('--force'),
 	};
 }

package/src/editor.ts

@@ -111,6 +111,11 @@ if (import.meta.main) {
 		await buildAssetPacks(parsePackArgs(process.argv.slice(3)));
 		process.exit(0);
 	}
+	if (command === 'clean') {
+		const { cleanProject } = await import('./bake.ts');
+		cleanProject();
+		process.exit(0);
+	}
 	const exe = await resolveEditor();
 	const result = spawnSync(exe, process.argv.slice(2), { stdio: 'inherit', env: { ...process.env, GODOT_NODE_WRAPPER: '1' } });
 	process.exit(result.status ?? 1);

package/src/export_presets.example.cfg

@@ -7,9 +7,9 @@
 ; (see `dump-deps.gd`), not read from the pack. `export_filter="all_resources"`
 ; ignores `include_filter` — scope with `exclude_filter` only.
 ;
-; The bake always splits — one pack per scene (`Pack: <scene>`) plus a shared one — and
-; derives those presets from this one, pruning them again after exporting. Don't write
-; them by hand.
+; The bake rewrites this preset's `exclude_filter` once per pack (the boot pack, then one per
+; content pack) and puts the file back when it finishes, so the export carries exactly one scope.
+; Don't write those scopes by hand.
 
 [preset.0]
 

package/src/load.ts

@@ -13,9 +13,7 @@ import { transcoder } from '@ringozz/godot/transcoder';
 import {
 	FILES_DIR,
 	PACK_DOC,
-	RELEASE,
 	mountClosure,
-	packPath,
 	parseDoc,
 	parseRelease,
 	pckOf,
@@ -368,12 +366,23 @@ export interface MountedPack {
 	url: (file: string) => string;
 }
 
-/** How the runtime reads content packs: `at('<name>/<version>/<file>')` → a fetchable URL. */
+/**
+ * How the runtime reads content packs: a URL per file, and the release that names the packs (or where
+ * to read one). The host owns its base and the way a version is encoded in it, so the protocol never
+ * builds a release-relative path — it knows a pack's name and its files (`pack.json`, `<name>.pck`,
+ * `files/<product>`), and asks.
+ */
 export interface PackSource {
-	/** Where a release document and its packs are read (a CDN prefix, or a dev server's directory). */
-	at?: (path: string) => string;
+	/** A pack's file, as a fetchable URL or a local path — how the host addresses a version is its own. */
+	at?: (pack: string, version: string, file: string) => string;
 	/** The app's own pack, configured by the bake's own code: always mounted, its bytes bundled. */
 	boot?: MountedPack;
+	/**
+	 * The packs to mount. The app's own dependencies (pinned by its lockfile) are one way: there is no
+	 * release document to fetch, and the versions the app was built and tested with are the ones it
+	 * mounts. A URL is the other: mount what a release document names — a bake's `release.json`, a CDN's.
+	 */
+	release?: Release | string;
 }
 
 let packSource: PackSource = {};
@@ -386,11 +395,8 @@ export function configurePacks(source: PackSource): void {
 	packSource = { ...packSource, ...source };
 }
 
-/** Reads a pack document: a URL (a release) over the network, anything else off the filesystem. */
-async function fetchPack(path: string): Promise<string> {
-	const at = packSource.at;
-	if (!at) throw new Error('godot-assets: no pack source — call configurePacks({ at }) first.');
-	const url = at(path);
+/** Reads a document: a URL over the network, anything else off the filesystem. */
+async function readText(url: string): Promise<string> {
 	if (/^https?:/i.test(url)) {
 		const res = await fetch(url);
 		if (!res.ok) throw new Error(`godot-assets: ${url} (${res.status})`);
@@ -402,24 +408,27 @@ async function fetchPack(path: string): Promise<string> {
 	return text;
 }
 
+/** The release to mount: the packs the app pinned, or the document `configurePacks` was pointed at. */
+async function mountedRelease(): Promise<Release> {
+	const pinned = packSource.release;
+	if (!pinned) throw new Error('godot-assets: no release — configurePacks({ release }) with the packs to mount or its URL.');
+	return typeof pinned === 'string' ? parseRelease(await readText(pinned)) : pinned;
+}
+
 /**
  * A resolved entry's files, as the loader stages them: the app's own pack addresses a product from its
- * bundled URLs, a release pack from the version-addressed path the entry was resolved against. This is
- * the addressing the protocol deliberately does not know — which is why a resolution returns packs and
- * file names rather than URLs.
+ * bundled URLs, a mounted pack from the host's addressing. This is the addressing the protocol
+ * deliberately does not know — which is why a resolution returns packs and file names, not URLs.
  */
 function stagedFiles(
 	plan: ResolvedEntry,
-	release: Release,
 	boot: MountedPack | undefined,
-	at: (path: string) => string,
+	fileUrl: (pack: string, file: string) => string,
 ): StagedFiles {
 	const files: StagedFiles = {};
 	for (const { sidecar, content, product, pack, file } of plan.files) {
 		files[sidecar] = { content };
-		files[product] = {
-			path: pack === null ? boot!.url(file) : at(packPath(pack, release[pack].version, `${FILES_DIR}/${file}`)),
-		};
+		files[product] = { path: pack === null ? boot!.url(file) : fileUrl(pack, `${FILES_DIR}/${file}`) };
 	}
 	return files;
 }
@@ -436,24 +445,31 @@ export async function loadPackEntry<C extends ResourceConstructor>(
 ): Promise<InstanceType<C>> {
 	const at = packSource.at;
 	if (!at) throw new Error('godot-assets: no pack source — call configurePacks({ at }) first.');
+	const release = await mountedRelease();
 	// Mounting needs only the release — a pack's `.pck` is `<name>.pck` by convention — so the closure's
-	// packs are mounted while their documents are fetched, and only staging waits on those.
-	const release = parseRelease(await fetchPack(RELEASE));
+	// packs are mounted while their documents are read, and only staging waits on those.
 	const names = mountClosure(release, pack);
-	const pckUrl = (name: string) => at(packPath(name, release[name].version, pckOf(name)));
+	const url = (name: string, file: string) => at(name, release[name].version, file);
 	const boot = packSource.boot;
-	const mounts = [...(boot ? [boot.pck] : []), ...names.map(pckUrl)].map((url) => loadAssetPack(url));
+	const mounts = [...(boot ? [boot.pck] : []), ...names.map((name) => url(name, pckOf(name)))].map((pck) =>
+		loadAssetPack(pck),
+	);
 	const docs = Object.fromEntries(
 		await Promise.all(
 			names.map(async (name): Promise<[string, PackDoc]> => {
-				const { version } = release[name];
-				return [name, parseDoc(await fetchPack(packPath(name, version, PACK_DOC)))];
+				const doc = parseDoc(await readText(url(name, PACK_DOC)));
+				// A base that serves a version it wasn't asked for is the one thing a client cannot see:
+				// production's URLs are immutable, and a dev server pointed at a local bake serves content
+				// at another version on purpose. Say so; the load still works.
+				if (doc.version !== release[name].version) {
+					console.warn(`godot-assets: ${name} ${release[name].version} asked, ${doc.version ?? 'no version'} served`);
+				}
+				return [name, doc];
 			}),
 		),
 	);
 	const plan = resolveEntry(release, docs, pack, entry, boot?.doc);
 	// The boot is a mounted pack like any other, so an entry borrows its loose files too.
-	const files = stagedFiles(plan, release, boot, at);
 	await Promise.all(mounts);
-	return loadAsset(plan.res, cls, files).load;
+	return loadAsset(plan.res, cls, stagedFiles(plan, boot, url)).load;
 }

package/src/pack.ts

@@ -87,11 +87,6 @@ export function mountClosure(release: Release, entry: string): string[] {
 	return out;
 }
 
-/** A pack's file, relative to a release base: `<name>/<version>/<file>` (version-addressed, immutable). */
-export function packPath(name: string, version: string, file: string): string {
-	return `${name}/${version}/${file}`;
-}
-
 /** The `.pck` beside a pack's document: its name's last segment (a scoped name stays flat). The one
  * convention the bake's writer and the runtime's reader share — mounting resolves it from the release
  * alone, so it never waits on the document. */

package/src/preload.ts

@@ -1,165 +1,164 @@
-/**********************************************************************
- Copyright (c) Vladimir Davidovich. All rights reserved.
-***********************************************************************/
-
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { plugin } from 'bun';
-import { classOf, moduleExtensions } from './formats.ts';
-import { BOOT_MANIFEST, BOOT_MODULE, PACK_DIR, PACK_DIR_ENV, PACK_DOC, RELEASE, descriptorOf, packEntries, stagedKeys, type PackDoc, type PackEntry } from './pack.ts';
-import { assetModule, packModule, type ServedAsset } from './serve.ts';
-import type { BunPlugin } from 'bun';
-
-// Registers the godot-assets plugin: importing a Godot source asset becomes a module that stages what
-// the source needs and loads it (default export = the load promise, `materialize` = its files staged).
-//
-// What a source needs comes from the bake (`@ringozz/godot/pack`), never from scanning source text:
-// `dump-deps.gd` walked the project at bake time and wrote, per source, the loose (WebP-backed)
-// texture sources the wasm engine cannot decode — and the descriptor of every loose file the app's
-// pack owns. A packed source resolves inside the mounted `.pck`; only its loose textures are staged
-// per file, each with the `.import` text and product `descriptorOf` reads from the same sidecar the
-// bake read.
-//
-// The bake's own pack is the module it generated beside the packs (`boot-pack.js`): its `.pck`, the
-// config the runtime stages content packs from, and the mount every asset module waits for. So
-// importing any asset is what mounts the app's pack, and the config an app still supplies
-// (`configurePacks({ at })`, where a content release is read) merges with it in either order.
-//
-// The load promise persists on `import.meta.hot.data` (carried across HMR re-evaluations) so `use()`
-// never re-suspends; a rejected load is evicted so the next evaluation retries. The default export is
-// the single plugin — registered globally via bunfig preload and loaded by `[serve.static] plugins`.
-
-const ROOT = process.cwd();
-const NS = 'godot';
-
-const ASSET_RE = new RegExp(`\\.(${moduleExtensions.join('|')})$`, 'i');
-
-const resOf = (abs: string) => 'res://' + abs.slice(ROOT.length + 1).replaceAll('\\', '/');
-
-const readJson = <T>(file: string): T | null =>
-	existsSync(file) ? (JSON.parse(readFileSync(file, 'utf8')) as T) : null;
-
-/** Where the boot pack was baked — `godot pack`'s `--out` ({@link PACK_DIR_ENV} overrides for a host). */
-const DIR = resolve(ROOT, process.env[PACK_DIR_ENV] ?? PACK_DIR);
-const MANIFEST = readJson<PackDoc>(resolve(DIR, BOOT_MANIFEST));
-/** The bake's generated boot module (`{ mounting }` + its config); null when unbaked. */
-const BOOT = MANIFEST ? resolve(DIR, BOOT_MODULE) : null;
-
-/**
- * A content pack's entries, from the bake's own documents — `release.json` and each pack's emitted
- * manifest, the same shapes the runtime fetches. A pack carries no entry module: the plugin serves one
- * built from these, so an entry, its `res://` path and its class come from one declaration — the rule
- * the bake emits the pack's types from as well (`packEntries`).
- */
-const PACK_ENTRIES = readPacks();
-
-function readPacks(): Map<string, PackEntry[]> {
-	const packs = new Map<string, PackEntry[]>();
-	const release = readJson<Record<string, { version?: string }>>(resolve(DIR, RELEASE));
-	for (const [pack, { version }] of Object.entries(release ?? {})) {
-		if (!version) continue;
-		const entries = packEntries(readJson<PackDoc>(resolve(DIR, pack, version, PACK_DOC))?.exports);
-		if (entries.length) packs.set(pack, entries);
-	}
-	return packs;
-}
-
-/**
- * The loose texture sources one asset stages: what the bake's manifest recorded for it, or itself when
- * it *is* a loose texture — a source with an `.import` sidecar is excluded from the pack, so a texture
- * imported on its own has no packed source to name it (the same rule `dump-deps.gd` classifies by).
- */
-function needsOf(abs: string): string[] {
-	const res = resOf(abs);
-	const baked = MANIFEST?.needs[res];
-	if (baked) return baked;
-	return existsSync(abs + '.import') ? [res] : [];
-}
-
-/**
- * A loose file's staging descriptor: the bake's own (its manifest carries every loose file the app's
- * pack owns), or its sidecar when the bake never saw it — which is what keeps the plugin and a content
- * pack's runtime staging on the same rule, `descriptorOf`.
- */
-function descriptorFor(loose: string): { path: string; import: string } | null {
-	const baked = MANIFEST?.stage[loose];
-	if (baked) return baked;
-	const sidecar = resolve(ROOT, loose.slice('res://'.length)) + '.import';
-	return existsSync(sidecar) ? descriptorOf(readFileSync(sidecar, 'utf8')) : null;
-}
-
-/**
- * One source's module, from the bake's own records: the loose textures the bake recorded for it (`needs`
- * / `stage`, or its sidecar when the bake never saw it), each as the absolute path the bundler imports
- * plus the two keys it stages under. Every other decision is the module text's (`serve.ts`).
- */
-function servedAsset(abs: string): ServedAsset {
-	return {
-		res: resOf(abs),
-		// The filter is `moduleExtensions`, so a path that reached here has a class.
-		cls: classOf(abs)!,
-		boot: BOOT,
-		files: needsOf(abs).flatMap((loose) => {
-			const descriptor = descriptorFor(loose);
-			if (!descriptor) return [];
-			const { sidecar, product } = stagedKeys(loose, descriptor);
-			return [
-				{
-					specifier: resolve(ROOT, descriptor.path.replace(/^res:\/\//, '')),
-					sidecar,
-					content: descriptor.import,
-					product,
-				},
-			];
-		}),
-	};
-}
-
-/**
- * Exactly the pack names the bake declares — nothing else is touched. A wider filter would shadow
- * resolutions Bun makes itself (it injects a `react-refresh` import in dev, and that import must fall
- * through to it, not to a plugin that declines).
- */
-const PACK_RE = PACK_ENTRIES.size
-	? new RegExp(`^(${[...PACK_ENTRIES.keys()].map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})$`)
-	: null;
-
-const assetPlugin: BunPlugin = {
-	name: 'godot-assets',
-	setup(build) {
-		build.onResolve({ filter: ASSET_RE }, (args) => {
-			// Only JS module imports of Godot source assets become `godot` modules.
-			// `Bun.build` reports JS imports as `import-statement` (and
-			// `dynamic-import`/`require-*`) but HTML asset references (<link>/<img>)
-			// and CSS url() refs as `internal`/`url-token` — those fall through so
-			// Bun copies/hashes the file normally. The runtime preload (bun run /
-			// bun test) reports JS imports with no kind (`undefined`), so treat that
-			// as a JS import too.
-			if (
-				args.kind !== undefined &&
-				args.kind !== 'import-statement' &&
-				args.kind !== 'dynamic-import' &&
-				args.kind !== 'require-call' &&
-				args.kind !== 'require-resolve'
-			) {
-				return;
-			}
-			const base = args.importer ? dirname(args.importer) : (args.resolveDir ?? ROOT);
-			return { path: resolve(base, args.path), namespace: NS };
-		});
-		// A pack's own module (the pack carries no entry file, so the plugin serves it, built from the
-		// bake's manifests). The filter names the packs exactly: anything else resolves as usual.
-		if (PACK_RE) {
-			build.onResolve({ filter: PACK_RE }, (args) => ({ path: args.path, namespace: NS }));
-		}
-		build.onLoad({ filter: /.*/, namespace: NS }, (args) => ({
-			contents: PACK_ENTRIES.has(args.path)
-				? packModule(args.path, PACK_ENTRIES.get(args.path)!)
-				: assetModule(servedAsset(args.path)),
-			loader: 'js',
-		}));
-	},
-};
-
-export default assetPlugin;
-plugin(assetPlugin);
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { plugin } from 'bun';
+import { classOf, moduleExtensions } from './formats.ts';
+import { BOOT_MANIFEST, BOOT_MODULE, PACK_DIR, PACK_DIR_ENV, PACK_DOC, RELEASE, descriptorOf, packEntries, stagedKeys, type PackDoc, type PackEntry } from './pack.ts';
+import { assetModule, packModule, type ServedAsset } from './serve.ts';
+import type { BunPlugin } from 'bun';
+
+// Registers the godot-assets plugin: importing a Godot source asset becomes a module that stages what
+// the source needs and loads it (default export = the load promise, `materialize` = its files staged).
+//
+// What a source needs comes from the bake (`@ringozz/godot/pack`), never from scanning source text:
+// `dump-deps.gd` walked the project at bake time and wrote, per source, the loose (WebP-backed)
+// texture sources the wasm engine cannot decode — and the descriptor of every loose file the app's
+// pack owns. A packed source resolves inside the mounted `.pck`; only its loose textures are staged
+// per file, each with the `.import` text and product `descriptorOf` reads from the same sidecar the
+// bake read.
+//
+// The bake's own pack is the module it generated beside the packs (`boot-pack.js`): its `.pck`, the
+// config the runtime stages content packs from, and the mount every asset module waits for. So
+// importing any asset is what mounts the app's pack, and the config an app still supplies
+// (`configurePacks({ at })`, where a content release is read) merges with it in either order.
+//
+// The load promise persists on `import.meta.hot.data` (carried across HMR re-evaluations) so `use()`
+// never re-suspends; a rejected load is evicted so the next evaluation retries. The default export is
+// the single plugin — registered globally via bunfig preload and loaded by `[serve.static] plugins`.
+
+const ROOT = process.cwd();
+const NS = 'godot';
+
+const ASSET_RE = new RegExp(`\\.(${moduleExtensions.join('|')})$`, 'i');
+
+const resOf = (abs: string) => 'res://' + abs.slice(ROOT.length + 1).replaceAll('\\', '/');
+
+const readJson = <T>(file: string): T | null =>
+	existsSync(file) ? (JSON.parse(readFileSync(file, 'utf8')) as T) : null;
+
+/** Where the boot pack was baked — `godot pack`'s `--out` ({@link PACK_DIR_ENV} overrides for a host). */
+const DIR = resolve(ROOT, process.env[PACK_DIR_ENV] ?? PACK_DIR);
+const MANIFEST = readJson<PackDoc>(resolve(DIR, BOOT_MANIFEST));
+/** The bake's generated boot module (`{ mounting }` + its config); null when unbaked. */
+const BOOT = MANIFEST ? resolve(DIR, BOOT_MODULE) : null;
+
+/**
+ * A content pack's entries, from the bake's own documents — `release.json` and each pack's emitted
+ * manifest, the same shapes the runtime fetches. A pack carries no entry module: the plugin serves one
+ * built from these, so an entry, its `res://` path and its class come from one declaration — the rule
+ * the bake emits the pack's types from as well (`packEntries`).
+ */
+const PACK_ENTRIES = readPacks();
+
+function readPacks(): Map<string, PackEntry[]> {
+	const packs = new Map<string, PackEntry[]>();
+	const release = readJson<Record<string, unknown>>(resolve(DIR, RELEASE));
+	for (const pack of Object.keys(release ?? {})) {
+		const entries = packEntries(readJson<PackDoc>(resolve(DIR, pack, PACK_DOC))?.exports);
+		if (entries.length) packs.set(pack, entries);
+	}
+	return packs;
+}
+
+/**
+ * The loose texture sources one asset stages: what the bake's manifest recorded for it, or itself when
+ * it *is* a loose texture — a source with an `.import` sidecar is excluded from the pack, so a texture
+ * imported on its own has no packed source to name it (the same rule `dump-deps.gd` classifies by).
+ */
+function needsOf(abs: string): string[] {
+	const res = resOf(abs);
+	const baked = MANIFEST?.needs[res];
+	if (baked) return baked;
+	return existsSync(abs + '.import') ? [res] : [];
+}
+
+/**
+ * A loose file's staging descriptor: the bake's own (its manifest carries every loose file the app's
+ * pack owns), or its sidecar when the bake never saw it — which is what keeps the plugin and a content
+ * pack's runtime staging on the same rule, `descriptorOf`.
+ */
+function descriptorFor(loose: string): { path: string; import: string } | null {
+	const baked = MANIFEST?.stage[loose];
+	if (baked) return baked;
+	const sidecar = resolve(ROOT, loose.slice('res://'.length)) + '.import';
+	return existsSync(sidecar) ? descriptorOf(readFileSync(sidecar, 'utf8')) : null;
+}
+
+/**
+ * One source's module, from the bake's own records: the loose textures the bake recorded for it (`needs`
+ * / `stage`, or its sidecar when the bake never saw it), each as the absolute path the bundler imports
+ * plus the two keys it stages under. Every other decision is the module text's (`serve.ts`).
+ */
+function servedAsset(abs: string): ServedAsset {
+	return {
+		res: resOf(abs),
+		// The filter is `moduleExtensions`, so a path that reached here has a class.
+		cls: classOf(abs)!,
+		boot: BOOT,
+		files: needsOf(abs).flatMap((loose) => {
+			const descriptor = descriptorFor(loose);
+			if (!descriptor) return [];
+			const { sidecar, product } = stagedKeys(loose, descriptor);
+			return [
+				{
+					specifier: resolve(ROOT, descriptor.path.replace(/^res:\/\//, '')),
+					sidecar,
+					content: descriptor.import,
+					product,
+				},
+			];
+		}),
+	};
+}
+
+/**
+ * Exactly the pack names the bake declares — nothing else is touched. A wider filter would shadow
+ * resolutions Bun makes itself (it injects a `react-refresh` import in dev, and that import must fall
+ * through to it, not to a plugin that declines).
+ */
+const PACK_RE = PACK_ENTRIES.size
+	? new RegExp(`^(${[...PACK_ENTRIES.keys()].map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})$`)
+	: null;
+
+const assetPlugin: BunPlugin = {
+	name: 'godot-assets',
+	setup(build) {
+		build.onResolve({ filter: ASSET_RE }, (args) => {
+			// Only JS module imports of Godot source assets become `godot` modules.
+			// `Bun.build` reports JS imports as `import-statement` (and
+			// `dynamic-import`/`require-*`) but HTML asset references (<link>/<img>)
+			// and CSS url() refs as `internal`/`url-token` — those fall through so
+			// Bun copies/hashes the file normally. The runtime preload (bun run /
+			// bun test) reports JS imports with no kind (`undefined`), so treat that
+			// as a JS import too.
+			if (
+				args.kind !== undefined &&
+				args.kind !== 'import-statement' &&
+				args.kind !== 'dynamic-import' &&
+				args.kind !== 'require-call' &&
+				args.kind !== 'require-resolve'
+			) {
+				return;
+			}
+			const base = args.importer ? dirname(args.importer) : (args.resolveDir ?? ROOT);
+			return { path: resolve(base, args.path), namespace: NS };
+		});
+		// A pack's own module (the pack carries no entry file, so the plugin serves it, built from the
+		// bake's manifests). The filter names the packs exactly: anything else resolves as usual.
+		if (PACK_RE) {
+			build.onResolve({ filter: PACK_RE }, (args) => ({ path: args.path, namespace: NS }));
+		}
+		build.onLoad({ filter: /.*/, namespace: NS }, (args) => ({
+			contents: PACK_ENTRIES.has(args.path)
+				? packModule(args.path, PACK_ENTRIES.get(args.path)!)
+				: assetModule(servedAsset(args.path)),
+			loader: 'js',
+		}));
+	},
+};
+
+export default assetPlugin;
+plugin(assetPlugin);

package/src/serve.ts

@@ -1,67 +1,67 @@
-/**********************************************************************
- Copyright (c) Vladimir Davidovich. All rights reserved.
-***********************************************************************/
-
-// The source text the preload plugin serves, as a virtual module per import: one for a Godot source
-// asset (the loose textures it stages, then the load), one for a content pack (a named export per entry
-// it declares). Pure — a module's text is a function of the facts the plugin resolved — which is what
-// makes the one part of the plugin that decides what an import becomes reachable without a bake, a
-// bundler or an engine. The plugin resolves those facts (`preload.ts`); nothing here touches a disk.
-
-import { entryId, type PackEntry } from './pack.ts';
-
-/** The facts the plugin resolved for one source asset, as the module it serves reads them. */
-export interface ServedAsset {
-	/** The source's `res://` path — what the module loads. */
-	res: string;
-	/** The class it loads as. */
-	cls: string;
-	/**
-	 * One entry per loose texture the source needs: the file to bundle (an absolute path, so the host can
-	 * transcode it), and the two keys it stages under. The sidecar text is inlined rather than imported
-	 * as text — Bun's `with { type: 'text' }` resolves to a null/default under the dev server's HMR
-	 * wrapper for a module's own path.
-	 */
-	files: Array<{ specifier: string; sidecar: string; content: string; product: string }>;
-	/** The boot module every asset module waits for (`{ mounting }`); `null` when the project is unbaked. */
-	boot: string | null;
-}
-
-/**
- * One source's module: its loose textures as bundled files, and the load. The boot module supplies the
- * mount to wait for, so the pack's remaps are in place before anything resolves — and importing it is
- * also what mounts the boot pack.
- */
-export function assetModule({ res, cls, files, boot }: ServedAsset): string {
-	const imports = [
-		`import { loadAsset } from '@ringozz/godot/load';`,
-		`import { ${cls} } from '@ringozz/godot/${cls}';`,
-	];
-	const map: string[] = [];
-	files.forEach(({ specifier, sidecar, content, product }, n) => {
-		imports.push(`import f${n} from ${JSON.stringify(specifier)} with { type: 'file' };`);
-		map.push(`\t${JSON.stringify(sidecar)}: { content: ${JSON.stringify(content)} },`);
-		map.push(`\t${JSON.stringify(product)}: { path: f${n} },`);
-	});
-	if (boot) imports.push(`import { mounting } from ${JSON.stringify(boot)};`);
-	const staged = map.length ? `const files = {\n${map.join('\n')}\n};` : 'const files = {};';
-	const load = `const { materialize, load } = loadAsset(${JSON.stringify(res)}, ${cls}, files, import.meta.hot.data, ${boot ? 'mounting' : 'undefined'});`;
-	return `${imports.join('\n')}\n${staged}\n${load}\nexport { materialize, load as default };\n`;
-}
-
-/**
- * A content pack's module: one named export per entry its document declares, each loading through
- * `loadPackEntry`, so a client resolves the entry by name from the document it fetched. Nothing about
- * the pack is baked in — no entry file, no path — and the class is the same format-table rule every
- * asset import uses.
- */
-export function packModule(pack: string, entries: PackEntry[]): string {
-	const imports = ["import { loadPackEntry } from '@ringozz/godot/load';"];
-	for (const cls of new Set(entries.map((e) => e.cls))) {
-		imports.push(`import { ${cls} } from '@ringozz/godot/${cls}';`);
-	}
-	const lines = entries.map(
-		(e) => `export const ${entryId(e.entry)} = loadPackEntry(${JSON.stringify(pack)}, ${JSON.stringify(e.entry)}, ${e.cls});`,
-	);
-	return `${imports.join('\n')}\n\n${lines.join('\n')}\n`;
-}
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+// The source text the preload plugin serves, as a virtual module per import: one for a Godot source
+// asset (the loose textures it stages, then the load), one for a content pack (a named export per entry
+// it declares). Pure — a module's text is a function of the facts the plugin resolved — which is what
+// makes the one part of the plugin that decides what an import becomes reachable without a bake, a
+// bundler or an engine. The plugin resolves those facts (`preload.ts`); nothing here touches a disk.
+
+import { entryId, type PackEntry } from './pack.ts';
+
+/** The facts the plugin resolved for one source asset, as the module it serves reads them. */
+export interface ServedAsset {
+	/** The source's `res://` path — what the module loads. */
+	res: string;
+	/** The class it loads as. */
+	cls: string;
+	/**
+	 * One entry per loose texture the source needs: the file to bundle (an absolute path, so the host can
+	 * transcode it), and the two keys it stages under. The sidecar text is inlined rather than imported
+	 * as text — Bun's `with { type: 'text' }` resolves to a null/default under the dev server's HMR
+	 * wrapper for a module's own path.
+	 */
+	files: Array<{ specifier: string; sidecar: string; content: string; product: string }>;
+	/** The boot module every asset module waits for (`{ mounting }`); `null` when the project is unbaked. */
+	boot: string | null;
+}
+
+/**
+ * One source's module: its loose textures as bundled files, and the load. The boot module supplies the
+ * mount to wait for, so the pack's remaps are in place before anything resolves — and importing it is
+ * also what mounts the boot pack.
+ */
+export function assetModule({ res, cls, files, boot }: ServedAsset): string {
+	const imports = [
+		`import { loadAsset } from '@ringozz/godot/load';`,
+		`import { ${cls} } from '@ringozz/godot/${cls}';`,
+	];
+	const map: string[] = [];
+	files.forEach(({ specifier, sidecar, content, product }, n) => {
+		imports.push(`import f${n} from ${JSON.stringify(specifier)} with { type: 'file' };`);
+		map.push(`\t${JSON.stringify(sidecar)}: { content: ${JSON.stringify(content)} },`);
+		map.push(`\t${JSON.stringify(product)}: { path: f${n} },`);
+	});
+	if (boot) imports.push(`import { mounting } from ${JSON.stringify(boot)};`);
+	const staged = map.length ? `const files = {\n${map.join('\n')}\n};` : 'const files = {};';
+	const load = `const { materialize, load } = loadAsset(${JSON.stringify(res)}, ${cls}, files, import.meta.hot.data, ${boot ? 'mounting' : 'undefined'});`;
+	return `${imports.join('\n')}\n${staged}\n${load}\nexport { materialize, load as default };\n`;
+}
+
+/**
+ * A content pack's module: one named export per entry its document declares, each loading through
+ * `loadPackEntry`, so a client resolves the entry by name from the document it fetched. Nothing about
+ * the pack is baked in — no entry file, no path — and the class is the same format-table rule every
+ * asset import uses.
+ */
+export function packModule(pack: string, entries: PackEntry[]): string {
+	const imports = ["import { loadPackEntry } from '@ringozz/godot/load';"];
+	for (const cls of new Set(entries.map((e) => e.cls))) {
+		imports.push(`import { ${cls} } from '@ringozz/godot/${cls}';`);
+	}
+	const lines = entries.map(
+		(e) => `export const ${entryId(e.entry)} = loadPackEntry(${JSON.stringify(pack)}, ${JSON.stringify(e.entry)}, ${e.cls});`,
+	);
+	return `${imports.join('\n')}\n\n${lines.join('\n')}\n`;
+}