@datamoc/mw_games 0.16.0 → 0.17.1

package/tools/benchmark-browser.d.mts

@@ -0,0 +1,33 @@
+export interface MeasurePageOptions {
+	/** a `file://` url of the built page */
+	url: string;
+	/** frame intervals timed; at least 30, default 180 */
+	frames?: number;
+	/** fails below this mean fps; default 45 */
+	minFps?: number;
+	/** fails above this 95th-percentile frame time; default 40 ms */
+	maxP95FrameMs?: number;
+	/** a JSON history the run is appended to and compared with; none by default */
+	historyPath?: string | null;
+	/** how far below the history's best fps a run may fall; default 0.15 */
+	maxFpsRegression?: number;
+	screenshot?: string;
+}
+
+export interface MeasurePageResult {
+	page: string;
+	gameReady: boolean;
+	canvas: { width: number; height: number };
+	renderer: string;
+	fps: number;
+	averageMs: number;
+	p95FrameMs: number;
+	frames: number;
+	memoryMB: number | null;
+	screenshot: string;
+	pageErrors: string[];
+	thresholds: { minFps: number; maxP95FrameMs: number };
+}
+
+/** measures a built page's frame rate in headless Chrome and throws past its thresholds */
+export function measurePage(options: MeasurePageOptions): Promise<MeasurePageResult>;

package/tools/benchmark-browser.mjs

@@ -0,0 +1,163 @@
+#!/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) {
+	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));

package/tools/benchmark-history.d.mts

@@ -0,0 +1,8 @@
+/** 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;

package/tools/benchmark-history.mjs

@@ -0,0 +1,31 @@
+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;
+}

package/tools/browser-smoke.d.mts

@@ -0,0 +1,30 @@
+import type { Page } from 'playwright-core';
+
+export interface SmokePageOptions {
+	/** a `file://` url of the built page */
+	url: string;
+	/** where the screenshot is written */
+	screenshot: string;
+	keyToPress?: string | null;
+	reducedMotion?: 'reduce' | 'no-preference' | null;
+	/** a JavaScript expression evaluated in the page, returned as `probe` */
+	probe?: string | null;
+	after?: ((page: Page) => Promise<void>) | null;
+}
+
+export interface SmokePageResult {
+	url: string;
+	screenshot: string;
+	pageErrors: string[];
+	gameReady: boolean;
+	renderer: string;
+	canvas: { width: number; height: number };
+	sample: { width: number; height: number; sampled: number; opaque: number; distinctColours: number } | null;
+	probe: unknown;
+}
+
+/** opens a built page from `file://` in headless Chrome and throws unless it rendered a live, non-blank game canvas */
+export function smokePage(options: SmokePageOptions): Promise<SmokePageResult>;
+
+/** waits up to 5 s for an mwg game to be ready on `page`, then throws naming the page and its logged errors */
+export function waitForGame(page: Page, url: string, pageErrors?: string[]): Promise<void>;

package/tools/browser-smoke.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+import { realpathSync, statSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { launchChrome } from './find-chrome.mjs';
+
+/**
+ * Waits up to five seconds for an mwg game to be ready on `page` (`window.__MWG__` or
+ * `window.__MWG_3D__` set, and a canvas with a size), and otherwise throws a sentence naming the
+ * page and whatever errors it logged. Shared with `benchmark-browser.mjs`.
+ */
+export async function waitForGame(page, url, pageErrors = []) {
+	try {
+		await page.waitForFunction(
+			() => {
+				const canvas = document.querySelector('canvas');
+				return (
+					Boolean(window.__MWG__ || window.__MWG_3D__) &&
+					Boolean(canvas && canvas.width > 0 && canvas.height > 0)
+				);
+			},
+			undefined,
+			{ timeout: 5000 },
+		);
+	} catch {
+		const errors = pageErrors.length ? `; page errors: ${pageErrors.join('; ')}` : '';
+		throw new Error(`no mwg game became ready within 5 s on ${url} (window.__MWG__ and a sized canvas)${errors}`);
+	}
+}
+
+/**
+ * Opens a built page from `file://` in headless Chrome and asserts it actually rendered.
+ *
+ * Shared by the per-pull-request visual smoke and the published-package smoke so both judge
+ * a page the same way: no uncaught error, a canvas on Pixi's WebGL/WebGPU path, and pixels
+ * that are neither empty nor one flat colour. Each caller chooses the page and where its
+ * screenshot goes.
+ *
+ * It deliberately does not pixel-diff against a committed baseline. Font hinting and
+ * anti-aliasing differ between a developer's machine and the Linux runner, and a gate that
+ * fails for the renderer rather than the change is worse than no gate - the same argument the
+ * scheduled browser benchmark records for keeping its fps history off the per-push path.
+ *
+ * `MWG_VISUAL_CHROME_ARGS` carries machine-specific flags, as on a runner with no GPU.
+ *
+ * Three optional extras let a caller check more than "it rendered":
+ *
+ *   - `reducedMotion`: `'reduce'` or `'no-preference'`, emulated before the page loads;
+ *   - `probe`: a JavaScript expression evaluated in the page after it settles, returned as
+ *     `state.probe` (the reduced-motion smoke reads `window.__MWG_MOTION__` this way);
+ *   - `after`: an async hook run once the page has settled and `keyToPress` has fired, for a
+ *     scenario that changes something while the page is open (flipping the emulated media).
+ */
+export async function smokePage({
+	url,
+	screenshot,
+	keyToPress = null,
+	reducedMotion = null,
+	probe = null,
+	after = null,
+}) {
+	await mkdir(dirname(screenshot), { recursive: true });
+	const browser = await launchChrome({ argsEnv: 'MWG_VISUAL_CHROME_ARGS' });
+
+	try {
+		const page = await browser.newPage({ viewport: { width: 1280, height: 720 }, deviceScaleFactor: 1 });
+		if (reducedMotion) await page.emulateMedia({ reducedMotion });
+		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);
+
+		//let the scene finish its first frames before reading pixels back
+		await page.waitForTimeout(250);
+		if (keyToPress) {
+			await page.keyboard.press(keyToPress);
+			//give whatever the key opened time to lay itself out and draw
+			await page.waitForTimeout(250);
+		}
+		if (after) await after(page);
+
+		const state = await page.evaluate(() => {
+			const canvas = document.querySelector('canvas');
+			const app = window.__PIXI_APP__;
+			const renderer = String(app?.renderer?.name ?? 'unknown').toLowerCase();
+			const base = {
+				gameReady: Boolean(window.__MWG__),
+				renderer,
+				canvas: { width: canvas?.width ?? 0, height: canvas?.height ?? 0 },
+				sample: null,
+			};
+			if (!app?.renderer?.extract) return base;
+
+			//Pixi's own extract reads the rendered pixels back, so this works without the
+			//page having to preserve its WebGL drawing buffer
+			const { pixels, width, height } = app.renderer.extract.pixels(app.stage);
+			//sample every 16th pixel: enough to tell a painted scene from an empty or solid
+			//one, without copying millions of values back to Node
+			const colours = new Set();
+			let opaque = 0;
+			let sampled = 0;
+			for (let i = 0; i < pixels.length; i += 4 * 16) {
+				sampled++;
+				if (pixels[i + 3] === 0) continue;
+				opaque++;
+				if (colours.size < 64) colours.add((pixels[i] << 16) | (pixels[i + 1] << 8) | pixels[i + 2]);
+			}
+			return { ...base, sample: { width, height, sampled, opaque, distinctColours: colours.size } };
+		});
+
+		await page.screenshot({ path: screenshot, type: 'png' });
+		const probed =
+			probe === null ? null : await page.evaluate((source) => new Function(`return (${source})`)(), probe);
+
+		if (!state.gameReady || state.canvas.width === 0 || state.canvas.height === 0) {
+			throw new Error(`page did not render a ready game canvas: ${url}`);
+		}
+		if (!['webgl', 'webgpu'].includes(state.renderer)) {
+			throw new Error(`page is not on Pixi's WebGL/WebGPU path, got ${state.renderer}: ${url}`);
+		}
+		if (pageErrors.length) throw new Error(`page errors on ${url}: ${pageErrors.join('; ')}`);
+		const sample = state.sample;
+		if (!sample || sample.opaque < sample.sampled * 0.5 || sample.distinctColours < 8) {
+			throw new Error(`canvas looks blank on ${url}: ${JSON.stringify(sample)}`);
+		}
+
+		return { url, keyToPress, reducedMotion, screenshot, pageErrors, ...state, probe: probed };
+	} finally {
+		await browser.close();
+	}
+}
+
+/**
+ * `mwg-smoke <page.html | dist folder> [--screenshot=<file.png>] [--key=<key>]`: the same check
+ * from a game's own CI. Prints the result as JSON and exits non-zero when the page did not
+ * render, so `vite build && mwg-smoke dist` proves a build still opens by double-clicking.
+ * Needs `playwright-core` and a Chrome or Chromium (`CHROME_PATH` to name one).
+ */
+async function main(argv) {
+	const target = argv.find((arg) => !arg.startsWith('--'));
+	if (!target) {
+		console.error('usage: mwg-smoke <page.html | dist folder> [--screenshot=<file.png>] [--key=<key>]');
+		process.exit(1);
+	}
+	const value = (name) => argv.find((a) => a.startsWith(`--${name}=`))?.slice(name.length + 3);
+	const page = statSync(target).isDirectory() ? join(target, 'index.html') : target;
+	try {
+		const result = await smokePage({
+			url: pathToFileURL(resolve(page)).href,
+			screenshot: resolve(value('screenshot') ?? join(dirname(page), 'smoke.png')),
+			keyToPress: value('key') ?? null,
+		});
+		console.log(JSON.stringify(result, null, 2));
+	} catch (error) {
+		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));

package/tools/bundle-size.d.mts

@@ -0,0 +1,11 @@
+export type SizeMetrics = Record<string, Partial<Record<'raw' | 'gzip', number>>>;
+
+/** raw and gzipped bytes of every file a player receives from `dist`, plus `total` */
+export function measureBuild(dist: string): SizeMetrics;
+
+/** each metric against its baseline; `failed` when one grew more than `tolerance` (0.02 by default) */
+export function compareBudget(
+	current: SizeMetrics,
+	baseline: SizeMetrics,
+	tolerance?: number,
+): { lines: string[]; failed: boolean };

package/tools/bundle-size.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import { gzipSync } from 'node:zlib';
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * The bundle-size budget: the rendering-backend policy weighs bundle cost, and this is the
+ * number it weighs. Here it records the classic global build (the one file a script-tag player
+ * downloads, raw and gzipped) and the whole published `dist` tree, source maps excluded so
+ * the separate map-files decision cannot perturb it.
+ *
+ * `npm run size:check` fails when either grows past `MWG_SIZE_TOLERANCE` (default 2%) over
+ * the committed baseline; `npm run size:update` rewrites the baseline after a deliberate
+ * growth, the same "commit the new number on purpose" shape `npm run api:report` uses.
+ * Run `npm run build` first.
+ *
+ * A game uses the same gate on its own build (item 386): `mwg-size dist` measures every file a
+ * player receives, raw and gzipped, plus their total, against `size-budget.json` beside the
+ * project (`--baseline=` to move it, `--update` to write it on purpose). A page that grows past
+ * the tolerance fails the game's CI, which matters most for a player on a phone.
+ */
+
+/** every file under `dir`, recursively */
+function walk(dir) {
+	const out = [];
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) out.push(...walk(full));
+		else out.push(full);
+	}
+	return out;
+}
+
+/**
+ * Raw and gzipped bytes of every file a player receives from a finished build, keyed by path,
+ * plus `total`. Source maps, precompressed siblings and SBOMs are left out: none of them is
+ * what the page loads.
+ */
+export function measureBuild(dist) {
+	const current = {};
+	let raw = 0;
+	let gzip = 0;
+	for (const file of walk(dist).sort()) {
+		const path = relative(dist, file).split(sep).join('/');
+		if (/\.(map|gz|br|xz)$/.test(path) || path.endsWith('.cdx.json')) continue;
+		const bytes = readFileSync(file);
+		const entry = { raw: bytes.length, gzip: gzipSync(bytes).length };
+		current[path] = entry;
+		raw += entry.raw;
+		gzip += entry.gzip;
+	}
+	current.total = { raw, gzip };
+	return current;
+}
+
+/**
+ * Compares `current` with `baseline` metric by metric: a metric more than `tolerance` over its
+ * baseline fails, one with no baseline (a new file) is reported and passes, since the total
+ * still counts it. Returns the report lines and whether anything is over.
+ */
+export function compareBudget(current, baseline, tolerance = 0.02) {
+	const lines = [];
+	let failed = false;
+	for (const [name, metrics] of Object.entries(current)) {
+		for (const [metric, bytes] of Object.entries(metrics)) {
+			const before = baseline[name]?.[metric];
+			if (before === undefined) {
+				lines.push(`${name} ${metric}: ${bytes} B (no baseline)`);
+				continue;
+			}
+			const growth = bytes / before - 1;
+			const over = growth > tolerance;
+			if (over) failed = true;
+			lines.push(
+				`${name} ${metric}: ${bytes} B vs ${before} B baseline (${growth >= 0 ? '+' : ''}${(growth * 100).toFixed(1)}%) ${over ? 'OVER' : 'ok'}`,
+			);
+		}
+	}
+	return { lines, failed };
+}
+
+/** this repository's own budget: the global bundle and the published `dist` tree */
+function measureFramework(root) {
+	const dist = join(root, 'dist');
+	const globalBundle = join(dist, 'mw_games.global.js');
+	if (!existsSync(globalBundle)) {
+		throw new Error(`no build found at ${relative(root, globalBundle)} - run "npm run build" first`);
+	}
+	const globalBytes = readFileSync(globalBundle);
+	return {
+		'mw_games.global.js': { raw: globalBytes.length, gzip: gzipSync(globalBytes).length },
+		dist: {
+			raw: walk(dist)
+				.filter((file) => !file.endsWith('.map'))
+				.reduce((sum, file) => sum + statSync(file).size, 0),
+		},
+	};
+}
+
+function main(argv) {
+	const tolerance = Number(
+		argv.find((a) => a.startsWith('--tolerance='))?.slice(12) ?? process.env.MWG_SIZE_TOLERANCE ?? 0.02,
+	);
+	const target = argv.find((arg) => !arg.startsWith('--'));
+	const root = resolve(import.meta.dirname, '..');
+	let current;
+	let baselinePath;
+	if (target) {
+		const dist = resolve(target);
+		if (!existsSync(join(dist, 'index.html')))
+			throw new Error(`${target} holds no index.html - build the game first`);
+		current = measureBuild(dist);
+		baselinePath = resolve(argv.find((a) => a.startsWith('--baseline='))?.slice(11) ?? 'size-budget.json');
+	} else {
+		current = measureFramework(root);
+		baselinePath = join(import.meta.dirname, 'bundle-size.json');
+	}
+	const update = target ? 'mwg-size --update' : 'npm run size:update';
+
+	if (argv.includes('--update') || (target && !existsSync(baselinePath))) {
+		writeFileSync(baselinePath, `${JSON.stringify(current, null, '\t')}\n`);
+		console.log(`wrote ${relative(process.cwd(), baselinePath)}`);
+		for (const [name, metrics] of Object.entries(current)) console.log(`  ${name}: ${JSON.stringify(metrics)}`);
+		return;
+	}
+	const { lines, failed } = compareBudget(current, JSON.parse(readFileSync(baselinePath, 'utf8')), tolerance);
+	for (const line of lines) console.log(line);
+	if (failed) {
+		console.error(
+			`bundle grew more than ${(tolerance * 100).toFixed(0)}% - trim it, or run "${update}" and explain the growth in the commit`,
+		);
+		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)) main(process.argv.slice(2));

package/tools/csp.d.mts

@@ -0,0 +1,7 @@
+import type { CspOptions } from './emit-page.mjs';
+
+/** the policy `emitPage` writes, for a page's HTML; `scripts` are extra script texts allowed by hash */
+export function contentSecurityPolicy(html: string, options?: CspOptions & { scripts?: string[] }): string;
+
+/** `html` with that policy as the first element of `<head>`, replacing an earlier one */
+export function withContentSecurityPolicy(html: string, options?: CspOptions & { scripts?: string[] }): string;

package/tools/csp.mjs

@@ -0,0 +1,65 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * The Content-Security-Policy `emitPage` writes into every page it finishes (item 374), as a
+ * `<meta http-equiv>` at the top of `<head>`, so a game gets it with no configuration.
+ *
+ * What it buys, for a page that opens from `file://`: no script from anywhere but the page's own
+ * folder and the hashed inline scripts it ships with, no network request except to the
+ * endpoints the game declares (`connect`), so a compromised dependency cannot send a save or
+ * anything else away, and no exfiltration through an image, font or media URL either, since
+ * those only accept `data:`/`blob:`. `base-uri`, `form-action` and `object-src` are `'none'`.
+ *
+ * `'unsafe-eval'` stays allowed by default, measured rather than assumed: Pixi 8 refuses to start
+ * without it ("please use pixi.js/unsafe-eval") unless the game imports `pixi.js/unsafe-eval`,
+ * which swaps its generated uniform uploads for slower polyfills. mwg itself never evaluates
+ * data, so the eval permission gives nothing to an attacker who does not already have code in
+ * the bundle. A game that imports that module passes `eval: false`.
+ *
+ * @param {string} html the finished page
+ * @param {{ connect?: string[], eval?: boolean, scripts?: string[] }} [options] `scripts` are
+ *   extra script texts to allow by hash (a single-file loader's unpacked scripts)
+ */
+export function contentSecurityPolicy(html, { connect = [], eval: allowEval = true, scripts = [] } = {}) {
+	//The HTML parser normalises newlines before it hashes an inline script: CRLF and lone CR
+	//become LF. A checkout with core.autocrlf=true (every Windows clone) hands the source page
+	//over with CRLF, so hashing the bytes on disk here would emit a policy Chrome computes
+	//differently from the file it just parsed, and the page refuses its own script while
+	//`file://` on Linux stays quiet. Hash the text the browser will see.
+	const inline = [...html.matchAll(/<script(?![^>]*\bsrc=)[^>]*>([\s\S]*?)<\/script>/gi)].map((match) =>
+		match[1].replace(/\r\n?/g, '\n'),
+	);
+	//`scripts` are texts the standalone page's unpacker sets on a script element at runtime
+	//(`s.text = code`), where no parser runs: those are hashed exactly as they are written.
+	const hashes = [...new Set([...inline, ...scripts].map((text) => `'sha256-${sha256(text)}'`))];
+	const directives = {
+		'default-src': ["'none'"],
+		'script-src': ["'self'", 'file:', ...hashes, ...(allowEval ? ["'unsafe-eval'"] : [])],
+		'style-src': ["'self'", 'file:', "'unsafe-inline'"],
+		'img-src': ["'self'", 'file:', 'data:', 'blob:'],
+		'media-src': ["'self'", 'file:', 'data:', 'blob:'],
+		'font-src': ["'self'", 'file:', 'data:'],
+		//Pixi loads a `data:` texture through fetch, so `data:` is a connect source
+		'connect-src': ['data:', 'blob:', ...connect],
+		'worker-src': ['blob:'],
+		'base-uri': ["'none'"],
+		'form-action': ["'none'"],
+		'object-src': ["'none'"],
+	};
+	return Object.entries(directives)
+		.map(([name, values]) => `${name} ${values.join(' ')}`)
+		.join('; ');
+}
+
+/** `html` with the policy inserted as the first element of `<head>`, replacing an earlier one */
+export function withContentSecurityPolicy(html, options) {
+	const cleaned = html.replace(/[ \t]*<meta http-equiv="Content-Security-Policy"[^>]*>\n?/i, '');
+	const policy = contentSecurityPolicy(cleaned, options);
+	const meta = `<meta http-equiv="Content-Security-Policy" content="${policy.replace(/"/g, '&quot;')}">`;
+	if (!/<head[^>]*>/i.test(cleaned)) throw new Error('page has no <head> to carry a Content-Security-Policy');
+	return cleaned.replace(/<head[^>]*>/i, (head) => `${head}\n\t${meta}`);
+}
+
+function sha256(text) {
+	return createHash('sha256').update(text, 'utf8').digest('base64');
+}