@driftengine/package 3.63.0 → 4.1.0

package/src/manifest.ts

@@ -13,7 +13,8 @@
 import { checkPermission, fullPermissionName } from './mobile/androidManifest.ts';
 
 export type WebGpuPolicy = 'prefer' | 'require' | 'off';
-export type Target = 'win-x64' | 'mac-arm64' | 'mac-x64' | 'linux-x64' | 'android' | 'ios';
+export type Target =
+  'win-x64' | 'mac-arm64' | 'mac-x64' | 'linux-x64' | 'native-linux-x64' | 'android' | 'ios';
 
 /** The two that are a phone rather than a desktop, and differ in almost every way that matters. */
 export const MOBILE_TARGETS: readonly Target[] = ['android', 'ios'];
@@ -24,6 +25,7 @@ const TARGETS: readonly Target[] = [
   'mac-arm64',
   'mac-x64',
   'linux-x64',
+  'native-linux-x64',
   'android',
   'ios',
 ];
@@ -54,6 +56,11 @@ export interface PackageManifest {
   readonly backend: { readonly webgpu: WebGpuPolicy; readonly allowSoftwareRenderer: boolean };
   readonly features: { readonly clipExport: boolean; readonly gamepad: boolean };
   readonly targets: readonly Target[];
+  /**
+   * The module a native target mounts: it exports `mount(canvas)`, which the native host calls with
+   * its canvas, since there is no page there to find one in. Null unless a native target is built.
+   */
+  readonly native: { readonly entry: string } | null;
   readonly steam: { readonly appId: number | null };
   readonly splash: { readonly show: boolean; readonly minMs: number };
   /**
@@ -133,6 +140,16 @@ export function parseManifest(raw: unknown): PackageManifest {
     }
   }
 
+  const nativeRaw = (source.native ?? {}) as Record<string, unknown>;
+  const nativeEntry =
+    typeof nativeRaw.entry === 'string' && nativeRaw.entry.length > 0 ? nativeRaw.entry : null;
+  if ((targetsRaw as unknown[]).includes('native-linux-x64') && nativeEntry === null) {
+    throw new Error(
+      'drift.package.json: the native-linux-x64 target needs "native.entry", the module whose ' +
+        '`mount(canvas)` the native host calls — there is no page there to find a canvas in',
+    );
+  }
+
   const windowRaw = (source.window ?? {}) as Record<string, unknown>;
   const featuresRaw = (source.features ?? {}) as Record<string, unknown>;
   const steamRaw = (source.steam ?? {}) as Record<string, unknown>;
@@ -175,6 +192,7 @@ export function parseManifest(raw: unknown): PackageManifest {
       gamepad: featuresRaw.gamepad !== false,
     },
     targets: targetsRaw as readonly Target[],
+    native: nativeEntry === null ? null : { entry: nativeEntry },
     steam: { appId: typeof appId === 'number' ? appId : null },
     publisher:
       typeof source.publisher === 'string' && source.publisher.length > 0

package/src/native.ts

@@ -0,0 +1,263 @@
+/**
+ * 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.ts';
+import type { PackageManifest } from './manifest.ts';
+import { bundleNative, NATIVE_MODULES } from './nativeBundle.ts';
+import { copyPackages, findPackage, packageDirOf, runtimeClosure } from './nativeCopy.ts';
+import { copyleftOf, type FetchText, nodeLicense, writeLicenses } from './nativeLicenses.ts';
+import { consumerVersion } from './stage.ts';
+
+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: Readonly<Record<string, readonly string[]>> = {
+  '@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" "$@"
+`;
+
+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 function nativeMachineRefusal(platform: string, arch: string): string | null {
+  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(): string {
+  const manifest = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8')) as {
+    version: string;
+  };
+  return manifest.version;
+}
+
+/** The host's directory in the game's tree, at `version`, or a refusal naming the install. */
+export function nativeHost(cwd: string, version: string): string {
+  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')) as { version: string })
+    .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: PackageManifest, host: string, game: string): string {
+  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: PackageManifest): string[] {
+  const notes: string[] = [];
+  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: PackageManifest): string {
+  return manifest.id.split('.').pop() ?? 'app';
+}
+
+async function fetchText(url: string): Promise<string> {
+  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: string, entry: string, archive: string): Promise<void> {
+  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: PackageManifest,
+  cwd: string,
+  outDir: string,
+  options: NativeOptions = {},
+): Promise<string> {
+  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<string>();
+  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/src/nativeBundle.ts

@@ -0,0 +1,215 @@
+/**
+ * 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.
+ */
+
+import { type BuildOptions, build as esbuild, type Metafile, type Plugin } 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: readonly string[] = ['codec-parser'];
+
+/** 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 const NATIVE_MODULES = [
+  '@kmamal/gpu',
+  '@kmamal/sdl',
+  'node-web-audio-api',
+  '@jsquash/jpeg',
+] as const;
+
+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: string,
+  file: string,
+  prefix: string,
+  found: Map<string, string>,
+): string {
+  return code.replace(MODULE_URL, (_match, _quote: string, relative: string) => {
+    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);';
+
+type Transform = (code: string, path: string) => { code: string } | null;
+
+/** The language's own transform, from the game's tree, or a refusal naming the module that asked. */
+async function driftScript(projectDir: string, asker: string): Promise<Transform> {
+  let resolved: string;
+  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(resolved)) as {
+    driftScript: () => {
+      transform: (this: object, code: string, path: string) => { code: string } | null;
+    };
+  };
+  const made = plugin();
+  return (code, path) => made.transform.call({ addWatchFile() {} }, code, path);
+}
+
+const LINKED = new RegExp(`^(${LINKED_LIBRARIES.join('|')})$`);
+
+function plugin(
+  prefix: string,
+  found: Map<string, string>,
+  projectDir: string,
+  linked: Map<string, { readonly name: string; readonly from: string }>,
+): Plugin {
+  let compile: Transform | null = 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: string, input: string): string | null {
+  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: string,
+  appDir: string,
+  projectDir: string,
+  conditions: readonly string[] = [],
+): Promise<NativeBundle> {
+  const found = new Map<string, string>();
+  const inputs = new Set<string>();
+  const linked = new Map<string, { readonly name: string; readonly from: string }>();
+  const common: BuildOptions = {
+    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: Metafile | undefined): void => {
+    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<string>();
+  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/src/nativeCopy.ts

@@ -0,0 +1,133 @@
+/**
+ * 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';
+
+export interface FoundPackage {
+  readonly name: string;
+  readonly version: string;
+  readonly dir: string;
+}
+
+function manifestOf(dir: string): Record<string, unknown> | null {
+  const path = join(dir, 'package.json');
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+}
+
+/** The directory of the package `name` as a module in `from` would load it, or null. */
+export function findPackage(name: string, from: string): string | null {
+  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: string): string | null {
+  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;
+  }
+}
+
+/** 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 function runtimeClosure(
+  requests: readonly CopyRequest[],
+  installOnly: Readonly<Record<string, readonly string[]>>,
+): FoundPackage[] {
+  const found: FoundPackage[] = [];
+  const byName = new Map<string, FoundPackage>();
+  const visit = (name: string, asker: string, askerDir: string): void => {
+    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 ?? {}) as Record<string, string>;
+    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: string, host: { platform: string; arch: string }): boolean {
+  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: readonly FoundPackage[],
+  into: string,
+  host: { readonly platform: string; readonly arch: string },
+): Promise<void> {
+  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);
+      },
+    });
+  }
+}