@datamoc/mw_games 0.42.0 → 0.43.0

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';
@@ -81,6 +81,7 @@ export async function emitPage({
 	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`);
@@ -97,7 +98,7 @@ export async function emitPage({
 				soundFont,
 				soundFontUsage,
 			})
-		: { groups: [], rawBytes: 0, embeddedBytes: 0, webpConverted: 0, svgOptimised: 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);
@@ -124,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';
@@ -170,6 +202,7 @@ async function main(argv) {
 		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)) },
@@ -186,6 +219,13 @@ async function main(argv) {
 		);
 	}
 	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

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/vite.mjs

@@ -80,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

@@ -201,6 +201,7 @@ same build.
 | --- | --- | --- |
 | `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/` + 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` |