@datamoc/mw_games 0.43.0 → 0.45.0

package/tools/benchmark-browser.mjs

@@ -1,169 +1 @@
-#!/usr/bin/env node
-import { statSync, realpathSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { launchChrome } from './find-chrome.mjs';
-import { waitForGame } from './browser-smoke.mjs';
-import { readHistory, appendHistory, bestSeen } from './benchmark-history.mjs';
-
-/**
- * Measures a built page's frame rate in headless Chrome: `frames` frame intervals timed with
- * `requestAnimationFrame`, their mean as fps and their 95th percentile, and Chrome's JS heap
- * where it reports one. Throws when the page is not a ready game on Pixi's (or Babylon's)
- * WebGL/WebGPU path, when it logs an error, when it misses `minFps` or `maxP95FrameMs`, or, with
- * a `historyPath`, when it falls more than `maxFpsRegression` below the best fps that history
- * has seen (a fixed gate alone cannot see a slow decline that never quite crosses it). The run is
- * appended to that history either way.
- *
- * Shipped for a game (item 387) as `@datamoc/mw_games/tools/benchmark-browser` and
- * `mwg-bench <page | dist>`; this repository runs it through `npm run benchmark:*`. A CI runner
- * has no GPU, so Chrome there is told which software WebGL path to take through
- * `MWG_BENCHMARK_CHROME_ARGS` (`--use-gl=angle --use-angle=swiftshader`), a property of the
- * machine rather than of the page.
- */
-export async function measurePage({
-	url,
-	frames = 180,
-	minFps = 45,
-	maxP95FrameMs = 40,
-	historyPath = null,
-	maxFpsRegression = 0.15,
-	screenshot = join(tmpdir(), `mwg-browser-benchmark-${process.pid}.png`),
-}) {
-	if (!Number.isInteger(frames) || frames < 30) throw new Error('frames must be an integer of at least 30');
-	const browser = await launchChrome();
-	try {
-		const page = await browser.newPage({ viewport: { width: 1280, height: 720 }, deviceScaleFactor: 1 });
-		const pageErrors = [];
-		page.on('pageerror', (error) => pageErrors.push(error.message));
-		page.on('console', (message) => {
-			if (message.type() === 'error') pageErrors.push(message.text());
-		});
-		await page.goto(url, { waitUntil: 'load' });
-		await waitForGame(page, url, pageErrors);
-
-		const state = await page.evaluate(() => {
-			const canvas = document.querySelector('canvas');
-			const app = window.__PIXI_APP__;
-			const babylon = window.__MWG_3D__;
-			return {
-				gameReady: Boolean(window.__MWG__ || babylon),
-				canvas: { width: canvas?.width ?? 0, height: canvas?.height ?? 0 },
-				renderer: babylon?.engine?.isWebGPU
-					? 'webgpu'
-					: babylon?.engine?.webGLVersion > 0
-						? 'webgl'
-						: String(app?.renderer?.name ?? 'unknown').toLowerCase(),
-				webGLVersion: babylon?.engine?.webGLVersion ?? null,
-				meshes: babylon?.scene?.meshes?.length ?? null,
-			};
-		});
-		const metrics = await page.evaluate(async (count) => {
-			const samples = [];
-			let previous;
-			await new Promise((resolve) => {
-				const frame = (now) => {
-					if (previous !== undefined) samples.push(now - previous);
-					previous = now;
-					if (samples.length >= count) resolve();
-					else requestAnimationFrame(frame);
-				};
-				requestAnimationFrame(frame);
-			});
-			samples.sort((a, b) => a - b);
-			const averageMs = samples.reduce((sum, value) => sum + value, 0) / samples.length;
-			const p95FrameMs = samples[Math.min(samples.length - 1, Math.floor(samples.length * 0.95))];
-			//`performance.memory` is a non-standard Chrome extension: null everywhere else,
-			//reported as such rather than guessed at
-			const memory = performance.memory;
-			const memoryMB = memory ? memory.usedJSHeapSize / (1024 * 1024) : null;
-			return { averageMs, p95FrameMs, fps: 1000 / averageMs, frames: samples.length, memoryMB };
-		}, frames);
-
-		await page.screenshot({ path: screenshot, type: 'png' });
-		const result = {
-			page: url,
-			...state,
-			...metrics,
-			screenshot,
-			pageErrors,
-			thresholds: { minFps, maxP95FrameMs },
-		};
-
-		if (!['webgl', 'webgpu'].includes(state.renderer)) {
-			throw new Error(`browser benchmark requires WebGL or WebGPU, got ${state.renderer}`);
-		}
-		if (pageErrors.length) throw new Error(`browser benchmark page errors: ${pageErrors.join('; ')}`);
-		if (metrics.fps < minFps || metrics.p95FrameMs > maxP95FrameMs) {
-			throw Object.assign(
-				new Error(
-					`browser performance threshold failed: ${metrics.fps.toFixed(1)} FPS, p95 ${metrics.p95FrameMs.toFixed(2)} ms`,
-				),
-				{ result },
-			);
-		}
-
-		if (historyPath) {
-			const history = await readHistory(historyPath);
-			const bestPriorFps = bestSeen(history, (entry) => entry.fps);
-			await appendHistory(historyPath, history, {
-				timestamp: new Date().toISOString(),
-				fps: metrics.fps,
-				p95FrameMs: metrics.p95FrameMs,
-				memoryMB: metrics.memoryMB,
-			});
-			if (bestPriorFps !== null && metrics.fps < bestPriorFps * (1 - maxFpsRegression)) {
-				throw Object.assign(
-					new Error(
-						`browser performance regressed against history: ${metrics.fps.toFixed(1)} FPS now vs ` +
-							`${bestPriorFps.toFixed(1)} FPS best-seen (${historyPath})`,
-					),
-					{ result },
-				);
-			}
-		}
-		return result;
-	} finally {
-		await browser.close();
-	}
-}
-
-/**
- * `mwg-bench <page | dist> [--frames=180] [--min-fps=45] [--max-p95=40] [--history=<file>]`,
- * each option also read from `MWG_BENCHMARK_FRAMES`, `MWG_BENCHMARK_MIN_FPS`,
- * `MWG_BENCHMARK_MAX_P95_MS` and `MWG_BENCHMARK_MAX_FPS_REGRESSION`. The history defaults to
- * `benchmark-results/<page>.json`, named by the page so two pages keep separate histories.
- */
-async function main(argv) {
-	if (argv.includes('--help') || argv.includes('-h')) {
-		console.log(
-			'usage: mwg-bench <page.html | dist folder> [--frames=180] [--min-fps=45] [--max-p95=40] [--history=<file>]',
-		);
-		return;
-	}
-	const value = (name, env, fallback) =>
-		argv.find((a) => a.startsWith(`--${name}=`))?.split('=')[1] ?? process.env[env] ?? fallback;
-	const target = argv.find((arg) => !arg.startsWith('--')) ?? 'examples/dungeon/dist/index.html';
-	const relativePage = statSync(target).isDirectory() ? join(target, 'index.html') : target;
-	const slug = relativePage.replace(/[\\/]/g, '-').replace(/\.html$/, '');
-	try {
-		const result = await measurePage({
-			url: pathToFileURL(resolve(relativePage)).href,
-			frames: Number(value('frames', 'MWG_BENCHMARK_FRAMES', 180)),
-			minFps: Number(value('min-fps', 'MWG_BENCHMARK_MIN_FPS', 45)),
-			maxP95FrameMs: Number(value('max-p95', 'MWG_BENCHMARK_MAX_P95_MS', 40)),
-			maxFpsRegression: Number(process.env.MWG_BENCHMARK_MAX_FPS_REGRESSION ?? 0.15),
-			historyPath: resolve(value('history', 'MWG_BENCHMARK_HISTORY', join('benchmark-results', `${slug}.json`))),
-		});
-		console.log(JSON.stringify(result, null, 2));
-	} catch (error) {
-		if (error?.result) console.log(JSON.stringify(error.result, null, 2));
-		console.error(error instanceof Error ? error.message : error);
-		process.exitCode = 1;
-	}
-}
-
-//realpath, since an npm `bin` shim reaches this file through a symlink
-if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url))
-	await main(process.argv.slice(2));
+export * from '@datamoc/mwg/tools/benchmark-browser';

package/tools/benchmark-history.d.mts

@@ -1,8 +1 @@
-/** a benchmark's recorded runs, or `[]` when none has been recorded yet */
-export function readHistory<T = Record<string, unknown>>(historyPath: string): Promise<T[]>;
-
-/** appends `entry` to `history` and writes the last 50 runs back */
-export function appendHistory<T>(historyPath: string, history: T[], entry: T): Promise<void>;
-
-/** the best value of `metric` across `history`, or null when it is empty */
-export function bestSeen<T>(history: readonly T[], metric: (entry: T) => number): number | null;
+export * from '@datamoc/mwg/tools/benchmark-history';

package/tools/benchmark-history.mjs

@@ -1,31 +1 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname } from 'node:path';
-
-const maxHistoryEntries = 50;
-
-/**
- * Per-benchmark history: read what a prior run of the same benchmark recorded, append what
- * this run measured, and detect a regression against the best one seen so far. Shared by
- * `benchmark-browser.mjs` (fps/p95/memory) and `benchmark-simulation.mjs` (commands/steps per
- * second) - the two started as separate copies of the same read/append/compare logic before
- * this module existed to hold it once.
- */
-export async function readHistory(historyPath) {
-	try {
-		return JSON.parse(await readFile(historyPath, 'utf8'));
-	} catch {
-		return []; //no prior run recorded yet - not an error, just nothing to compare against
-	}
-}
-
-/** appends `entry` to `history` (already loaded by the caller) and persists the result */
-export async function appendHistory(historyPath, history, entry) {
-	history.push(entry);
-	await mkdir(dirname(historyPath), { recursive: true });
-	await writeFile(historyPath, JSON.stringify(history.slice(-maxHistoryEntries), null, 2));
-}
-
-/** the best value of `metric` seen across `history`, or null if it is empty */
-export function bestSeen(history, metric) {
-	return history.length > 0 ? Math.max(...history.map((entry) => metric(entry))) : null;
-}
+export * from '@datamoc/mwg/tools/benchmark-history';

package/tools/browser-driver.d.mts

@@ -1,122 +1 @@
-export interface ServedDir {
-	url: string;
-	port: number;
-	/**
-	 * Presses and releases one key through the engine's trusted input channel (P41): a
-	 * named key from the table (`Enter`, `Escape`, `ArrowUp`, ...), or a single character
-	 * that types itself. `holdMs` parks between the down and the up.
-	 */
-	press(key: string, holdMs?: number): Promise<void>;
-	close(): Promise<void>;
-}
-
-export interface CdpMouseEvent {
-	type: 'mouseMoved' | 'mousePressed' | 'mouseReleased';
-	x: number;
-	y: number;
-	button: 'none' | 'left';
-	buttonValue?: number;
-	clickCount?: number;
-	buttons: number;
-}
-
-export interface BidiPointerAction {
-	type: 'pointer';
-	id: string;
-	parameters: { pointerType: 'mouse' };
-	actions: (
-		| { type: 'pointerMove'; x: number; y: number }
-		| { type: 'pointerDown'; button: number }
-		| { type: 'pointerUp'; button: number }
-	)[];
-}
-
-export interface BrowserDriver {
-	kind: 'chrome-cdp' | 'firefox-bidi';
-	goto(url: string): Promise<void>;
-	waitReady(url: string, timeoutMs?: number): Promise<void>;
-	evaluate<T>(expression: string): Promise<T>;
-	script<Args extends unknown[], T>(fn: (...args: Args) => T | Promise<T>, ...args: Args): Promise<T>;
-	tap(xFraction: number, yFraction: number): Promise<void>;
-	/** presses at one canvas fraction, moves to another with the button held in `steps` moves (default 8), releases */
-	drag(fromX: number, fromY: number, toX: number, toY: number, steps?: number): Promise<void>;
-	screenshot(): Promise<Buffer>;
-	consoleErrors(): string[];
-	close(): Promise<void>;
-}
-
-export interface DriveOptions {
-	executable?: string;
-	chromeArgs?: string[];
-	firefoxArgs?: string[];
-	profileDir?: string;
-	/**
-	 * The inner page viewport, applied through each engine's protocol call (CDP
-	 * `Emulation.setDeviceMetricsOverride`, BiDi `browsingContext.setViewport`) rather
-	 * than window flags, whose outer size is what a consumer's compensation kept
-	 * rediscovering (P41).
-	 */
-	viewport?: { width: number; height: number };
-	/** show the browser window instead of running headless, for watching a driven run */
-	headed?: boolean;
-}
-
-/** the readiness predicate browser-smoke's waitForGame waits on, as page JS */
-export function readinessExpression(): string;
-
-/** an OS-chosen free port, so Windows' excluded-port ranges cannot bite */
-export function pickFreePort(): Promise<number>;
-
-/** serves root over HTTP on an OS-chosen free port */
-export function serveDir(root: string): Promise<ServedDir>;
-
-/** the ws:// endpoint Chrome prints as DevTools listening on ..., or null */
-export function parseDevToolsEndpoint(stderr: string): string | null;
-
-/** the ws:// endpoint Firefox prints as WebDriver BiDi listening on ..., or null */
-export function parseBidiEndpoint(stderr: string): string | null;
-
-/** the CDP Input.dispatchMouseEvent sequence a tap is, at CSS pixels */
-export function buildTapSequence(x: number, y: number): CdpMouseEvent[];
-
-/** the CDP Input.dispatchMouseEvent sequence a drag is: press, held moves, release, at CSS pixels */
-export function buildDragSequence(
-	x1: number,
-	y1: number,
-	x2: number,
-	y2: number,
-	steps?: number,
-): Record<string, unknown>[];
-
-/** the in-page synthetic pointer drag, the Firefox path (see pageTapSource) */
-export function pageDragSource(x1: number, y1: number, x2: number, y2: number, steps?: number): string;
-
-/** the BiDi input.performActions pointer half of a tap, at CSS pixels */
-export function buildPointerActions(x: number, y: number): BidiPointerAction[];
-
-/** everything a named key's press needs per protocol: DOM `code`, Windows VK, the typed character, the WebDriver key value; null for the unmapped */
-export function keyInfoOf(key: string): { code: string; vk: number; bidi: string; text?: string } | null;
-
-/** the CDP `Input.dispatchKeyEvent` pair one press is */
-export function cdpKeySequence(key: string): unknown[] | null;
-
-/** the BiDi `input.performActions` key sequence one press is, with the hold as a pause */
-export function bidiKeyActions(key: string, holdMs?: number): unknown[] | null;
-
-/**
- * The in-page synthetic pointer sequence a tap is, as page JS - the Firefox tap path,
- * because the BiDi pointer actions do not reach Pixi 8's canvas EventSystem (P41).
- */
-export function pageTapSource(x: number, y: number): string;
-
-/** unwraps a WebDriver BiDi remote value into plain JSON */
-export function unwrapRemoteValue(node: unknown): unknown;
-
-/** locates a browser executable without a driver install, or null when neither yields anything */
-export function findBrowser(kind: 'chrome' | 'firefox'): string | null;
-
-/** drives headless Chrome over CDP */
-export function driveChrome(options?: DriveOptions): Promise<BrowserDriver>;
-
-/** drives headless Firefox over WebDriver BiDi, with the same surface as driveChrome */
-export function driveFirefox(options?: DriveOptions): Promise<BrowserDriver>;
+export * from '@datamoc/mwg/tools/browser-driver';