@driftengine/package 3.63.0 → 4.1.0

package/dist/nativeLicenses.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The native artifact's `licenses/`: Node's licence, and each package's licence files, with an
+ * index saying what every part is under.
+ *
+ * **Because a bundle drops them.** The desktop target ships Electron, whose own licence files come
+ * with it, and a game's web build that its own bundler made. The native target bundles every
+ * package the game and the host import into one file, and most of them are MIT or BSD, whose one
+ * condition is that the notice goes with the copy — so this build is the one that has to carry it.
+ *
+ * **Node's licence is the binary's own**, and covers what Node carries inside it: V8, OpenSSL, ICU
+ * and the rest. It is read from beside the binary where the release archive puts it, or from `n`'s
+ * cache, and otherwise fetched at the exact release that is being shipped. A file there that does
+ * not open as Node's does is passed over, because `LICENSE` one directory above `/usr/local/bin` can
+ * be anybody's.
+ *
+ * **The LGPL 3.0 comes with the GPL 3.0**, because it is written as permissions on top of it and
+ * asks for both texts; the library's own package carries only the first. And **a copyleft package is
+ * named** (`copyleftOf`) so that the build can refuse to bundle one: a dual licence counts as
+ * permissive when either half is.
+ *
+ * What it gives up: a package whose licence is only a word in its manifest has no text to copy, and
+ * the index says so for each one rather than inventing one.
+ */
+/**
+ * Each of `packageDirs` under a copyleft licence, as `name (licence)`. The native build refuses to
+ * bundle one: the LGPL lets a work of any licence use its library so long as a person can put a
+ * modified copy in its place, which one file with the game in it does not allow, and the others
+ * reach further.
+ */
+export declare function copyleftOf(packageDirs: Iterable<string>): string[];
+export type FetchText = (url: string) => Promise<string>;
+/** Node's licence for the binary at `execPath`, which is `version`, or a refusal naming both. */
+export declare function nodeLicense(execPath: string, version: string, fetchText: FetchText): Promise<string>;
+/**
+ * The licences directory for `packageDirs` and Node, written into `into`. `gpl` is the GPL's text,
+ * which goes beside any part under the LGPL 3.0: that licence is written as permissions on top of
+ * the GPL, and its section 4 asks for both texts to accompany a work that uses the library.
+ */
+export declare function writeLicenses(packageDirs: Iterable<string>, node: {
+    readonly version: string;
+    readonly text: string;
+}, into: string, gpl: string | null): Promise<void>;

package/dist/nativeLicenses.js

@@ -0,0 +1,131 @@
+/**
+ * The native artifact's `licenses/`: Node's licence, and each package's licence files, with an
+ * index saying what every part is under.
+ *
+ * **Because a bundle drops them.** The desktop target ships Electron, whose own licence files come
+ * with it, and a game's web build that its own bundler made. The native target bundles every
+ * package the game and the host import into one file, and most of them are MIT or BSD, whose one
+ * condition is that the notice goes with the copy — so this build is the one that has to carry it.
+ *
+ * **Node's licence is the binary's own**, and covers what Node carries inside it: V8, OpenSSL, ICU
+ * and the rest. It is read from beside the binary where the release archive puts it, or from `n`'s
+ * cache, and otherwise fetched at the exact release that is being shipped. A file there that does
+ * not open as Node's does is passed over, because `LICENSE` one directory above `/usr/local/bin` can
+ * be anybody's.
+ *
+ * **The LGPL 3.0 comes with the GPL 3.0**, because it is written as permissions on top of it and
+ * asks for both texts; the library's own package carries only the first. And **a copyleft package is
+ * named** (`copyleftOf`) so that the build can refuse to bundle one: a dual licence counts as
+ * permissive when either half is.
+ *
+ * What it gives up: a package whose licence is only a word in its manifest has no text to copy, and
+ * the index says so for each one rather than inventing one.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { copyFile, mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/** What a package's licence files are called, and its notice, which Apache-2.0 asks to go too. */
+const LICENCE_FILE = /^(licen[cs]e|copying|notice)([.-].*)?$/i;
+const NODE_OPENS = 'Node.js is licensed';
+/** The licences whose terms reach the file a library is bundled into, by their SPDX names. */
+const COPYLEFT = /\b(?:AGPL|LGPL|GPL|MPL|EPL|EUPL|CDDL|OSL)-/i;
+const LGPL3 = /\bLGPL-3\.0/i;
+function manifestOf(dir) {
+    return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+}
+/**
+ * Whether `license`, an SPDX expression, holds a work to a copyleft licence: every alternative of
+ * an `OR` is copyleft, since otherwise a permissive one can be chosen.
+ */
+function copyleft(license) {
+    return license
+        .replace(/[()]/g, '')
+        .split(/\s+OR\s+/i)
+        .every((alternative) => COPYLEFT.test(alternative));
+}
+/**
+ * Each of `packageDirs` under a copyleft licence, as `name (licence)`. The native build refuses to
+ * bundle one: the LGPL lets a work of any licence use its library so long as a person can put a
+ * modified copy in its place, which one file with the game in it does not allow, and the others
+ * reach further.
+ */
+export function copyleftOf(packageDirs) {
+    const found = [];
+    for (const dir of packageDirs) {
+        const { name, license } = manifestOf(dir);
+        if (typeof license === 'string' && copyleft(license))
+            found.push(`${name} (${license})`);
+    }
+    return found;
+}
+/** Node's licence for the binary at `execPath`, which is `version`, or a refusal naming both. */
+export async function nodeLicense(execPath, version, fetchText) {
+    const prefix = dirname(dirname(execPath));
+    for (const candidate of [
+        join(prefix, 'LICENSE'),
+        join(prefix, 'n', 'versions', 'node', version.replace(/^v/, ''), 'LICENSE'),
+    ]) {
+        if (!existsSync(candidate))
+            continue;
+        const text = readFileSync(candidate, 'utf8');
+        if (text.startsWith(NODE_OPENS))
+            return text;
+    }
+    const url = `https://raw.githubusercontent.com/nodejs/node/${version}/LICENSE`;
+    let text;
+    try {
+        text = await fetchText(url);
+    }
+    catch (cause) {
+        throw new Error(`the native artifact ships Node ${version} and must carry Node's licence, and there is no ` +
+            `copy beside ${execPath} and none could be fetched from ${url}: ${String(cause)}`);
+    }
+    if (!text.startsWith(NODE_OPENS)) {
+        throw new Error(`${url} answered a text that is not Node's licence; nothing was written`);
+    }
+    return text;
+}
+/**
+ * The licences directory for `packageDirs` and Node, written into `into`. `gpl` is the GPL's text,
+ * which goes beside any part under the LGPL 3.0: that licence is written as permissions on top of
+ * the GPL, and its section 4 asks for both texts to accompany a work that uses the library.
+ */
+export async function writeLicenses(packageDirs, node, into, gpl) {
+    const packages = [...packageDirs].map((dir) => ({ dir, manifest: manifestOf(dir) }));
+    packages.sort((a, b) => (a.manifest.name < b.manifest.name ? -1 : 1));
+    const lesser = packages.find(({ manifest }) => typeof manifest.license === 'string' && LGPL3.test(manifest.license));
+    if (lesser !== undefined && gpl === null) {
+        throw new Error(`${lesser.manifest.name} is ${String(lesser.manifest.license)}, which asks for the GPL's text ` +
+            'to go with it, and none was given to write beside it');
+    }
+    await mkdir(join(into, 'node'), { recursive: true });
+    await writeFile(join(into, 'node', 'LICENSE'), node.text);
+    const lines = [`node ${node.version} — node/LICENSE`];
+    for (const { dir, manifest } of packages) {
+        const folder = manifest.name.replace('/', '+');
+        const named = typeof manifest.license === 'string' ? manifest.license : 'no licence';
+        const files = readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && LICENCE_FILE.test(entry.name))
+            .map((entry) => entry.name)
+            .sort();
+        const heading = `${manifest.name} ${manifest.version ?? ''} (${named})`;
+        if (files.length === 0) {
+            lines.push(`${heading} — the package carries no licence file; its manifest names ${named}`);
+            continue;
+        }
+        await mkdir(join(into, folder), { recursive: true });
+        for (const file of files)
+            await copyFile(join(dir, file), join(into, folder, file));
+        lines.push(`${heading} — ${files.map((file) => `${folder}/${file}`).join(', ')}`);
+    }
+    if (lesser !== undefined && gpl !== null) {
+        await writeFile(join(into, 'GPL-3.0.txt'), gpl);
+        lines.push('GPL-3.0 — GPL-3.0.txt, which the LGPL-3.0 above is written against and asks to accompany it');
+    }
+    await writeFile(join(into, 'INDEX.txt'), [
+        'Everything this application ships, and the licence each part is under.',
+        '',
+        ...lines,
+        '',
+    ].join('\n'));
+}

package/dist/signing.js

@@ -5,14 +5,14 @@ function has(env, name) {
     return typeof value === 'string' && value.length > 0;
 }
 export function planSigning(target, env, platform) {
-    if (target === 'linux-x64') {
+    if (target === 'linux-x64' || target === 'native-linux-x64') {
         return {
             ...HOST_SIGNED,
             mode: 'none',
             notarise: false,
             /* No signature is expected of a Linux artifact by anything that runs one. An AppImage can
                carry a detached GPG signature and nothing checks it by default, so producing one would be
-               ceremony rather than protection. */
+               ceremony rather than protection. The native host's archive is the same case. */
             reason: 'Linux artifacts are not signed; nothing on the platform checks one',
         };
     }

package/dist/toolchain.js

@@ -167,6 +167,9 @@ export function requirementsFor(target) {
             /* XcodeGen is downloadable; Xcode is not, and pretending otherwise would be the lie this
                file exists to avoid — it is a sign-in and an App Store download, and only on a Mac. */
             return ['macOS', 'Xcode with the iOS SDK', PINS.xcodegen.label];
+        case 'native-linux-x64':
+            /* Nothing of the machine: it ships the Node that runs the build. The host is the game's. */
+            return ["@driftengine/native-host at the packager's version, installed in the game"];
         default:
             return [
                 'the Electron runtime for this platform',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/package",
-  "version": "3.63.0",
+  "version": "4.1.0",
   "description": "Builds an installable application from a game built on the engine",
   "license": "Apache-2.0",
   "type": "module",
@@ -12,6 +12,16 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./bridge": {
+      "drift-source": "./src/preload/bridge.ts",
+      "types": "./dist/preload/bridge.d.ts",
+      "default": "./dist/preload/bridge.js"
+    },
+    "./store": {
+      "drift-source": "./src/main/storeFile.ts",
+      "types": "./dist/main/storeFile.d.ts",
+      "default": "./dist/main/storeFile.js"
+    },
     "./package.json": "./package.json",
     "./*": "./*"
   },
@@ -35,7 +45,7 @@
     "drift-package": "bin/drift-package.mjs"
   },
   "peerDependencies": {
-    "@driftengine/core": "3.63.0",
+    "@driftengine/core": "4.1.0",
     "steamworks.js": ">=0.4.0"
   },
   "dependencies": {

package/src/bootstrap.ts

@@ -36,9 +36,19 @@ import {
 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');
+  const wantsDesktop = targets.some(
+    (target) => target !== 'android' && target !== 'ios' && target !== 'native-linux-x64',
+  );
 
   if (wantsDesktop) await bootstrapElectron();
+  if (targets.includes('native-linux-x64')) {
+    /* A machine is ready for it as it is: the artifact carries the Node running the build, and the
+       host is a dependency of the game, which `npm install` there fetches. */
+    console.log(
+      'ok: native-linux-x64 needs nothing fetched for this machine — it ships the Node running the ' +
+        "build — and the game needs @driftengine/native-host installed, at the packager's version",
+    );
+  }
   if (targets.some((target) => needsRcodesign(target))) await bootstrapRcodesign();
   if (wantsAndroid) await bootstrapAndroid();
   if (wantsIos) await bootstrapIos();

package/src/build.ts

@@ -7,6 +7,7 @@ import { buildAndroid } from './android.ts';
 import { buildIos } from './ios.ts';
 import { crossSignMacApp, zipMacApp } from './macCrossSign.ts';
 import type { PackageManifest, Target } from './manifest.ts';
+import { buildNative } from './native.ts';
 import { outFor } from './outDir.ts';
 import { resourceFile } from './resources.ts';
 import { ensureElectronRuntime } from './runtime.ts';
@@ -45,6 +46,9 @@ const HOST_FOR: Readonly<Record<Target, NodeJS.Platform | null>> = {
   'mac-arm64': 'darwin',
   'mac-x64': 'darwin',
   'linux-x64': 'linux',
+  /* The native host ships the Node that runs the build and the binaries installed beside it;
+     `native.ts` refuses the machine itself, architecture included. */
+  'native-linux-x64': 'linux',
   /* Android's toolchain is Java and it runs anywhere; iOS needs Xcode, which is a Mac. */
   android: null,
   ios: 'darwin',
@@ -84,19 +88,6 @@ export async function build(
   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);
@@ -106,9 +97,30 @@ export async function build(
       await buildIos(manifest, cwd, outFor(cwd, target, options), options);
       continue;
     }
+    if (target === 'native-linux-x64') {
+      await buildNative(manifest, cwd, outFor(cwd, target, options));
+      continue;
+    }
     const refusal = refuseHost(target, process.platform);
     if (refusal !== null) throw new Error(refusal);
 
+    /*
+     * **Electron's builder and version are read here, for an Electron target**, rather than before
+     * the loop: a build of the native target alone needs neither.
+     *
+     * 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 { build: run, Arch, Platform } = await import('electron-builder');
+    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();
+
     /*
      * **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

package/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
-import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { existsSync, 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';
@@ -13,6 +13,7 @@ import { init } from './init.ts';
 import { outFor } from './outDir.ts';
 import { parseManifest } from './manifest.ts';
 import type { PackageManifest, Target } from './manifest.ts';
+import { executableName, nativeHost, nativeNotes, packagerVersion } from './native.ts';
 import { planSigning } from './signing.ts';
 import { electronMajor } from './runtimeVersion.ts';
 import { depotScripts } from './steam/depot.ts';
@@ -40,7 +41,7 @@ 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
+ * Seven 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.
@@ -132,6 +133,20 @@ async function doctor(cwd: string, options: ResourceOptions = {}): Promise<Packa
    * arrive twenty minutes later from Gradle.
    */
   for (const target of manifest.targets) {
+    /*
+     * **The native target asks nothing of the machine and one thing of the game**: it ships the
+     * Node running this, and it needs the host installed beside the game, which `bootstrap` cannot
+     * do because it prepares a machine rather than a project.
+     */
+    if (target === 'native-linux-x64') {
+      for (const note of nativeNotes(manifest)) console.log(`  ${target}: ${note}`);
+      try {
+        nativeHost(cwd, packagerVersion());
+      } catch (cause) {
+        console.log(`  ${target}: ${cause instanceof Error ? cause.message : String(cause)}`);
+      }
+      continue;
+    }
     const ready = await toolchainReady(target);
     if (ready) continue;
     console.log(
@@ -142,10 +157,34 @@ async function doctor(cwd: string, options: ResourceOptions = {}): Promise<Packa
   return manifest;
 }
 
-function verify(cwd: string, needle: string): void {
+/**
+ * **The native target is looked at in its own bundle**, because the build makes that from the game's
+ * source rather than copying the web build: the web build inside it, `public/`, and the copied
+ * modules are left out, so a fresh web build cannot vouch for a stale native one.
+ */
+function verify(
+  cwd: string,
+  needle: string,
+  target: Target | null,
+  options: ResourceOptions,
+): void {
   const manifest = loadManifest(cwd);
-  const root = join(cwd, dirname(manifest.entry));
-  const found = walk(root).some((file) => readFileSync(file, 'utf8').includes(needle));
+  let root = join(cwd, dirname(manifest.entry));
+  let files: string[];
+  if (target === 'native-linux-x64') {
+    root = join(outFor(cwd, target, options), executableName(manifest), 'app');
+    if (!existsSync(root)) {
+      throw new Error(
+        `verify: there is no native build at ${root}; \`drift-package build ` +
+          '--target=native-linux-x64` makes one.',
+      );
+    }
+    const skip = new Set([join(root, 'public'), join(root, 'node_modules')]);
+    files = walk(root).filter((file) => ![...skip].some((dir) => file.startsWith(`${dir}/`)));
+  } else {
+    files = walk(root);
+  }
+  const found = files.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 ` +
@@ -250,7 +289,13 @@ async function writeSteamScripts(
 
   const outDir = outFor(cwd, target, options);
   const content =
-    target === 'linux-x64' ? 'linux-unpacked' : target === 'win-x64' ? 'win-unpacked' : 'mac';
+    target === 'native-linux-x64'
+      ? executableName(manifest)
+      : target === 'linux-x64'
+        ? 'linux-unpacked'
+        : target === 'win-x64'
+          ? 'win-unpacked'
+          : 'mac';
   const scripts = depotScripts({
     appId: manifest.steam.appId,
     depotId,
@@ -340,7 +385,9 @@ try {
   } 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));
+    const asked = rest.find((entry) => entry.startsWith('--target='));
+    const target = asked === undefined ? null : (asked.slice('--target='.length) as Target);
+    verify(cwd, arg.slice('--contains='.length), target, resources);
   } else if (command === 'run') {
     process.exitCode = await run(cwd, resources);
   } else if (command === 'bootstrap') {

package/src/flags.ts

@@ -70,6 +70,24 @@ export function planFlags(
    */
   if (target === 'android' || target === 'ios') return { switches: [], refusal: null, notes: [] };
 
+  /*
+   * **The native host has no Chromium either, and no WebGL2 beneath its WebGPU**: Dawn is its whole
+   * renderer. So a switch is nothing there, and a manifest that turns WebGPU off asks for the one
+   * backend that target does not have — refused, rather than shipped as a window that cannot draw.
+   */
+  if (target === 'native-linux-x64') {
+    return {
+      switches: [],
+      notes: [],
+      refusal:
+        manifest.backend.webgpu === 'off'
+          ? "native-linux-x64 draws with WebGPU alone — Dawn is the host's renderer and there is " +
+            'no WebGL2 beneath it — so backend.webgpu "off" cannot be honoured there. Set it to ' +
+            '"prefer" or "require", or build a desktop target for WebGL2.'
+          : null,
+    };
+  }
+
   const switches: (readonly [string, string])[] = [];
   const notes: string[] = [];
   const wantsWebGpu = manifest.backend.webgpu !== 'off';

package/src/main/ipc.ts

@@ -1,11 +1,11 @@
 import { BrowserWindow, app, dialog, ipcMain, screen } from 'electron';
-import { readFileSync, writeFileSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import type { WindowMode } from '@driftengine/core';
 
 import { SteamCloudStore } from '../steam/cloudStore.ts';
+import { readStoreFile, writeStoreFile, writeStoreFileSync } from './storeFile.ts';
 import type { SteamRuntime } from '../steam/main.ts';
 
 /**
@@ -67,19 +67,8 @@ function cloudSnapshot(steam: SteamRuntime): Record<string, string> {
 }
 
 function readLocalSnapshot(): Record<string, string> {
-  try {
-    const parsed: unknown = JSON.parse(readFileSync(storeFile(), 'utf8'));
-    if (typeof parsed !== 'object' || parsed === null) return {};
-    const out: Record<string, string> = {};
-    for (const [key, value] of Object.entries(parsed)) {
-      if (typeof value === 'string') out[key] = value;
-    }
-    return out;
-  } catch {
-    /* No file yet, or an unreadable one. A fresh store is the right answer to both: a
-       preference is never worth failing a boot for. */
-    return {};
-  }
+  /* No file yet, or an unreadable one, reads as a fresh store: see `storeFile.ts`. */
+  return readStoreFile(storeFile());
 }
 
 /** What the window half needs back from here, so quitting is one decision in one place. */
@@ -114,8 +103,8 @@ export function installIpc(
       for (const [key, value] of entries) cloud.write(key, value);
       return;
     }
-    void writeFile(storeFile(), JSON.stringify(Object.fromEntries(entries)), 'utf8').catch(
-      (cause: unknown) => console.error('[driftengine] could not write the store:', cause),
+    void writeStoreFile(storeFile(), entries).catch((cause: unknown) =>
+      console.error('[driftengine] could not write the store:', cause),
     );
   };
   const schedule = (): void => {
@@ -273,7 +262,7 @@ export function installIpc(
         for (const [key, value] of entries) cloud.write(key, value);
         return;
       }
-      writeFileSync(storeFile(), JSON.stringify(Object.fromEntries(entries)), 'utf8');
+      writeStoreFileSync(storeFile(), entries);
     } catch (cause) {
       console.error('[driftengine] could not write the store on the way out:', cause);
     }

package/src/main/storeFile.ts

@@ -0,0 +1,113 @@
+/**
+ * A shell's key-value store as one JSON file, replaced whole so that nothing ever sees half of it.
+ *
+ * **Written beside the store and renamed over it.** A rename replaces a file in one step, so a
+ * reader — or the next boot, after a crash at any instant — finds the previous store or the next
+ * one and never a mixture. Written in place, as this was until 2026-09-19, the file is empty from
+ * the moment it is opened until the write lands: a test reading it during rewrites found it torn on
+ * 72 reads of 119, and a store that does not parse is read as an empty one, so a crash then costs
+ * the player every setting they ever made, with nothing said. **Synced before the rename**, so the
+ * replacement carries its bytes to the disk before the name moves: without it a power cut can
+ * leave the new name on a file whose contents never arrived.
+ *
+ * **Asynchronous writes land in the order they were asked for.** Each waits for the one before it,
+ * so a large early write finishing after a small late one cannot put the older store back.
+ *
+ * What it gives up: the directory is not synced, so a power cut straight after a rename may bring
+ * back the previous store rather than the new one — a lost second of settings, not a lost store.
+ * Both shells use this: the desktop shell's main process and the native host.
+ */
+
+import {
+  closeSync,
+  fsyncSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeSync,
+} from 'node:fs';
+import { open, rename, rm } from 'node:fs/promises';
+
+type Entries = Iterable<readonly [string, string]>;
+
+/**
+ * The store, or an empty one when there is no file or the file is not a store. A value that is not a
+ * string is dropped. A preference is never worth failing a boot for.
+ */
+export function readStoreFile(path: string): Record<string, string> {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    if (typeof parsed !== 'object' || parsed === null) return {};
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      if (typeof value === 'string') out[key] = value;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+let temporaries = 0;
+/** One name per write, so two writes in flight never share a half-written file. */
+function temporaryFor(path: string): string {
+  temporaries += 1;
+  return `${path}.${process.pid}.${temporaries}.tmp`;
+}
+
+function textOf(entries: Entries): string {
+  return JSON.stringify(Object.fromEntries(entries));
+}
+
+/** Replace the store now, for the way out, where there is no later to wait for. */
+export function writeStoreFileSync(path: string, entries: Entries): void {
+  const temporary = temporaryFor(path);
+  try {
+    const file = openSync(temporary, 'w');
+    try {
+      writeSync(file, textOf(entries));
+      fsyncSync(file);
+    } finally {
+      closeSync(file);
+    }
+    renameSync(temporary, path);
+  } catch (cause) {
+    rmSync(temporary, { force: true });
+    throw cause;
+  }
+}
+
+const queues = new Map<string, Promise<void>>();
+
+/** Replace the store after every write already asked for, with `entries` as they are now. */
+export function writeStoreFile(path: string, entries: Entries): Promise<void> {
+  const text = textOf(entries);
+  const before = queues.get(path) ?? Promise.resolve();
+  const next = before
+    .catch(() => undefined)
+    .then(async () => {
+      const temporary = temporaryFor(path);
+      try {
+        const file = await open(temporary, 'w');
+        try {
+          await file.writeFile(text, 'utf8');
+          await file.sync();
+        } finally {
+          await file.close();
+        }
+        await rename(temporary, path);
+      } catch (cause) {
+        await rm(temporary, { force: true });
+        throw cause;
+      }
+    });
+  queues.set(path, next);
+  /* Forgotten once it is the last, so the map holds nothing for a store no longer written. */
+  void next
+    .catch(() => undefined)
+    .then(() => {
+      if (queues.get(path) === next) queues.delete(path);
+    });
+  return next;
+}

package/src/main/window.ts

@@ -163,7 +163,10 @@ export async function startApp(
        the single most common way a packaged web application looks unfinished. */
     window.once('ready-to-show', () => window?.show());
   } else {
-    const startedAt = Date.now();
+    /* Monotonic. Every reading here is subtracted from another and compared against a minimum,
+       and a wall clock that steps backwards holds the badge forever while one that steps forwards
+       flashes it and shows a white window. */
+    const startedAt = performance.now();
     let painted = false;
     let badgeShownAt: number | null = null;
     window.once('ready-to-show', () => {
@@ -175,7 +178,7 @@ export async function startApp(
      * the time it is meant to be readable for — so it is counted from here.
      */
     splash.once('show', () => {
-      badgeShownAt ??= Date.now();
+      badgeShownAt ??= performance.now();
     });
     /*
      * And a badge that cannot load is not worth holding a game for: counting its minimum from
@@ -186,7 +189,7 @@ export async function startApp(
       badgeShownAt ??= startedAt;
     });
     const poll = setInterval(() => {
-      const now = Date.now();
+      const now = performance.now();
       const sinceBadge = badgeShownAt === null ? null : now - badgeShownAt;
       if (splashDecision(now - startedAt, sinceBadge, manifest.splash.minMs, painted) === 'hold')
         return;