@datamoc/mw_games 0.36.1 → 0.37.0

package/sbom.cdx.json

@@ -1,7 +1,7 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:17cd32d6-94ff-58fa-90e1-9bec6171c507",
+  "serialNumber": "urn:uuid:fc255c4f-4827-5c1a-9b7d-2851ddb9d40e",
   "version": 1,
   "metadata": {
     "tools": {
@@ -10,16 +10,16 @@
           "type": "application",
           "group": "datamoc",
           "name": "tools/sbom.mjs",
-          "version": "0.36.1"
+          "version": "0.37.0"
         }
       ]
     },
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/%40datamoc/mw_games@0.36.1",
+      "bom-ref": "pkg:npm/%40datamoc/mw_games@0.37.0",
       "name": "@datamoc/mw_games",
-      "version": "0.36.1",
-      "purl": "pkg:npm/%40datamoc/mw_games@0.36.1",
+      "version": "0.37.0",
+      "purl": "pkg:npm/%40datamoc/mw_games@0.37.0",
       "description": "A local-file game framework: renderer-free game logic, drawn through PixiJS in 2D or Babylon.js in 3D, with mobile and desktop packaging.",
       "licenses": [
         {
@@ -1375,6 +1375,27 @@
         }
       ]
     },
+    {
+      "type": "library",
+      "bom-ref": "pkg:npm/%40types/matter-js@0.20.2",
+      "name": "@types/matter-js",
+      "version": "0.20.2",
+      "purl": "pkg:npm/%40types/matter-js@0.20.2",
+      "scope": "excluded",
+      "hashes": [
+        {
+          "alg": "SHA-512",
+          "content": "dcf3cacb7431bd9f3d87dfb0741576e3cf08d492d5b3b0c4a4890fbe03bc242d6651d89548edfb648bd572d3930fb848abc3802f6809dee8064ae522a7a0e10b"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "MIT"
+          }
+        }
+      ]
+    },
     {
       "type": "library",
       "bom-ref": "pkg:npm/%40types/node@26.6.5",
@@ -3160,6 +3181,27 @@
         }
       ]
     },
+    {
+      "type": "library",
+      "bom-ref": "pkg:npm/matter-js@0.20.0",
+      "name": "matter-js",
+      "version": "0.20.0",
+      "purl": "pkg:npm/matter-js@0.20.0",
+      "scope": "excluded",
+      "hashes": [
+        {
+          "alg": "SHA-512",
+          "content": "882f5f611ef3553dc7a69367b05b29f573a841d40ddad5327da2a0e021cb1fc6cdfa3e864f81b0ec81f6acfd2d7e501e6eb1c5c3bdf4451dc3915499457f21c0"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "MIT"
+          }
+        }
+      ]
+    },
     {
       "type": "library",
       "bom-ref": "pkg:npm/minimatch@10.2.6",
@@ -4601,7 +4643,7 @@
       ]
     },
     {
-      "ref": "pkg:npm/%40datamoc/mw_games@0.36.1",
+      "ref": "pkg:npm/%40datamoc/mw_games@0.37.0",
       "dependsOn": [
         "pkg:npm/%40babylonjs/core@9.30.0",
         "pkg:npm/%40babylonjs/loaders@9.30.0",
@@ -4610,9 +4652,11 @@
         "pkg:npm/%40capacitor/core@8.5.3",
         "pkg:npm/%40capacitor/ios@8.5.3",
         "pkg:npm/%40datamoc/pyroeis@0.9.0",
+        "pkg:npm/%40types/matter-js@0.20.2",
         "pkg:npm/%40types/node@26.6.5",
         "pkg:npm/%40types/ws@8.18.2",
         "pkg:npm/json5@2.2.3",
+        "pkg:npm/matter-js@0.20.0",
         "pkg:npm/multithreading@0.3.52",
         "pkg:npm/pixi.js@8.22.0",
         "pkg:npm/playwright-core@1.64.0",
@@ -4936,6 +4980,10 @@
         "pkg:npm/%40types/node@26.6.5"
       ]
     },
+    {
+      "ref": "pkg:npm/%40types/matter-js@0.20.2",
+      "dependsOn": []
+    },
     {
       "ref": "pkg:npm/%40types/node@26.6.5",
       "dependsOn": [
@@ -5337,6 +5385,10 @@
       "ref": "pkg:npm/lru-cache@11.5.3",
       "dependsOn": []
     },
+    {
+      "ref": "pkg:npm/matter-js@0.20.0",
+      "dependsOn": []
+    },
     {
       "ref": "pkg:npm/minimatch@10.2.6",
       "dependsOn": [

package/tools/browser-driver.d.mts

@@ -38,6 +38,8 @@ export interface BrowserDriver {
 	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>;
@@ -77,6 +79,18 @@ 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[];
 

package/tools/browser-driver.mjs

@@ -146,6 +146,47 @@ export function buildTapSequence(x, y) {
 	];
 }
 
+/** `steps` evenly spaced points from (x1, y1) to (x2, y2), both ends included */
+function dragPath(x1, y1, x2, y2, steps) {
+	const count = Math.max(1, Math.floor(steps));
+	return Array.from({ length: count + 1 }, (_, i) => ({
+		x: Math.round(x1 + ((x2 - x1) * i) / count),
+		y: Math.round(y1 + ((y2 - y1) * i) / count),
+	}));
+}
+
+/**
+ * The CDP `Input.dispatchMouseEvent` sequence a drag is: press at the start, move through
+ * `steps` intermediate points with the button held, release at the end - the down, move, up a
+ * pointer-drag handler (a bridge builder, a slider, a pan) needs and `tap` cannot give.
+ */
+export function buildDragSequence(x1, y1, x2, y2, steps = 8) {
+	const path = dragPath(x1, y1, x2, y2, steps);
+	const last = path[path.length - 1];
+	return [
+		{ type: 'mouseMoved', x: x1, y: y1, button: 'none', buttons: 0 },
+		{ type: 'mousePressed', x: x1, y: y1, button: 'left', buttonValue: 0, clickCount: 1, buttons: 1 },
+		...path.slice(1).map((p) => ({ type: 'mouseMoved', x: p.x, y: p.y, button: 'left', buttons: 1 })),
+		{ type: 'mouseReleased', x: last.x, y: last.y, button: 'left', buttonValue: 0, clickCount: 1, buttons: 0 },
+	];
+}
+
+/** the in-page counterpart of `buildDragSequence` for Firefox, for the reason `pageTapSource` exists */
+export function pageDragSource(x1, y1, x2, y2, steps = 8) {
+	const path = dragPath(x1, y1, x2, y2, steps);
+	return `(() => {
+		const canvas = document.querySelector("canvas");
+		const base = { bubbles: true, cancelable: true, composed: true, pointerId: 1, pointerType: "mouse", isPrimary: true, button: 0 };
+		const fire = (type, x, y, buttons) => canvas.dispatchEvent(new PointerEvent(type, { ...base, clientX: x, clientY: y, buttons }));
+		const path = ${JSON.stringify(path)};
+		fire("pointermove", path[0].x, path[0].y, 0);
+		fire("pointerdown", path[0].x, path[0].y, 1);
+		for (const p of path.slice(1)) fire("pointermove", p.x, p.y, 1);
+		const end = path[path.length - 1];
+		fire("pointerup", end.x, end.y, 0);
+	})()`;
+}
+
 /**
  * The named keys a game binds, with everything each input protocol needs: the
  * DOM `code`, the Windows virtual-key code CDP wants, the character the key types
@@ -520,6 +561,13 @@ async function waitForReadyPage(evaluate, consoleErrors, url, timeoutMs = READY_
 	}
 }
 
+/** the canvas rectangle in CSS pixels, which canvas fractions are measured against */
+function canvasBox(evaluate) {
+	return evaluate(
+		'(() => { const box = document.querySelector("canvas").getBoundingClientRect(); return { x: box.x, y: box.y, w: box.width, h: box.height }; })()',
+	);
+}
+
 /** runs a consumer function against the live page, awaiting it when it is async */
 function runPageScript(evaluate, fn, args) {
 	return evaluate(`(${fn.toString()})(...${JSON.stringify(args)})`, true);
@@ -616,6 +664,14 @@ export async function driveChrome(options = {}) {
 				await cdp.send('Input.dispatchMouseEvent', event);
 			}
 		},
+		/** press at one canvas fraction, move to another with the button held, release */
+		drag: async (fromX, fromY, toX, toY, steps) => {
+			const box = await canvasBox(evaluate);
+			const at = (fx, fy) => [Math.round(box.x + box.w * fx), Math.round(box.y + box.h * fy)];
+			for (const event of buildDragSequence(...at(fromX, fromY), ...at(toX, toY), steps)) {
+				await cdp.send('Input.dispatchMouseEvent', event);
+			}
+		},
 		/** presses and releases one key through Chrome's trusted input channel (P41) */
 		press: async (key, holdMs = 60) => {
 			const sequence = cdpKeySequence(key);
@@ -769,6 +825,12 @@ export async function driveFirefox(options = {}) {
 			//actions never reach Pixi 8's EventSystem, and this is the measured-working path.
 			await evaluate(pageTapSource(x, y), true);
 		},
+		/** press at one canvas fraction, move to another with the button held, release */
+		drag: async (fromX, fromY, toX, toY, steps) => {
+			const box = await canvasBox(evaluate);
+			const at = (fx, fy) => [Math.round(box.x + box.w * fx), Math.round(box.y + box.h * fy)];
+			await evaluate(pageDragSource(...at(fromX, fromY), ...at(toX, toY), steps), true);
+		},
 		/** presses and releases one key through WebDriver's key actions (P41) */
 		press: async (key, holdMs = 60) => {
 			const actions = bidiKeyActions(key, holdMs);

package/tools/build-tablebases.mjs

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { mkdirSync, writeFileSync } from 'node:fs';
-import { join, relative, basename } from 'node:path';
+import { join, relative } from 'node:path';
 import { huffEncode } from '../src/board/tablebase.ts';
 import { spawn } from '../src/threads/spawn.ts';
 
@@ -451,7 +453,9 @@ function defaultJobs() {
 	return 2;
 }
 
-const isMain = process.argv[1] && import.meta.url.endsWith(basename(process.argv[1]));
+//the real path, since an npm `bin` shim reaches this file through a symlink; a suffix test on the
+//name is not enough (`compress-dist.mjs` ends with `t.mjs`)
+const isMain = process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
 
 if (isMain) {
 	const args = process.argv.slice(2);

package/tools/classic-html.mjs

@@ -37,7 +37,7 @@ export function toClassicScript(html) {
 	return { html: html.replace(scriptTag, `<script defer src="${match[1]}"></script>`), src: match[1] };
 }
 
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+async function runCli() {
 	const input = process.argv[2];
 	if (!input) {
 		console.error('Usage: node tools/classic-html.mjs dist/index.html');
@@ -59,3 +59,11 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
 		}
 	}
 }
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+	//no top-level await: a vite config loaded as CommonJS has to be able to require() this module
+	runCli().catch((error) => {
+		console.error(error);
+		process.exitCode = 1;
+	});
+}

package/tools/compile-openings.mjs

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { readFileSync, writeFileSync, readdirSync } from 'node:fs';
-import { basename, join, relative } from 'node:path';
+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';
 
@@ -115,7 +117,9 @@ export function compileBook(dir) {
 	return { version: 1, positions };
 }
 
-const isMain = process.argv[1] && import.meta.url.endsWith(basename(process.argv[1]));
+//the real path, since an npm `bin` shim reaches this file through a symlink; a suffix test on the
+//name is not enough (`compress-dist.mjs` ends with `t.mjs`)
+const isMain = process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
 
 if (isMain) {
 	const [dir, out] = process.argv.slice(2);

package/tools/compile-resources.d.mts

@@ -24,6 +24,11 @@ export interface CompileResourcesResult {
 	embeddedBytes: number;
 	webpConverted: number;
 	skipped: number;
+	/** the `CREDITS.txt` text when the asset folder holds a `credits.json`, else null */
+	credits: string | null;
 }
 
+/** the plain-text credits for a manifest (an array, or `{ credits: [...] }`, of `{ name, license, author?, url? }`) */
+export function creditsText(manifest: unknown): string;
+
 export function compileResources(options: CompileResourcesOptions): Promise<CompileResourcesResult>;

package/tools/compile-resources.mjs

@@ -1,5 +1,7 @@
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { readdir, readFile, mkdir, writeFile, rm } from 'node:fs/promises';
-import { join, extname, relative, sep, dirname, basename } from 'node:path';
+import { join, extname, relative, sep, dirname } from 'node:path';
 import { WEBP_CONVERTIBLE_EXTENSIONS } from './webp-convert.mjs';
 
 /**
@@ -68,6 +70,11 @@ export async function* walk(dir) {
  *   lossy re-encoding for photographic source art)
  * @param options.webpQuality 0-100, used only when `webpLossless` is false (default 90)
  * @returns the group names, in the order the page should load them
+ *
+ * An `assets/credits.json` (an array, or `{ "credits": [...] }`, of `{ name, license, author?, url? }`)
+ * is not embedded as an asset: it is turned into `CREDITS.txt` beside the compiled scripts, for
+ * the attribution that free art packs require. An entry without a `name` and a `license` is an
+ * error, since a credits file that silently omits a pack defeats its purpose.
  */
 export async function compileResources({
 	from,
@@ -96,7 +103,14 @@ export async function compileResources({
 	// (or requires installing) sharp
 	const toWebp = convertToWebp ? (await import('./webp-convert.mjs')).toWebp : null;
 
+	const creditsFile = join(from, 'credits.json');
+	let credits = null;
+
 	for await (const file of walk(from)) {
+		if (file === creditsFile) {
+			credits = creditsText(JSON.parse(await readFile(file, 'utf8')));
+			continue;
+		}
 		const ext = extname(file).toLowerCase();
 		const type = types[ext];
 		if (!type) {
@@ -136,14 +150,33 @@ export async function compileResources({
 		written.push({ name, count: Object.keys(assets).length, size: js.length });
 	}
 
-	return { groups: written, rawBytes, embeddedBytes, webpConverted, skipped };
+	if (credits) await writeFile(join(to, 'CREDITS.txt'), credits, 'utf8');
+
+	return { groups: written, rawBytes, embeddedBytes, webpConverted, skipped, credits };
+}
+
+/** the plain-text credits for a manifest, one block per entry; throws on an entry that cannot be attributed */
+export function creditsText(manifest) {
+	const entries = Array.isArray(manifest) ? manifest : manifest?.credits;
+	if (!Array.isArray(entries)) throw new Error('credits.json must be an array or { "credits": [...] }');
+	const blocks = entries.map((entry, index) => {
+		if (typeof entry?.name !== 'string' || typeof entry?.license !== 'string') {
+			throw new Error(`credits.json entry ${index} needs a "name" and a "license"`);
+		}
+		const lines = [entry.name + (entry.author ? ` by ${entry.author}` : ''), `License: ${entry.license}`];
+		if (entry.url) lines.push(entry.url);
+		return lines.join('\n');
+	});
+	return blocks.join('\n\n') + '\n';
 }
 
 // ---------------------------------------------------------------- CLI
 
-const isMain = process.argv[1] && import.meta.url.endsWith(basename(process.argv[1]));
+//the real path, since an npm `bin` shim reaches this file through a symlink; a suffix test on the
+//name is not enough (`compress-dist.mjs` ends with `t.mjs`)
+const isMain = process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
 
-if (isMain) {
+async function runCli() {
 	const args = process.argv.slice(2);
 	const [from, to] = args.filter((a) => !a.startsWith('--'));
 	if (!from || !to) {
@@ -180,4 +213,12 @@ if (isMain) {
 	}
 }
 
+//no top-level await: a vite config loaded as CommonJS has to be able to require() this module
+if (isMain) {
+	runCli().catch((error) => {
+		console.error(error);
+		process.exitCode = 1;
+	});
+}
+
 export { dirname };

package/tools/compress-dist.mjs

@@ -1,5 +1,7 @@
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { readFile, writeFile } from 'node:fs/promises';
-import { relative, extname, basename } from 'node:path';
+import { relative, extname } from 'node:path';
 import { gzip, brotliCompress, constants } from 'node:zlib';
 import { promisify } from 'node:util';
 import { availableParallelism } from 'node:os';
@@ -153,9 +155,11 @@ async function compressOne(dir, file, { gzip, brotli, wantXz }) {
 	return row;
 }
 
-const isMain = process.argv[1] && import.meta.url.endsWith(basename(process.argv[1]));
+//the real path, since an npm `bin` shim reaches this file through a symlink; a suffix test on the
+//name is not enough (`compress-dist.mjs` ends with `t.mjs`)
+const isMain = process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
 
-if (isMain) {
+async function runCli() {
 	const [dir, ...flags] = process.argv.slice(2);
 	if (!dir) {
 		console.error('usage: node tools/compress-dist.mjs <dist folder> [--xz] [--no-gzip] [--no-brotli]');
@@ -179,3 +183,11 @@ if (isMain) {
 	}
 	console.log(`  ${rows.length} file(s) considered in ${relative(process.cwd(), dir)}`);
 }
+
+//no top-level await: a vite config loaded as CommonJS has to be able to require() this module
+if (isMain) {
+	runCli().catch((error) => {
+		console.error(error);
+		process.exitCode = 1;
+	});
+}

package/tools/emit-page.mjs

@@ -184,5 +184,9 @@ async function main(argv) {
 }
 
 //realpath, since an npm `bin` shim reaches this file through a symlink
+//no top-level await: a vite config loaded as CommonJS has to be able to require() this module
 if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url))
-	await main(process.argv.slice(2));
+	main(process.argv.slice(2)).catch((error) => {
+		console.error(error);
+		process.exitCode = 1;
+	});

package/tools/init.d.mts

@@ -0,0 +1,5 @@
+/** the starter project's files as `{ path: content }`, for a package called `name` */
+export function initFiles(name: string): Record<string, string>;
+
+/** writes the starter project into an empty or missing `folder`; throws if it already holds files */
+export function initProject(folder: string): { folder: string; files: string[] };

package/tools/init.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * `mwg-init <folder>`: the smallest game that builds into one double-clickable page.
+ *
+ * It writes a vite project that uses `mwgPage()`: one scene, a moving square, a vite config
+ * that loads without `"type": "module"` in the way `.mts` files do, and the scripts to run
+ * and build it. The point is that the nearest example to copy is already on disk, in the
+ * shape the published package supports, rather than a folder of this repository's own
+ * examples that import their sources by relative path.
+ */
+const PACKAGE_VERSION = JSON.parse(
+	readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'),
+).version;
+
+/** the project's files as `{ path: content }`, named after `name` */
+export function initFiles(name) {
+	return {
+		'package.json':
+			JSON.stringify(
+				{
+					name,
+					private: true,
+					version: '0.0.0',
+					type: 'module',
+					scripts: { dev: 'vite', build: 'vite build', check: 'tsc --noEmit' },
+					dependencies: { '@datamoc/mw_games': `^${PACKAGE_VERSION}`, 'pixi.js': '^8.20.1' },
+					devDependencies: { typescript: '^7.0.2', vite: '^8.2.2' },
+				},
+				null,
+				2,
+			) + '\n',
+		'vite.config.mts': [
+			"import { defineConfig } from 'vite';",
+			"import { mwgPage } from '@datamoc/mw_games/tools/vite';",
+			'',
+			'//`singleFile: true` also writes dist/standalone.html, the whole game in one file',
+			'export default defineConfig({ plugins: [mwgPage({ singleFile: true })] });',
+			'',
+		].join('\n'),
+		'tsconfig.json':
+			JSON.stringify(
+				{
+					compilerOptions: {
+						target: 'ES2022',
+						module: 'ESNext',
+						moduleResolution: 'bundler',
+						lib: ['ES2022', 'DOM'],
+						strict: true,
+						noEmit: true,
+						skipLibCheck: true,
+					},
+					include: ['src'],
+				},
+				null,
+				2,
+			) + '\n',
+		'index.html': [
+			'<!DOCTYPE html>',
+			'<html lang="en">',
+			'<head>',
+			'\t<meta charset="utf-8">',
+			'\t<meta name="viewport" content="width=device-width, initial-scale=1">',
+			`\t<title>${name}</title>`,
+			'\t<style>html, body { margin: 0; height: 100%; background: #101018; overflow: hidden; } #game { display: block; width: 100vw; height: 100vh; }</style>',
+			'</head>',
+			'<body>',
+			'\t<canvas id="game"></canvas>',
+			'\t<script type="module" src="./src/main.ts"></script>',
+			'</body>',
+			'</html>',
+			'',
+		].join('\n'),
+		'src/main.ts': [
+			"import { Game, Scene2D } from '@datamoc/mw_games/two-d';",
+			"import { Shape2D, Text2D } from '@datamoc/mw_games/two-d/render';",
+			'',
+			'class MainScene extends Scene2D {',
+			'\tprivate square!: Shape2D;',
+			'\tprivate elapsed = 0;',
+			'',
+			'\toverride create(): void {',
+			"\t\tconst label = new Text2D({ text: 'Hello, mwg!', style: { fill: 0xd8dae6, fontFamily: 'monospace', fontSize: 16 } });",
+			'\t\tlabel.position.set(24, 24);',
+			'\t\tthis.stage.addChild(label);',
+			'\t\tthis.square = new Shape2D().rect(-20, -20, 40, 40).fill(0x6fb1ff);',
+			'\t\tthis.stage.addChild(this.square);',
+			'\t}',
+			'',
+			'\toverride update(dt: number): void {',
+			'\t\tthis.elapsed += dt;',
+			'\t\tthis.square.position.set(Game.current.width / 2 + Math.sin(this.elapsed) * 120, Game.current.height / 2);',
+			'\t}',
+			'}',
+			'',
+			"const game = new Game({ canvas: document.getElementById('game') as HTMLCanvasElement, background: 0x101018 });",
+			'game.start(MainScene).catch((error) => console.error(error));',
+			'',
+		].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`,
+	};
+}
+
+/** writes the project into `folder`; refuses a folder that already holds files, so nothing is overwritten */
+export function initProject(folder) {
+	const target = resolve(folder);
+	if (existsSync(target) && readdirSync(target).length > 0) {
+		throw new Error(`${target} is not empty; run mwg-init in a new or empty folder`);
+	}
+	const written = [];
+	for (const [path, content] of Object.entries(
+		initFiles(
+			basename(target)
+				.toLowerCase()
+				.replace(/[^a-z0-9-]/g, '-'),
+		),
+	)) {
+		const file = join(target, path);
+		mkdirSync(dirname(file), { recursive: true });
+		writeFileSync(file, content, 'utf8');
+		written.push(path);
+	}
+	return { folder: target, files: written };
+}
+
+//no top-level await: this module is also imported, and the real path covers an npm bin symlink
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+	const folder = process.argv[2];
+	if (!folder) {
+		console.error('usage: mwg-init <new folder>');
+		process.exitCode = 2;
+	} else {
+		try {
+			const { folder: target, files } = initProject(folder);
+			console.log(`wrote ${files.length} files to ${target}\nnext: cd ${folder} && npm install && npm run dev`);
+		} catch (error) {
+			console.error(error.message);
+			process.exitCode = 1;
+		}
+	}
+}

package/tools/play-uci.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { readFileSync, readdirSync } from 'node:fs';
-import { join, basename, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { 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';
@@ -164,7 +165,9 @@ export function createUciSession(options = {}) {
 	};
 }
 
-const isMain = process.argv[1] && import.meta.url.endsWith(basename(process.argv[1]));
+//the real path, since an npm `bin` shim reaches this file through a symlink; a suffix test on the
+//name is not enough (`compress-dist.mjs` ends with `t.mjs`)
+const isMain = process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
 
 if (isMain) {
 	const args = process.argv.slice(2);

package/tools/sbom.mjs

@@ -328,5 +328,9 @@ async function main(argv) {
 }
 
 //realpath, since an npm `bin` shim reaches this file through a symlink
+//no top-level await: a vite config loaded as CommonJS has to be able to require() this module
 if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url))
-	await main(process.argv.slice(2));
+	main(process.argv.slice(2)).catch((error) => {
+		console.error(error);
+		process.exitCode = 1;
+	});

package/tools/single-file.mjs

@@ -200,7 +200,7 @@ function renderBootstrap(payloads, algorithm) {
 
 const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 
-if (isMain) {
+async function runCli() {
 	const args = process.argv.slice(2);
 	const dist = args[0];
 	if (!dist || dist.startsWith('--')) {
@@ -229,3 +229,11 @@ if (isMain) {
 	);
 	console.log('  one file, no server, no sibling script - open it directly');
 }
+
+//no top-level await: a vite config loaded as CommonJS has to be able to require() this module
+if (isMain) {
+	runCli().catch((error) => {
+		console.error(error);
+		process.exitCode = 1;
+	});
+}