@datamoc/mw_games 0.41.0 → 0.43.0

package/tools/browser-driver.mjs

@@ -361,12 +361,12 @@ function findOnPath(names) {
 }
 
 /**
- * Locates a browser executable without a driver install: the `CHROME_PATH` /
- * `FIREFOX_PATH` override first, then well-known install locations. Returns null
+ * Locates a browser executable without a driver install: `CHROME_PATH` (or `CHROME`) /
+ * `FIREFOX_PATH` overrides first, then well-known install locations. Returns null
  * when neither yields anything, so callers skip rather than fail.
  */
 export function findBrowser(kind) {
-	const override = process.env[kind === 'chrome' ? 'CHROME_PATH' : 'FIREFOX_PATH'];
+	const override = kind === 'chrome' ? process.env.CHROME_PATH || process.env.CHROME : process.env.FIREFOX_PATH;
 	if (override) return override;
 	const onPath = findOnPath(kind === 'chrome' ? ['chrome', 'chromium', 'google-chrome'] : ['firefox']);
 	if (onPath) return onPath;

package/tools/browser-smoke.mjs

@@ -29,6 +29,23 @@ export async function waitForGame(page, url, pageErrors = []) {
 	}
 }
 
+/**
+ * Waits for the page to draw a few frames instead of sleeping a fixed time: a software renderer can need
+ * far longer than any fixed pause, and a fast one far less. Capped, since a hidden tab throttles frames.
+ */
+async function settle(page, frames = 3, capMs = 5000) {
+	await page.evaluate(
+		([count, cap]) =>
+			new Promise((done) => {
+				const timer = setTimeout(done, cap);
+				const next = (left) =>
+					left === 0 ? (clearTimeout(timer), done()) : requestAnimationFrame(() => next(left - 1));
+				next(count);
+			}),
+		[frames, capMs],
+	);
+}
+
 /**
  * Opens a built page from `file://` in headless Chrome and asserts it actually rendered.
  *
@@ -76,11 +93,11 @@ export async function smokePage({
 		await waitForGame(page, url, pageErrors);
 
 		//let the scene finish its first frames before reading pixels back
-		await page.waitForTimeout(250);
+		await settle(page);
 		if (keyToPress) {
 			await page.keyboard.press(keyToPress);
 			//give whatever the key opened time to lay itself out and draw
-			await page.waitForTimeout(250);
+			await settle(page);
 		}
 		if (after) await after(page);
 

package/tools/build-tablebases.mjs

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { huffEncode } from '../src/board/tablebase.ts';
-import { spawn } from '../src/threads/spawn.ts';
+//the framework's own modules: the TypeScript sources inside this repository, the built `dist` inside an
+//installed package, which ships no `src`
+const fromSource = existsSync(new URL('../src/board/tablebase.ts', import.meta.url));
+const load = (path) => import(fromSource ? `../src/${path}.ts` : `../dist/${path}.js`);
+const { huffEncode } = await load('board/tablebase');
+const { spawn } = await load('threads/spawn');
 
 /**
  * Generates pawnless endgame tablebases (WDL plus distance-to-mate) and ships

package/tools/compile-openings.mjs

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { applyMove, legalMoves, positionKey, sq, squareName, startingChess } from '../src/board/chess.ts';
-import { parseUciMove } from '../src/board/openings.ts';
+//the framework's own modules: the TypeScript sources inside this repository, the built `dist` inside an
+//installed package, which ships no `src`
+const fromSource = existsSync(new URL('../src/board/chess.ts', import.meta.url));
+const load = (path) => import(fromSource ? `../src/${path}.ts` : `../dist/${path}.js`);
+const { applyMove, legalMoves, positionKey, sq, squareName, startingChess } = await load('board/chess');
+const { parseUciMove } = await load('board/openings');
 
 /**
  * Compiles opening tables (`eco`, `name`, `pgn` TSV rows, one per line after the header)

package/tools/compile-resources.d.mts

@@ -12,6 +12,8 @@ export interface CompileResourcesOptions {
 	toWebp?: boolean;
 	webpLossless?: boolean;
 	webpQuality?: number;
+	/** minify embedded `.svg` assets through the optional `svgo` package (version 4 or newer); false by default */
+	svgo?: boolean;
 	/** Subset an embedded `.sf2` to the programs the embedded `.mid`/`.midi` files use. Default true; `false` embeds every SoundFont whole. */
 	soundFont?: boolean;
 	/** Explicit `{ bank, program }` list to subset a SoundFont to, overriding the MIDI-derived list. */
@@ -26,9 +28,13 @@ export interface CompileResourcesGroup {
 
 export interface CompileResourcesResult {
 	groups: CompileResourcesGroup[];
+	/** the asset path of every embedded file, as game code passes it to `load()` */
+	keys: string[];
 	rawBytes: number;
 	embeddedBytes: number;
 	webpConverted: number;
+	/** SVG assets embedded smaller than their source because of `svgo` */
+	svgOptimised: number;
 	skipped: number;
 	/** the `CREDITS.txt` text when the asset folder holds a `credits.json`, else null */
 	credits: string | null;
@@ -50,6 +56,8 @@ export interface SoundFontEmbed {
 	programs: number | null;
 	rawBytes: number;
 	embeddedBytes: number;
+	/** the programs the game's MIDI files ask for that this font does not carry; empty when none */
+	missing: SoundFontUsage[];
 }
 
 /** parses a `--soundfont-usage=bank:program,...` CLI value; undefined when the flag is absent */

package/tools/compile-resources.mjs

@@ -121,6 +121,10 @@ export async function* walk(dir) {
  *   pixel-art tileset's exact colours survive; set false only with `webpQuality` to opt into
  *   lossy re-encoding for photographic source art)
  * @param options.webpQuality 0-100, used only when `webpLossless` is false (default 90)
+ * @param options.svgo minify embedded `.svg` assets through the optional `svgo` package (default
+ *   false - see `tools/svg-optimise.mjs`). The key never changes, only the embedded bytes, and
+ *   only when the optimised file is actually smaller. A file svgo cannot parse fails the build by
+ *   name rather than shipping unoptimised in silence.
  * @param options.soundFont subset an embedded `.sf2` or `.sf3` to the programs the embedded
  *   `.mid`/`.midi` files use (default true); `false` embeds every SoundFont whole
  * @param options.soundFontUsage explicit `{ bank, program }` list to subset to, for a
@@ -141,6 +145,7 @@ export async function compileResources({
 	toWebp: convertToWebp = false,
 	webpLossless = true,
 	webpQuality = 90,
+	svgo: optimiseSvgFiles = false,
 	soundFont = true,
 	soundFontUsage,
 } = {}) {
@@ -205,13 +210,16 @@ export async function compileResources({
 	let rawBytes = 0;
 	let embeddedBytes = 0;
 	let webpConverted = 0;
+	let svgOptimised = 0;
 
 	// only paid when toWebp is actually used, so a build that never asks for it never imports
 	// (or requires installing) sharp
 	const toWebp = convertToWebp ? (await import('./webp-convert.mjs')).toWebp : null;
+	const optimiseSvg = optimiseSvgFiles ? (await import('./svg-optimise.mjs')).optimiseSvg : null;
 
 	const creditsFile = join(from, 'credits.json');
 	let credits = null;
+	const keys = [];
 
 	for (const file of files) {
 		if (selected && !selected.has(keyOf(file))) continue;
@@ -240,6 +248,19 @@ export async function compileResources({
 			}
 		}
 
+		if (optimiseSvg && ext === '.svg') {
+			let optimised;
+			try {
+				optimised = await optimiseSvg(data);
+			} catch (error) {
+				throw new Error(`cannot optimise SVG asset ${key}: ${error.message ?? error}`);
+			}
+			if (optimised.length < data.length) {
+				bytes = optimised;
+				svgOptimised++;
+			}
+		}
+
 		if (isSoundFontKey(key)) {
 			if (usage !== undefined && soundFontTools) {
 				try {
@@ -247,7 +268,14 @@ export async function compileResources({
 				} catch (error) {
 					throw new Error(`cannot subset SoundFont asset ${key}: ${error.message ?? error}`);
 				}
-				soundFonts.push({ key, programs: usage.length, rawBytes: data.length, embeddedBytes: bytes.length });
+				soundFonts.push({
+					key,
+					programs: usage.length,
+					rawBytes: data.length,
+					embeddedBytes: bytes.length,
+					//the programs the MIDI files ask for that this font does not carry
+					missing: soundFontTools.missingSoundFontPrograms(data, usage),
+				});
 			} else {
 				soundFonts.push({ key, programs: null, rawBytes: data.length, embeddedBytes: data.length });
 			}
@@ -256,6 +284,7 @@ export async function compileResources({
 		const name = group(key);
 		if (!groups.has(name)) groups.set(name, {});
 		groups.get(name)[key] = `data:${mimeType};base64,${bytes.toString('base64')}`;
+		keys.push(key);
 		rawBytes += data.length;
 		embeddedBytes += bytes.length;
 	}
@@ -273,7 +302,17 @@ export async function compileResources({
 
 	if (credits) await writeFile(join(to, 'CREDITS.txt'), credits, 'utf8');
 
-	return { groups: written, rawBytes, embeddedBytes, webpConverted, skipped, credits, soundFonts };
+	return {
+		groups: written,
+		keys,
+		rawBytes,
+		embeddedBytes,
+		webpConverted,
+		svgOptimised,
+		skipped,
+		credits,
+		soundFonts,
+	};
 }
 
 /** the plain-text credits for a manifest, one block per entry; throws on an entry that cannot be attributed */
@@ -302,7 +341,7 @@ async function runCli() {
 	const [from, to] = args.filter((a) => !a.startsWith('--'));
 	if (!from || !to) {
 		console.error(
-			'usage: node compile-resources.mjs <asset folder> <output folder> [--to-webp] [--webp-lossy[=quality]] [--no-soundfont-subset] [--soundfont-usage=bank:program,...]',
+			'usage: node compile-resources.mjs <asset folder> <output folder> [--to-webp] [--webp-lossy[=quality]] [--svgo] [--no-soundfont-subset] [--soundfont-usage=bank:program,...]',
 		);
 		process.exit(1);
 	}
@@ -315,17 +354,19 @@ async function runCli() {
 		args.find((a) => a.startsWith('--soundfont-usage='))?.slice('--soundfont-usage='.length),
 	);
 
-	const { groups, rawBytes, embeddedBytes, webpConverted, skipped, soundFonts } = await compileResources({
-		from,
-		to,
-		//a flat folder has no subdirectories to group by, so everything lands in one file
-		groupBy: (key) => (key.includes('/') ? key.slice(0, key.indexOf('/')) : 'assets'),
-		toWebp,
-		webpLossless,
-		webpQuality,
-		soundFont: !args.includes('--no-soundfont-subset'),
-		soundFontUsage,
-	});
+	const { groups, rawBytes, embeddedBytes, webpConverted, svgOptimised, skipped, soundFonts } =
+		await compileResources({
+			from,
+			to,
+			//a flat folder has no subdirectories to group by, so everything lands in one file
+			groupBy: (key) => (key.includes('/') ? key.slice(0, key.indexOf('/')) : 'assets'),
+			toWebp,
+			webpLossless,
+			webpQuality,
+			svgo: args.includes('--svgo'),
+			soundFont: !args.includes('--no-soundfont-subset'),
+			soundFontUsage,
+		});
 
 	const kb = (n) => (n / 1024).toFixed(1).padStart(8) + ' KB';
 	for (const { name, count, size } of groups) {
@@ -338,7 +379,14 @@ async function runCli() {
 				? `  ${font.key}: SoundFont embedded whole (${kb(font.rawBytes)}), no shipped MIDI to subset against`
 				: `  ${font.key}: SoundFont subset to ${font.programs} program(s), ${kb(font.rawBytes)} -> ${kb(font.embeddedBytes)}`,
 		);
+		if (font.missing?.length > 0) {
+			console.log(
+				`  warning: ${font.key} does not carry ${font.missing.map(({ bank, program }) => `${bank}:${program}`).join(', ')}: ` +
+					"they play the font's piano, or the built-in synthesizer with `missingProgram: 'synth'`",
+			);
+		}
 	}
+	if (args.includes('--svgo')) console.log(`  ${svgOptimised} SVG(s) optimised`);
 	if (toWebp) {
 		console.log(
 			`  ${webpConverted} image(s) converted to WebP (${webpLossless ? 'lossless' : `lossy, quality ${webpQuality}`}), ` +

package/tools/emit-page.d.mts

@@ -20,12 +20,16 @@ export interface EmitPageOptions {
 	toWebp?: boolean;
 	webpLossless?: boolean;
 	webpQuality?: number;
+	/** minify embedded `.svg` assets through the optional `svgo` package; false by default */
+	svgo?: boolean;
 	/** Subset an embedded `.sf2` to the programs the embedded `.mid`/`.midi` files use. Default true; `false` embeds every SoundFont whole. */
 	soundFont?: boolean;
 	/** Explicit `{ bank, program }` list to subset a SoundFont to, overriding the MIDI-derived list. */
 	soundFontUsage?: readonly SoundFontUsage[];
 	/** the page's Content-Security-Policy: on by default, `false` to leave it out */
 	csp?: boolean | CspOptions;
+	/** fails the build when the page a player downloads (the standalone file, else the page and its scripts) is larger than this many bytes */
+	maxPageBytes?: number;
 }
 
 export interface CspOptions {
@@ -42,10 +46,15 @@ export interface EmitPageResult {
 	rawBytes: number;
 	embeddedBytes: number;
 	webpConverted: number;
+	svgOptimised: number;
 	/** one entry per embedded `.sf2`: the programs kept (null when embedded whole) and the byte saving */
 	soundFonts: SoundFontEmbed[];
 	compressed: CompressRow[] | null;
 	single: SingleFileResult | null;
+	/** embedded assets whose path is never named in the game's script: a hint, since a path built at run time is not seen */
+	unusedAssets: string[];
+	/** bytes a player downloads to open the page */
+	pageBytes: number;
 }
 
 /** finishes a vite build as a page that opens from `file://` */

package/tools/emit-page.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFile, writeFile, rm, stat } from 'node:fs/promises';
+import { readFile, readdir, writeFile, rm, stat } from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
 import { join, resolve as resolvePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -29,7 +29,7 @@ import { withContentSecurityPolicy } from './csp.mjs';
  * usage: mwg-emit <project folder> [--dist=<dir>] [--assets=<dir>] [--no-csp] [--connect=<origin>]...
  *                 [--no-compress] [--xz]
  *                 [--single-file] [--single-file-compress[=level]]
- *                 [--single-file-brotli[=quality]] [--to-webp] [--webp-lossy[=quality]]
+ *                 [--single-file-brotli[=quality]] [--to-webp] [--webp-lossy[=quality]] [--svgo]
  *                 [--no-soundfont-subset] [--soundfont-usage=bank:program,...]
  *
  * `--dist` defaults to `<project folder>/dist` and `--assets` to `<project folder>/assets`; with
@@ -53,6 +53,9 @@ import { withContentSecurityPolicy } from './csp.mjs';
  * `--to-webp` converts `.png`/`.jpg`/`.jpeg` example assets to WebP before embedding (see
  * `tools/webp-convert.mjs`), lossless by default; `--webp-lossy[=quality]` opts into lossy
  * re-encoding instead. Needs the optional `sharp` devDependency installed.
+ *
+ * `--svgo` minifies embedded `.svg` assets (see `tools/svg-optimise.mjs`), keeping the `viewBox` and
+ * every id. Needs the optional `svgo` package installed.
  */
 
 /**
@@ -74,9 +77,11 @@ export async function emitPage({
 	toWebp = false,
 	webpLossless = true,
 	webpQuality = 90,
+	svgo = false,
 	soundFont = true,
 	soundFontUsage,
 	csp = true,
+	maxPageBytes,
 }) {
 	if (!dist) throw new Error('emitPage needs the dist folder of a vite build');
 	if (!assets && assetFiles?.length) throw new Error(`unknown asset file ${assetFiles[0]}: no assets folder`);
@@ -89,10 +94,11 @@ export async function emitPage({
 				toWebp,
 				webpLossless,
 				webpQuality,
+				svgo,
 				soundFont,
 				soundFontUsage,
 			})
-		: { groups: [], rawBytes: 0, embeddedBytes: 0, webpConverted: 0, soundFonts: [] };
+		: { groups: [], keys: [], rawBytes: 0, embeddedBytes: 0, webpConverted: 0, svgOptimised: 0, soundFonts: [] };
 
 	const html = await readFile(join(dist, 'index.html'), 'utf8');
 	const classic = toClassicScript(html);
@@ -119,7 +125,38 @@ export async function emitPage({
 		const standalone = await readFile(single.path, 'utf8');
 		await writeFile(single.path, withContentSecurityPolicy(standalone, { ...cspOptions, scripts }), 'utf8');
 	}
-	return { dist, entry: classic.src, ...compiled, compressed, single };
+	const unusedAssets = await unreferencedAssets(dist, classic.src, compiled.keys);
+	const pageBytes = await pageWeight(dist, single, compiled.groups);
+	if (maxPageBytes !== undefined && pageBytes > maxPageBytes) {
+		throw new Error(
+			`the page weighs ${kb(pageBytes)}, over the ${kb(maxPageBytes)} budget (maxPageBytes)` +
+				(unusedAssets.length
+					? `; ${unusedAssets.length} embedded asset(s) are never named in the game code: ${unusedAssets.slice(0, 5).join(', ')}`
+					: ''),
+		);
+	}
+	return { dist, entry: classic.src, ...compiled, compressed, single, unusedAssets, pageBytes };
+}
+
+/** the embedded assets whose path appears nowhere in the game's script: a hint (a path built at run time is not seen), never an error */
+async function unreferencedAssets(dist, entry, keys) {
+	if (keys.length === 0) return [];
+	const code = await readFile(join(dist, entry), 'utf8').catch(() => '');
+	return keys.filter((key) => !code.includes(key)).sort();
+}
+
+/** the bytes a player downloads to open the page: the single file when there is one, else the page, the game script and the asset scripts */
+async function pageWeight(dist, single, groups) {
+	const files = single
+		? [single.path]
+		: [
+				join(dist, 'index.html'),
+				...(await readdir(dist)).filter((name) => name.endsWith('.js')).map((name) => join(dist, name)),
+				...groups.map((g) => join(dist, 'assets', `${g.name}.js`)),
+			];
+	let total = 0;
+	for (const file of files) total += (await stat(file)).size;
+	return total;
 }
 
 const kb = (n) => (n / 1024).toFixed(1) + ' KB';
@@ -162,8 +199,10 @@ async function main(argv) {
 		toWebp: argv.includes('--to-webp'),
 		webpLossless: !webpLossyFlag,
 		webpQuality: webpLossyFlag?.includes('=') ? Number(webpLossyFlag.split('=')[1]) : 90,
+		svgo: argv.includes('--svgo'),
 		soundFont: !argv.includes('--no-soundfont-subset'),
 		soundFontUsage,
+		maxPageBytes: value('max-page-bytes') ? Number(value('max-page-bytes')) : undefined,
 		csp: argv.includes('--no-csp')
 			? false
 			: { connect: argv.filter((a) => a.startsWith('--connect=')).map((a) => a.slice('--connect='.length)) },
@@ -179,12 +218,26 @@ async function main(argv) {
 				`${kb(result.rawBytes)} -> ${kb(result.embeddedBytes)} embedded`,
 		);
 	}
+	if (argv.includes('--svgo')) console.log(`  ${result.svgOptimised} SVG(s) optimised`);
+	console.log(`  page weight ${kb(result.pageBytes)}`);
+	if (result.unusedAssets.length > 0) {
+		console.log(
+			`  warning: ${result.unusedAssets.length} embedded asset(s) are never named in the game code, ` +
+				`so they only add weight (a path built at run time is not seen): ${result.unusedAssets.join(', ')}`,
+		);
+	}
 	for (const font of result.soundFonts ?? []) {
 		console.log(
 			font.programs === null
 				? `  ${font.key}: SoundFont embedded whole (${kb(font.rawBytes)}), no shipped MIDI to subset against`
 				: `  ${font.key}: SoundFont subset to ${font.programs} program(s), ${kb(font.rawBytes)} -> ${kb(font.embeddedBytes)}`,
 		);
+		if (font.missing?.length > 0) {
+			console.log(
+				`  warning: ${font.key} does not carry ${font.missing.map(({ bank, program }) => `${bank}:${program}`).join(', ')}: ` +
+					"they play the font's piano, or the built-in synthesizer with `missingProgram: 'synth'`",
+			);
+		}
 	}
 	console.log('  open index.html directly - no server needed');
 	if (result.compressed) {

package/tools/find-chrome.mjs

@@ -17,9 +17,11 @@ async function playwright() {
 /**
  * The browser to drive: the platform's usual Chrome (or, on Windows, Edge), then a Chromium that
  * Playwright itself installed (`PLAYWRIGHT_BROWSERS_PATH`, common in CI images and containers),
- * then whatever is on PATH. `CHROME_PATH` overrides all of them in `launchChrome`.
+ * then whatever is on PATH. `CHROME_PATH` or `CHROME` overrides all of them.
  */
 export async function findChrome() {
+	const override = process.env.CHROME_PATH || process.env.CHROME;
+	if (override) return override;
 	const candidates =
 		process.platform === 'win32'
 			? [
@@ -93,7 +95,7 @@ async function playwrightChromium() {
  * page setup and assertions; this is the launch they all had in common.
  */
 export async function launchChrome({ argsEnv = 'MWG_BENCHMARK_CHROME_ARGS' } = {}) {
-	const executablePath = process.env.CHROME_PATH ?? (await findChrome());
+	const executablePath = await findChrome();
 	const extraArgs = (process.env[argsEnv] ?? '').split(' ').filter(Boolean);
 	const { chromium } = await playwright();
 	return chromium.launch({

package/tools/init.mjs

@@ -26,7 +26,13 @@ export function initFiles(name) {
 					private: true,
 					version: '0.0.0',
 					type: 'module',
-					scripts: { dev: 'vite', build: 'vite build', check: 'tsc --noEmit' },
+					scripts: {
+						dev: 'vite',
+						build: 'vite build',
+						check: 'tsc --noEmit',
+						test: 'node --test',
+						'hooks:install': 'git config core.hooksPath .githooks',
+					},
 					dependencies: { '@datamoc/mw_games': `^${PACKAGE_VERSION}`, 'pixi.js': '^8.20.1' },
 					devDependencies: { typescript: '^7.0.2', vite: '^8.2.2' },
 				},
@@ -101,7 +107,9 @@ export function initFiles(name) {
 			'',
 		].join('\n'),
 		'assets/.gitkeep': '',
-		'README.md': `# ${name}\n\n\`npm install\`, then \`npm run dev\` to play it while you edit, \`npm run build\` to write \`dist/\`.\nOpen \`dist/index.html\` (or \`dist/standalone.html\`) by double-clicking it: no server needed.\n\nPut images and sounds under \`assets/\`; the build compiles them into the page. An \`assets/credits.json\`\n(\`[{ "name": "...", "license": "...", "author": "...", "url": "..." }]\`) becomes \`dist/CREDITS.txt\`.\n`,
+		'.gitignore': 'node_modules/\ndist/\n.opencode/\n.coord-session\n',
+		'.githooks/pre-commit': '#!/bin/sh\nset -e\nnpm run check\nnpm test\n',
+		'README.md': `# ${name}\n\n\`npm install\`, then \`npm run dev\` to play it while you edit, \`npm run build\` to write \`dist/\`.\nOpen \`dist/index.html\` (or \`dist/standalone.html\`) by double-clicking it: no server needed.\n\nPut images and sounds under \`assets/\`; the build compiles them into the page. An \`assets/credits.json\`\n(\`[{ "name": "...", "license": "...", "author": "...", "url": "..." }]\`) becomes \`dist/CREDITS.txt\`.\n\nAfter \`git init\`, run \`npm run hooks:install\` to enable the included pre-commit hook.\nIt runs \`npm run check\` and \`npm test\`; add your tests under \`tests/\`.\n`,
 	};
 }
 
@@ -121,7 +129,7 @@ export function initProject(folder) {
 	)) {
 		const file = join(target, path);
 		mkdirSync(dirname(file), { recursive: true });
-		writeFileSync(file, content, 'utf8');
+		writeFileSync(file, content, { encoding: 'utf8', mode: path === '.githooks/pre-commit' ? 0o755 : 0o644 });
 		written.push(path);
 	}
 	return { folder: target, files: written };

package/tools/play-uci.mjs

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 import { fileURLToPath } from 'node:url';
-import { readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import { join, extname } from 'node:path';
 import { createInterface } from 'node:readline';
-import { applyMove, cloneChess, legalMoves, parseFen, squareName, startingChess } from '../src/board/chess.ts';
-import { parseUciMove, probeBook } from '../src/board/openings.ts';
-import { searchTourney } from '../src/board/tourney.ts';
-import { loadTablebaseEnding, probeTablebase } from '../src/board/tablebase.ts';
+//the framework's own modules: the TypeScript sources inside this repository, the built `dist` inside an
+//installed package, which ships no `src`
+const fromSource = existsSync(new URL('../src/board/chess.ts', import.meta.url));
+const load = (path) => import(fromSource ? `../src/${path}.ts` : `../dist/${path}.js`);
+const { applyMove, cloneChess, legalMoves, parseFen, squareName, startingChess } = await load('board/chess');
+const { parseUciMove, probeBook } = await load('board/openings');
+const { searchTourney } = await load('board/tourney');
+const { loadTablebaseEnding, probeTablebase } = await load('board/tablebase');
 
 /**
  * A UCI adapter over the tournament engine: `position`/`go` on stdin, `bestmove`

package/tools/svg-optimise.d.mts

@@ -0,0 +1,8 @@
+/** the svgo configuration `optimiseSvg` runs */
+export declare const SVGO_CONFIG: {
+	multipass: boolean;
+	plugins: { name: string; params: { overrides: Record<string, boolean> } }[];
+};
+
+/** the SVG bytes minified; needs the optional `svgo` package, and throws for a file that is not valid SVG */
+export declare function optimiseSvg(buffer: Buffer): Promise<Buffer>;

package/tools/svg-optimise.mjs

@@ -0,0 +1,45 @@
+/**
+ * Minifies an SVG for embedding, the SVG half of what `webp-convert` is for raster images, kept as
+ * its own module so `tools/compile-resources.mjs` never has to import an optimiser itself: it
+ * dynamically imports `svgo`, which a game that opts in installs in its own project the way it does
+ * `sharp` for WebP (`npm install --save-dev svgo`). A game that never passes `svgo: true` carries
+ * no new dependency at all.
+ *
+ * Optimising must not change what the game can see or name. Ids are left alone (`cleanupIds` is off:
+ * a `<use href="#id">`, a gradient reference or a style selector inside the file, or an id the game
+ * looks up, would break if minified), and the `viewBox` stays because svgo 4's default preset no
+ * longer removes it (a game scales a texture by it), which is why this needs svgo 4 or newer.
+ * Everything else in the default preset applies: comments, metadata, editor data, default
+ * attributes, redundant groups, path precision.
+ */
+
+/** the svgo configuration `optimiseSvg` runs, exposed so a game can see exactly what it opts into */
+export const SVGO_CONFIG = {
+	multipass: true,
+	plugins: [{ name: 'preset-default', params: { overrides: { cleanupIds: false } } }],
+};
+
+let svgoModule;
+async function loadSvgo() {
+	if (svgoModule) return svgoModule;
+	try {
+		svgoModule = await import('svgo');
+	} catch (err) {
+		throw new Error(
+			'SVG optimisation needs the optional `svgo` package, which is not installed. ' +
+				'Run `npm install --save-dev svgo` in your project to use `svgo: true`, or leave ' +
+				'it off (the default) to embed SVG files as they are.',
+			{ cause: err },
+		);
+	}
+	return svgoModule;
+}
+
+/**
+ * @param {Buffer} buffer the SVG file's bytes (UTF-8)
+ * @returns {Promise<Buffer>} the optimised SVG; svgo throws for a file that is not valid SVG
+ */
+export async function optimiseSvg(buffer) {
+	const { optimize } = await loadSvgo();
+	return Buffer.from(optimize(buffer.toString('utf8'), SVGO_CONFIG).data, 'utf8');
+}

package/tools/vite.mjs

@@ -16,6 +16,7 @@ import { buildArtifactSbom, serialize, shippedFiles } from './sbom.mjs';
  * affects the build only, so the dev server still serves the asset folder normally.
  * An embedded `.sf2` or `.sf3` is subset at build time to the programs the embedded `.mid` files
  * use (`soundFont: false` embeds it whole, `soundFontUsage` names the programs instead).
+ * `svgo: true` minifies embedded `.svg` assets (needs the optional `svgo` package).
  * At the end of the build it runs `emitPage` over the output folder with the same
  * options. A setting the game's own config gives explicitly still wins, since vite merges a
  * plugin's `config` result under the user's.
@@ -79,7 +80,15 @@ export function mwgPage(options = {}) {
 			const { assets: _assets, sbom = true, ...emitOptions } = options;
 			const source = assets ? resolve(root, assets) : undefined;
 			const dist = resolve(root, outDir);
-			await emitPage({ ...emitOptions, dist, assets: source && existsSync(source) ? source : undefined });
+			const page = await emitPage({
+				...emitOptions,
+				dist,
+				assets: source && existsSync(source) ? source : undefined,
+			});
+			if (page.unusedAssets.length > 0)
+				console.warn(
+					`mwg-page: ${page.unusedAssets.length} embedded asset(s) are never named in the game code: ${page.unusedAssets.join(', ')}`,
+				);
 			if (sbom) {
 				const manifest = join(root, 'package.json');
 				const packageJson = existsSync(manifest)

package/tools.md

@@ -23,7 +23,8 @@ by double-clicking. Run from the repo root.
 
 | tool | what it does | run |
 | --- | --- | --- |
-| `compile-resources` | Turns an asset folder into `data:` URI scripts under `window.__MWG_ASSETS__`, grouped by top-level folder. `toWebp: true` converts `.png`/`.jpg`/`.jpeg` to WebP first (lossless by default, only kept when actually smaller, key unchanged) via the optional `sharp` devDependency, dynamically imported only when used (item 350) | called by the example builds; `node tools/compile-resources.mjs <asset folder> <output folder> [--to-webp] [--webp-lossy[=quality]]` |
+| `compile-resources` | Turns an asset folder into `data:` URI scripts under `window.__MWG_ASSETS__`, grouped by top-level folder. `toWebp: true` converts `.png`/`.jpg`/`.jpeg` to WebP first (lossless by default, only kept when actually smaller, key unchanged) via the optional `sharp` devDependency, dynamically imported only when used (item 350). `svgo: true` minifies `.svg` assets through the optional `svgo` package (version 4 or newer, ids and `viewBox` kept, only kept when smaller). Each subset SoundFont's result lists the programs the game's MIDI files ask for that the font does not carry, and `mwg-emit` warns about them | called by the example builds; `node tools/compile-resources.mjs <asset folder> <output folder> [--to-webp] [--webp-lossy[=quality]] [--svgo]` |
+| `svg-optimise` | Minifies one SVG file's bytes through `svgo` with ids and the `viewBox` left alone; the standalone half of `compile-resources`'s `svgo` option (item 428). On the repository's own 30 SVGs: 13.6% smaller, worst rendered pixel difference 1 in 255 | `optimiseSvg` from `@datamoc/mw_games/tools/svg-optimise`, or `mwg-emit <folder> --svgo` |
 | `webp-convert` | Converts one raster image buffer (PNG/JPEG) to WebP, lossless by default; the standalone half of `compile-resources`'s `toWebp` option (item 350) | `node tools/webp-convert.mjs <file.png\|file.jpg> [--lossy[=quality]]` |
 | `emit-page` | Finishes a vite build so it opens from `file://` with no server: compiles the assets, rewrites the entry to a classic deferred script with the asset scripts before it, then optionally precompresses and writes a single-file variant (item 381) | `emitPage(options)` from `@datamoc/mw_games/tools/emit-page`, the `mwg-emit <folder> [--dist=] [--assets=]` command, or called by each `example:*:build` script here |
 | `init` | `mwg-init <folder>` writes a starter project (vite config using `mwgPage`, one scene, tsconfig, scripts) that builds to a double-clickable page | `npx mwg-init my-game` |
@@ -199,7 +200,9 @@ same build.
 | tool | what it does | run |
 | --- | --- | --- |
 | `roadmap-progress` | Reports CLOSED.md + ROADMAP.md completion: numbered items in batches of 25, plus the 1.0 exit checklist on its own row (checks to run, not capabilities, so they stay out of the numbered totals), optionally in a browser | `npm run roadmap:progress` |
-| `build-webpage-examples` / `build-webpage-docs` | Generate the live examples and Documentation page under `webpage/` (`REFERENCE.md` guide + TypeDoc under `documentation/api/`) | `npm run webpage:examples`, `npm run webpage:docs` |
+| `build-webpage-examples` / `build-webpage-docs` | Generate the live examples and Documentation page under `webpage/` (`REFERENCE.md` guide + TypeDoc under `documentation/api/` + the examples index) | `npm run webpage:examples`, `npm run webpage:docs` |
+| `build-bridge-tutorial` / `bins-smoke` | `build-bridge-tutorial` writes `webpage/tutorials/bridge/index.html` from `tools/templates/bridge-tutorial.html`, quoting the code blocks of `examples/bridge` so a test can check them. `bins-smoke` packs the project, installs the tarball in an empty folder and runs every `mwg-*` bin with `--help` on the Node that runs it; CI runs it on Node 20.19.0. Repository tools, not shipped | `npm run build:bridge-tutorial`, `npm run bins:smoke` |
+| `build-example-index` | Writes `documentation/examples.html`, read from source text (no typedoc, no renderer): for each public module the symbols that carry an `@example`, each linked to its typedoc page when one exists, with the runnable `examples/` that import the module. Part of `webpage:docs`; a repository tool, not shipped (item 430) | `npm run webpage:docs`, or `node tools/build-example-index.mjs [outFile]` |
 | `make-example-diagrams` / `make-architecture-diagrams` | Rebuild the generated diagrams under `webpage/assets` (never hand-drawn) | `npm run webpage:diagrams` |
 | `api-report` | Regenerates `API_REPORT.md` from the built declarations; `--check` compares instead. A CI gate | `npm run api:report`, `npm run api:check` |
 | `project-stats` | Writes `PROJECT_STATS.json`/`PROJECT_STATS.md` and the website statistics page; `--check` compares. A CI gate | `npm run stats:write`, `npm run stats:check` |