@driftengine/package 3.61.0

package/src/bootstrap.ts

@@ -0,0 +1,389 @@
+import { spawn } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
+import { chmod, readdir, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+import type { Target } from './manifest.ts';
+import {
+  PINS,
+  ensureDir,
+  findAndroidSdk,
+  findGradle,
+  findJavaHome,
+  findRcodesign,
+  findXcodeGen,
+  needsRcodesign,
+  toolchainHome,
+} from './toolchain.ts';
+
+/**
+ * Fetch everything a target needs to be built, so nobody has to install seven things by hand.
+ *
+ * **This is the command that makes the other ones work on a fresh machine.** A packaging toolchain
+ * is a JDK, an Android SDK, a Gradle distribution and an Electron runtime, in pinned versions;
+ * every one of those is a download and a licence prompt, and a README that lists them is a README
+ * somebody follows wrongly at two in the morning.
+ *
+ * **Nothing is installed system-wide and nothing needs a password.** Everything lands under a
+ * cache directory this owns, and a machine that already has a working toolchain — `JAVA_HOME`,
+ * `ANDROID_HOME` — is used as it is rather than duplicated.
+ *
+ * **Only what is actually downloadable is downloaded.** Xcode is not: it is a sign-in and an App
+ * Store install on a Mac, so the iOS branch prints what to get rather than pretending.
+ */
+export async function bootstrap(targets: readonly Target[]): Promise<void> {
+  const wantsAndroid = targets.includes('android');
+  const wantsIos = targets.includes('ios');
+  const wantsDesktop = targets.some((target) => target !== 'android' && target !== 'ios');
+
+  if (wantsDesktop) await bootstrapElectron();
+  if (targets.some((target) => needsRcodesign(target))) await bootstrapRcodesign();
+  if (wantsAndroid) await bootstrapAndroid();
+  if (wantsIos) await bootstrapIos();
+}
+
+/**
+ * `rcodesign`, which signs a Mac target on a machine that has no `codesign`.
+ *
+ * **Fetched only when a Mac target is asked for off a Mac**, because that is the only situation
+ * where the platform's own signer is missing. On a Mac this is never downloaded: `codesign` ships
+ * with the command line tools and electron-builder drives it directly.
+ *
+ * A single static musl binary, so unlike the JDK there is nothing to discover in the archive and
+ * nothing that cares which distribution it lands on.
+ */
+async function bootstrapRcodesign(): Promise<void> {
+  const existing = await findRcodesign();
+  if (existing !== null) {
+    console.log(`ok: rcodesign is present at ${existing}`);
+    return;
+  }
+
+  const asset = rcodesignAsset();
+  if (asset === null) {
+    throw new Error(
+      `there is no published rcodesign for ${process.platform}/${process.arch}. ` +
+        '`cargo install apple-codesign` builds one, and the build will find it in ~/.cargo/bin',
+    );
+  }
+
+  const home = toolchainHome();
+  await ensureDir(home);
+  console.log(`fetching ${PINS.rcodesign.label}…`);
+  const archive = join(home, asset.archive);
+  await download(
+    'https://github.com/indygreg/apple-platform-rs/releases/download/' +
+      `apple-codesign%2F${PINS.rcodesign.version}/${asset.archive}`,
+    archive,
+  );
+
+  const staging = join(home, 'rcodesign-unpack');
+  await rm(staging, { recursive: true, force: true });
+  await ensureDir(staging);
+  await extract(archive, staging);
+
+  /* The archive unpacks one directory named for the triple, holding the binary and its licences.
+     The binary is searched for rather than assumed at that path: the name of the wrapper
+     directory is the one part of a release asset that has changed before. */
+  const found = await findFile(
+    staging,
+    process.platform === 'win32' ? 'rcodesign.exe' : 'rcodesign',
+  );
+  if (found === null) throw new Error('the rcodesign archive did not contain a binary');
+
+  const target = join(home, `rcodesign-${PINS.rcodesign.version}`);
+  await rm(target, { recursive: true, force: true });
+  await ensureDir(target);
+  const binary = join(target, 'rcodesign');
+  await rename(found, binary);
+  await chmod(binary, 0o755).catch(() => undefined);
+  await rm(staging, { recursive: true, force: true });
+  await rm(archive, { force: true });
+  console.log(`ok: rcodesign is at ${binary}`);
+}
+
+/** Which published rcodesign asset this machine can run, or null if the release page has none. */
+function rcodesignAsset(): { readonly archive: string } | null {
+  const version = PINS.rcodesign.version;
+  if (process.platform === 'linux') {
+    /* musl rather than gnu: the release publishes only the static build, which is the one that
+       does not care about the host's glibc. */
+    const arch = process.arch === 'arm64' ? 'aarch64' : 'x86_64';
+    return { archive: `apple-codesign-${version}-${arch}-unknown-linux-musl.tar.gz` };
+  }
+  if (process.platform === 'win32') {
+    return { archive: `apple-codesign-${version}-x86_64-pc-windows-msvc.zip` };
+  }
+  return null;
+}
+
+/** The first file with this name anywhere under a directory, or null. */
+async function findFile(root: string, name: string): Promise<string | null> {
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    const full = join(root, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await findFile(full, name);
+      if (nested !== null) return nested;
+    } else if (entry.name === name) {
+      return full;
+    }
+  }
+  return null;
+}
+
+/**
+ * The Electron runtime, which npm sometimes does not fetch.
+ *
+ * Its binary arrives through a postinstall script, and an install run with scripts disabled —
+ * which several sandboxes, CI images and corporate setups do by default — leaves the package
+ * present and the runtime missing. The failure that produces is `Electron failed to install
+ * correctly` at the moment somebody first tries to run a game.
+ */
+async function bootstrapElectron(): Promise<void> {
+  const require = (await import('node:module')).createRequire(import.meta.url);
+  let installer: string;
+  try {
+    installer = require.resolve('electron/install.js');
+  } catch {
+    throw new Error('electron is not installed; run npm install first');
+  }
+  const dist = join(installer, '..', 'dist');
+  if (await pathExists(dist)) {
+    console.log('ok: the Electron runtime is present');
+    return;
+  }
+  console.log('fetching the Electron runtime…');
+  await run(process.execPath, [installer], {});
+  console.log('ok: the Electron runtime is present');
+}
+
+async function bootstrapAndroid(): Promise<void> {
+  const home = toolchainHome();
+  await ensureDir(home);
+
+  const javaHome = (await findJavaHome()) ?? (await installJdk(home));
+  const sdkRoot = (await findAndroidSdk()) ?? (await installAndroidSdk(home, javaHome));
+  await installAndroidPackages(sdkRoot, javaHome);
+  const gradle = (await findGradle()) ?? (await installGradle(home));
+
+  console.log(`ok: android toolchain ready`);
+  console.log(`  JDK:     ${javaHome}`);
+  console.log(`  SDK:     ${sdkRoot}`);
+  console.log(`  Gradle:  ${gradle}`);
+}
+
+async function bootstrapIos(): Promise<void> {
+  if (process.platform !== 'darwin') {
+    console.log('ios: this is not a Mac, and an iOS build needs one. Nothing to fetch here.');
+    return;
+  }
+
+  const home = toolchainHome();
+  await ensureDir(home);
+  if ((await findXcodeGen()) === null) {
+    console.log(`fetching ${PINS.xcodegen.label}…`);
+    const archive = join(home, 'xcodegen.zip');
+    await download(
+      `https://github.com/yonaskolb/XcodeGen/releases/download/${PINS.xcodegen.version}/xcodegen.zip`,
+      archive,
+    );
+    const target = join(home, `xcodegen-${PINS.xcodegen.version}`);
+    await rm(target, { recursive: true, force: true });
+    await ensureDir(target);
+    await extract(archive, target);
+    /* The archive unpacks a `xcodegen/` directory containing bin and share; flattened so the
+       path this file resolves is the path `findXcodeGen` looks for. */
+    const [inner] = await readdir(target);
+    if (inner !== undefined && inner === 'xcodegen') {
+      await rename(join(target, 'xcodegen', 'bin'), join(target, 'bin'));
+      await rename(join(target, 'xcodegen', 'share'), join(target, 'share')).catch(() => undefined);
+    }
+    await chmod(join(target, 'bin', 'xcodegen'), 0o755).catch(() => undefined);
+    await rm(archive, { force: true });
+  }
+
+  /* Xcode itself cannot be fetched, so it is checked for and named rather than installed. */
+  try {
+    await run('xcodebuild', ['-version'], { quiet: true });
+    console.log('ok: Xcode is here, and so is XcodeGen');
+  } catch {
+    console.log('ios: XcodeGen is ready; Xcode is not.');
+    console.log('  - install Xcode from the App Store, then `xcode-select --install`');
+    console.log('  - a free Apple ID installs to your own device for seven days at a time;');
+    console.log('    the paid Developer Program is what makes a build last and reach TestFlight');
+  }
+}
+
+/** Temurin, from the Adoptium API, which redirects to the current build of the pinned feature. */
+async function installJdk(home: string): Promise<string> {
+  const os =
+    process.platform === 'win32' ? 'windows' : process.platform === 'darwin' ? 'mac' : 'linux';
+  const arch = process.arch === 'arm64' ? 'aarch64' : 'x64';
+  const url =
+    `https://api.adoptium.net/v3/binary/latest/${PINS.jdk.feature}/ga/${os}/${arch}` +
+    '/jdk/hotspot/normal/eclipse';
+
+  console.log(`fetching ${PINS.jdk.label}…`);
+  const archive = join(home, os === 'windows' ? 'jdk.zip' : 'jdk.tar.gz');
+  await download(url, archive);
+
+  const staging = join(home, 'jdk-unpack');
+  await rm(staging, { recursive: true, force: true });
+  await ensureDir(staging);
+  await extract(archive, staging);
+  /* Every JDK archive unpacks into one versioned directory; the pin is on the feature release, so
+     the exact name changes with each patch and is discovered rather than assumed. */
+  const [inner] = await readdir(staging);
+  if (inner === undefined) throw new Error('the JDK archive unpacked into nothing');
+  const target = join(home, 'jdk');
+  await rm(target, { recursive: true, force: true });
+  await rename(join(staging, inner), target);
+  await rm(staging, { recursive: true, force: true });
+  await rm(archive, { force: true });
+  return target;
+}
+
+async function installAndroidSdk(home: string, javaHome: string): Promise<string> {
+  const os = process.platform === 'win32' ? 'win' : process.platform === 'darwin' ? 'mac' : 'linux';
+  const url = `https://dl.google.com/android/repository/commandlinetools-${os}-${PINS.androidTools.build}_latest.zip`;
+
+  console.log(`fetching ${PINS.androidTools.label}…`);
+  const archive = join(home, 'cmdline-tools.zip');
+  await download(url, archive);
+
+  const sdkRoot = join(home, 'android-sdk');
+  const staging = join(home, 'cmdline-unpack');
+  await rm(staging, { recursive: true, force: true });
+  await ensureDir(staging);
+  await extract(archive, staging);
+  /* sdkmanager insists on living at `cmdline-tools/latest/`, and the archive unpacks a directory
+     called `cmdline-tools`. Getting this wrong produces a tool that refuses to run and blames the
+     SDK root rather than its own location. */
+  await ensureDir(join(sdkRoot, 'cmdline-tools'));
+  await rm(join(sdkRoot, 'cmdline-tools', 'latest'), { recursive: true, force: true });
+  await rename(join(staging, 'cmdline-tools'), join(sdkRoot, 'cmdline-tools', 'latest'));
+  await rm(staging, { recursive: true, force: true });
+  await rm(archive, { force: true });
+
+  await acceptLicences(sdkRoot, javaHome);
+  return sdkRoot;
+}
+
+/**
+ * Accept the SDK licences, which is a prompt that cannot be skipped and can be answered.
+ *
+ * Google requires an explicit acceptance per licence before any package installs. Answering it by
+ * piping `y` is what every CI image does; it is recorded here rather than hidden because accepting
+ * a licence on somebody's behalf is a thing they should be able to see in a diff.
+ */
+async function acceptLicences(sdkRoot: string, javaHome: string): Promise<void> {
+  console.log('accepting the Android SDK licences…');
+  await run(sdkManager(sdkRoot), [`--sdk_root=${sdkRoot}`, '--licenses'], {
+    env: { JAVA_HOME: javaHome },
+    stdin: `${'y\n'.repeat(64)}`,
+    quiet: true,
+  });
+}
+
+async function installAndroidPackages(sdkRoot: string, javaHome: string): Promise<void> {
+  console.log(`installing ${PINS.androidPackages.join(', ')}…`);
+  await run(sdkManager(sdkRoot), [`--sdk_root=${sdkRoot}`, ...PINS.androidPackages], {
+    env: { JAVA_HOME: javaHome },
+    quiet: true,
+  });
+}
+
+async function installGradle(home: string): Promise<string> {
+  console.log(`fetching ${PINS.gradle.label}…`);
+  const archive = join(home, 'gradle.zip');
+  await download(
+    `https://services.gradle.org/distributions/gradle-${PINS.gradle.version}-bin.zip`,
+    archive,
+  );
+  await extract(archive, home);
+  await rm(archive, { force: true });
+  const binary = join(
+    home,
+    `gradle-${PINS.gradle.version}`,
+    'bin',
+    process.platform === 'win32' ? 'gradle.bat' : 'gradle',
+  );
+  if (!(await pathExists(binary))) throw new Error('the Gradle archive did not contain a launcher');
+  return binary;
+}
+
+function sdkManager(sdkRoot: string): string {
+  const name = process.platform === 'win32' ? 'sdkmanager.bat' : 'sdkmanager';
+  return join(sdkRoot, 'cmdline-tools', 'latest', 'bin', name);
+}
+
+async function download(url: string, to: string): Promise<void> {
+  const response = await fetch(url, { redirect: 'follow' });
+  if (!response.ok || response.body === null) {
+    throw new Error(`could not download ${url}: ${response.status} ${response.statusText}`);
+  }
+  /* The DOM's `ReadableStream` and Node's are structurally the same and typed apart; the cast is
+     at the one line where the two type worlds meet rather than spread through the signature. */
+  await pipeline(
+    Readable.fromWeb(response.body as Parameters<typeof Readable.fromWeb>[0]),
+    createWriteStream(to),
+  );
+}
+
+/**
+ * Unpack an archive with whatever this machine has.
+ *
+ * `tar` handles both formats on macOS and on Windows, where it is bsdtar; GNU tar on Linux cannot
+ * read a zip, so `unzip` is tried first for those. Two attempts rather than a dependency: an
+ * archive extractor is a large amount of code to carry for a step that runs once per machine.
+ */
+async function extract(archive: string, into: string): Promise<void> {
+  if (archive.endsWith('.zip')) {
+    try {
+      await run('unzip', ['-q', '-o', archive, '-d', into], { quiet: true });
+      return;
+    } catch {
+      await run('tar', ['-xf', archive, '-C', into], { quiet: true });
+      return;
+    }
+  }
+  await run('tar', ['-xzf', archive, '-C', into], { quiet: true });
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await (await import('node:fs/promises')).access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+interface RunOptions {
+  readonly env?: Readonly<Record<string, string>>;
+  readonly stdin?: string;
+  readonly quiet?: boolean;
+}
+
+async function run(command: string, args: readonly string[], options: RunOptions): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(command, [...args], {
+      env: { ...process.env, ...options.env },
+      stdio: [
+        options.stdin === undefined ? 'ignore' : 'pipe',
+        options.quiet === true ? 'ignore' : 'inherit',
+        'inherit',
+      ],
+    });
+    if (options.stdin !== undefined && child.stdin !== null) {
+      child.stdin.write(options.stdin);
+      child.stdin.end();
+    }
+    child.on('error', reject);
+    child.on('close', (code) =>
+      code === 0 ? resolve() : reject(new Error(`${command} exited with ${String(code)}`)),
+    );
+  });
+}

package/src/build.ts

@@ -0,0 +1,285 @@
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { buildAndroid } from './android.ts';
+import { buildIos } from './ios.ts';
+import { crossSignMacApp, zipMacApp } from './macCrossSign.ts';
+import type { PackageManifest, Target } from './manifest.ts';
+import { outFor } from './outDir.ts';
+import { resourceFile } from './resources.ts';
+import { ensureElectronRuntime } from './runtime.ts';
+import type { ResourceOptions } from './resources.ts';
+import { planSigning } from './signing.ts';
+import { consumerVersion, stageApp } from './stage.ts';
+import { findRcodesign } from './toolchain.ts';
+
+/**
+ * An installable artifact per target.
+ *
+ * **The builder configuration is derived, not authored.** Every value it needs is already in
+ * `drift.package.json`, and a second configuration file would be a second place for the
+ * application id to be wrong — which is the failure that is silent until saves land in a directory
+ * nobody looks in.
+ *
+ * **Linux gets a native artifact and that is a Steam Deck decision**, recorded here because it
+ * looks like an ordinary target otherwise: a Windows build under Proton is the default assumption
+ * and it carries a known regression — gamepads undetected in Electron under Proton after 26.6.10,
+ * where the same build works natively. Valve's own guidance points the same way.
+ *
+ * **A target is refused where this machine cannot honestly produce it**, and the interesting word
+ * is *honestly*: the danger was never a build error, it is an artifact that looks finished and
+ * will not launch, or one that cannot be signed. `scripts/` carries the Windows and macOS hosts.
+ *
+ * **macOS is the one target that moved off that rule, and only from Linux.** Nothing in a Mac
+ * build is compiled — Electron ships a prebuilt darwin runtime and packing it is file copying and
+ * a plist — so the artifact itself was never the problem. The signature was: electron-builder
+ * skips signing off darwin, and an unsigned binary is refused by Apple Silicon's loader. With
+ * `rcodesign` putting an ad-hoc signature on afterwards, the two things a Linux host still cannot
+ * do are named rather than worked around — there is no `.dmg`, because that is `hdiutil`, and
+ * there is no proof it launches, because that needs the machine it runs on. See `macCrossSign.ts`.
+ */
+const HOST_FOR: Readonly<Record<Target, NodeJS.Platform | null>> = {
+  'win-x64': 'win32',
+  'mac-arm64': 'darwin',
+  'mac-x64': 'darwin',
+  'linux-x64': 'linux',
+  /* Android's toolchain is Java and it runs anywhere; iOS needs Xcode, which is a Mac. */
+  android: null,
+  ios: 'darwin',
+};
+
+/**
+ * Why this machine cannot build that target, or null.
+ *
+ * A Mac target is allowed from Linux and still refused from Windows — that second refusal is
+ * electron-builder's own and would fire a few seconds later anyway, so it is stated here where
+ * the reason can be given.
+ */
+function refuseHost(target: Target, platform: NodeJS.Platform): string | null {
+  const host = HOST_FOR[target];
+  if (host === null || platform === host) return null;
+
+  if ((target === 'mac-arm64' || target === 'mac-x64') && platform === 'linux') return null;
+
+  if (target === 'mac-arm64' || target === 'mac-x64') {
+    return (
+      `${target} is cross-built from Linux and built natively on a Mac, and this is ${platform}. ` +
+      'electron-builder refuses a Mac target on Windows outright, so there is nothing to work ' +
+      'around here.'
+    );
+  }
+
+  return (
+    `${target} is built on ${String(host)}, and this is ${platform}. ` +
+    'See packages/package/scripts for the Windows and macOS hosts; cross-building under ' +
+    'Wine cannot reach a certificate store, which is the one platform where that matters.'
+  );
+}
+
+export async function build(
+  manifest: PackageManifest,
+  cwd: string,
+  targets: readonly Target[],
+  options: ResourceOptions = {},
+): Promise<void> {
+  const { build: run, Arch, Platform } = await import('electron-builder');
+
+  /* One artifact per target, and the architecture is named rather than inherited: a build on an
+     Apple Silicon machine defaults to arm64, so `mac-x64` asked for on one would quietly produce
+     the wrong slice. */
+  const targetFor = (name: Target): ReturnType<typeof Platform.LINUX.createTarget> =>
+    name === 'win-x64'
+      ? Platform.WINDOWS.createTarget(undefined, Arch.x64)
+      : name === 'linux-x64'
+        ? Platform.LINUX.createTarget(undefined, Arch.x64)
+        : Platform.MAC.createTarget(undefined, name === 'mac-x64' ? Arch.x64 : Arch.arm64);
+  const electronVersion = await installedElectronVersion();
+
+  for (const target of targets) {
+    if (target === 'android') {
+      await buildAndroid(manifest, cwd, outFor(cwd, target, options), options);
+      continue;
+    }
+    if (target === 'ios') {
+      await buildIos(manifest, cwd, outFor(cwd, target, options), options);
+      continue;
+    }
+    const refusal = refuseHost(target, process.platform);
+    if (refusal !== null) throw new Error(refusal);
+
+    /*
+     * **The runtime, before anything is staged.** `installedElectronVersion` below reads a version
+     * out of `electron/package.json`, which is in the npm tarball — so it answers even when the
+     * postinstall that downloads the actual binary never finished, and electron-builder then finds
+     * nothing to package several steps and several minutes later. Measured in this repository on
+     * 2026-08-29: a version of 43.4.1 against no `dist`. See `runtime.ts`.
+     */
+    await ensureElectronRuntime();
+
+    const signing = planSigning(target, process.env, process.platform);
+    if (signing.refusal !== null) throw new Error(`${target}: ${signing.refusal}`);
+    console.log(`[drift-package] ${target}: signing ${signing.mode} — ${signing.reason}`);
+
+    /*
+     * **Looked up before anything is staged.** Signing is the last step of a build that takes
+     * minutes, and a missing signer discovered there costs the whole thing — so the tool is
+     * resolved while the failure is still cheap.
+     */
+    const rcodesign = signing.crossSign ? await findRcodesign() : null;
+    if (signing.crossSign && rcodesign === null) {
+      throw new Error(
+        `${target} is signed here by rcodesign, and there is none on this machine. ` +
+          `Run \`drift-package bootstrap --target=${target}\`, which fetches it into a cache.`,
+      );
+    }
+
+    const outDir = outFor(cwd, target, options);
+    const stageDir = join(outDir, 'stage');
+    await stageApp(manifest, cwd, stageDir, { development: false, ...options });
+
+    /* Where the signing step found the `.app`, so the archive below does not have to guess at
+       electron-builder's own naming for the packed directory. */
+    const signed: { app: string | null } = { app: null };
+
+    await run({
+      targets: targetFor(target),
+      /*
+       * **The staged directory is the project, not just the application.** Pointed at the
+       * consumer's own directory instead, electron-builder looks for *their* `package.json`,
+       * tries to install *their* dependencies into the artifact, and fails on a project that
+       * has neither — which a game built by any other toolchain may well not.
+       */
+      projectDir: stageDir,
+      config: {
+        appId: manifest.id,
+        productName: manifest.name,
+        electronVersion,
+        /* One 1024px PNG for all three platforms: electron-builder derives an `.ico` and an
+           `.icns` from it, and a game that supplies its own replaces exactly this line. */
+        icon:
+          manifest.icon === null
+            ? await resourceFile('assets', 'icon.png', options.resourceRoot)
+            : resolve(cwd, manifest.icon),
+        directories: { output: outDir },
+        /* The staged directory is the application, whole. Nothing is filtered here because
+           nothing that should not ship was put there: see `stage.ts` for what it contains. */
+        files: ['**/*'],
+        /*
+         * **A native module cannot be loaded from inside an asar archive.** `steamworks.js` is a
+         * `.node` binary, and one packed into the archive fails at `require` with a message about
+         * a path that does not exist — which reads as a missing dependency rather than as a
+         * packing decision. Unpacked, and only it.
+         */
+        asarUnpack: ['**/node_modules/steamworks.js/**'],
+        /*
+         * **The signature goes on between packing and archiving, and that ordering is the whole
+         * point.** `afterPack` runs once the `.app` is complete and before any target wraps it, so
+         * the signed bundle is the one that ends up inside the `.zip`. Signing afterwards would
+         * leave the artifact people download carrying the unsigned copy.
+         */
+        afterPack: rcodesign === null ? undefined : macSignStep(rcodesign, target, signed),
+        mac: {
+          hardenedRuntime: signing.mode === 'real',
+          category: 'public.app-category.games',
+          /*
+           * `'-'` is `codesign`'s own spelling of an ad-hoc identity. `null` means *do not sign*,
+           * which on Apple Silicon means *does not run* — and is exactly right when this build
+           * signs the app itself a few lines below, because electron-builder would otherwise log
+           * a warning about skipping a step that is not being skipped.
+           */
+          identity: signing.crossSign ? null : signing.mode === 'adhoc' ? '-' : undefined,
+          notarize: signing.notarise,
+          /*
+           * **Both of electron-builder's Mac archives are macOS-only, for different reasons.** A
+           * `.dmg` is built by `hdiutil`, which exists nowhere else. Its `.zip` is worse than
+           * unavailable: it is produced by 7-Zip off darwin, which dereferences the symlinks every
+           * `.framework` is made of, and the result is a corrupt bundle rather than an error.
+           *
+           * So a cross-build asks for `dir` — pack the `.app` and stop — and the archive is made
+           * afterwards by `zipMacApp`, which keeps the links.
+           */
+          target: signing.crossSign ? ['dir'] : ['dmg', 'zip'],
+        },
+        win: {
+          target: ['nsis', 'zip'],
+          /* Nothing is named here: electron-builder reads `WIN_CSC_LINK`/`CSC_LINK` from the
+             environment itself, and repeating them is a second place for them to be wrong. */
+        },
+        linux: { target: ['AppImage', 'tar.gz'], category: 'Game' },
+      },
+    });
+
+    /*
+     * **The archive, for a cross-build only.** electron-builder was asked for `dir` above because
+     * neither of its Mac archives can be produced correctly off a Mac, so the artifact somebody
+     * downloads is made here — see `zipMacApp` for what 7-Zip does to a framework.
+     *
+     * The name matches what electron-builder would have written, so a Mac-built release and a
+     * Linux-built one are the same file under the same name.
+     */
+    if (signed.app !== null) {
+      const version = await consumerVersion(cwd);
+      const arch = target === 'mac-x64' ? 'x64' : 'arm64';
+      await zipMacApp(signed.app, join(outDir, `${manifest.name}-${version}-${arch}-mac.zip`));
+    }
+  }
+}
+
+/**
+ * The `afterPack` hook that ad-hoc signs a cross-built `.app`, or nothing on a Mac.
+ *
+ * A factory rather than an inline closure so the resolved signer is a `string` inside it: the
+ * lookup and the refusal happen once, before a build starts, and this cannot be reached without
+ * one. `electronPlatformName` is checked because the hook is called for whatever is being packed.
+ */
+function macSignStep(
+  rcodesign: string,
+  target: Target,
+  signed: { app: string | null },
+): (context: {
+  readonly appOutDir: string;
+  readonly electronPlatformName: string;
+}) => Promise<void> {
+  return async (context) => {
+    if (context.electronPlatformName !== 'darwin') return;
+    const app = await packedApp(context.appOutDir);
+    console.log(`[drift-package] ad-hoc signing ${app} with rcodesign`);
+    await crossSignMacApp({
+      app,
+      rcodesign,
+      arch: target === 'mac-x64' ? 'x64' : 'arm64',
+    });
+    console.log('[drift-package] signed, and every nested bundle checked');
+    signed.app = app;
+  };
+}
+
+/** The `.app` electron-builder just wrote, found rather than named after the product. */
+async function packedApp(appOutDir: string): Promise<string> {
+  const { readdir } = await import('node:fs/promises');
+  const found = (await readdir(appOutDir)).filter((entry) => entry.endsWith('.app'));
+  if (found.length !== 1) {
+    throw new Error(
+      `expected one .app in ${appOutDir} and found ${found.length ? found.join(', ') : 'none'}`,
+    );
+  }
+  return join(appOutDir, found[0] as string);
+}
+
+/**
+ * The Electron the artifact will carry, read from what is installed rather than declared.
+ *
+ * The staged application has no dependencies of its own — both entry points are bundled — so
+ * electron-builder has nothing to infer a version from and would refuse. Reading the installed
+ * one keeps the artifact and this repository on the same runtime by construction.
+ */
+export async function installedElectronVersion(): Promise<string> {
+  const require = createRequire(import.meta.url);
+  const manifestPath = require.resolve('electron/package.json');
+  const raw: unknown = JSON.parse(await readFile(manifestPath, 'utf8'));
+  const version = (raw as { version?: unknown }).version;
+  if (typeof version !== 'string') throw new Error('electron is installed without a version');
+  return version;
+}