@driftengine/package 3.63.0 → 4.0.0

package/dist/native.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A game packaged for the native host: a Node, the game bundled with the host and the engine, the
+ * modules that cannot be bundled, the game's own files, a launcher and the licences, in one archive.
+ *
+ *     <executable>/              what the archive holds, and what a Steam depot uploads
+ *       <executable>             the launcher: the Node beside it, running the game
+ *       runtime/node             the Node that ran this build
+ *       app/game.mjs             the game, the host and the engine, bundled for Node
+ *       app/modules/             each module the bundle starts by URL: workers, the thread bootstrap
+ *       app/node_modules/        the modules that cannot be bundled, what they load, and the
+ *                                libraries a licence keeps replaceable
+ *       app/public/              the game's web build, which its `fetch` of a relative path reads
+ *       licenses/                Node's licence and every package's, with INDEX.txt
+ *     <name>-<version>-linux-x64.tar.gz
+ *
+ * **The runtime is the Node running this build**, as the desktop target ships the Electron that is
+ * installed: the artifact is made of what this machine has, so it is built on the machine it is for
+ * — Linux on x64 — and the binaries beside the host are this machine's too. **The host comes from
+ * the game's own tree**, at the packager's own version, because the host depends on the packager and
+ * a range back would be a build cycle; a game that never builds this target never downloads a
+ * native binary.
+ *
+ * **The entry is generated, not written by the game.** A game's native entry exports
+ * `mount(canvas)`; the generated one starts the host in the manifest's window, hands the game its
+ * files and its store — the file the desktop shell keeps under the same name, so a player moving
+ * between the two builds keeps their saves — and prints when the first frame reached the screen
+ * under `DRIFT_STARTUP_REPORT=1`, which is how the target's start is measured.
+ *
+ * **No copyleft library is bundled.** One under the LGPL stays a file of its own, as the Opus
+ * decoder's Ogg parser does (`LINKED_LIBRARIES`), with the GPL's text beside it, which that licence
+ * asks for; any other that would land in the bundle stops the build, naming it.
+ *
+ * What it gives up: the game's whole web build is copied to `public/`, its page and scripts
+ * included, where the game reads only its assets; and the archive is `.tar.gz`, made by the
+ * system's `tar`, with no installer and no desktop entry.
+ */
+import type { PackageManifest } from './manifest.ts';
+import { type FetchText } from './nativeLicenses.ts';
+export interface NativeOptions {
+    /** The Node the artifact ships, and its version; the one running this build by default. */
+    readonly node?: {
+        readonly path: string;
+        readonly version: string;
+    };
+    /** How Node's licence is fetched when no copy is on this machine. */
+    readonly fetchText?: FetchText;
+    /** Package conditions resolved before `default`: `drift-source` bundles the engine's source. */
+    readonly conditions?: readonly string[];
+}
+/** Why this machine cannot build the native target, or null. */
+export declare function nativeMachineRefusal(platform: string, arch: string): string | null;
+/** The version of this packager, which the host has to match. */
+export declare function packagerVersion(): string;
+/** The host's directory in the game's tree, at `version`, or a refusal naming the install. */
+export declare function nativeHost(cwd: string, version: string): string;
+/** The module the bundle starts from: the host, started on the game at `game`. */
+export declare function nativeEntrySource(manifest: PackageManifest, host: string, game: string): string;
+/** What the desktop shell does for this manifest that the native host does not. */
+export declare function nativeNotes(manifest: PackageManifest): string[];
+/**
+ * The launcher's name, and the archive's directory: the id's last label, which is also the name the
+ * desktop target's Linux build gives its executable (`stage.ts`). Reverse-DNS keeps it to letters,
+ * digits and hyphens.
+ */
+export declare function executableName(manifest: PackageManifest): string;
+/** Build the native artifact for `manifest` into `outDir`, and answer the archive's path. */
+export declare function buildNative(manifest: PackageManifest, cwd: string, outDir: string, options?: NativeOptions): Promise<string>;

package/dist/native.js

@@ -0,0 +1,212 @@
+/**
+ * A game packaged for the native host: a Node, the game bundled with the host and the engine, the
+ * modules that cannot be bundled, the game's own files, a launcher and the licences, in one archive.
+ *
+ *     <executable>/              what the archive holds, and what a Steam depot uploads
+ *       <executable>             the launcher: the Node beside it, running the game
+ *       runtime/node             the Node that ran this build
+ *       app/game.mjs             the game, the host and the engine, bundled for Node
+ *       app/modules/             each module the bundle starts by URL: workers, the thread bootstrap
+ *       app/node_modules/        the modules that cannot be bundled, what they load, and the
+ *                                libraries a licence keeps replaceable
+ *       app/public/              the game's web build, which its `fetch` of a relative path reads
+ *       licenses/                Node's licence and every package's, with INDEX.txt
+ *     <name>-<version>-linux-x64.tar.gz
+ *
+ * **The runtime is the Node running this build**, as the desktop target ships the Electron that is
+ * installed: the artifact is made of what this machine has, so it is built on the machine it is for
+ * — Linux on x64 — and the binaries beside the host are this machine's too. **The host comes from
+ * the game's own tree**, at the packager's own version, because the host depends on the packager and
+ * a range back would be a build cycle; a game that never builds this target never downloads a
+ * native binary.
+ *
+ * **The entry is generated, not written by the game.** A game's native entry exports
+ * `mount(canvas)`; the generated one starts the host in the manifest's window, hands the game its
+ * files and its store — the file the desktop shell keeps under the same name, so a player moving
+ * between the two builds keeps their saves — and prints when the first frame reached the screen
+ * under `DRIFT_STARTUP_REPORT=1`, which is how the target's start is measured.
+ *
+ * **No copyleft library is bundled.** One under the LGPL stays a file of its own, as the Opus
+ * decoder's Ogg parser does (`LINKED_LIBRARIES`), with the GPL's text beside it, which that licence
+ * asks for; any other that would land in the bundle stops the build, naming it.
+ *
+ * What it gives up: the game's whole web build is copied to `public/`, its page and scripts
+ * included, where the game reads only its assets; and the archive is `.tar.gz`, made by the
+ * system's `tar`, with no installer and no desktop entry.
+ */
+import { spawn } from 'node:child_process';
+import { readFileSync, realpathSync } from 'node:fs';
+import { chmod, copyFile, cp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { refuseLyingFilesystem } from './identity.js';
+import { bundleNative, NATIVE_MODULES } from './nativeBundle.js';
+import { copyPackages, findPackage, packageDirOf, runtimeClosure } from './nativeCopy.js';
+import { copyleftOf, nodeLicense, writeLicenses } from './nativeLicenses.js';
+import { consumerVersion } from './stage.js';
+const HERE = dirname(fileURLToPath(import.meta.url));
+const HOST = '@driftengine/native-host';
+/**
+ * What each copied module declares and does not load: the two bindings' install scripts download
+ * or build their binary with these, and at run time they load that binary and nothing else.
+ */
+const INSTALL_ONLY = {
+    '@kmamal/gpu': ['node-addon-api', 'node-gyp', 'tar'],
+    '@kmamal/sdl': ['tar'],
+};
+const LAUNCHER = `#!/bin/sh
+# Starts this game on DriftEngine's native host: the Node in runtime/ runs app/game.mjs.
+here=$(dirname "$(readlink -f "$0")")
+exec "$here/runtime/node" "$here/app/game.mjs" "$@"
+`;
+/** Why this machine cannot build the native target, or null. */
+export function nativeMachineRefusal(platform, arch) {
+    if (platform === 'linux' && arch === 'x64')
+        return null;
+    const which = platform === 'linux' ? `on ${arch}` : `on ${platform}`;
+    return (`native-linux-x64 ships the Node that builds it and the binaries installed beside the host, so ` +
+        `it is built on Linux on x64, and this is ${which}.`);
+}
+/** The version of this packager, which the host has to match. */
+export function packagerVersion() {
+    const manifest = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8'));
+    return manifest.version;
+}
+/** The host's directory in the game's tree, at `version`, or a refusal naming the install. */
+export function nativeHost(cwd, version) {
+    const dir = findPackage(HOST, cwd);
+    if (dir === null) {
+        throw new Error(`native-linux-x64 runs the game on ${HOST}, and ${cwd} does not have it. ` +
+            `\`npm install ${HOST}@${version}\` there. It is kept out of the packager so that a game ` +
+            'that never builds this target never downloads a native binary.');
+    }
+    const found = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+        .version;
+    if (found !== version) {
+        throw new Error(`${HOST} is ${found} in ${cwd} and this packager is ${version}; the host is the engine's ` +
+            `own code and has to be the same release. \`npm install ${HOST}@${version}\` there.`);
+    }
+    return dir;
+}
+/** The module the bundle starts from: the host, started on the game at `game`. */
+export function nativeEntrySource(manifest, host, game) {
+    const text = JSON.stringify;
+    return `import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { configDirectory, runGame } from ${text(host)};
+
+const here = dirname(fileURLToPath(import.meta.url));
+await runGame({
+  title: ${text(manifest.name)},
+  width: ${text(manifest.window.width)},
+  height: ${text(manifest.window.height)},
+  mode: ${text(manifest.window.mode)},
+  resizable: ${text(manifest.window.resizable)},
+  publicDir: join(here, 'public'),
+  storePath: join(configDirectory(), ${text(manifest.name)}, 'store.json'),
+  startupReport: process.env.DRIFT_STARTUP_REPORT === '1',
+  load: () => import(${text(game)}),
+});
+`;
+}
+/** What the desktop shell does for this manifest that the native host does not. */
+export function nativeNotes(manifest) {
+    const notes = [];
+    if (manifest.splash.show) {
+        notes.push('no engine badge: the desktop shell shows it in a window of its own and a page draws it as ' +
+            'markup, and the host draws only the game');
+    }
+    if (manifest.steam.appId !== null) {
+        notes.push(`steam.appId is ${manifest.steam.appId} and the host has no store: achievements, presence ` +
+            'and cloud saves are absent from this build');
+    }
+    return notes;
+}
+/**
+ * The launcher's name, and the archive's directory: the id's last label, which is also the name the
+ * desktop target's Linux build gives its executable (`stage.ts`). Reverse-DNS keeps it to letters,
+ * digits and hyphens.
+ */
+export function executableName(manifest) {
+    return manifest.id.split('.').pop() ?? 'app';
+}
+async function fetchText(url) {
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`${response.status} ${response.statusText}`);
+    return response.text();
+}
+/**
+ * The archive, owned by nobody in particular: `--owner=0 --group=0` so it does not carry the
+ * builder's account name to every player's machine.
+ */
+function tarGz(dir, entry, archive) {
+    const args = ['--owner=0', '--group=0', '--numeric-owner', '-czf', archive, '-C', dir, entry];
+    return new Promise((done, fail) => {
+        const child = spawn('tar', args, { stdio: ['ignore', 'inherit', 'inherit'] });
+        child.on('error', (cause) => fail(new Error(`tar could not be run: ${String(cause)}`)));
+        child.on('close', (code) => {
+            if (code === 0)
+                done();
+            else
+                fail(new Error(`tar ${args.join(' ')} exited ${String(code)}`));
+        });
+    });
+}
+/** Build the native artifact for `manifest` into `outDir`, and answer the archive's path. */
+export async function buildNative(manifest, cwd, outDir, options = {}) {
+    const refusal = nativeMachineRefusal(process.platform, process.arch);
+    if (refusal !== null)
+        throw new Error(refusal);
+    if (manifest.native === null) {
+        throw new Error('native-linux-x64 needs "native.entry" in drift.package.json');
+    }
+    /* Everything that can refuse, before anything is written — the copy's own refusal first, as
+       `stageApp` makes it (see `identity.ts`). */
+    refuseLyingFilesystem(cwd, outDir);
+    const hostDir = nativeHost(cwd, packagerVersion());
+    const hosted = NATIVE_MODULES.map((name) => ({ name, from: hostDir }));
+    runtimeClosure(hosted, INSTALL_ONLY);
+    const node = options.node ?? { path: process.execPath, version: process.version };
+    const licence = await nodeLicense(node.path, node.version, options.fetchText ?? fetchText);
+    for (const note of nativeNotes(manifest))
+        console.warn(`[drift-package] native-linux-x64: ${note}`);
+    const executable = executableName(manifest);
+    const root = join(outDir, executable);
+    const app = join(root, 'app');
+    await rm(root, { recursive: true, force: true });
+    await mkdir(app, { recursive: true });
+    const game = resolve(cwd, manifest.native.entry);
+    const bundle = await bundleNative(nativeEntrySource(manifest, HOST, game), app, cwd, options.conditions);
+    /* The game's own package is the game's to license, and is left out of both. */
+    const own = realpathSync(cwd);
+    const bundled = new Set();
+    for (const file of bundle.inputs) {
+        const dir = packageDirOf(file);
+        if (dir !== null && dir !== own)
+            bundled.add(dir);
+    }
+    const held = copyleftOf(bundled);
+    if (held.length > 0) {
+        throw new Error(`native-linux-x64 would bundle ${held.join(', ')} into one file with the game. A library ` +
+            'under such a licence has to stay a file a person can replace, which the native build does ' +
+            'for the libraries in LINKED_LIBRARIES (nativeBundle.ts); this one is not among them.');
+    }
+    const modules = runtimeClosure([...hosted, ...bundle.linked], INSTALL_ONLY);
+    await copyPackages(modules, join(app, 'node_modules'), { platform: 'linux', arch: 'x64' });
+    await cp(resolve(cwd, dirname(manifest.entry)), join(app, 'public'), { recursive: true });
+    await mkdir(join(root, 'runtime'));
+    await copyFile(node.path, join(root, 'runtime', 'node'));
+    await writeFile(join(root, executable), LAUNCHER);
+    /* After writing rather than as a write option, which the umask would narrow. */
+    await chmod(join(root, 'runtime', 'node'), 0o755);
+    await chmod(join(root, executable), 0o755);
+    /* The host carries the GPL's text, because the LGPL library it brings in asks for it. */
+    const gpl = readFileSync(join(hostDir, 'licenses', 'GPL-3.0.txt'), 'utf8');
+    await writeLicenses([...bundled, ...modules.map((found) => found.dir)], { version: node.version, text: licence }, join(root, 'licenses'), gpl);
+    const archive = join(outDir, `${manifest.name}-${await consumerVersion(cwd)}-linux-x64.tar.gz`);
+    await rm(archive, { force: true });
+    await tarGz(outDir, executable, archive);
+    console.log(`[drift-package] native-linux-x64: ${archive}`);
+    return archive;
+}

package/dist/nativeBundle.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A game, the native host and the engine as one module for Node, with every module one of them
+ * names by URL bundled beside it.
+ *
+ * **esbuild, for the reason `stage.ts` gives**: it is already a dependency here and it bundles
+ * TypeScript in one call. What it does not do is what a browser bundler does for a page:
+ * `new Worker(new URL('./islandWorker.ts', import.meta.url))` is left pointing at a source file that
+ * a shipped game does not have. So every `new URL('./x.ts', import.meta.url)` in the game's modules
+ * becomes an entry of its own, bundled into `modules/` beside the game, and the reference is
+ * rewritten to it — the engine's physics islands and splat sorting, and the host's own thread
+ * bootstrap, are three. **A DriftScript module is compiled on the way in**, by the language's own
+ * transform resolved from the game's tree, as the Vite plugin compiles it for the browser.
+ *
+ * **Four modules are left out and copied beside it instead** (`NATIVE_MODULES`): three carry a
+ * compiled binary, which cannot be bundled, and the JPEG codec reads its WebAssembly from its own
+ * directory. **So is a library whose licence asks that it stay replaceable** (`LINKED_LIBRARIES`),
+ * left an import and reported with the directory that imports it, where it is found.
+ *
+ * What it gives up: a module named by a URL that is not a literal is left alone, and fails where it
+ * is loaded — the same limit a browser bundler has.
+ */
+/**
+ * Libraries left outside the bundle for their licence, and copied as files of their own: under the
+ * LGPL a work of any licence may use the library so long as a person can put a modified copy in its
+ * place, which one bundled file with the game in it does not allow. `codec-parser`, which the Opus
+ * decoder reads Ogg pages with, is LGPL-3.0-or-later. Each is found from the package that imports
+ * it, as Node will find it.
+ */
+export declare const LINKED_LIBRARIES: readonly string[];
+/** What a native bundle was made from, and what it imports from outside itself by licence. */
+export interface NativeBundle {
+    /** Every file the bundles were made from. */
+    readonly inputs: Set<string>;
+    /** Each linked library, and the directory of the module that imports it. */
+    readonly linked: Set<{
+        readonly name: string;
+        readonly from: string;
+    }>;
+}
+/** What stays outside the bundle and is copied beside it. */
+export declare const NATIVE_MODULES: readonly ['@kmamal/gpu', '@kmamal/sdl', 'node-web-audio-api', '@jsquash/jpeg'];
+/**
+ * Each module `code` names by a URL relative to `file`, renamed to an entry under `prefix` and
+ * recorded in `found`, source path to entry name. One module keeps one name however many name it.
+ */
+export declare function rewriteModuleUrls(code: string, file: string, prefix: string, found: Map<string, string>): string;
+/**
+ * Bundle the module `source` into `appDir/game.mjs`, and each module it names into
+ * `appDir/modules/`. `source` resolves its imports from `projectDir`, the game's own tree, and so
+ * does everything it imports; `conditions` are the package conditions resolved before `default`.
+ * Answers every file the bundles were made from.
+ */
+export declare function bundleNative(source: string, appDir: string, projectDir: string, conditions?: readonly string[]): Promise<NativeBundle>;

package/dist/nativeBundle.js

@@ -0,0 +1,177 @@
+/**
+ * A game, the native host and the engine as one module for Node, with every module one of them
+ * names by URL bundled beside it.
+ *
+ * **esbuild, for the reason `stage.ts` gives**: it is already a dependency here and it bundles
+ * TypeScript in one call. What it does not do is what a browser bundler does for a page:
+ * `new Worker(new URL('./islandWorker.ts', import.meta.url))` is left pointing at a source file that
+ * a shipped game does not have. So every `new URL('./x.ts', import.meta.url)` in the game's modules
+ * becomes an entry of its own, bundled into `modules/` beside the game, and the reference is
+ * rewritten to it — the engine's physics islands and splat sorting, and the host's own thread
+ * bootstrap, are three. **A DriftScript module is compiled on the way in**, by the language's own
+ * transform resolved from the game's tree, as the Vite plugin compiles it for the browser.
+ *
+ * **Four modules are left out and copied beside it instead** (`NATIVE_MODULES`): three carry a
+ * compiled binary, which cannot be bundled, and the JPEG codec reads its WebAssembly from its own
+ * directory. **So is a library whose licence asks that it stay replaceable** (`LINKED_LIBRARIES`),
+ * left an import and reported with the directory that imports it, where it is found.
+ *
+ * What it gives up: a module named by a URL that is not a literal is left alone, and fails where it
+ * is loaded — the same limit a browser bundler has.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { build as esbuild } from 'esbuild';
+import { realpathSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+/**
+ * Libraries left outside the bundle for their licence, and copied as files of their own: under the
+ * LGPL a work of any licence may use the library so long as a person can put a modified copy in its
+ * place, which one bundled file with the game in it does not allow. `codec-parser`, which the Opus
+ * decoder reads Ogg pages with, is LGPL-3.0-or-later. Each is found from the package that imports
+ * it, as Node will find it.
+ */
+export const LINKED_LIBRARIES = ['codec-parser'];
+/** What stays outside the bundle and is copied beside it. */
+export const NATIVE_MODULES = [
+    '@kmamal/gpu',
+    '@kmamal/sdl',
+    'node-web-audio-api',
+    '@jsquash/jpeg',
+];
+const MODULE_URL = /new URL\(\s*(['"])(\.{1,2}\/[^'"]+?\.(?:ts|mts|js|mjs))\1\s*,\s*import\.meta\.url\s*\)/g;
+/**
+ * Each module `code` names by a URL relative to `file`, renamed to an entry under `prefix` and
+ * recorded in `found`, source path to entry name. One module keeps one name however many name it.
+ */
+export function rewriteModuleUrls(code, file, prefix, found) {
+    return code.replace(MODULE_URL, (_match, _quote, relative) => {
+        const target = resolve(dirname(file), relative);
+        let name = found.get(target);
+        if (name === undefined) {
+            name = `${basename(relative, extname(relative))}-${found.size + 1}.mjs`;
+            found.set(target, name);
+        }
+        return `new URL('${prefix}${name}', import.meta.url)`;
+    });
+}
+/*
+ * A bundle of ESM for Node still carries CommonJS inside it, and esbuild's shim for a `require` of a
+ * builtin needs one in scope. The host's own `createRequire(import.meta.url)` calls then resolve the
+ * copied native modules from beside the bundle.
+ *
+ * **Imported under a name nothing bundled uses.** The banner is text esbuild does not read, so it
+ * cannot rename around it, and the host imports `createRequire` itself: two declarations of one
+ * name, and a bundle Node refused to parse.
+ */
+const REQUIRE = "import { createRequire as __driftCreateRequire } from 'node:module';\n" +
+    'const require = __driftCreateRequire(import.meta.url);';
+/** The language's own transform, from the game's tree, or a refusal naming the module that asked. */
+async function driftScript(projectDir, asker) {
+    let resolved;
+    try {
+        resolved = createRequire(join(projectDir, 'package.json')).resolve('driftscript/vite');
+    }
+    catch {
+        throw new Error(`${asker} is a DriftScript module and driftscript is not installed in ${projectDir}; ` +
+            '`npm install driftscript` there, at the version the engine pins');
+    }
+    const { driftScript: plugin } = (await import(__rewriteRelativeImportExtension(resolved)));
+    const made = plugin();
+    return (code, path) => made.transform.call({ addWatchFile() { } }, code, path);
+}
+const LINKED = new RegExp(`^(${LINKED_LIBRARIES.join('|')})$`);
+function plugin(prefix, found, projectDir, linked) {
+    let compile = null;
+    return {
+        name: 'drift-native',
+        setup(build) {
+            build.onResolve({ filter: LINKED }, (args) => {
+                const from = realpathSync(args.resolveDir);
+                linked.set(`${args.path}\0${from}`, { name: args.path, from });
+                return { path: args.path, external: true };
+            });
+            build.onLoad({ filter: /\.(ts|mts|js|mjs)$/ }, async (args) => {
+                const code = await readFile(args.path, 'utf8');
+                if (!code.includes('import.meta.url'))
+                    return undefined;
+                const contents = rewriteModuleUrls(code, args.path, prefix, found);
+                if (contents === code)
+                    return undefined;
+                const loader = /\.m?ts$/.test(args.path) ? 'ts' : 'js';
+                return { contents, loader, resolveDir: dirname(args.path) };
+            });
+            build.onLoad({ filter: /\.drs$/ }, async (args) => {
+                compile ??= await driftScript(projectDir, args.path);
+                const compiled = compile(await readFile(args.path, 'utf8'), args.path);
+                if (compiled === null)
+                    throw new Error(`${args.path} did not compile`);
+                return { contents: compiled.code, loader: 'js', resolveDir: dirname(args.path) };
+            });
+        },
+    };
+}
+/** Where esbuild says an input came from, as a path, or null for one that is not a file. */
+function inputPath(projectDir, input) {
+    return /^[a-z-]+:|^<stdin>$/.test(input) ? null : resolve(projectDir, input);
+}
+/**
+ * Bundle the module `source` into `appDir/game.mjs`, and each module it names into
+ * `appDir/modules/`. `source` resolves its imports from `projectDir`, the game's own tree, and so
+ * does everything it imports; `conditions` are the package conditions resolved before `default`.
+ * Answers every file the bundles were made from.
+ */
+export async function bundleNative(source, appDir, projectDir, conditions = []) {
+    const found = new Map();
+    const inputs = new Set();
+    const linked = new Map();
+    const common = {
+        bundle: true,
+        platform: 'node',
+        format: 'esm',
+        target: 'node22',
+        external: [...NATIVE_MODULES],
+        conditions: [...conditions],
+        banner: { js: REQUIRE },
+        absWorkingDir: projectDir,
+        metafile: true,
+        logLevel: 'warning',
+    };
+    const record = (metafile) => {
+        for (const input of Object.keys(metafile?.inputs ?? {})) {
+            const path = inputPath(projectDir, input);
+            if (path !== null)
+                inputs.add(path);
+        }
+    };
+    record((await esbuild({
+        ...common,
+        stdin: { contents: source, resolveDir: projectDir, sourcefile: 'entry.mjs', loader: 'js' },
+        outfile: join(appDir, 'game.mjs'),
+        plugins: [plugin('./modules/', found, projectDir, linked)],
+    })).metafile);
+    /* A module may name others in turn, so this runs until a pass finds nothing new. */
+    const built = new Set();
+    while (built.size < found.size) {
+        for (const [module, name] of [...found]) {
+            if (built.has(module))
+                continue;
+            built.add(module);
+            record((await esbuild({
+                ...common,
+                entryPoints: [module],
+                outfile: join(appDir, 'modules', name),
+                plugins: [plugin('./', found, projectDir, linked)],
+            })).metafile);
+        }
+    }
+    return { inputs, linked: new Set(linked.values()) };
+}

package/dist/nativeCopy.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The modules a native build copies rather than bundles, found as Node would find them and copied
+ * with what they load when they run.
+ *
+ * **Found by walking `node_modules` upwards, not by `require.resolve`**, because a package's
+ * directory is what is copied and most of these do not export their `package.json`. That walk is
+ * Node's own lookup for a bare name, so a module found here is the module the game would load, and
+ * it starts from the real path of whoever asks, as Node does through a workspace link.
+ *
+ * **Every declared dependency is followed but the ones a module only installs with**, which are
+ * named rather than inferred (`installOnly`): the two bindings declare `tar`, `node-gyp` and
+ * `node-addon-api` for the script that downloads or builds their binary, and load nothing at run
+ * time but that binary. Named rather than skipped wholesale, so a run-time dependency a later version
+ * adds is copied, not lost.
+ *
+ * What it gives up: one directory per name. Two versions of one package in the copy are refused
+ * rather than nested, which none of these four has needed.
+ */
+export interface FoundPackage {
+    readonly name: string;
+    readonly version: string;
+    readonly dir: string;
+}
+/** The directory of the package `name` as a module in `from` would load it, or null. */
+export declare function findPackage(name: string, from: string): string | null;
+/** The package `file` belongs to: the nearest directory above it whose manifest has a name. */
+export declare function packageDirOf(file: string): string | null;
+/** A package to copy, and the directory of the module that loads it, which is where it is found. */
+export interface CopyRequest {
+    readonly name: string;
+    readonly from: string;
+}
+/** Each requested package as its importer would load it, and every package they load in turn, once. */
+export declare function runtimeClosure(requests: readonly CopyRequest[], installOnly: Readonly<Record<string, readonly string[]>>): FoundPackage[];
+/** Copy each package into `into/<name>`, leaving its own `node_modules` and other machines' binaries. */
+export declare function copyPackages(packages: readonly FoundPackage[], into: string, host: {
+    readonly platform: string;
+    readonly arch: string;
+}): Promise<void>;

package/dist/nativeCopy.js

@@ -0,0 +1,110 @@
+/**
+ * The modules a native build copies rather than bundles, found as Node would find them and copied
+ * with what they load when they run.
+ *
+ * **Found by walking `node_modules` upwards, not by `require.resolve`**, because a package's
+ * directory is what is copied and most of these do not export their `package.json`. That walk is
+ * Node's own lookup for a bare name, so a module found here is the module the game would load, and
+ * it starts from the real path of whoever asks, as Node does through a workspace link.
+ *
+ * **Every declared dependency is followed but the ones a module only installs with**, which are
+ * named rather than inferred (`installOnly`): the two bindings declare `tar`, `node-gyp` and
+ * `node-addon-api` for the script that downloads or builds their binary, and load nothing at run
+ * time but that binary. Named rather than skipped wholesale, so a run-time dependency a later version
+ * adds is copied, not lost.
+ *
+ * What it gives up: one directory per name. Two versions of one package in the copy are refused
+ * rather than nested, which none of these four has needed.
+ */
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { cp } from 'node:fs/promises';
+import { basename, dirname, join, relative, sep } from 'node:path';
+function manifestOf(dir) {
+    const path = join(dir, 'package.json');
+    if (!existsSync(path))
+        return null;
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+/** The directory of the package `name` as a module in `from` would load it, or null. */
+export function findPackage(name, from) {
+    let dir = existsSync(from) ? realpathSync(from) : from;
+    for (;;) {
+        const candidate = join(dir, 'node_modules', name);
+        if (manifestOf(candidate) !== null)
+            return realpathSync(candidate);
+        const up = dirname(dir);
+        if (up === dir)
+            return null;
+        dir = up;
+    }
+}
+/** The package `file` belongs to: the nearest directory above it whose manifest has a name. */
+export function packageDirOf(file) {
+    let dir = dirname(file);
+    for (;;) {
+        const manifest = manifestOf(dir);
+        if (manifest !== null && typeof manifest.name === 'string')
+            return dir;
+        const up = dirname(dir);
+        if (up === dir)
+            return null;
+        dir = up;
+    }
+}
+/** Each requested package as its importer would load it, and every package they load in turn, once. */
+export function runtimeClosure(requests, installOnly) {
+    const found = [];
+    const byName = new Map();
+    const visit = (name, asker, askerDir) => {
+        const dir = findPackage(name, askerDir);
+        if (dir === null) {
+            throw new Error(`the native build needs "${name}", which ${asker} loads, and it is not installed where ` +
+                `${asker} would find it. \`npm install\` in the game, and check it finished.`);
+        }
+        const manifest = manifestOf(dir) ?? {};
+        const version = typeof manifest.version === 'string' ? manifest.version : '0.0.0';
+        const seen = byName.get(name);
+        if (seen !== undefined) {
+            if (seen.dir === dir)
+                return;
+            throw new Error(`the native build would copy ${name} ${seen.version} and ${version} into one ` +
+                `node_modules (${seen.dir} and ${dir}); only one can be there. Align the two ranges.`);
+        }
+        const entry = { name, version, dir };
+        byName.set(name, entry);
+        found.push(entry);
+        const skip = installOnly[name] ?? [];
+        const dependencies = (manifest.dependencies ?? {});
+        for (const dependency of Object.keys(dependencies)) {
+            if (!skip.includes(dependency))
+                visit(dependency, name, dir);
+        }
+    };
+    for (const request of requests)
+        visit(request.name, 'the bundle', request.from);
+    return found;
+}
+/**
+ * A compiled binary's platform, from the name napi-rs and its kind give it:
+ * `name.linux-x64-gnu.node`, `name.darwin-arm64.node`. A binary with no such suffix is taken to be
+ * this machine's, which is what a binding that builds or downloads its own writes.
+ */
+const TAGGED = /\.(darwin|win32|linux|freebsd|android|openbsd|sunos)-([a-z0-9]+)(?:-[a-z0-9]+)?\.node$/;
+function keeps(path, host) {
+    const match = TAGGED.exec(basename(path));
+    return match === null || (match[1] === host.platform && match[2] === host.arch);
+}
+/** Copy each package into `into/<name>`, leaving its own `node_modules` and other machines' binaries. */
+export async function copyPackages(packages, into, host) {
+    for (const found of packages) {
+        await cp(found.dir, join(into, found.name), {
+            recursive: true,
+            filter: (source) => {
+                const inside = relative(found.dir, source);
+                if (inside.split(sep)[0] === 'node_modules')
+                    return false;
+                return keeps(source, host);
+            },
+        });
+    }
+}