@driftengine/core 4.11.0 → 4.12.0

package/dist/ui/splash.js

@@ -80,8 +80,9 @@ export const SPLASH_FADE_MS = 420;
 /**
  * When the badge gives the screen to the game. Two conditions and a cap, each for a named failure.
  *
- *   - **The game has painted.** Swapping before that shows the empty canvas the badge exists to
- *     cover.
+ *   - **The game has painted**, and every promise it asked the badge to wait for has settled
+ *     (`holdSplash`). Swapping before that shows the empty canvas, or the half-loaded first screen,
+ *     the badge exists to cover.
  *   - **The minimum has passed.** A badge that vanishes the instant a fast machine paints is a
  *     flicker, and the machines that boot fastest are the ones a developer tests on.
  *   - **The cap overrides both**, and is checked first so that a minimum longer than the cap
@@ -99,6 +100,58 @@ export function splashDecision(elapsedMs, minMs, contentReady, capMs = SPLASH_HA
         return 'hold';
     return elapsedMs >= minMs ? 'swap' : 'hold';
 }
+/**
+ * What a badge waits for besides the clock: the game's first frame, and every promise the game asked
+ * it to wait for (`holdSplash`), under the cap the game named, the longest of several, or the engine's.
+ *
+ * **A hold settles whichever way its promise does.** A load that failed must not pin the logo: the
+ * game is shown, broken and visible, which is the cap's own argument. Pure apart from the promises,
+ * so the rule is testable in Node.
+ */
+export class SplashState {
+    /** Whether a frame of the game has reached the screen. */
+    painted = false;
+    pending = 0;
+    /** The longest cap a hold has named, or 0 for none. */
+    asked = 0;
+    /** The longest the badge may stay: the cap a hold named, the longest of several, or the engine's. */
+    get capMs() {
+        return this.asked > 0 ? this.asked : SPLASH_HARD_CAP_MS;
+    }
+    /** Wait for `until` too, under `capMs` where it names one; `settled` once it has. */
+    hold(until, capMs, settled) {
+        this.pending += 1;
+        if (capMs !== undefined && Number.isFinite(capMs) && capMs > this.asked)
+            this.asked = capMs;
+        const done = () => {
+            this.pending -= 1;
+            settled();
+        };
+        Promise.resolve(until).then(done, done);
+    }
+    /** Painted, with every hold settled: what `splashDecision` calls the content being ready. */
+    get ready() {
+        return this.painted && this.pending === 0;
+    }
+}
+/** The badge on the page, which `holdSplash` holds. One screen, so one badge: see `bootGate.ts`. */
+let mounted = null;
+/**
+ * Keep the engine's badge up until `until` settles, as well as until the game's first frame: a game
+ * whose first screen loads for longer than that frame — a stage, figures and their pictures on a
+ * first visit — is seen whole rather than loading. **`capMs` is the game's own ceiling** on the
+ * badge in place of the engine's twenty seconds, longer for a slow first visit or shorter, so a load
+ * that never settles is still shown in the end; the longest of several holds' wins, and the minimum
+ * hold is unchanged.
+ *
+ * **Frames run while the game loads behind the plate**, since a load may need them, and are held
+ * once it has settled, for whatever is left of the minimum, as they are after a first frame with no
+ * hold. Returns whether there was a badge to hold: none in a packaged build, whose shell shows its
+ * own until the first frame, nor where `splash: false` or `?splash=0` turned it off.
+ */
+export function holdSplash(until, options = {}) {
+    return mounted?.holdUntil(until, options.capMs) ?? false;
+}
 /**
  * The badge markup. One constant string, interpolated into nothing.
  *
@@ -228,17 +281,18 @@ export function mountSplash(options = {}) {
                the document and already styled; nothing here needs to be undone. */
         }
     }
-    let painted = false;
+    const state = new SplashState();
     let leaving = false;
     let timer = null;
     /*
-     * **Freeze the game the moment it has proved it can draw.**
+     * **Freeze the game the moment it has proved it can draw and has loaded.**
      *
-     * `painted` is the first `endFrame`, and everything after it until the plate leaves is time the
-     * game would otherwise spend running behind an opaque screen. `bootGate` is read by `startLoop`
+     * Ready is the first `endFrame` with every hold settled (`SplashState`), and everything after it
+     * until the plate leaves is time the game would otherwise spend running behind an opaque screen.
+     * Before it, frames run: a load the game is holding the badge for may need them. `bootGate` is read by `startLoop`
      * and named by neither of them; see its own comment for why the state is shared that way.
      */
-    const openGate = holdFrames(() => painted && !leaving);
+    const openGate = holdFrames(() => state.ready && !leaving);
     const remove = () => {
         /* Leaving the top layer is what `hidePopover` is for. `remove()` alone takes the element out
            of the document, and an element removed while shown is not a state worth relying on. */
@@ -256,6 +310,8 @@ export function mountSplash(options = {}) {
         if (leaving)
             return;
         leaving = true;
+        if (mounted === badge)
+            mounted = null;
         /* Before the fade, not after it: the game resumes as the plate becomes transparent, so what
            shows through is a running frame rather than the still one it was frozen on. */
         openGate();
@@ -278,23 +334,32 @@ export function mountSplash(options = {}) {
         if (leaving)
             return;
         const elapsed = performance.now() - started;
-        if (splashDecision(elapsed, minMs, painted) === 'swap') {
+        if (splashDecision(elapsed, minMs, state.ready, state.capMs) === 'swap') {
             release();
             return;
         }
         if (timer !== null)
             clearTimeout(timer);
-        const next = painted ? minMs - elapsed : SPLASH_HARD_CAP_MS - elapsed;
+        const next = state.ready ? minMs - elapsed : state.capMs - elapsed;
         timer = setTimeout(settle, Math.max(0, next));
     };
-    settle();
-    return {
+    const badge = {
         present() {
-            if (painted || leaving)
+            if (state.painted || leaving)
                 return;
-            painted = true;
+            state.painted = true;
             settle();
         },
         release,
+        holdUntil(until, capMs) {
+            if (leaving)
+                return false;
+            state.hold(until, capMs, settle);
+            settle();
+            return true;
+        },
     };
+    mounted = badge;
+    settle();
+    return badge;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.11.0",
+  "version": "4.12.0",
   "description": "The runtime of DriftEngine, a WebGPU game engine with a WebGL2 fallback: renderer, loop, input, cameras, scene graph and physics",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.11.0",
-    "@driftengine/physics": "4.11.0",
+    "@driftengine/drft": "4.12.0",
+    "@driftengine/physics": "4.12.0",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -67,8 +67,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.11.0",
-    "@driftengine/network": "4.11.0",
-    "@driftengine/texture": "4.11.0"
+    "@driftengine/nav": "4.12.0",
+    "@driftengine/network": "4.12.0",
+    "@driftengine/texture": "4.12.0"
   }
 }

package/scripts/browser.d.mts

@@ -7,6 +7,11 @@ export interface LaunchedBrowser {
   close(): Promise<void>;
 }
 
+/** Where a Chromium-based browser lives on a platform, in the order `chromePath` tries them. */
+export function browserCandidates(
+  platform?: string,
+  env?: Readonly<Record<string, string | undefined>>,
+): string[];
 export function chromePath(): string;
 export function launch(options?: {
   flags?: readonly string[];

package/scripts/browser.mjs

@@ -27,22 +27,64 @@
  * it, and it is what turns "leaks accumulate forever" into "at most one leak per still-running
  * process."
  */
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { once } from 'node:events';
 import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { sleep } from './cdp.mjs';
 
-/** Where a Chrome or Chromium lives, in the order worth trying. `CHROME_PATH` wins. */
-const CANDIDATES = [
-  '/opt/google/chrome/chrome',
-  '/usr/bin/google-chrome',
-  '/usr/bin/google-chrome-stable',
-  '/usr/bin/chromium',
-  '/usr/bin/chromium-browser',
-  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-];
+/**
+ * Where a Chromium-based browser lives on each platform, in the order worth trying.
+ *
+ * **Edge is last on every list and the only thing on Windows that is always there.** It is
+ * Chromium, it speaks the same DevTools protocol, and it ships with Windows 10 and 11, so a person
+ * who never installed Chrome still has a browser this module can drive. Chrome comes first where it
+ * exists because it is what the engine's captures are measured on.
+ *
+ * Windows paths are built from the environment rather than written out, because `Program Files`
+ * is wherever that machine put it and a per-user install sits under `LOCALAPPDATA`; a Mac's
+ * per-user install sits under `~/Applications`. Nothing here has been run on Windows or macOS by
+ * this repository yet; the lists are the browsers' documented install locations.
+ */
+export function browserCandidates(platform = process.platform, env = process.env) {
+  if (platform === 'win32') {
+    const roots = [env['PROGRAMFILES'], env['PROGRAMFILES(X86)'], env['LOCALAPPDATA']].filter(
+      (root) => typeof root === 'string' && root !== '',
+    );
+    return [
+      ...roots.map((root) =>
+        path.win32.join(root, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+      ),
+      ...roots.map((root) =>
+        path.win32.join(root, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+      ),
+    ];
+  }
+  if (platform === 'darwin') {
+    /* `/Applications` for an install by an administrator, `~/Applications` for one without. */
+    const roots = [
+      '/Applications',
+      typeof env['HOME'] === 'string' && env['HOME'] !== ''
+        ? path.posix.join(env['HOME'], 'Applications')
+        : null,
+    ].filter((root) => root !== null);
+    const apps = [
+      'Google Chrome.app/Contents/MacOS/Google Chrome',
+      'Chromium.app/Contents/MacOS/Chromium',
+      'Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    ];
+    return apps.flatMap((app) => roots.map((root) => path.posix.join(root, app)));
+  }
+  return [
+    '/opt/google/chrome/chrome',
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/usr/bin/microsoft-edge',
+  ];
+}
 
 /**
  * What it takes to reach the real card from a headless process.
@@ -80,7 +122,7 @@ const PROFILE_PREFIX = 'driftengine-shots-';
 const OWNER_FILE = 'driftengine-owner.json';
 
 /**
- * Signal an entire process group, escalating if it does not go.
+ * Stop a browser and every process it started, escalating if it does not go.
  *
  * **Chrome is a tree, not a process.** It forks a zygote, a GPU process and one renderer per
  * page, and signalling the parent alone leaves the rest running with the port closed and the
@@ -89,9 +131,20 @@ const OWNER_FILE = 'driftengine-owner.json';
  *
  * SIGTERM first because a browser asked politely flushes and exits; SIGKILL after a grace period
  * because one that is wedged never will, and a wedged browser is exactly the case this exists for.
+ *
+ * **Windows has no process groups to signal**, so there `taskkill /T` walks the tree from the
+ * browser's own PID and `/F` ends it at once. Synchronous, because this also runs from an `exit`
+ * handler, where nothing asynchronous gets to finish.
  */
 function killTree(pid, graceMs = 2000) {
   if (!Number.isInteger(pid) || pid <= 0) return;
+  if (process.platform === 'win32') {
+    spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], {
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    return;
+  }
   try {
     process.kill(-pid, 'SIGTERM');
   } catch {
@@ -194,10 +247,11 @@ function defaultIsAlive(pid) {
 export function chromePath() {
   const asked = process.env['CHROME_PATH'];
   if (asked !== undefined && asked !== '') return asked;
-  const found = CANDIDATES.find((candidate) => existsSync(candidate));
+  const candidates = browserCandidates();
+  const found = candidates.find((candidate) => existsSync(candidate));
   if (found === undefined) {
     throw new Error(
-      `no Chrome or Chromium found. Tried:\n  ${CANDIDATES.join('\n  ')}\nSet CHROME_PATH to one.`,
+      `no Chrome, Chromium or Edge found. Tried:\n  ${candidates.join('\n  ')}\nSet CHROME_PATH to one.`,
     );
   }
   return found;
@@ -227,7 +281,7 @@ export async function launch({ flags = GPU_FLAGS, headless = true, timeoutMs = 2
      process and every renderer with one signal to the negative PID. `unref()` is deliberately
      not called: the parent must stay attached, or its own exit and signal handlers below never
      fire, and those are half of what closes the other three holes. */
-  const child = spawn(binary, args, { stdio: 'ignore', detached: true });
+  const child = spawn(binary, args, { stdio: 'ignore', detached: true, windowsHide: true });
   writeFileSync(
     path.join(profile, OWNER_FILE),
     JSON.stringify({ ownerPid: process.pid, chromePid: child.pid }),

package/scripts/look.d.mts

@@ -0,0 +1,81 @@
+import type { RgbaImage } from './png.d.mts';
+
+/** The backends `look` photographs by default, in the order a consumer runs them. */
+export const LOOK_BACKENDS: readonly ['webgpu', 'webgl2'];
+
+/** At or above this share of one colour, a canvas is called empty. */
+export const EMPTY_SHARE: number;
+
+/** What a frame is made of. */
+export interface FrameStats {
+  readonly width: number;
+  readonly height: number;
+  /** The most common colour, as `#rrggbb`. */
+  readonly dominant: string;
+  /** The share of the frame that colour covers, 0 to 1. */
+  readonly dominantShare: number;
+  /** Rec. 709 luminance averaged over the frame, 0 to 255. */
+  readonly meanLuminance: number;
+}
+
+/** One backend's photograph and everything the page said while it was taken. */
+export interface LookCapture {
+  readonly backend: string;
+  readonly url: string;
+  /** What a player sees, interface included. */
+  readonly file: string;
+  /**
+   * The backend that actually drew, read from the context the page's canvas asked for: `'webgpu'`,
+   * `'webgl2'`, or `null` when no canvas in the page asked for either.
+   */
+  readonly drawnWith: 'webgpu' | 'webgl2' | null;
+  /** Measured over the canvas alone; `null` when the page never booted. */
+  readonly stats: FrameStats | null;
+  /** The share of the canvas that changed between two frames; `null` when the page never booted. */
+  readonly moved: number | null;
+  readonly errors: readonly string[];
+  readonly warnings: readonly string[];
+  /** Every console line, `level: text`. */
+  readonly logs: readonly string[];
+  readonly problems: readonly string[];
+}
+
+export interface LookReport {
+  readonly url: string;
+  /** The renderer string of the GPU that drew, read from a WebGL2 context. */
+  readonly gpu: string;
+  readonly captures: readonly LookCapture[];
+  readonly problems: readonly string[];
+  /** True when no capture found a problem. */
+  readonly ok: boolean;
+}
+
+export interface LookOptions {
+  /** The address of the running game. */
+  readonly url: string;
+  readonly backends?: readonly string[];
+  /** Where the PNGs and `look.json` go. Defaults to `.driftengine/look`. */
+  readonly out?: string;
+  readonly width?: number;
+  readonly height?: number;
+  /** How long to wait for a canvas in the page to ask for a WebGPU or WebGL2 context. */
+  readonly bootMs?: number;
+  /** A pause after that for the first frames. */
+  readonly settleMs?: number;
+  /** How long to wait after that for the canvas to show more than one colour. */
+  readonly drawMs?: number;
+  /** The gap between the two frames compared to tell whether the game moves. */
+  readonly moveMs?: number;
+  /** Browser flags; defaults to `gpuFlagsFor()`. */
+  readonly flags?: readonly string[] | null;
+  /** `false` opens a real window, for a machine whose headless browser cannot reach its GPU. */
+  readonly headless?: boolean;
+}
+
+export function gpuFlagsFor(platform?: string): string[] | null;
+export function lookUrl(url: string, backend: string): string;
+export function frameStats(image: RgbaImage): FrameStats;
+export function changedShare(a: RgbaImage, b: RgbaImage, tolerance?: number): number;
+export function sortConsole(lines: readonly string[]): { errors: string[]; warnings: string[] };
+export function look(options: LookOptions): Promise<LookReport>;
+export function formatLook(report: LookReport): string;