@ringozz/godot 4.7.2-659 → 4.7.2-664

package/README.md

@@ -52,8 +52,9 @@ await import('./app.ts'); // may now import @ringozz/godot / react-godot freely
 | `@ringozz/godot/ClassName` | Classes, one per module — e.g. `@ringozz/godot/Label`, `@ringozz/godot/Node` |
 | `@ringozz/godot/runtime` | Low-level dispatch: `_C`, `_S`, `_R`, `_G`, `_P`, `_V`, `toValueType`, `getGodot`, `GodotVar` |
 | `@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) |
-| `@ringozz/godot/pack` | `buildAssetPacks()` + the `godot pack` subcommand: bake a project's `.pck`(s) + loose-texture manifest, one pack per level (its scene, or the `.gltfx` its plan lives in) |
+| `@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/debug` | `initDebug()`, `dumpStr`, `snapshot`, `inspect`, `click`, `find`, `gc` |
 
 Class-scoped enums use bare names (import `ProcessMode` from `@ringozz/godot/Node`, not `NodeProcessMode`).
@@ -91,19 +92,37 @@ const tex   = await loadResourceAsync('res://textures/icon.jpg', Texture2D); //
 ```
 
 - `loadResourceAsync(path, cls, files?)` — generic over the Godot class: `cls.name` is the `ResourceLoader` type hint, and the return type is `InstanceType<typeof cls>`. Loads in the background (`loadThreadedRequest` + status polling). Godot default arguments apply: the napi dispatch truncates trailing `undefined` args, so `loadThreadedRequest` uses its default `CACHE_MODE_REUSE` and the resource stays cached in the engine (scene re-references don't re-read the file). On web it only works for paths already staged into MEMFS (generated asset modules handle this). When the asset's `files` map is passed, the staged product files (`.ctex`/`.scn`/native sources) are deleted from MEMFS after the resource loads — only the `.import` sidecars are kept, since they route imported source paths to their products. The decoded texture bytes don't linger in the JS heap. `files` lists overlap (a scene and the model it instantiates can share one loose texture), so a product may need re-staging after another module's cleanup: `materialize` creates the parent directory itself and treats an already-staged file as done, because the engine's `copyToFS` throws on a path that is already there while `FileAccess.fileExists('res://…')` cannot see the Emscripten spelling of it.
-- `loadAsset(path, cls, files, deps, data)` — the generated asset modules' entry point (also usable directly): returns `{ materialize, load }`. It checks the engine's `ResourceCache` first (when the asset is already loaded, `load` resolves to the cached instance and staging is skipped), stages the bundled files via Godot's `copyToFS` (zero-copy handover of the fetched bytes; a no-op on desktop where the files already exist), loads via `loadResourceAsync`, and memoizes `load` on `data` (pass `import.meta.hot.data`) so HMR re-evaluations reuse the same fulfilled promise.
+- `loadAsset(path, cls, files, data, ready)` — the generated asset modules' entry point (also usable directly): returns `{ materialize, load }`. It checks the engine's `ResourceCache` first (when the asset is already loaded, `load` resolves to the cached instance and staging is skipped), stages the bundled files via Godot's `copyToFS` (zero-copy handover of the fetched bytes; a no-op on desktop where the files already exist), loads via `loadResourceAsync`, and memoizes `load` on `data` (pass `import.meta.hot.data`) so HMR re-evaluations reuse the same fulfilled promise.
 
 ### Asset packs
 
-`godot pack` (the `godot` bin, `@ringozz/godot/pack`) bakes a project's assets for the runtime: it imports them, asks `dump-deps.gd` for each source's packed closure and its loose (WebP-backed) textures, and exports native `.pck`s — the engine-converted binary resources plus a remap table — through the project's committed `export_presets.cfg`. `loadAssetPack(url)` fetches a pack into MEMFS and hands it to `ProjectSettings.loadResourcePack`; packs are add-only, so several can be mounted and `res://` resolves across all of them.
+`godot pack` (the `godot` bin, `@ringozz/godot/bake`) bakes a project's assets for the runtime: it imports them, asks `dump-deps.gd` for every source's loose (WebP-backed) textures — including a plan, which names refs no resource edge exposes (it warns when a plan resolves no ref at all, or is stamped under another `extras` namespace — that reading has no static check) — and exports one native `.pck` — the engine-converted binary resources plus a remap table — through the project's committed `export_presets.cfg`. `loadAssetPack(url)` fetches a pack into MEMFS and hands it to `ProjectSettings.loadResourcePack`; packs are add-only, so several can be mounted and `res://` resolves across all of them.
 
-The bake always splits: **one pack per level, plus a shared pack**, so a host fetches the shared data and only the level it is playing. A level is its scene — or, in a project that builds levels from their plans at run time, the `.gltfx` its plan lives in; a project with neither under its roots gets a single `shared.pck`. What the runtime reads is `.godot/packs/packs.json` beside the packs: which packs exist, which sources each owns, and which loose sources the host must stage per file (the WebP-backed textures are transcoded; a plan's plain header JSONs are just written). The preload plugin mounts the right packs per asset, so importing a level pulls in the shared pack and that level's, nothing else. How the split is decided — and why it needs no configuration — is in `AGENTS.md`.
+The bake produces **one boot pack** — the project's own sources, exported through its committed `export_presets.cfg` preset, and always mounted by the preload plugin, which is what makes a scene's own run-time paths (a script named by a constant, a level chosen at run time) resolvable — plus **one pack per directory under `dlc/` that declares itself with a `package.json`**: that file gives the pack its name, its dependencies on other packs and its `exports` entries, the pack is that directory and nothing else (the bake rewrites the preset's one `exclude_filter` line per pack), and the bake fails if a pack references anything but the boot sources and its declared dependencies. The boot pack's document is `.godot/packs/packs.json` (`needs` = which loose files each source needs staged, `stage` = the descriptor and product of each loose file the pack owns); a content pack's is a `pack.json` emitted beside its `.pck` (`PACK_DOC` — not `package.json`, which is the pack's own manifest in its source directory, an input the bake reads) (its declared fields plus `needs`/`stage` — the same document the boot's `packs.json` is). Deploying those packs independently — versioning, an index, a CDN — is the host's business, not the bake's.
 
 ```ts
 import { loadAssetPack } from '@ringozz/godot/load';
 await loadAssetPack('/packs/shared.pck');   // usually the preload plugin does this per asset
 ```
 
+### Content packs
+
+A content pack is deployed apart from the app, so nothing about it is in the bundle: the runtime reads a **release** (which version of which pack to mount — a `bun.lock`, or the plain map a local bake emits) and each mounted pack's document, then loads a declared entry. Point the runtime at the packs once, at start-up:
+
+```ts
+import { configurePacks } from '@ringozz/godot/load';
+configurePacks({ at: (path) => `https://cdn.example/packs/${path}` });   // '<name>/<version>/<file>'
+```
+
+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`):
+
+```ts
+import { level } from '@tiv/dlc-beach';   // → a PackedScene, via loadPackEntry(pack, 'level', …)
+```
+
+Mounting is add-only, so every pack in the closure stays mounted for the page's lifetime.
+
+
 ### Asset imports
 
 Asset imports are resolved by `@ringozz/godot/preload` (a Bun plugin, registered via `bunfig.toml` preload for `bun run`/`bun test` and via `[serve.static] plugins` for `Bun.serve`'s fullstack HTML routes; the module's default export is the single plugin object) into a module per asset. Only **JS imports** are virtualized — HTML asset references (`<link rel="icon">`, `<img src>`) and CSS `url()` refs fall through to Bun's normal (content-hashed) asset handling, so favicons and other web assets co-exist with Godot imports:
@@ -113,7 +132,7 @@ import foo from './models/foo.gltf';
 const scene = await foo;          // PackedScene
 ```
 
-Each asset module's default export is its load **promise** (`const { materialize, load } = loadAsset(resPath, Class, files, deps, import.meta.hot.data)` — the default is `load`, memoized on the module's HMR data), started eagerly at module import, and it also exports a `materialize` promise (its own files plus its deps' files). The files Godot reads are bundled into the module — `.import` sidecars and native text sources (`tscn`/`tres`/`po`/`gd`/`gdshader`/`gdshaderinc`) are inlined as text, imported products (`.scn`/`.ctex`) are emitted as files — and the module imports its **dependencies as generated modules too**, waiting only for their `materialize` before loading itself (dep loads start at module evaluation and run concurrently). Text-based source assets (`.gltf`/`.tscn`/`.tres`/`.obj`/`.gd`/`.gdshader`/`.gdshaderinc`) are scanned for references (`res://` paths and relative paths ending in known asset extensions); referenced loadable assets become dep modules, native-text leaves are staged as raw text so the engine loads them by `res://` on web, raw `.mtl` files (OBJ materials) are recursed into, and raw `.bin` buffers are import-time only. The modules are virtual (namespace `godot`), and every import of the same asset resolves to the same one (evaluated once) — so the promise is a stable singleton, read with `await` or React 19's `use()`:
+Each asset module's default export is its load **promise** (`const { materialize, load } = loadAsset(resPath, Class, files, import.meta.hot.data, mounting)` — the default is `load`, memoized on the module's HMR data), started eagerly at module import, and it also exports a `materialize` promise (its files staged). The files Godot reads are bundled into the module — `.import` sidecars are inlined as text, imported products (`.ctex`) are emitted as files — from the bake's document, never from scanning the 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 pack's `stage` gives each of those its sidecar and its product. A packed source resolves inside the mounted `.pck` (the engine-converted resources plus a remap table); only its loose textures are staged per file, transcoded in the browser. The `mounting` promise comes from the bake's boot pack — the module the bake generates beside the packs (`.godot/packs/boot-pack.js`): its `.pck`, plus a bundled URL for every loose product it owns — so importing any asset is also what mounts the app's own pack, and the runtime can stage a content pack's loose files even when the boot owns them. The modules are virtual (namespace `godot`), and every import of the same asset resolves to the same one (evaluated once) — so the promise is a stable singleton, read with `await` or React 19's `use()`:
 
 ```tsx
 import foo from './models/foo.gltf';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/godot",
   "author": "Vladimir Davidovich",
-  "version": "4.7.2-659",
+  "version": "4.7.2-664",
   "description": "Node-API bindings for Godot Engine — call Godot classes from JavaScript",
   "publishConfig": {
     "access": "public"
@@ -27,6 +27,7 @@
     },
     "./load": "./src/load.ts",
     "./pack": "./src/pack.ts",
+    "./bake": "./src/bake.ts",
     "./transcoder": {
       "browser": "./src/transcoder.browser.ts",
       "default": "./src/transcoder.ts"
@@ -66,9 +67,9 @@
     "precision": "single"
   },
   "optionalDependencies": {
-    "@ringozz/godot-macos-arm64": "^4.7.2-659",
-    "@ringozz/godot-windows-x86_64": "^4.7.2-659",
-    "@ringozz/godot-web-wasm32": "^4.7.2-659"
+    "@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"
   },
   "peerDependencies": {
     "@types/bun": "*"

package/src/assets.d.ts

@@ -30,7 +30,7 @@ declare module '*.gdshaderinc' {
 	export default asset;
 	export const materialize: Promise<unknown>;
 }
-
+
 declare module '*.tres' {
 	import type { Resource } from '@ringozz/godot/Resource';
 	const asset: Promise<Resource>;
@@ -108,6 +108,15 @@ declare module '*.svg' {
 	export const materialize: Promise<unknown>;
 }
 
+// The layer manifest `godot/addons/sourcewebp` imports into a `.ctexarray` (a texture array whose
+// layers are source WebP bytes); its product is what is staged.
+declare module '*.webparray' {
+	import type { CompressedTexture2DArray } from '@ringozz/godot/CompressedTexture2DArray';
+	const asset: Promise<CompressedTexture2DArray>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
 declare module '*.exr' {
 	import type { TextureLayered } from '@ringozz/godot/TextureLayered';
 	const asset: Promise<TextureLayered>;

package/src/bake.ts

@@ -0,0 +1,469 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveEditor } from './editor.ts';
+import { packedExtensions, scannedExtensions } from './formats.ts';
+import {
+	BOOT_MANIFEST,
+	BOOT_MODULE,
+	BOOT_PCK,
+	FILES_DIR,
+	PACK_DIR,
+	PACK_DOC,
+	RELEASE,
+	descriptorOf,
+	entryId,
+	packEntries,
+	pckOf,
+	serializeDoc,
+	type Exports,
+	type PackDoc,
+	type Release,
+} from './pack.ts';
+
+// Bakes a Godot project's assets for the runtime. Two kinds of pack, both native `.pck`s (the
+// engine-converted binary resources + remap table) exported through the project's own committed
+// `export_presets.cfg`:
+//
+//  - **the boot pack**: the app's own sources (`src/`), exported with the preset, and always mounted
+//    by the runtime — a scene may load a path it assembles itself (a script named by a constant, a
+//    level chosen at run time), and only a mounted pack resolves those.
+//  - **content packs**: one per directory under `dlc/` that declares itself with a `package.json`.
+//    Each is exported on its own — the preset's `exclude_filter` is rewritten per pack, so a pack
+//    carries its own directory and nothing else — and carries the declared package fields plus the
+//    staging data the runtime needs, so it can be published and deployed apart from the app.
+//
+// A pack may reference the boot sources and the packs it declares as `dependencies`, never a sibling,
+// and the bake fails otherwise: the runtime mounts a pack by import, so a reference "upward" or
+// "sideways" is a reference that will not resolve.
+//
+// This is the bake half: everything that spawns the editor or touches the disk. What it writes is the
+// pack protocol's (`pack.ts`), which the plugin and the runtime read without any of this.
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** The dump's one build-time output, rewritten by every bake. */
+const DUMP = '.godot/pack-dump.json';
+
+export interface BuildAssetPackOptions {
+	/** The project root the bake reads and writes (default: `process.cwd()`). */
+	cwd?: string;
+	/** res:// roots whose assets the boot pack carries (default `['res://src']`). */
+	roots?: string[];
+	/** res:// root to discover content packs under (default `res://dlc`). */
+	dlc?: string;
+	/** Output directory for the packs + documents, project-relative (default {@link PACK_DIR}). */
+	out?: string;
+	/** The `export_presets.cfg` preset every pack exports with (default `Pack`). */
+	preset?: string;
+	/** Editor executable override (default: `resolveEditor()`). */
+	godot?: string;
+}
+
+/** A content pack: a directory that declares itself with a `package.json`. */
+interface ContentPack {
+	/** The declared package name (`@tiv/packs/assets`), or the directory's own name. */
+	name: string;
+	/** Project-relative directory, no trailing slash (`dlc/assets`). */
+	dir: string;
+	/** Declared version, if any. */
+	version?: string;
+	/** Declared pack dependencies: package name → version range. */
+	dependencies: Record<string, string>;
+	/** The declared `exports` verbatim: how the pack names the entries a client may load. */
+	exports?: Exports;
+}
+
+/** A `spawnSync` runner for the editor — the bake's one injected dependency. */
+export type Run = (args: string[], env?: Record<string, string>) => void;
+
+/**
+ * Bakes the boot pack, then one pack per directory under `dlc/` that declares a `package.json`.
+ * Three editor runs per pack (import, dump, export); no project file is left changed.
+ *
+ * `run` is the seam: the editor by default, a stand-in in a test — so what a caller gets (the
+ * documents, the products beside them, the preset put back) can be asserted through this interface
+ * rather than through the helpers it is made of. Everything else is the filesystem, which `opts.cwd`
+ * can point at any root.
+ */
+export async function buildAssetPacks(opts: BuildAssetPackOptions = {}, run?: Run): Promise<void> {
+	const cwd = opts.cwd ?? process.cwd();
+	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);
+	mkdirSync(resolve(cwd, out), { recursive: true });
+
+	// 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'), '');
+	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);
+	// Every scoped directory: the boot sources and the pack directories. A pack's export excludes all
+	// of them but its own, so no source can belong to two packs.
+	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 {
+		// **One dump for the whole project**, sliced per scope below (a loose file is staged by the pack
+		// 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`);
+
+		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}`;
+			mkdirSync(resolve(cwd, dir), { recursive: true });
+			const own = manifestOf(dump, cwd, dir, [pack.dir]);
+			const entries = packEntries(pack.exports);
+			const allowed = [...bootRoots, ...Object.keys(pack.dependencies).map((dep) => resPath(dirOf.get(dep) ?? dep))];
+			assertRefs(pack.name, own.external, allowed);
+			exportPack(ctx, [pack.dir], `${dir}/${pckOf(pack.name)}`);
+			writeFileSync(
+				resolve(cwd, dir, PACK_DOC),
+				serializeDoc({
+					// The pack's own declaration (`name`/`version`/`dependencies`/`exports`) plus what the
+					// bake computed: the same document shape the boot pack's is, so a client reads one. The
+					// `.pck` is `<name>.pck` beside it, by convention — mounting never waits on this document.
+					name: pack.name,
+					version,
+					dependencies: pack.dependencies,
+					exports: withoutTypes(pack.exports),
+					needs: own.needs,
+					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));
+			} else {
+				rmSync(types, { force: true });
+			}
+			console.log(`[pack] ${pack.name}@${version} over ${Object.keys(own.needs).length} sources`);
+		}
+		if (packs.length) {
+			writeFileSync(resolve(cwd, out, RELEASE), serializeDoc(release));
+		}
+	} finally {
+		// The preset is scoped per pack, so it is rewritten per export and put back once.
+		writeFileSync(presets, cfg);
+	}
+}
+
+/** The bake's shared context: the runner, the project, the preset, and every scoped directory. */
+interface Bake {
+	run: Run;
+	cwd: string;
+	cfg: string;
+	preset: string;
+	base: string[];
+	all: string[];
+	/** The converter's output root, which a plan's routes are relative to. */
+	planBase: string;
+}
+
+/** Scopes the preset to `mine` and exports that scope to `pck`. */
+function exportPack(ctx: Bake, mine: string[], pck: string): void {
+	writeFileSync(resolve(ctx.cwd, 'export_presets.cfg'), withExcludes(ctx.cfg, ctx.preset, excludesFor(ctx.base, ctx.all, mine)));
+	ctx.run(['--headless', '--path', '.', '--export-pack', ctx.preset, pck]);
+}
+
+/**
+ * One scope's half of the dump, as a document's `needs`/`stage` (and the refs the bake checks). A pack's
+ * export carries its own directory and nothing else, so `needs` — what each source under `dirs` needs
+ * staged — is that scope's slice, while `stage` — the descriptor of each loose file it *owns* — is
+ * judged over the **whole project**: a level's sky lives in the shared pack and is named by nothing but
+ * the level's plan, and the owner stages it all the same. `needs` stays paths (whoever owns them),
+ * which is what lets a pack borrow another's texture without carrying its bytes. `external` is what the
+ * scope's sources leak, for the ref check.
+ */
+function manifestOf(
+	dump: Record<string, Dumped>,
+	cwd: string,
+	dir: string,
+	dirs: string[],
+): Pick<PackDoc, 'needs' | 'stage'> & { external: string[] } {
+	const roots = dirs.map((d) => resPath(d));
+	const needs: Record<string, string[]> = {};
+	const external: string[] = [];
+	for (const [source, d] of Object.entries(dump)) {
+		if (!roots.some((root) => source.startsWith(`${root}/`))) continue;
+		if (d.loose.length) needs[source] = d.loose;
+		external.push(...d.external);
+	}
+	const stage: Record<string, { path: string; import: string }> = {};
+	for (const loose of new Set(Object.values(dump).flatMap((d) => d.loose))) {
+		// Only this scope's own: a borrowed loose file is staged from the pack that owns it, so carrying
+		// a copy would make every level ship the shared textures — exactly what deploying a level on its
+		// own must not do.
+		if (!roots.some((root) => loose.startsWith(`${root}/`))) continue;
+		const abs = resolve(cwd, rel(loose));
+		if (!existsSync(`${abs}.import`)) continue;
+		const descriptor = descriptorOf(readFileSync(`${abs}.import`, 'utf8'));
+		if (!descriptor || !existsSync(resolve(cwd, rel(descriptor.path)))) continue;
+		mkdirSync(resolve(cwd, dir, FILES_DIR), { recursive: true });
+		copyFileSync(resolve(cwd, rel(descriptor.path)), resolve(cwd, dir, FILES_DIR, descriptor.path.split('/').pop()!));
+		stage[loose] = descriptor;
+	}
+	return { needs, stage, external: [...new Set(external)].sort() };
+}
+
+/** A `spawnSync` runner that throws on a non-zero editor exit. */
+function runner(editor: string, cwd: string): Run {
+	return (args, env) => {
+		const r = spawnSync(editor, args, { cwd, stdio: 'inherit', env: { ...process.env, ...env } });
+		if ((r.status ?? 1) !== 0) {
+			throw new Error(`godot-assets: \`${editor} ${args.join(' ')}\` failed (${r.status})`);
+		}
+	};
+}
+
+/** One bucket of the dump: the loose textures a source needs, and the refs that left the scan roots. */
+interface Dumped {
+	loose: string[];
+	external: string[];
+}
+
+/** Runs `dump-deps.gd` over `scope` (res:// roots): per source, its loose textures and its leaks. */
+function runDump(ctx: Bake, scope: string[]): Record<string, Dumped> {
+	copyFileSync(resolve(HERE, 'dump-deps.gd'), resolve(ctx.cwd, '.godot', 'pack-dump-deps.gd'));
+	ctx.run(['--headless', '--path', '.', '--script', 'res://.godot/pack-dump-deps.gd'], {
+		GODOT_DUMP_OUT: resPath(DUMP),
+		GODOT_DUMP_ROOTS: scope.join(','),
+		GODOT_DUMP_PLAN_BASE: ctx.planBase,
+		// The dump holds no extension lists of its own: they come from the format table, so a source
+		// cannot be walked by the dump and staged by the plugin for want of one entry.
+		GODOT_DUMP_PACKED: packedExtensions.join(','),
+		GODOT_DUMP_SCANNED: scannedExtensions.join(','),
+	});
+	const abs = resolve(ctx.cwd, DUMP);
+	if (!existsSync(abs)) throw new Error(`godot-assets: the dump wrote no ${DUMP} (see dump-deps.gd).`);
+	return JSON.parse(readFileSync(abs, 'utf8')) as Record<string, Dumped>;
+}
+
+const resPath = (rel: string) => `res://${rel.replace(/^res:\/\//, '')}`;
+const rel = (res: string) => res.replace(/^res:\/\//, '').replace(/\/+$/, '');
+
+/** Fails the bake on a reference that leaves the pack (a sibling, or a source no pack owns). */
+function assertRefs(what: string, external: string[], allowed: string[]): void {
+	const illegal = external.filter((ref) => !allowed.some((dir) => ref.startsWith(`${dir}/`)));
+	if (illegal.length) {
+		throw new Error(
+			`godot-assets: ${what} references ${illegal.length} source(s) outside itself and ${allowed.join(', ')} — a pack's refs point at the boot sources or a declared dependency:\n  ${illegal.slice(0, 10).join('\n  ')}`,
+		);
+	}
+}
+
+/**
+ * Finds the content packs under `rootAbs` (searching the subdirectory `under`, so the returned `dir`s
+ * are `rootAbs`-relative): every directory holding a `package.json`, identified by that file's `name`.
+ * Packs do not nest — a pack inside a pack could not be scoped to one export — and a directory holding
+ * one is a container, so stray files beside it belong to no pack.
+ */
+function discoverPacks(rootAbs: string, under = ''): ContentPack[] {
+	const dirs: string[] = [];
+	walk(rootAbs, under, dirs);
+	const packs: ContentPack[] = [];
+	for (const dir of dirs.sort()) {
+		const parent = packs.find((pack) => dir.startsWith(`${pack.dir}/`));
+		if (parent) throw new Error(`godot-assets: ${dir}/ is inside the pack ${parent.dir} — packs do not nest.`);
+		if (!dir) throw new Error('godot-assets: the discovery root itself declares a package.json.');
+		const pkg = JSON.parse(readFileSync(join(rootAbs, dir, 'package.json'), 'utf8')) as {
+			name?: string;
+			version?: string;
+			dependencies?: Record<string, string>;
+			exports?: Exports;
+		};
+		packs.push({
+			name: pkg.name ?? dir.split('/').pop()!,
+			dir,
+			...(pkg.version ? { version: pkg.version } : {}),
+			dependencies: pkg.dependencies ?? {},
+			// Passed through verbatim: the declaration is what a client resolves an entry against, so
+			// the bake copies it rather than restating it (a client reads it through the entry's
+			// `godot` condition).
+			exports: pkg.exports,
+		});
+	}
+	return packs;
+}
+
+/** Collects every directory (relative, `/`-separated) under `rootAbs` that holds a `package.json`. */
+function walk(rootAbs: string, dir: string, out: string[]): void {
+	const abs = dir ? join(rootAbs, dir) : rootAbs;
+	let names: string[];
+	try {
+		names = readdirSync(abs);
+	} catch {
+		return;
+	}
+	if (names.includes('package.json')) out.push(dir);
+	for (const name of names) {
+		if (name.startsWith('.') || name === 'node_modules') continue;
+		if (statSync(join(abs, name)).isDirectory()) walk(rootAbs, dir ? `${dir}/${name}` : name, out);
+	}
+}
+
+/**
+ * The release a local bake serves, in the shape `parseRelease` reads: pack name → the version it just
+ * wrote and the dependencies it declared. A deploy publishes the same graph (resolved by `bun install`
+ * into a lockfile) under one immutable name, which is the only thing that identifies a content release.
+ */
+function releaseOf(packs: ContentPack[]): Release {
+	return Object.fromEntries(
+		packs.map((pack) => [pack.name, { version: pack.version ?? '0.0.0', deps: Object.keys(pack.dependencies) }]),
+	);
+}
+
+/**
+ * The boot pack as a module the app's bundle imports (beside the packs it describes): its `.pck`
+ * mounted once, however many modules import this, and the same `needs`/`stage` — with each loose
+ * product it owns imported as a file, so its URL is the bundle's. A content pack may need one, and the
+ * boot is mounted like any other pack, so its files belong in a client's staging lookup. Only the app
+ * can name those URLs, which is why the bake renders them here.
+ */
+function bootModule({ needs, stage }: Pick<PackDoc, 'needs' | 'stage'>): string {
+	const imports: string[] = [];
+	const files: string[] = [];
+	for (const descriptor of Object.values(stage)) {
+		const name = descriptor.path.split('/').pop()!;
+		imports.push(`import file${files.length} from ${JSON.stringify(`./${FILES_DIR}/${name}`)} with { type: 'file' };`);
+		files.push(`\t${JSON.stringify(name)}: file${files.length},`);
+	}
+	return (
+		[
+			"// Generated by `godot pack`: the app's own pack, as a module (see @ringozz/godot/preload).",
+			`import bootPck from ${JSON.stringify(`./${BOOT_PCK}`)} with { type: 'file' };`,
+			`import { configurePacks, loadAssetPack } from '@ringozz/godot/load';`,
+			...imports,
+			files.length ? `const bootFiles = {\n${files.join('\n')}\n};` : 'const bootFiles = {};',
+			`configurePacks({ boot: { pck: bootPck, doc: ${JSON.stringify({ needs, stage })}, url: (file) => bootFiles[file] } });`,
+			`export const mounting = loadAssetPack(bootPck);`,
+		].join('\n') + '\n'
+	);
+}
+
+/**
+ * A pack's type surface, emitted beside the declaration that names it (`types` in its own
+ * `package.json`): one typed export per declared entry, so importing the module the plugin serves is
+ * type-checked with no generated module — `packEntries` resolves each entry, exactly as the served
+ * module's is. The bake's, not the protocol's: it writes it.
+ */
+export function packTypes(exports: Exports): string {
+	const entries = packEntries(exports);
+	const classes = [...new Set(entries.map((e) => e.cls))];
+	return [
+		"// Generated by `godot pack` from the pack's `exports` — do not edit.",
+		...classes.map((cls) => `import type { ${cls} } from '@ringozz/godot/${cls}';`),
+		'',
+		...entries.map((e) => `export declare const ${entryId(e.entry)}: Promise<${e.cls}>;`),
+		'',
+	].join('\n');
+}
+
+/**
+ * A pack's declared `exports` minus its `types` condition. The document is emitted beside the `.pck`,
+ * while the declarations a pack's `types` names stay in its source directory (the bake writes them
+ * there), so the path would not resolve from the document and nothing reads it — `packEntries` reads
+ * the `godot` condition. A subpath left with no conditions goes with it: the document says what a
+ * client may resolve.
+ */
+function withoutTypes(exports: Exports): Exports {
+	if (!exports) return exports;
+	const declared: Record<string, string | { [condition: string]: string | undefined }> = {};
+	for (const [subpath, value] of Object.entries(exports)) {
+		if (typeof value !== 'object') {
+			declared[subpath] = value;
+			continue;
+		}
+		const conditions = Object.fromEntries(Object.entries(value).filter(([condition]) => condition !== 'types'));
+		if (Object.keys(conditions).length) declared[subpath] = conditions;
+	}
+	return declared;
+}
+
+/**
+ * The bake's scopes must not overlap. Each pack's export excludes every *other* scoped directory, so a
+ * boot root that contains a pack would exclude that pack's own files from its own export — an empty
+ * pack, which shows up much later as a scene whose assets are missing. The mistake is easy to make
+ * (`--roots res://src,res://dlc` when the packs live under `dlc/`), so the bake says so instead.
+ */
+function assertScopes(bootDirs: string[], packs: ContentPack[]): void {
+	for (const pack of packs) {
+		const root = bootDirs.find((dir) => pack.dir.startsWith(`${dir}/`));
+		if (root) {
+			throw new Error(
+				`godot-assets: the boot root ${root} contains the content pack ${pack.dir} — the boot pack would carry it and the pack's own export would exclude it. Point --roots at sources only: a pack's directory is its own export.`,
+			);
+		}
+	}
+}
+
+/**
+ * A pack's `exclude_filter`: the preset's own entries plus a glob per scoped directory that is not
+ * `mine` — so the export carries this pack and nothing else.
+ */
+function excludesFor(base: string[], all: string[], mine: string[]): string[] {
+	return [...base, ...all.filter((dir) => !mine.includes(dir)).map((dir) => `${dir}/*`)];
+}
+
+/** A preset block's `exclude_filter` entries. */
+function excludeFilter(cfg: string): string[] {
+	const line = /^exclude_filter="([^"]*)"/m.exec(cfg);
+	return (line?.[1] ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+/** The config with the preset named `preset`'s `exclude_filter` replaced by `exclude`. */
+function withExcludes(cfg: string, preset: string, exclude: string[]): string {
+	const at = new RegExp(`^name=${JSON.stringify(preset)}$`, 'm').exec(cfg)?.index ?? -1;
+	if (at < 0) {
+		throw new Error(`godot-assets: no "${preset}" preset in export_presets.cfg (see export_presets.example.cfg).`);
+	}
+	const line = /^exclude_filter="[^"]*"$/m.exec(cfg.slice(at));
+	if (!line) throw new Error(`godot-assets: the "${preset}" preset has no exclude_filter.`);
+	const start = at + line.index;
+	return `${cfg.slice(0, start)}exclude_filter=${JSON.stringify(exclude.join(','))}${cfg.slice(start + line[0].length)}`;
+}
+
+/** Parses `godot pack` CLI args into {@link BuildAssetPackOptions}. */
+export function parsePackArgs(args: string[]): BuildAssetPackOptions {
+	const opt = (flag: string): string | undefined => {
+		const i = args.indexOf(flag);
+		return i >= 0 ? args[i + 1] : undefined;
+	};
+	return {
+		roots: opt('--roots')?.split(',').filter(Boolean),
+		dlc: opt('--dlc'),
+		out: opt('--out'),
+		preset: opt('--preset'),
+		godot: opt('--godot'),
+	};
+}