@ringozz/godot 4.7.2-659 → 4.7.2-664

package/src/pack.ts

@@ -2,261 +2,320 @@
  Copyright (c) Vladimir Davidovich. All rights reserved.
 ***********************************************************************/
 
-import { spawnSync } from 'node:child_process';
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { resolveEditor } from './editor.ts';
-import { mergePlanRefs, planRefs } from './planRefs.ts';
-
-// Bakes a Godot project's assets for the runtime: imports them, then exports one native
-// `.pck` **per scene** plus a shared one, so a host fetches the shared data and only the
-// level it is playing. `dump-deps.gd` supplies both inputs (no host-side scanning): each
-// source's packed closure — which decides what a pack owns — and the loose (WebP-backed)
-// texture sources, which the host stages and transcodes per file.
+// The pack protocol: the document a bake emits for every pack, the names that document and its pack are
+// written and read under, the entries a pack declares, and the resolution that turns one entry into the
+// packs to mount and the loose files to stage before it is loaded. Three callers speak it — the bake
+// (`bake.ts`, which writes the documents), the preload plugin (which reads them at build time to serve
+// a pack's module) and the runtime loader (which fetches them) — so the shapes live here once instead of
+// being re-spelled by each of them.
 //
-// The result the runtime reads is one file beside the packs: `<out>/packs.json`, holding
-// each pack (its path, whether it mounts always, and the sources it owns) plus those loose
-// texture lists. `preload.ts` reads it to mount the right packs per asset.
-//
-// The project owns `export_presets.cfg` (a committed, editor-managed file), and the scoping
-// has to live there: `--export-pack` runs against a preset. Per-pack scoping is therefore an
-// `exclude_filter` — the repo's `all_resources` convention, which ignores `include_filter`
-// and, unlike the selected modes, never pulls dependencies back in — so each pack excludes
-// exactly the sources the others own (see `splitPacks`). Those presets are cloned from the
-// project's own base preset, one written at a time, and the file is restored when the bake
-// ends: they are derived and the file is tracked.
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-
-/** The dump's one build-time output, merged into the manifest beside the packs. */
-const DUMP = '.godot/pack-dump.json';
-
-export interface BuildAssetPackOptions {
-	/** res:// roots whose assets are baked (default `['res://src']`). */
-	roots?: string[];
-	/** Output directory for the packs + manifest, project-relative (default `.godot/packs`). */
-	out?: string;
-	/** The `export_presets.cfg` preset the generated pack presets derive from (default `Pack`). */
-	preset?: string;
-	/** Editor executable override (default: `resolveEditor()`). */
-	godot?: string;
+// Nothing here touches the filesystem, the editor or the engine. A document arrives as text, and a
+// resolved file names the pack that owns its product rather than a URL: how a pack's bytes are
+// addressed — fetched over the network, bundled beside the app, or read off the disk — belongs to the
+// caller doing the I/O, which is also the only caller that knows which of the three it is.
+
+import { classOf } from './formats.ts';
+
+/** One pack in a release: the version to mount, and its declared dependencies by pack name. */
+export interface ReleasePack {
+	version: string;
+	deps: string[];
+}
+
+/** A release: pack name → what to mount. */
+export type Release = Record<string, ReleasePack>;
+
+/** A `bun.lock` package entry: `[name@version, registry, { dependencies? }, "sha512-…"]`. */
+type LockEntry = [string, string, { dependencies?: Record<string, string>; optionalDependencies?: Record<string, string> }?, ...unknown[]];
+
+/**
+ * Parses a release document: a `bun.lock` (whose `packages` map is flattened to one entry per name,
+ * with the dependency *names* as its edges) or an explicit `{ name: { version, deps } }` map. The
+ * edges are names, not ranges: the lockfile already chose one version per name, so nothing here has to
+ * resolve semver. Throws on anything else — a document this can't read would mount nothing and show up
+ * as missing assets.
+ */
+export function parseRelease(text: string): Release {
+	const doc = JSON.parse(text.replace(/,\s*([}\]])/g, '$1')) as Record<string, unknown>;
+	const packages = doc.packages as Record<string, LockEntry> | undefined;
+	if (packages) {
+		const release: Release = {};
+		for (const [name, entry] of Object.entries(packages)) {
+			if (!Array.isArray(entry) || typeof entry[0] !== 'string') continue;
+			const at = entry[0].lastIndexOf('@');
+			release[name] = { version: at > 0 ? entry[0].slice(at + 1) : entry[0], deps: depsOf(entry) };
+		}
+		if (!Object.keys(release).length) throw new Error('godot-assets: the release document has no packages.');
+		return release;
+	}
+	const values = Object.values(doc);
+	if (values.length && values.every(isPack)) {
+		return Object.fromEntries(
+			Object.entries(doc).map(([name, pack]) => [
+				name,
+				{ version: (pack as ReleasePack).version, deps: (pack as ReleasePack).deps ?? [] },
+			]),
+		);
+	}
+	throw new Error('godot-assets: unrecognized release document (expected a bun.lock or a name → {version, deps} map).');
 }
 
-/** A pack's assignment: its name, whether it mounts always, and the sources it owns. */
-interface AssetPackSplit {
-	/** `shared`, or a scene's file stem. */
-	name: string;
-	/** Mount for every asset (the shared pack). */
-	always?: boolean;
-	/** The packable sources this pack owns — the lookup the plugin mounts by. */
-	owns: string[];
+/** A value shaped like a {@link ReleasePack}. */
+function isPack(value: unknown): boolean {
+	return !!value && typeof value === 'object' && typeof (value as ReleasePack).version === 'string';
 }
 
-/** One baked pack as the runtime sees it. */
-interface AssetPackManifestEntry extends AssetPackSplit {
-	/** `res://` path of the `.pck`, for `loadAssetPack`. */
-	pck: string;
+/** A lock entry's dependency *names* — the lockfile already chose one version per name. */
+function depsOf(entry: LockEntry): string[] {
+	return Object.keys(entry[2]?.dependencies ?? entry[2]?.optionalDependencies ?? {});
 }
 
-/** The runtime manifest beside the packs: what to mount, and what to stage per file. */
-export interface AssetPackManifest {
-	packs: AssetPackManifestEntry[];
-	/** Packed source → the loose texture sources it needs at runtime (from `dump-deps.gd`). */
-	deps: Record<string, string[]>;
+/** The packs to mount for `entry`: the pack itself, then every pack its dependencies reach (depth first). */
+export function mountClosure(release: Release, entry: string): string[] {
+	if (!release[entry]) throw new Error(`godot-assets: the release has no pack ${entry}.`);
+	const out: string[] = [];
+	const seen = new Set<string>();
+	const visit = (name: string) => {
+		if (seen.has(name)) return;
+		const pack = release[name];
+		if (!pack) throw new Error(`godot-assets: the release has no pack ${name} (a declared dependency).`);
+		seen.add(name);
+		out.push(name);
+		for (const dep of pack.deps) visit(dep);
+	};
+	visit(entry);
+	return out;
 }
 
-/** Each packed source's packed closure, as `dump-deps.gd` reports it. */
-interface Graph {
-	[source: string]: string[];
+/** 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 two build-time outputs of `dump-deps.gd`. */
-interface Dump {
-	graph: Graph;
-	deps: Record<string, string[]>;
+/** 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. */
+export function pckOf(name: string): string {
+	return `${name.split('/').pop()}.pck`;
 }
 
+// The names a pack is written and read under, shared by the bake (the writer) and its readers (the
+// preload plugin and the runtime loader).
+
 /**
- * The ownership partition, from the dependency graph. A **level is a scene** (`.tscn`) among
- * the scanned sources — a project's levels are its scenes, so nothing declares them — and:
- * **a source exactly one scene reaches is that scene's** (so a model only one level uses
- * rides its pack, though it lives in a shared asset tree), while **a source several scenes
- * reach, or none does, is shared**. A scene whose own pack would be empty is dropped: every
- * source it reaches is reached by another scene too, so it is already in `shared`, and a pack
- * is mounted by *owner*.
- *
- * The graph it reads is the dump's *plus* every level's plan refs (`mergePlanRefs`), so a level's
- * terrain, its layered containers and their layers, and its ground/environment textures are part of
- * its closure whether or not a baked scene names them. When a project stops baking one scene per
- * level — a level built from its plan at run time is a single shared scene plus the plan — the level
- * unit becomes the `.gltfx` its plan lives in instead; until then both units exist and this keying
- * keeps the scenes.
+ * A pack's document, beside its `.pck`. Not `package.json`: that is the pack's own manifest in its
+ * source directory — an input the bake reads to discover a pack — and one string naming both an input
+ * and an output is one string nobody can read unambiguously.
  */
-export function splitPacks(graph: Graph): AssetPackSplit[] {
-	const stem = (asset: string) =>
-		asset.slice(asset.lastIndexOf('/') + 1).replace(/\.(prefab|level)\.[^.]+$/i, '').replace(/\.[^.]+$/, '');
-	// A level is its scene — and, in a project that builds levels from their plans at run time, the
-	// `.gltfx` its plan lives in. A `.gltfx` a scene **reaches** is that scene's composition, not a
-	// second level: keying both would make every source of a baked level look shared.
-	const scenes = Object.keys(graph).filter((s) => s.toLowerCase().endsWith('.tscn')).sort();
-	const reachedByScene = new Set(scenes.flatMap((s) => graph[s] ?? []));
-	const levels = [
-		...scenes,
-		...Object.keys(graph).filter((s) => s.toLowerCase().endsWith('.gltfx') && !reachedByScene.has(s)),
-	].sort();
-	const closure = new Map(levels.map((s) => [s, new Set([s, ...(graph[s] ?? [])])]));
-
-	// One pack per level, named after its file stem (`shared` is reserved; a repeated stem —
-	// two `level.tscn` in different directories — gets a suffix).
-	const used = new Set(['shared']);
-	const packOf = new Map<string, AssetPackSplit>();
-	for (const level of levels) {
-		let name = stem(level);
-		for (let n = 2; used.has(name); n++) name = `${stem(level)}-${n}`;
-		used.add(name);
-		packOf.set(level, { name, owns: [] });
-	}
+export const PACK_DOC = 'pack.json';
 
-	const shared: string[] = [];
-	const sources = new Set([...Object.keys(graph), ...Object.values(graph).flat()]);
-	for (const source of sources) {
-		const owners = levels.filter((level) => closure.get(level)!.has(source));
-		if (owners.length === 1) packOf.get(owners[0])!.owns.push(source);
-		else shared.push(source);
-	}
-	shared.sort();
-	return [
-		{ name: 'shared', always: true, owns: shared },
-		...[...packOf.values()]
-			.filter((pack) => pack.owns.length > 0)
-			.map((pack) => ({ ...pack, owns: pack.owns.sort() })),
-	];
+/** The release document: which version of which pack a client mounts. */
+export const RELEASE = 'release.json';
+
+/** A pack's directory of loose products, beside its document. */
+export const FILES_DIR = 'files';
+
+/** The bake's output directory, project-relative, unless {@link PACK_DIR_ENV} names another. */
+export const PACK_DIR = '.godot/packs';
+
+/** The environment variable that overrides {@link PACK_DIR}. */
+export const PACK_DIR_ENV = 'GODOT_PACKS';
+
+/** The boot pack's `.pck`, in the bake's output directory. */
+export const BOOT_PCK = 'boot.pck';
+
+/** The boot pack's document — the `needs`/`stage` every document carries, for the bake's own pack. */
+export const BOOT_MANIFEST = 'packs.json';
+
+/** The generated module an app's bundle imports for the boot pack (`{ mounting }` + its config). */
+export const BOOT_MODULE = 'boot-pack.js';
+
+/**
+ * One pack, as a document: what the pack **declares** (`name`/`version`/`dependencies`/`exports` — its
+ * own `package.json`) plus the `needs`/`stage` a client stages from. Both kinds of pack carry the
+ * *same* document: a content pack's is emitted beside its `.pck`, the boot pack's is `<out>/packs.json`.
+ * So the bake's writer, the preload plugin's build-time read and the runtime's fetch all read one
+ * shape.
+ */
+export interface PackDoc {
+	/** Declared package name (the boot pack is the app's own, and declares none). */
+	name?: string;
+	/** Declared version (the release pins the one a client mounts). */
+	version?: string;
+	/** Declared dependencies: package name → version range. */
+	dependencies?: Record<string, string>;
+	/** Declared entries verbatim — a subpath → its conditions, one of which is `godot`. */
+	exports?: Exports;
+	/** Packed source → the loose files it needs (paths, whoever owns them). */
+	needs: Record<string, string[]>;
+	/** A loose source this pack owns → the sidecar text and the product it remaps to. */
+	stage: Record<string, { path: string; import: string }>;
 }
 
+/** A package manifest's `exports`, as far as this project reads it: a subpath → its conditions. */
+export type Exports = Record<string, string | { [condition: string]: string | undefined }> | undefined;
+
 /**
- * Bakes the packs (see {@link splitPacks}) and writes the runtime manifest. A project with no
- * scene under its roots gets a single `shared.pck` and the same manifest.
+ * A pack document, validated: its manifest half (`needs`/`stage`) must be there — a document without
+ * one would stage nothing and show up much later as missing assets. `null` when it isn't a pack.
  */
-export async function buildAssetPacks(opts: BuildAssetPackOptions = {}): Promise<void> {
-	const editor = opts.godot ?? (await resolveEditor());
-	const cwd = process.cwd();
-	const roots = opts.roots ?? ['res://src'];
-	const out = opts.out ?? '.godot/packs';
-	const base = opts.preset ?? 'Pack';
-	const prefix = `${base}: `;
-	const presets = resolve(cwd, 'export_presets.cfg');
-
-	const cfg = readFileSync(presets, 'utf8');
-	const basePreset = presetBlock(cfg, base);
-	const baseExcludes = excludeFilter(basePreset);
-	mkdirSync(resolve(cwd, out), { recursive: true });
-
-	const run = runner(editor, cwd);
-	run(['--headless', '--path', '.', '--import']);
-	const { graph, deps } = dump(run, cwd, roots);
-	// A level's plan names what no scene does any more — its terrain directory, its layered containers
-	// and their layers, its ground/environment textures (`planRefs`). Merged here so the graph and the
-	// loose lists carry the level's whole closure with or without a baked scene.
-	mergePlanRefs(graph, deps, planRefs(cwd, roots));
-
-	const packs = splitPacks(graph);
-	const owned = packs.flatMap((pack) => pack.owns);
-	const manifest: AssetPackManifestEntry[] = [];
-
-	// The project's own presets, with any this tool generated in an earlier run dropped.
-	const original = pruneGenerated(cfg, prefix);
-	const index = (original.match(/^\[preset\.\d+\]/gm) ?? []).length;
-	try {
-		for (const { name, always, owns } of packs) {
-			const exclude = [
-				...baseExcludes,
-				...owned.filter((source) => !owns.includes(source)).map((source) => source.replace(/^res:\/\//, '')),
-			];
-			writeFileSync(presets, `${original.trimEnd()}\n\n${presetFor(basePreset, index, `${prefix}${name}`, exclude)}\n`);
-			const pck = `${out}/${name}.pck`;
-			run(['--headless', '--path', '.', '--export-pack', `${prefix}${name}`, pck]);
-			manifest.push({ name, pck: resPath(pck), ...(always ? { always } : {}), owns });
-		}
-	} finally {
-		// Derived — leave the project's own file as it was, so a bake does not churn a tracked,
-		// editor-managed file.
-		writeFileSync(presets, original);
-	}
-	writeFileSync(resolve(cwd, out, 'packs.json'), `${JSON.stringify({ packs: manifest, deps } satisfies AssetPackManifest, null, '\t')}\n`);
-	console.log(`[pack] ${manifest.length} packs (${manifest.map((p) => `${p.name}:${p.owns.length}`).join(', ')}) over ${owned.length} sources`);
+function packDoc(document: unknown): PackDoc | null {
+	const doc = document as PackDoc | null;
+	return doc && doc.needs && doc.stage ? doc : null;
 }
 
-/** A `spawnSync` runner that throws on a non-zero editor exit. */
-function runner(editor: string, cwd: string) {
-	return (args: string[], env?: Record<string, string>) => {
-		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})`);
-		}
-	};
+/** A document's text, as the shape it is: throws when the text is not a pack document. */
+export function parseDoc(text: string): PackDoc {
+	const doc = packDoc(JSON.parse(text) as unknown);
+	if (!doc) throw new Error('godot-assets: the document carries no manifest half (`needs`/`stage`).');
+	return doc;
 }
 
-/** Runs `dump-deps.gd` and splits its output into the graph and the loose-texture lists. */
-function dump(run: (args: string[], env?: Record<string, string>) => void, cwd: string, roots: string[]): Dump {
-	copyFileSync(resolve(HERE, 'dump-deps.gd'), resolve(cwd, '.godot', 'pack-dump-deps.gd'));
-	run(['--headless', '--path', '.', '--script', 'res://.godot/pack-dump-deps.gd'], {
-		GODOT_DUMP_OUT: resPath(DUMP),
-		GODOT_DUMP_ROOTS: roots.join(','),
-	});
-	const abs = resolve(cwd, DUMP);
-	if (!existsSync(abs)) throw new Error(`godot-assets: the dump wrote no ${DUMP} (see dump-deps.gd).`);
-	const sources = JSON.parse(readFileSync(abs, 'utf8')) as Record<string, { packed: string[]; loose: string[] }>;
-	const entries = Object.entries(sources);
-	return {
-		graph: Object.fromEntries(entries.map(([source, s]) => [source, s.packed])),
-		deps: Object.fromEntries(entries.map(([source, s]) => [source, s.loose])),
-	};
+/** A document as it is written: one tab-indented JSON document, with a trailing newline. */
+export function serializeDoc(value: PackDoc | Release): string {
+	return `${JSON.stringify(value, null, '\t')}\n`;
 }
 
-const resPath = (rel: string) => `res://${rel.replace(/^res:\/\//, '')}`;
+/**
+ * The `res://` path one declared entry names — the subpath's `godot` condition. A pack declares its
+ * entries once, in its `package.json`; the bake copies that declaration into the document it emits, so
+ * an entry resolves against the same statement the pack was built from. Internal: `resolveEntry` is
+ * how a client reaches it, and `packEntries` is the entry vocabulary's public face.
+ */
+function godotEntry(exports: Exports, entry: string): string | undefined {
+	const value = exports?.[`./${entry.replace(/^\.\//, '')}`];
+	return typeof value === 'object' ? value.godot : undefined;
+}
 
-/** The preset whose `name=` matches, as its raw `[preset.N]` … block (options included). */
-function presetBlock(cfg: string, name: string): string {
-	const m = new RegExp(`^name=${JSON.stringify(name)}$`, 'm').exec(cfg);
-	if (!m) throw new Error(`godot-assets: no "${name}" preset in export_presets.cfg (see export_presets.example.cfg).`);
-	const rest = cfg.slice(cfg.lastIndexOf('[preset.', m.index));
-	// The next *preset* header — not this one's `[preset.N.options]`.
-	const end = rest.search(/\n\[preset\.\d+\]/);
-	return (end < 0 ? rest : rest.slice(0, end)).trimEnd();
+/** One declared entry, resolved: its name, the `res://` path it names, and that path's class. */
+export interface PackEntry {
+	entry: string;
+	res: string;
+	cls: string;
 }
 
-/** A preset block's `exclude_filter` entries. */
-function excludeFilter(block: string): string[] {
-	const line = /^exclude_filter="([^"]*)"/m.exec(block);
-	return (line?.[1] ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+/**
+ * A pack's declared entries, each with the class its path loads as — the one rule a declared entry,
+ * the types emitted for it and the module the plugin serves all read (`FORMATS` by extension, so a
+ * `.tscn` is a `PackedScene` everywhere). Entries that name no asset are skipped: they exist to
+ * declare something else.
+ */
+export function packEntries(exports: Exports): PackEntry[] {
+	const entries: PackEntry[] = [];
+	for (const [subpath, declared] of Object.entries(exports ?? {})) {
+		const res = typeof declared === 'object' ? declared.godot : undefined;
+		const cls = res ? classOf(res) : undefined;
+		if (res && cls) entries.push({ entry: subpath.replace(/^\.\//, ''), res, cls });
+	}
+	return entries;
 }
 
-/** A pack's preset: the base preset's own (platform + options), renamed and re-excluded. */
-function presetFor(base: string, index: number, name: string, exclude: string[]): string {
-	return base
-		.replace(/^\[preset\.\d+\]/, `[preset.${index}]`)
-		.replace(/\[preset\.\d+\.options\]/, `[preset.${index}.options]`)
-		.replace(/^name="[^"]*"/m, `name=${JSON.stringify(name)}`)
-		.replace(/^exclude_filter="[^"]*"/m, `exclude_filter=${JSON.stringify(exclude.join(','))}`);
+/** An entry name as the identifier both the served module and its emitted types use (`my-level` → `my_level`). */
+export const entryId = (entry: string) => entry.replace(/[^A-Za-z0-9_$]/g, '_');
+
+/**
+ * A loose source's staging descriptor, read from its `.import` sidecar: the product it serves — the
+ * first `deps/dest_files` entry, or the single `[remap] path` an importer that writes only that serves
+ * it as — and the sidecar text itself. A client has no source tree to read either from, so the pack
+ * carries them. The bake and the preload plugin both walk a sidecar with this one rule, so a source
+ * can never stage in one place and not the other.
+ */
+export function descriptorOf(sidecar: string): { path: string; import: string } | null {
+	const dests = /^dest_files=\[([^\]]*)\]/m.exec(sidecar)?.[1];
+	const path = dests ? /"([^"]+)"/.exec(dests)?.[1] : /^path="([^"]+)"/m.exec(sidecar)?.[1];
+	return path ? { path, import: sidecar } : null;
 }
 
-/** Drops the presets this tool generated in an earlier run (so re-bakes are idempotent). */
-function pruneGenerated(cfg: string, prefix: string): string {
-	const generated = new RegExp(`^name="${prefix}[^"]*"$`, 'm');
-	return cfg.split(/(?=\[preset\.\d+\])/).filter((block) => !generated.test(block)).join('');
+/**
+ * The two files one loose source stages: the sidecar the engine looks for, and the product path it
+ * remaps to. Stated once because the bake (which emits a module's source) and the runtime (which builds
+ * the files a loader stages) both derive them from the same descriptor, and a rule told twice is a rule
+ * that can be told differently.
+ */
+export function stagedKeys(loose: string, descriptor: { path: string }): { sidecar: string; product: string } {
+	return { sidecar: `${loose}.import`, product: descriptor.path };
 }
 
-/** 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),
-		out: opt('--out'),
-		preset: opt('--preset'),
-		godot: opt('--godot'),
+/**
+ * A file to stage before loading, keyed by `res://` path: a sidecar (`.import`) arrives as `content`
+ * (text), an imported product (`.ctex`/`.scn`) as `path` (fetched).
+ */
+export interface StagedFile {
+	content?: string;
+	path?: string;
+}
+
+/** The files one load stages, keyed by `res://` path. */
+export type StagedFiles = Record<string, StagedFile>;
+
+/**
+ * A declared entry, resolved: the packs to mount, the `res://` path it names, and the loose files to
+ * stage before loading it. Nothing here is a URL — addressing is the caller's.
+ */
+export interface ResolvedEntry {
+	/** The packs to mount, in mount order; version-addressed, so each is immutable and cacheable. */
+	mounts: Array<{ name: string; version: string }>;
+	/** The `res://` path the entry names. */
+	res: string;
+	/** What to stage before loading `res`: one entry per loose file the entry needs. */
+	files: Array<{
+		/** The sidecar's key — where the engine looks for it (`<loose>.import`) — and its text. */
+		sidecar: string;
+		content: string;
+		/** The product's key: the `res://` path it is looked up by. */
+		product: string;
+		/** The pack the product's bytes come from — its name, or `null` for the app's own pack, which declares none. */
+		pack: string | null;
+		/** The product's file name inside that pack. */
+		file: string;
+	}>;
+}
+
+/**
+ * Resolves one declared entry to what must happen before it loads: the release's closure with the
+ * version of each pack, the `res://` path the entry names, and the loose files that path needs, each
+ * owned by whichever mounted pack carries its product — the descriptor is looked up across the stated
+ * documents, so a pack borrows another's textures without carrying them. `boot` is the app's own pack,
+ * which declares no name and is staged from like any other.
+ */
+export function resolveEntry(
+	release: Release,
+	docs: Record<string, PackDoc>,
+	pack: string,
+	entry: string,
+	boot?: PackDoc,
+): ResolvedEntry {
+	const names = mountClosure(release, pack);
+	const own = docs[pack];
+	if (!own) throw new Error(`godot-assets: no document for ${pack}, which declares the entry.`);
+
+	// Ownership over the whole mounted set: the app's own pack last, so it wins where both own a file.
+	const owned = new Map<string, { path: string; import: string; pack: string | null; file: string }>();
+	const claim = (doc: PackDoc, owner: string | null) => {
+		for (const [loose, descriptor] of Object.entries(doc.stage)) {
+			owned.set(loose, { ...descriptor, pack: owner, file: fileOf(descriptor.path) });
+		}
 	};
+	for (const name of names) {
+		const doc = docs[name];
+		if (!doc) throw new Error(`godot-assets: no document for ${name}, which the release mounts.`);
+		claim(doc, name);
+	}
+	if (boot) claim(boot, null);
+
+	const res = godotEntry(own.exports, entry);
+	if (!res) throw new Error(`godot-assets: ${pack} declares no entry ${entry}.`);
+	const files = (own.needs[res] ?? []).flatMap((loose) => {
+		const descriptor = owned.get(loose);
+		// A loose file no mounted pack owns is skipped, not staged as a dangling reference.
+		if (!descriptor) return [];
+		const { sidecar, product } = stagedKeys(loose, descriptor);
+		return [{ sidecar, content: descriptor.import, product, pack: descriptor.pack, file: descriptor.file }];
+	});
+	return { mounts: names.map((name) => ({ name, version: release[name].version })), res, files };
+}
+
+/** The file name a product path ends in — what a pack stages it under in its {@link FILES_DIR}. */
+function fileOf(path: string): string {
+	return path.split('/').pop()!;
 }