@driftengine/package 3.61.0

package/dist/main/ipc.js

@@ -0,0 +1,284 @@
+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 { SteamCloudStore } from '../steam/cloudStore.js';
+/**
+ * The main-process half of the bridge: a file-backed store, dialogs, focus, and quit.
+ *
+ * **The store is read once, synchronously, before the window exists.** That is what lets the
+ * renderer satisfy `KeyValueStore`'s synchronous contract; see `preload/bridge.ts` for why that
+ * contract is not negotiable. Writes are debounced to one file write, because a settings screen
+ * with a slider writes on every frame of a drag and a save per frame is a stutter.
+ *
+ * **Three channels answer synchronously** — the snapshot, fullscreen state and refresh rate — and
+ * that is a deliberate cost. A synchronous IPC blocks the renderer, so each is a single value
+ * read at boot or from a settings screen, never anything per frame.
+ */
+const storeFile = () => join(app.getPath('userData'), 'store.json');
+/** Milliseconds a write waits for its neighbours. A drag writes every frame; disk should not. */
+const WRITE_DEBOUNCE_MS = 250;
+/** How long a quit waits for a game that asked to be told about it. */
+const QUIT_GRACE_MS = 3000;
+/**
+ * What the game starts with, read from wherever this build's saves live.
+ *
+ * Steam Cloud first where a store answered, because a player who moved machines expects their
+ * settings to have travelled — and falling back to the local file when the cloud has nothing is
+ * what makes the first launch after enabling Steam keep the saves it already had.
+ */
+export function readStoreSnapshot(steam = null) {
+    if (steam !== null) {
+        const cloud = cloudSnapshot(steam);
+        if (Object.keys(cloud).length > 0)
+            return cloud;
+    }
+    return readLocalSnapshot();
+}
+/**
+ * Every key Steam Cloud holds for this application.
+ *
+ * The API lists files rather than keys, and `SteamCloudStore` writes one file per key with a
+ * `.txt` suffix — so the mapping is undone here rather than guessed at by a caller.
+ */
+function cloudSnapshot(steam) {
+    const out = {};
+    try {
+        const cloud = steam.cloud;
+        for (const file of cloud.listFiles?.() ?? []) {
+            if (!file.name.endsWith('.txt'))
+                continue;
+            const value = cloud.readFile(file.name);
+            if (typeof value === 'string' && value.length > 0) {
+                out[file.name.slice(0, -'.txt'.length)] = value;
+            }
+        }
+    }
+    catch {
+        /* Cloud storage off for this title or this account. The local file is the answer. */
+    }
+    return out;
+}
+function readLocalSnapshot() {
+    try {
+        const parsed = JSON.parse(readFileSync(storeFile(), 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return {};
+        const out = {};
+        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 {};
+    }
+}
+export function installIpc(snapshot, windowOf, steam = null) {
+    const entries = new Map(Object.entries(snapshot));
+    let pending = null;
+    /*
+     * **Where a save actually lands, decided once, here.** A game asks the same `KeyValueStore` for
+     * its preferences whatever platform it is on; whether those bytes go to a file beside the
+     * application or into Steam Cloud — and therefore onto the player's other machine — is this
+     * process's decision and nothing the renderer can see. That is the whole return on the seam.
+     */
+    const cloud = steam === null ? null : new SteamCloudStore(steam.cloud);
+    const flush = () => {
+        pending = null;
+        if (cloud !== null) {
+            for (const [key, value] of entries)
+                cloud.write(key, value);
+            return;
+        }
+        void writeFile(storeFile(), JSON.stringify(Object.fromEntries(entries)), 'utf8').catch((cause) => console.error('[driftengine] could not write the store:', cause));
+    };
+    const schedule = () => {
+        if (pending === null)
+            pending = setTimeout(flush, WRITE_DEBOUNCE_MS);
+    };
+    ipcMain.on('drift:snapshot', (event) => {
+        event.returnValue = Object.fromEntries(entries);
+    });
+    ipcMain.on('drift:write', (_event, key, value) => {
+        entries.set(key, value);
+        schedule();
+    });
+    ipcMain.on('drift:remove', (_event, key) => {
+        entries.delete(key);
+        schedule();
+    });
+    ipcMain.on('drift:platformAvailable', (event) => {
+        event.returnValue = steam !== null;
+    });
+    ipcMain.on('drift:achievement', (_event, id) => steam?.unlockAchievement(id));
+    ipcMain.on('drift:presence', (_event, text) => steam?.setRichPresence(text));
+    ipcMain.on('drift:isFullscreen', (event) => {
+        event.returnValue = windowOf()?.isFullScreen() ?? false;
+    });
+    ipcMain.handle('drift:setFullscreen', (_event, on) => {
+        windowOf()?.setFullScreen(on);
+    });
+    ipcMain.on('drift:refreshHz', (event) => {
+        event.returnValue = refreshHzFor(windowOf());
+    });
+    ipcMain.on('drift:mode', (event) => {
+        event.returnValue = windowOf()?.isFullScreen() === true ? 'fullscreen' : 'windowed';
+    });
+    ipcMain.handle('drift:setMode', (_event, mode) => {
+        const window = windowOf();
+        if (window === null)
+            return false;
+        window.setFullScreen(mode === 'fullscreen');
+        /* Read back rather than assume. A window manager may refuse, and a settings screen that
+           believed the request would show a state the desktop disagrees with. */
+        return window.isFullScreen() === (mode === 'fullscreen');
+    });
+    ipcMain.on('drift:size', (event) => {
+        const [width = 0, height = 0] = windowOf()?.getContentSize() ?? [];
+        event.returnValue = { width, height };
+    });
+    /**
+     * Whether a resize would be performed, decided once for the two handlers that need it.
+     *
+     * **Refused while the window is covering a display**, because there is nothing honest to do:
+     * Chromium never takes an exclusive fullscreen, so there is no display mode to change, and
+     * resizing the window out from under a fullscreen state would silently leave it. A game that
+     * wants fewer pixels while fullscreen changes its render scale, which is the engine's own
+     * `RenderQuality`, not the window's business.
+     *
+     * **One function and not two conditions**, because the two handlers below answer the same
+     * question — one by doing it and one by being asked — and a pair that drifted would give a
+     * settings screen a greyed control that works, or a live one that does nothing. `AGENTS.md` calls
+     * that shape out on its own: two implementations of one decision drift, and they drift invisibly
+     * when they start identical.
+     */
+    const resizable = () => {
+        const window = windowOf();
+        return window !== null && !window.isFullScreen();
+    };
+    /*
+     * Synchronous, like `drift:size`: a settings screen asks this while it is drawing a control, and
+     * an answer a frame later would draw the control twice.
+     */
+    ipcMain.on('drift:canSetSize', (event) => {
+        event.returnValue = resizable();
+    });
+    ipcMain.handle('drift:setSize', (_event, width, height) => {
+        if (!resizable())
+            return false;
+        const window = windowOf();
+        if (window === null)
+            return false;
+        window.setContentSize(Math.round(width), Math.round(height));
+        return true;
+    });
+    ipcMain.on('drift:displays', (event) => {
+        const primary = screen.getPrimaryDisplay();
+        event.returnValue = screen.getAllDisplays().map((display) => ({
+            id: String(display.id),
+            /* A platform that has no name for a display gets its size, which is what a person picking
+               between two monitors in a list actually recognises. */
+            label: typeof display.label === 'string' && display.label.length > 0
+                ? display.label
+                : `${display.size.width}x${display.size.height}`,
+            width: display.size.width,
+            height: display.size.height,
+            scale: display.scaleFactor,
+            refreshHz: typeof display.displayFrequency === 'number' && display.displayFrequency > 0
+                ? display.displayFrequency
+                : null,
+            primary: display.id === primary.id,
+        }));
+    });
+    /*
+     * **Quitting is a two-part protocol and the interest flag is what keeps it cheap.** A game that
+     * registers `onQuitRequest` wants a moment to flush a save; a game that does not must close
+     * instantly. Without the flag the only correct implementation defers *every* close for a grace
+     * period, which is three seconds of nothing on the way out of a game that had nothing to say.
+     */
+    let noticeWanted = false;
+    let closing = false;
+    ipcMain.on('drift:quitInterest', () => {
+        noticeWanted = true;
+    });
+    ipcMain.on('drift:quit', () => {
+        closing = true;
+        app.quit();
+    });
+    ipcMain.handle('drift:openFile', async (_event, accept) => {
+        const result = await dialog.showOpenDialog({
+            properties: ['openFile'],
+            filters: [{ name: 'files', extensions: accept.map((entry) => entry.replace(/^\./, '')) }],
+        });
+        const path = result.filePaths[0];
+        if (result.canceled || path === undefined)
+            return null;
+        return { name: path.split(/[\\/]/).pop() ?? path, bytes: new Uint8Array(await readFile(path)) };
+    });
+    ipcMain.handle('drift:saveFile', async (_event, name, bytes) => {
+        const result = await dialog.showSaveDialog({ defaultPath: name });
+        if (result.canceled || result.filePath === undefined)
+            return false;
+        await writeFile(result.filePath, bytes);
+        return true;
+    });
+    /*
+     * **Flushed synchronously on the way out, and the synchronous part is the whole point.**
+     *
+     * A debounce that loses its last write loses exactly the setting somebody just changed before
+     * quitting — and an *asynchronous* flush here loses it too, silently, because `app.quit()`
+     * tears the process down without waiting for a promise. Measured: a probe that wrote a key and
+     * then asked to quit left no file at all. A blocking write of a few kilobytes on the way out is
+     * not a cost anybody can perceive; the alternative is a settings screen that sometimes works.
+     */
+    app.on('before-quit', () => {
+        if (pending === null)
+            return;
+        clearTimeout(pending);
+        pending = null;
+        try {
+            if (cloud !== null) {
+                for (const [key, value] of entries)
+                    cloud.write(key, value);
+                return;
+            }
+            writeFileSync(storeFile(), JSON.stringify(Object.fromEntries(entries)), 'utf8');
+        }
+        catch (cause) {
+            console.error('[driftengine] could not write the store on the way out:', cause);
+        }
+    });
+    return {
+        wantsNotice: () => noticeWanted,
+        mayClose: () => closing,
+        deferClose: (window) => {
+            window.webContents.send('drift:quitRequest');
+            /* The grace is a ceiling, not a wait: a game that answers with `requestQuit` closes at
+               once. Without one, a game that hangs must not make the window unclosable. */
+            setTimeout(() => {
+                closing = true;
+                window.close();
+            }, QUIT_GRACE_MS);
+        },
+    };
+}
+/**
+ * The refresh rate of the display this window is on, which the browser implementation of
+ * `DisplayControl` has to answer null for.
+ *
+ * Null rather than a plausible 60 where the platform withholds it, matching the engine's rule:
+ * something will divide by this.
+ */
+export function refreshHzFor(window) {
+    if (window === null)
+        return null;
+    const bounds = window.getBounds();
+    const display = screen.getDisplayNearestPoint({ x: bounds.x, y: bounds.y });
+    return typeof display.displayFrequency === 'number' && display.displayFrequency > 0
+        ? display.displayFrequency
+        : null;
+}

package/dist/main/links.d.ts

@@ -0,0 +1 @@
+export declare function externalTarget(url: string): string | null;

package/dist/main/links.js

@@ -0,0 +1,29 @@
+/**
+ * Which links leave the application, and which are refused outright.
+ *
+ * **A link to the web opens in the person's own browser.** That is what a packaged application is
+ * expected to do — their bookmarks, their session, their extensions, an address bar and a way back
+ * — and it is also the safer of the two: a second Electron window is a browser with no address bar
+ * that nobody is maintaining, showing a page that can then see how it was opened.
+ *
+ * **Everything else is refused, and that list is short on purpose.** `shell.openExternal` hands a
+ * string to the operating system: `file:` opens whatever it names, and a handler-registered scheme
+ * can launch another application with an argument. A page that controls a link would then control
+ * that. So three schemes leave — `http`, `https` and `mailto` — and everything else, including the
+ * game's own `drift://`, answers null.
+ *
+ * Pure, so every one of those refusals is a test rather than a comment.
+ */
+const ALLOWED = new Set(['http:', 'https:', 'mailto:']);
+export function externalTarget(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        /* Not a URL at all. A relative link inside the game never reaches here — it resolves against
+           drift:// before anything asks — so this is a malformed one, and nothing opens it. */
+        return null;
+    }
+    return ALLOWED.has(parsed.protocol) ? url : null;
+}

package/dist/main/menu.d.ts

@@ -0,0 +1,17 @@
+import type { MenuItemConstructorOptions } from 'electron';
+/**
+ * The menu a shipped game has, which on two of three platforms is none.
+ *
+ * Electron installs a default menu bar with File, Edit, View, Window and Help. Nothing in it
+ * belongs to a game — two of its items reload the page and open developer tools — and its presence
+ * is the single clearest sign that what you are looking at is a web page in a frame.
+ *
+ * **macOS is the exception, and not for appearance.** The application menu is where `Cmd+Q`,
+ * `Cmd+H` and the services menu live; an application with no menu on that platform is one a person
+ * cannot quit with the shortcut every other application answers to. So it keeps the smallest menu
+ * that behaves like a Mac application: the app menu, Edit — where copy and paste are roles rather
+ * than key handlers a game would have to write — and Window.
+ *
+ * Pure, so the shape is testable without a running Electron.
+ */
+export declare function appMenuTemplate(productName: string, platform: NodeJS.Platform): MenuItemConstructorOptions[] | null;

package/dist/main/menu.js

@@ -0,0 +1,49 @@
+/**
+ * The menu a shipped game has, which on two of three platforms is none.
+ *
+ * Electron installs a default menu bar with File, Edit, View, Window and Help. Nothing in it
+ * belongs to a game — two of its items reload the page and open developer tools — and its presence
+ * is the single clearest sign that what you are looking at is a web page in a frame.
+ *
+ * **macOS is the exception, and not for appearance.** The application menu is where `Cmd+Q`,
+ * `Cmd+H` and the services menu live; an application with no menu on that platform is one a person
+ * cannot quit with the shortcut every other application answers to. So it keeps the smallest menu
+ * that behaves like a Mac application: the app menu, Edit — where copy and paste are roles rather
+ * than key handlers a game would have to write — and Window.
+ *
+ * Pure, so the shape is testable without a running Electron.
+ */
+export function appMenuTemplate(productName, platform) {
+    if (platform !== 'darwin')
+        return null;
+    return [
+        {
+            label: productName,
+            submenu: [
+                { role: 'about' },
+                { type: 'separator' },
+                { role: 'hide' },
+                { role: 'hideOthers' },
+                { role: 'unhide' },
+                { type: 'separator' },
+                { role: 'quit' },
+            ],
+        },
+        {
+            label: 'Edit',
+            submenu: [
+                { role: 'undo' },
+                { role: 'redo' },
+                { type: 'separator' },
+                { role: 'cut' },
+                { role: 'copy' },
+                { role: 'paste' },
+                { role: 'selectAll' },
+            ],
+        },
+        {
+            label: 'Window',
+            submenu: [{ role: 'minimize' }, { role: 'zoom' }, { role: 'front' }],
+        },
+    ];
+}

package/dist/main/serve.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A path inside the packaged application, or null when it is not inside it.
+ *
+ * **Separate from the protocol handler so it can be tested at all.** This is the only part of the
+ * main process with a security consequence: the renderer runs with `nodeIntegration: false` and
+ * `sandbox: true`, so `drift://` is the single filesystem surface it can reach, and a traversal
+ * through it hands a compromised renderer the disk.
+ *
+ * The separator in the comparison is load-bearing. A plain `startsWith(root)` accepts
+ * `/app-secrets` for a root of `/app`, which is a sibling directory rather than a child.
+ */
+export declare function resolveWithinRoot(root: string, pathname: string): string | null;
+/**
+ * A content type, from the extension, for the handful a game serves.
+ *
+ * **A wrong one is not cosmetic here.** A module served as `text/plain` is refused by the module
+ * loader with a message about MIME type, and a `.wasm` served as anything but
+ * `application/wasm` cannot be streamed-compiled. Everything unrecognised is
+ * `application/octet-stream`, which is correct for the container and for every asset.
+ */
+export declare function contentTypeFor(path: string): string;

package/dist/main/serve.js

@@ -0,0 +1,69 @@
+import { join, normalize, sep } from 'node:path';
+/**
+ * A path inside the packaged application, or null when it is not inside it.
+ *
+ * **Separate from the protocol handler so it can be tested at all.** This is the only part of the
+ * main process with a security consequence: the renderer runs with `nodeIntegration: false` and
+ * `sandbox: true`, so `drift://` is the single filesystem surface it can reach, and a traversal
+ * through it hands a compromised renderer the disk.
+ *
+ * The separator in the comparison is load-bearing. A plain `startsWith(root)` accepts
+ * `/app-secrets` for a root of `/app`, which is a sibling directory rather than a child.
+ */
+export function resolveWithinRoot(root, pathname) {
+    const resolved = normalize(join(root, pathname));
+    if (resolved === root)
+        return resolved;
+    return resolved.startsWith(root + sep) ? resolved : null;
+}
+/**
+ * A content type, from the extension, for the handful a game serves.
+ *
+ * **A wrong one is not cosmetic here.** A module served as `text/plain` is refused by the module
+ * loader with a message about MIME type, and a `.wasm` served as anything but
+ * `application/wasm` cannot be streamed-compiled. Everything unrecognised is
+ * `application/octet-stream`, which is correct for the container and for every asset.
+ */
+export function contentTypeFor(path) {
+    const dot = path.lastIndexOf('.');
+    switch (dot === -1 ? '' : path.slice(dot + 1).toLowerCase()) {
+        case 'html':
+            return 'text/html; charset=utf-8';
+        case 'js':
+        case 'mjs':
+            return 'text/javascript; charset=utf-8';
+        case 'css':
+            return 'text/css; charset=utf-8';
+        case 'json':
+            return 'application/json; charset=utf-8';
+        case 'wasm':
+            return 'application/wasm';
+        case 'svg':
+            /* An `<img>` refuses an SVG served as anything else, and the shell's own badge is one:
+               the splash showed a broken-image icon until this case existed. */
+            return 'image/svg+xml';
+        case 'png':
+            return 'image/png';
+        case 'jpg':
+        case 'jpeg':
+            return 'image/jpeg';
+        case 'webp':
+            return 'image/webp';
+        case 'gif':
+            return 'image/gif';
+        case 'ico':
+            return 'image/x-icon';
+        case 'txt':
+            return 'text/plain; charset=utf-8';
+        case 'ktx2':
+            return 'image/ktx2';
+        case 'ogg':
+            return 'audio/ogg';
+        case 'mp3':
+            return 'audio/mpeg';
+        case 'wav':
+            return 'audio/wav';
+        default:
+            return 'application/octet-stream';
+    }
+}

package/dist/main/shortcuts.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The browser's own key bindings, taken away from a shipped game.
+ *
+ * **Chromium answers these itself and there is no menu item to remove.** With the menu bar gone a
+ * player still has Ctrl+R and F5 reloading the game mid-run, Ctrl+P offering to print it, Ctrl+F
+ * opening a find bar over it, Ctrl+minus shrinking the whole interface, and Ctrl+Shift+I opening
+ * an inspector on it. None of those belong to a game, and every one of them is somebody's bug
+ * report about a run they lost.
+ *
+ * **In a development run nothing is blocked**, because those are exactly the tools a developer
+ * wants. The build kind is decided by `build.json`, written by the packager — never by an
+ * environment variable a player could set.
+ *
+ * **Quit is left alone on macOS**, and so is Cmd+W: they are what every application on that
+ * platform answers to, and a game that swallowed them would be the one a person cannot get out
+ * of. Ctrl+W elsewhere is a browser habit rather than a platform one, and goes.
+ *
+ * Pure, and every rule above is a test.
+ */
+export interface KeyPress {
+    readonly type: string;
+    readonly key: string;
+    readonly control: boolean;
+    readonly meta: boolean;
+    readonly shift: boolean;
+    readonly alt: boolean;
+}
+export declare function isBlockedShortcut(input: KeyPress, platform: NodeJS.Platform, development: boolean): boolean;

package/dist/main/shortcuts.js

@@ -0,0 +1,26 @@
+/** Reload, print, view source, find, and the two zoom directions plus reset. */
+const WITH_MODIFIER = new Set(['r', 'p', 'u', 'f', 'g', '+', '-', '=', '0']);
+/** The inspector, on the two combinations every platform binds it to. */
+const INSPECTOR = new Set(['i', 'j', 'c']);
+export function isBlockedShortcut(input, platform, development) {
+    if (development)
+        return false;
+    if (input.type !== 'keyDown')
+        return false;
+    const key = input.key.toLowerCase();
+    if (key === 'f5' || key === 'f12')
+        return true;
+    const command = input.control || input.meta;
+    if (!command)
+        return false;
+    if (input.shift && INSPECTOR.has(key))
+        return true;
+    if (input.meta && input.alt && INSPECTOR.has(key))
+        return true;
+    if (WITH_MODIFIER.has(key))
+        return true;
+    /* Closing: a platform gesture on macOS, a browser one everywhere else. */
+    if (key === 'w' && input.control && platform !== 'darwin')
+        return true;
+    return false;
+}

package/dist/main/splash.d.ts

@@ -0,0 +1,14 @@
+import { BrowserWindow } from 'electron';
+/**
+ * The window the engine badge is drawn in.
+ *
+ * Frameless and fixed, because a splash somebody can resize is a splash somebody has to think
+ * about. Opaque rather than transparent: transparency on Linux depends on a compositor that may
+ * not be there, and the failure is a black rectangle with the logo cut out of it — worse than
+ * having no rounded corners.
+ *
+ * **Shown on its own first paint, not on creation.** The same rule the main window follows, for
+ * the same reason: a window that appears empty and then fills is the thing this page exists to
+ * prevent, and a splash that does it is an unusually poor joke.
+ */
+export declare function createSplash(): BrowserWindow;

package/dist/main/splash.js

@@ -0,0 +1,41 @@
+import { BrowserWindow } from 'electron';
+/**
+ * The window the engine badge is drawn in.
+ *
+ * Frameless and fixed, because a splash somebody can resize is a splash somebody has to think
+ * about. Opaque rather than transparent: transparency on Linux depends on a compositor that may
+ * not be there, and the failure is a black rectangle with the logo cut out of it — worse than
+ * having no rounded corners.
+ *
+ * **Shown on its own first paint, not on creation.** The same rule the main window follows, for
+ * the same reason: a window that appears empty and then fills is the thing this page exists to
+ * prevent, and a splash that does it is an unusually poor joke.
+ */
+export function createSplash() {
+    const splash = new BrowserWindow({
+        width: 420,
+        height: 300,
+        frame: false,
+        resizable: false,
+        movable: false,
+        minimizable: false,
+        maximizable: false,
+        fullscreenable: false,
+        skipTaskbar: true,
+        /* Above the game's own window, which is hidden until the swap, and above whatever else is
+           on screen for the second or two it lives. A splash that can be buried looks like a hang. */
+        alwaysOnTop: true,
+        show: false,
+        backgroundColor: '#0b0b0d',
+        webPreferences: {
+            /* It runs no script and reaches nothing. There is no bridge here on purpose: the badge has
+               no business holding a handle to the filesystem. */
+            contextIsolation: true,
+            nodeIntegration: false,
+            sandbox: true,
+        },
+    });
+    splash.once('ready-to-show', () => splash.show());
+    void splash.loadURL('drift://shell/splash.html');
+    return splash;
+}

package/dist/main/splashTiming.d.ts

@@ -0,0 +1,36 @@
+/**
+ * When the badge gives the screen to the game.
+ *
+ * Two conditions and a cap, and each is there for a failure that has a name:
+ *
+ *   - **The game has painted.** Swapping before that shows a white or black window while the
+ *     first frame is still being built, which is the thing a splash exists to prevent.
+ *   - **The minimum has passed *since the badge reached the screen*.** A badge that vanishes the
+ *     instant a fast machine paints is a flicker rather than a splash, and the machines that boot
+ *     fastest are the ones a developer tests on. Measured from the badge rather than from process
+ *     start because the badge's own arrival is an unbounded wait — a second window, a protocol
+ *     handler and an SVG — and measuring the budget from before it started is how a splash gets
+ *     closed before it is ever shown. Timed on one machine at `minMs: 900`: the badge reached the
+ *     screen at 411 ms unpacked and at 1659 ms as an AppImage, where the whole budget had already
+ *     elapsed. It survived there only because the game happened to paint later still.
+ *   - **The cap overrides both.** A boot that never finishes must not leave a logo as the whole
+ *     product; past the cap the window is shown whatever state it is in, because a broken game
+ *     that can be seen is better than a brand that cannot be dismissed.
+ *
+ * Pure, so all three are testable without a window: the caller owns the clock.
+ */
+export type SplashDecision = 'hold' | 'swap';
+/**
+ * The ceiling on the whole splash, whatever the manifest asked for.
+ *
+ * Twenty seconds is long enough for a large world to stream in on a slow disk — which is exactly
+ * the boot a splash should cover — and short enough that a failure is seen in the same sitting.
+ */
+export declare const SPLASH_HARD_CAP_MS = 20000;
+/**
+ * @param sinceStartMs Since the main window was created, which is what the cap is measured against.
+ * @param sinceBadgeMs Since the badge reached the screen, or `null` while it has not. A caller that
+ *   has given up on the badge ever appearing passes `sinceStartMs`, which is the behaviour this had
+ *   before the badge was waited for at all.
+ */
+export declare function splashDecision(sinceStartMs: number, sinceBadgeMs: number | null, minMs: number, contentReady: boolean, capMs?: number): SplashDecision;

package/dist/main/splashTiming.js

@@ -0,0 +1,24 @@
+/**
+ * The ceiling on the whole splash, whatever the manifest asked for.
+ *
+ * Twenty seconds is long enough for a large world to stream in on a slow disk — which is exactly
+ * the boot a splash should cover — and short enough that a failure is seen in the same sitting.
+ */
+export const SPLASH_HARD_CAP_MS = 20_000;
+/**
+ * @param sinceStartMs Since the main window was created, which is what the cap is measured against.
+ * @param sinceBadgeMs Since the badge reached the screen, or `null` while it has not. A caller that
+ *   has given up on the badge ever appearing passes `sinceStartMs`, which is the behaviour this had
+ *   before the badge was waited for at all.
+ */
+export function splashDecision(sinceStartMs, sinceBadgeMs, minMs, contentReady, capMs = SPLASH_HARD_CAP_MS) {
+    if (sinceStartMs >= capMs)
+        return 'swap';
+    if (!contentReady)
+        return 'hold';
+    /* The game is ready and the badge is not on screen yet: showing the game now is what makes a
+       splash vanish entirely on somebody else's machine. The cap above is what bounds this. */
+    if (sinceBadgeMs === null)
+        return 'hold';
+    return sinceBadgeMs >= minMs ? 'swap' : 'hold';
+}