@driftengine/package 3.61.0

package/src/cli.ts

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+import { bootstrap } from './bootstrap.ts';
+import { build, installedElectronVersion } from './build.ts';
+import { planFlags } from './flags.ts';
+import { refuseLyingFilesystem } from './identity.ts';
+import { init } from './init.ts';
+import { outFor } from './outDir.ts';
+import { parseManifest } from './manifest.ts';
+import type { PackageManifest, Target } from './manifest.ts';
+import { planSigning } from './signing.ts';
+import { electronMajor } from './runtimeVersion.ts';
+import { depotScripts } from './steam/depot.ts';
+import { androidToolchain, findRcodesign, needsRcodesign, requirementsFor } from './toolchain.ts';
+import { stageApp } from './stage.ts';
+import { resourceDir } from './resources.ts';
+import type { ResourceOptions } from './resources.ts';
+
+/*
+ * **`ELECTRON_RUN_AS_NODE` is removed from this process before anything else happens.**
+ *
+ * Any terminal that is itself an Electron application — an editor's built-in one is the ordinary
+ * case, and a developer's own shell had it set — exports the variable to everything it spawns.
+ * Inherited, it turns Electron into plain Node: a packaged build dies on `Cannot find module
+ * 'electron'` under a Node banner, which looks nothing like its cause, and in that mode the
+ * built-in module genuinely is not there.
+ *
+ * **It used to be removed for `run` alone**, in `launchEnv` below, which left `build` and every
+ * other subcommand inheriting it — and `build` is the one that spends twenty minutes before
+ * anything can go wrong. Deleted rather than set empty: Electron treats the variable as set
+ * whatever its value.
+ */
+delete process.env.ELECTRON_RUN_AS_NODE;
+
+/**
+ * `drift-package` — the command a consumer runs to get an installable application.
+ *
+ * Four subcommands, and `verify` is the one that is not obvious. An artifact that was never
+ * rebuilt is byte-identical in every respect a build log can see, so the only honest check is to
+ * look inside the shipped thing for a string from the change. This repository already learned that
+ * about deploys: an asset hash proves nothing.
+ *
+ * Every failure exits non-zero with the reason on stderr. A packaging command that prints a
+ * complaint and exits 0 is a command that passes in a script.
+ */
+function loadManifest(cwd: string): PackageManifest {
+  const path = join(cwd, 'drift.package.json');
+  try {
+    return parseManifest(JSON.parse(readFileSync(path, 'utf8')) as unknown);
+  } catch (cause) {
+    throw new Error(`could not read ${path}: ${String(cause)}`);
+  }
+}
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) walk(full, out);
+    else out.push(full);
+  }
+  return out;
+}
+
+async function doctor(cwd: string, options: ResourceOptions = {}): Promise<PackageManifest> {
+  /*
+   * **Before anything is read, downloaded or staged**, because the failure it replaces arrives ten
+   * minutes in and talks about copying a file into a subdirectory of itself. See `identity.ts`:
+   * a share that invents a file index makes Node refuse a copy that is perfectly legitimate.
+   */
+  refuseLyingFilesystem(cwd, options.outRoot);
+  const manifest = loadManifest(cwd);
+  /*
+   * **The packager's own three directories, checked here rather than met mid-build.** `assets/`
+   * becomes every desktop artifact's `drift://shell/` origin, and a copy of the engine that
+   * flattened its packages has moved all three out of reach — which used to arrive as `ENOENT` on a
+   * path that is not in the project, after esbuild had already run. `doctor` is where this file
+   * already refuses what a build cannot do, before anything is downloaded or staged.
+   *
+   * `assets` alone: it is the one every target needs, and naming `android/` or `ios/` on a machine
+   * building for Linux would refuse a build that was never going to touch them. The two mobile
+   * builders check their own.
+   */
+  await resourceDir('assets', options.resourceRoot);
+  /*
+   * **Against the Electron this machine would actually package**, not the one the package declares.
+   * A switch written for one Chromium and applied to another is ignored without a word, so doctor
+   * is where a runtime too old for it is named — before a build spends its minutes and ships a
+   * game that silently has no WebGPU.
+   */
+  const electron = electronMajor(await installedElectronVersion().catch(() => null));
+  for (const target of manifest.targets) {
+    const plan = planFlags(manifest, target, electron);
+    if (plan.refusal !== null) throw new Error(`${target}: ${plan.refusal}`);
+    for (const note of plan.notes) console.log(`  ${target}: ${note}`);
+  }
+  console.log(`ok: ${manifest.name} (${manifest.id}) for ${manifest.targets.join(', ')}`);
+  for (const target of manifest.targets) {
+    const signing = planSigning(target, process.env, process.platform);
+    console.log(`  ${target}: signing ${signing.mode} — ${signing.reason}`);
+  }
+  console.log(
+    `  splash: ${manifest.splash.show ? `the engine badge, held ${manifest.splash.minMs} ms` : 'off'}`,
+  );
+
+  /*
+   * **What each target still needs, and the command that fetches it.** A `doctor` that only
+   * validated a manifest would pass on a machine with no Java and no SDK, and the failure would
+   * arrive twenty minutes later from Gradle.
+   */
+  for (const target of manifest.targets) {
+    const ready = await toolchainReady(target);
+    if (ready) continue;
+    console.log(
+      `  ${target}: needs ${requirementsFor(target).join(', ')} — ` +
+        `run \`drift-package bootstrap --target=${target}\``,
+    );
+  }
+  return manifest;
+}
+
+function verify(cwd: string, needle: string): void {
+  const manifest = loadManifest(cwd);
+  const root = join(cwd, dirname(manifest.entry));
+  const found = walk(root).some((file) => readFileSync(file, 'utf8').includes(needle));
+  if (!found) {
+    throw new Error(
+      `verify: "${needle}" is in no file under ${root}. That is what a build that did not rerun ` +
+        'looks like — the artifact exists and is stale.',
+    );
+  }
+  console.log(`ok: "${needle}" is in the built bundle`);
+}
+
+/**
+ * The packaged application, run from source without producing an installer.
+ *
+ * **The whole point is that it is the same code path.** It stages exactly what a build stages and
+ * starts Electron on it, so the window, the flags, the `drift://` origin and the badge are the
+ * ones that will ship. A `run` that took a shortcut would be a rehearsal of something else.
+ */
+async function run(cwd: string, options: ResourceOptions): Promise<number> {
+  const manifest = await doctor(cwd, options);
+  const stageDir = mkdtempSync(join(tmpdir(), 'drift-run-'));
+  /* A development run: developer tools open, warnings forwarded. `build` stages the other kind. */
+  await stageApp(manifest, cwd, stageDir, { development: true, ...options });
+  const electron = await import('electron');
+  const binary = electron.default as unknown as string;
+  console.log(`[drift-package] running from ${stageDir}`);
+  return new Promise((resolve) => {
+    const child = spawn(binary, [stageDir], { stdio: 'inherit', env: launchEnv() });
+    child.on('close', (code) => {
+      /* The staging directory holds a whole copy of the game's build — tens of megabytes for a
+         real one — and a `run` per iteration would leave one of each in the temp directory. */
+      rmSync(stageDir, { recursive: true, force: true });
+      resolve(code ?? 0);
+    });
+  });
+}
+
+/**
+ * The environment Electron is started in, with one variable removed.
+ *
+ * **`ELECTRON_RUN_AS_NODE` turns Electron into plain Node**, and any Electron-based terminal sets
+ * it for the processes it spawns — an editor's integrated terminal is the common case, and this
+ * workspace's own shell had it set. Inherited, it produces a failure that looks nothing like its
+ * cause: the binary starts, prints a Node banner and dies on `Cannot find module 'electron'`,
+ * because in that mode the built-in module genuinely is not there.
+ *
+ * Deleted rather than overridden with an empty string: Electron treats the variable as set
+ * whatever its value.
+ *
+ * **This is now the second place it is removed** and it stays: the top of this file clears it for
+ * the whole process, and this clears it for the child. The reason is written twice because it is
+ * the reason somebody will come here looking for, and a copy of `process.env` taken elsewhere
+ * would not inherit the first deletion.
+ */
+function launchEnv(): NodeJS.ProcessEnv {
+  const env = { ...process.env };
+  delete env.ELECTRON_RUN_AS_NODE;
+  return env;
+}
+
+/**
+ * Whether this machine can build that target today.
+ *
+ * Desktop targets need the Electron runtime, which is present unless an install skipped its
+ * postinstall; Android needs a whole toolchain; iOS needs Xcode, which nothing here can check for
+ * beyond the platform it would have to be on.
+ */
+async function toolchainReady(target: Target): Promise<boolean> {
+  if (target === 'android') return (await androidToolchain()) !== null;
+  if (target === 'ios') return process.platform === 'darwin';
+  /* A Mac target built anywhere else is signed by rcodesign, and an unsigned .app will not
+     launch — so a machine without it is not ready for that target, however well it packs. */
+  if (needsRcodesign(target)) return (await findRcodesign()) !== null;
+  return true;
+}
+
+/**
+ * The two files `steamcmd` uploads a build with, written beside the artifacts they describe.
+ *
+ * A separate command rather than part of `build`, because uploading is a decision: the scripts
+ * name an app id that costs money to get wrong, and a build is often made several times before one
+ * of them is the one that ships.
+ */
+async function writeSteamScripts(
+  cwd: string,
+  args: readonly string[],
+  options: ResourceOptions,
+): Promise<void> {
+  const manifest = loadManifest(cwd);
+  if (manifest.steam.appId === null) {
+    throw new Error(
+      'steam: `steam.appId` is null in drift.package.json. Set it to the app id Valve gave you; ' +
+        "a depot script with the wrong one uploads into somebody else's game.",
+    );
+  }
+  const target = (
+    args.find((entry) => entry.startsWith('--target=')) ?? '--target=linux-x64'
+  ).slice('--target='.length) as Target;
+  const depotArg = args.find((entry) => entry.startsWith('--depot='));
+  /* A first depot is conventionally the app id plus one, which is how Valve numbers them. */
+  const depotId =
+    depotArg === undefined ? manifest.steam.appId + 1 : Number.parseInt(depotArg.slice(8), 10);
+  const branchArg = args.find((entry) => entry.startsWith('--branch='));
+
+  const outDir = outFor(cwd, target, options);
+  const content =
+    target === 'linux-x64' ? 'linux-unpacked' : target === 'win-x64' ? 'win-unpacked' : 'mac';
+  const scripts = depotScripts({
+    appId: manifest.steam.appId,
+    depotId,
+    description: `${manifest.name} ${target}`,
+    contentRoot: content,
+    branch: branchArg === undefined ? null : branchArg.slice('--branch='.length),
+  });
+
+  await writeFile(join(outDir, scripts.appFileName), scripts.app, 'utf8');
+  await writeFile(join(outDir, scripts.depotFileName), scripts.depot, 'utf8');
+  console.log(`ok: ${join(outDir, scripts.appFileName)}`);
+  console.log(`ok: ${join(outDir, scripts.depotFileName)}`);
+  console.log(
+    `  upload with: steamcmd +login <user> +run_app_build "${join(outDir, scripts.appFileName)}" +quit`,
+  );
+  console.log("  nothing is set live: the build waits in Steam's admin for a person");
+}
+
+/** What this machine builds for itself, used when nothing has said otherwise. */
+function hostTarget(): Target {
+  if (process.platform === 'win32') return 'win-x64';
+  if (process.platform === 'darwin') return process.arch === 'x64' ? 'mac-x64' : 'mac-arm64';
+  return 'linux-x64';
+}
+
+function targetsFrom(manifest: PackageManifest, args: readonly string[]): readonly Target[] {
+  const asked = args.find((entry) => entry.startsWith('--target='));
+  if (asked === undefined) return manifest.targets;
+  const name = asked.slice('--target='.length);
+  const found = manifest.targets.find((target) => target === name);
+  if (found === undefined) {
+    throw new Error(
+      `--target=${name} is not in this manifest's targets (${manifest.targets.join(', ')})`,
+    );
+  }
+  return [found];
+}
+
+const [command, ...rest] = process.argv.slice(2);
+
+/**
+ * The project being packaged, which is the working directory unless `--project=` says otherwise.
+ *
+ * **Because the packager and the game are often not the same repository.** A game that keeps its
+ * `drift.package.json` and nothing else — no Electron, no electron-builder, no Android SDK in its
+ * own `node_modules` — is packaged by pointing this at it from wherever the tool lives, and that
+ * is the arrangement most consumers actually want: half a gigabyte of build tooling does not
+ * belong in a game's dependency tree.
+ */
+const projectFlag = rest.find((entry) => entry.startsWith('--project='));
+const cwd =
+  projectFlag === undefined
+    ? process.cwd()
+    : resolve(process.cwd(), projectFlag.slice('--project='.length));
+
+/**
+ * Where the packager's own `assets/`, `android/` and `ios/` are, if not beside its sources.
+ *
+ * **For a consumer that vendors engine source** rather than installing it: such a vendor copies
+ * `packages/<name>/src/**` to `<name>/**` and the flattening moves
+ * the three out of reach of anything this package can compute. Reported from outside, where the
+ * workaround was a layout exception in the vendor script for this one package. See `resources.ts`
+ * for why this is a flag rather than an environment variable.
+ */
+const resourcesFlag = rest.find((entry) => entry.startsWith('--resources='));
+
+/**
+ * Where builds write, if not `out/` inside the project.
+ *
+ * **For a project on a filesystem that misreports file identity**, where the first staging copy
+ * of a build refuses itself: `fs.cp` compares `dev` and `ino` up the destination's ancestors, and
+ * a shared or network folder can answer the same pair for a file and a directory. `outDir.ts`
+ * carries the measurement. Absolute here, or relative to wherever the command was run, which is
+ * not necessarily `--project=`.
+ */
+const outFlag = rest.find((entry) => entry.startsWith('--out='));
+const resources: ResourceOptions = {
+  ...(resourcesFlag === undefined
+    ? {}
+    : { resourceRoot: resourcesFlag.slice('--resources='.length) }),
+  ...(outFlag === undefined ? {} : { outRoot: outFlag.slice('--out='.length) }),
+};
+
+try {
+  if (command === 'doctor') {
+    await doctor(cwd, resources);
+  } else if (command === 'verify') {
+    const arg = rest.find((entry) => entry.startsWith('--contains='));
+    if (arg === undefined) throw new Error('verify needs --contains=<string>');
+    verify(cwd, arg.slice('--contains='.length));
+  } else if (command === 'run') {
+    process.exitCode = await run(cwd, resources);
+  } else if (command === 'bootstrap') {
+    /* Deliberately does not need a manifest: a machine is prepared before a project exists on it,
+       and `--target=` names what to prepare for. */
+    const asked = rest.find((entry) => entry.startsWith('--target='));
+    const targets =
+      asked === undefined
+        ? ((): readonly Target[] => {
+            try {
+              return loadManifest(cwd).targets;
+            } catch {
+              /* No manifest here: prepare for this desktop, which is the useful default on a
+                 machine somebody is setting up. */
+              return [hostTarget()];
+            }
+          })()
+        : [asked.slice('--target='.length) as Target];
+    await bootstrap(targets);
+  } else if (command === 'init') {
+    /*
+     * Scaffolds a *project*, where `bootstrap` prepares a *machine*. Two commands because a
+     * machine is prepared once and a project once per project, and conflating them would make the
+     * one that writes files into your repository the one you run to install a JDK.
+     */
+    await init(cwd, loadManifest(cwd), rest.includes('--force'));
+  } else if (command === 'steam') {
+    await writeSteamScripts(cwd, rest, resources);
+  } else if (command === 'build') {
+    /* Checked before anything is downloaded or staged: a build that would be refused must be
+       refused first, not after twenty minutes of Electron. */
+    const manifest = await doctor(cwd, resources);
+    await build(manifest, cwd, targetsFrom(manifest, rest), resources);
+  } else {
+    throw new Error(
+      'usage: drift-package <init|bootstrap|doctor|build|run|verify|steam> [--project=<dir>] ' +
+        `[--target=<target>] [--resources=<dir>] [--out=<dir>] [--force] — got "${String(command)}"`,
+    );
+  }
+} catch (cause) {
+  console.error(String(cause instanceof Error ? cause.message : cause));
+  process.exit(1);
+}

package/src/flags.ts

@@ -0,0 +1,171 @@
+import type { PackageManifest, Target } from './manifest.ts';
+
+/**
+ * The Chromium switches a shipped build launches with.
+ *
+ * **This is most of why the packager exists.** Every switch below was paid for once already, in
+ * this repository or by a consumer, and a game that wraps Electron by hand rediscovers each of
+ * them — two of them only by measuring a frame nobody thought to measure.
+ *
+ * **What this costs**: the flags are ours rather than the platform's defaults, so a Chromium
+ * change can invalidate one and nothing will say so. **What would make it wrong**: Electron
+ * enabling Vulkan on Linux by default, at which point the first block below becomes a no-op worth
+ * deleting rather than a fix worth keeping.
+ *
+ * **Checked 2026-09-09 and still needed**, on Electron 43.4.1 / Chromium 150.0.7871.224 with an
+ * RX 9070 XT: launched with no switches at all, `navigator.gpu` is present and `requestAdapter`
+ * answers **null**. With the interop feature it hands back an `amd`/`rdna-4` adapter and a device.
+ * So the block below is doing the work rather than riding along, six Chromium majors after it was
+ * written.
+ *
+ * **And a switch is now only asked for on a runtime it has been seen to work on**, because the
+ * other half of "nothing will say so" is a name Chromium does not recognise: unknown features in
+ * `--enable-features` are dropped in silence, and the build that results is indistinguishable from
+ * a machine with no adapter to offer. See `WEBGPU_INTEROP_ELECTRON`.
+ */
+export interface FlagPlan {
+  readonly switches: readonly (readonly [string, string])[];
+  /** Non-null means refuse to build, and this is what to print. */
+  readonly refusal: string | null;
+  /**
+   * What a caller must print, having decided nothing.
+   *
+   * **A switch that names a feature the runtime has never heard of is worse than no switch**, and
+   * that is what these exist for: Chromium ignores an unknown name in `--enable-features` without a
+   * word, so a build that cannot deliver WebGPU looks exactly like a machine whose driver had no
+   * adapter to offer. Where this plan declines to ask for something, it says so out loud.
+   */
+  readonly notes: readonly string[];
+}
+
+/**
+ * The Electron the Linux WebGPU switch below is written against, and measured on.
+ *
+ * **Not the version the feature was introduced in, which nobody here has established.** It is the
+ * version this repository has run the switch against and watched WebGPU come up: Electron 43.4.1,
+ * Chromium 150.0.7871.224, an RX 9070 XT, where `requestAdapter` answers null without the switch
+ * and hands back an `amd`/`rdna-4` adapter with it. Reported from outside against Electron 33.4.11,
+ * Chromium 130: the feature name is not in that binary at all, and the switch is inert there.
+ *
+ * So a runtime older than this is *unverified*, not known-broken — and the plan declines to ship an
+ * unverified switch rather than shipping one that may do nothing silently.
+ */
+export const WEBGPU_INTEROP_ELECTRON = 43;
+
+/**
+ * @param electronMajor The major version of the Electron these switches will be applied to, or
+ *   `null` where a caller genuinely cannot know. Both callers in this package can: the build reads
+ *   it out of the installed package, and the main process reads it out of `process.versions`.
+ */
+export function planFlags(
+  manifest: PackageManifest,
+  target: Target,
+  electronMajor: number | null = null,
+): FlagPlan {
+  /*
+   * **A mobile host has no command line to pass switches on.** The renderer is the platform's own
+   * WebView, updated by the store rather than by us, and every decision below is about a Chromium
+   * this package ships. Returning nothing is the honest answer rather than switches that would be
+   * silently dropped — and it is why the Linux refusal further down cannot fire on a phone.
+   */
+  if (target === 'android' || target === 'ios') return { switches: [], refusal: null, notes: [] };
+
+  const switches: (readonly [string, string])[] = [];
+  const notes: string[] = [];
+  const wantsWebGpu = manifest.backend.webgpu !== 'off';
+  const linux = target === 'linux-x64';
+
+  /*
+   * **A software rasteriser is never chosen silently.** Plain headless Chromium selects
+   * SwiftShader on a development machine, measured, and says nothing about it — every
+   * frame it produces is a lie about what a player sees and it saturates the CPU producing it.
+   * `requireHardwareGpu()` refuses it in the capture harness; this refuses it in the product.
+   */
+  if (!manifest.backend.allowSoftwareRenderer) {
+    switches.push(['disable-software-rasterizer', '']);
+  }
+
+  if (linux && wantsWebGpu) {
+    /*
+     * **Electron does not enable WebGPU on Linux although Chrome does** (`electron#40929`), so
+     * without this there is no WebGPU on that target at all — `requestAdapter` simply answers null
+     * and the engine falls back, correctly and invisibly.
+     *
+     * **The interop feature, and deliberately not `--use-angle=vulkan --enable-features=Vulkan`.**
+     * Both yield WebGPU. The second also breaks video encoding under Wayland: measured on an
+     * RX 9070 XT, canvas frames encode as all-zero YUV — a green clip — with nothing reporting it,
+     * since `VideoEncoder.error` never fires and the muxer finalises a file of the expected size.
+     * `ForceEnableWebGpuInterop` composites WebGPU through GL instead of moving ANGLE onto Vulkan,
+     * and both survive: measured in a packaged build on this machine, WebGPU drew and a vp8 round
+     * trip came back magenta rather than green.
+     *
+     * **This is why clip export and WebGPU are no longer refused together.** They were, for as
+     * long as the only switch known to work was the one that broke encoding.
+     *
+     * **What would make it wrong** is a Chromium that retires the feature, at which point WebGPU
+     * quietly stops being offered on Linux and the acceptance probe reports the fallback — which
+     * is the failure mode to watch for rather than a green clip.
+     *
+     * **Reported from outside as hanging a Wayland session, and it does not do that here.** The
+     * report is a packaged game that never paints on AMD under Wayland: an adapter is offered and
+     * the renderer's creation never returns. Chromium does print
+     * `'--ozone-platform=wayland' is not compatible with Vulkan` on stderr while this switch is
+     * applied, on this machine too. But run against the engine's own starter — an RX 9070 XT on a
+     * Wayland session under COSMIC, Electron 43.4.1, Chromium 150 — the acquisition completes in
+     * **153 ms, three runs of three**, and the example draws with WebGPU. The bare path completes
+     * as well: adapter, device, canvas context, swapchain, submit, and a one-pixel readback that
+     * comes back magenta.
+     *
+     * **Chromium's own advice is worse here.** Pairing this with `--ozone-platform=x11`, which is
+     * what that message suggests, takes the GPU process down on this machine: `exit_code=139`, and
+     * a screenshot request answers `UnknownVizError`. So it is not offered.
+     *
+     * The switch is therefore kept, because withdrawing it on every Wayland session would take a
+     * measured-working backend away from every machine like this one. What the report is right
+     * about is that a stall had no floor under it, and that is closed where it belongs: see
+     * `BACKEND_TIMEOUT_MS` in the engine's backend selection, which answers WebGL2 rather than
+     * waiting for a device that is not coming.
+     */
+    /*
+     * **And it is only asked for on a runtime it has been seen to work on.** The switch was
+     * verified once and then travelled, unchecked, into whatever Electron a consumer's install
+     * happened to resolve — which is how a build reached a Chromium whose binary does not contain
+     * the feature name at all. Nothing reported it, because nothing could: an ignored feature name
+     * and an absent adapter produce the same product.
+     */
+    /*
+     * **And there is no second-best route on an older runtime, deliberately.**
+     *
+     * There is one that works: measured on Electron 33.4.11 against this machine, WebGPU comes up
+     * under `--enable-unsafe-webgpu` *and* `--enable-features=Vulkan` together — neither alone
+     * produces an adapter, nor does `--use-angle=vulkan` beside them. It is not offered, for two
+     * reasons that hold together. This package declares the Electron it is written against, so a
+     * build resolving an older one has an install to fix rather than a workaround to adopt; and the
+     * route costs video encoding under Wayland, where canvas frames encode as all-zero YUV — a
+     * green clip, with `VideoEncoder.error` never firing and the muxer finalising a file of the
+     * expected size. Shipping an unsafe flag and that trade, to a configuration this package says
+     * it does not support, is a worse answer than saying so.
+     */
+    if (electronMajor === null || electronMajor >= WEBGPU_INTEROP_ELECTRON) {
+      switches.push(['enable-features', 'ForceEnableWebGpuInterop']);
+    } else if (manifest.backend.webgpu === 'require') {
+      return {
+        switches,
+        notes,
+        refusal:
+          `backend.webgpu is "require" and Electron ${electronMajor} cannot deliver it on Linux. ` +
+          `This package declares Electron ${WEBGPU_INTEROP_ELECTRON}; an install resolving an older ` +
+          'one is the thing to fix. Otherwise set backend.webgpu to "prefer" or "off" to ship ' +
+          'WebGL2 on this target deliberately.',
+      };
+    } else {
+      notes.push(
+        `no WebGPU on Linux: Electron ${electronMajor} predates the interop switch this package is ` +
+          `written against (${WEBGPU_INTEROP_ELECTRON}), so this build falls back to WebGL2 there. ` +
+          'Install the Electron this package declares to get it back.',
+      );
+    }
+  }
+
+  return { switches, refusal: null, notes };
+}

package/src/identity.ts

@@ -0,0 +1,87 @@
+import { existsSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+/** The two fields Node compares to decide whether two paths are the same thing. */
+export interface Identity {
+  readonly dev: bigint;
+  readonly ino: bigint;
+}
+
+/**
+ * Node's own `areIdentical`, which is what decides whether a copy is refused.
+ *
+ * The two zeros are excluded there and here: a filesystem that hands out no index answers 0, and
+ * Node declines to believe it.
+ *
+ * **`bigint` and not `number`.** A Windows file index is 64 bits and loses precision as a double
+ * exactly in the high half where those values live, so two different indices can arrive equal and
+ * two equal ones different — the check would be wrong in both directions on precisely the platform
+ * it exists for.
+ */
+export function sameIdentity(a: Identity, b: Identity): boolean {
+  return a.ino !== 0n && a.dev !== 0n && a.ino === b.ino && a.dev === b.dev;
+}
+
+/**
+ * Refuse a filesystem that cannot tell a file from a directory, before a build spends its minutes.
+ *
+ * **The failure this replaces is a sentence about the one thing that is not happening.** `stage.ts`
+ * copies `drift.package.json` into the staging directory, and Node's `fs.cp` refuses to copy a
+ * thing into itself — deciding that by walking the destination's ancestors and comparing each
+ * one's `dev` and `ino` against the source's. On a filesystem that reports those honestly it never
+ * fires. On a network share it can, and what comes out is
+ *
+ *     cannot copy …\drift.package.json to a subdirectory of self …\out\win-x64\stage\…
+ *
+ * ten minutes into a build, about the thing furthest from the cause you could imagine. Reported
+ * from a Windows VM building over a mapped drive, where a file and a directory both answered
+ * `dev=66313 ino=-112686486700016`: a redirector that gets no file index from the server invents a
+ * constant one, and on Windows `dev` is already the volume serial number.
+ *
+ * **The witnesses are not the directories Node will really compare, and that is fine.**
+ * `checkParentPaths` walks up from `out/<target>/stage` and stops at the source's parent, so it
+ * compares `stage`, `<target>` and `out` — which on a first build do not exist yet and cannot be
+ * stat'ed here. What is being established is not *which* directory collides but that this volume
+ * gives a file and a directory the same identity, which is a property of the volume. The project
+ * root and `out/` are witnesses as good as any.
+ *
+ * **The remedy it names is `--out=<dir>`, and that is what changed.** Until that flag existed the
+ * only answer was to clone onto a local disk, which for a project with tens of gigabytes of assets
+ * is a real cost. Now the output can simply be sent somewhere that tells the truth, and the copy is
+ * the second suggestion rather than the first.
+ *
+ * **`look` is a seam and exists for one reason**: the condition cannot be reproduced on any
+ * filesystem this suite can create, so without it the refusal — the whole point of the function —
+ * would ship having never been seen to fire. The default is `statSync` and no caller passes
+ * anything else.
+ */
+export function refuseLyingFilesystem(
+  cwd: string,
+  outRoot: string | undefined,
+  look: (path: string) => Identity = (path) => statSync(path, { bigint: true }),
+): void {
+  /* Already pointed off this volume: whatever it answers about itself no longer decides a copy. */
+  if (outRoot !== undefined && !resolve(process.cwd(), outRoot).startsWith(resolve(cwd))) return;
+
+  const manifest = join(cwd, 'drift.package.json');
+  if (!existsSync(manifest)) return;
+  const its = look(manifest);
+
+  for (const witness of [cwd, join(cwd, 'out')]) {
+    if (!existsSync(witness)) continue;
+    const theirs = look(witness);
+    if (!sameIdentity(its, theirs)) continue;
+    throw new Error(
+      `${cwd} is on a filesystem that gives a file and a directory the same identity.\n\n` +
+        `  ${manifest}\n      dev=${its.dev} ino=${its.ino}\n` +
+        `  ${witness}\n      dev=${theirs.dev} ino=${theirs.ino}\n\n` +
+        'Node uses those two fields to avoid copying something into itself, so the first copy of ' +
+        'the staging step fails with "cannot copy … to a subdirectory of self …" — a message ' +
+        'about the thing furthest from the cause, ten minutes into a build. It is what a network ' +
+        'share does: the redirector invents a constant file index when the server gives it none.\n\n' +
+        'Send the output somewhere that tells the truth:\n\n' +
+        '    drift-package build --out=/a/local/disk\n\n' +
+        'Or build from a local copy of the project, if the assets are small enough to move.',
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * What a game imports from the packager.
+ *
+ * **The renderer half only.** The main process, the CLI, the builder and the staging step are
+ * Node and are reached through the `drift-package` command rather than through this barrel — a
+ * game bundling `electron` or `esbuild` into its own payload is the failure this boundary exists
+ * to prevent.
+ *
+ * `createHost` is the one call most consumers need; the classes beside it are for a game that
+ * assembles its capabilities itself.
+ */
+export { createHost } from './renderer/host.ts';
+export type { Host } from './renderer/host.ts';
+export { FileStore } from './renderer/fileStore.ts';
+export {
+  NativeDisplay,
+  NativeFileDialogs,
+  NativeLifecycle,
+  hostBridge,
+} from './renderer/nativeHost.ts';
+/*
+ * A store's own features, when a store answered.
+ *
+ * `createHost().services` is how a game reaches these — null in a browser, null where the manifest
+ * named no app, and null when the copy was launched outside the store. The SDK itself is not here:
+ * it is a native Node module held by the main process, because the renderer has no Node at all.
+ */
+export { NativePlatformServices } from './renderer/nativeHost.ts';
+export { BRIDGE_KEY } from './preload/bridge.ts';
+export type { DriftHostBridge } from './preload/bridge.ts';