@datamoc/mw_games 0.36.0 → 0.37.0

package/sbom.cdx.json

@@ -1,7 +1,7 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:d6286cd5-19f5-5fa4-a70a-a97edfc4b9dd",
+  "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.0"
+          "version": "0.37.0"
         }
       ]
     },
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/%40datamoc/mw_games@0.36.0",
+      "bom-ref": "pkg:npm/%40datamoc/mw_games@0.37.0",
       "name": "@datamoc/mw_games",
-      "version": "0.36.0",
-      "purl": "pkg:npm/%40datamoc/mw_games@0.36.0",
+      "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": [
         {
@@ -159,15 +159,15 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/%40datamoc/pyroeis@0.6.0",
+      "bom-ref": "pkg:npm/%40datamoc/pyroeis@0.9.0",
       "name": "@datamoc/pyroeis",
-      "version": "0.6.0",
-      "purl": "pkg:npm/%40datamoc/pyroeis@0.6.0",
+      "version": "0.9.0",
+      "purl": "pkg:npm/%40datamoc/pyroeis@0.9.0",
       "scope": "optional",
       "hashes": [
         {
           "alg": "SHA-512",
-          "content": "cd5087e67203c62762e4da82e249f4c662743c1b3479d0906e1dd774394b909e0819c1fe67aabf79212b035260af10752fcfa5e8259af909ce4b970f33d6c7dc"
+          "content": "22c2104fc4df7b87209157a3168afb143eefd46abdb5b4f92c45125244c26265badca578a81b78be2bc6c5f59c29973b5b20dc0b940143aa00016abebed6da22"
         }
       ],
       "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.0",
+      "ref": "pkg:npm/%40datamoc/mw_games@0.37.0",
       "dependsOn": [
         "pkg:npm/%40babylonjs/core@9.30.0",
         "pkg:npm/%40babylonjs/loaders@9.30.0",
@@ -4609,10 +4651,12 @@
         "pkg:npm/%40capacitor/cli@8.5.3",
         "pkg:npm/%40capacitor/core@8.5.3",
         "pkg:npm/%40capacitor/ios@8.5.3",
-        "pkg:npm/%40datamoc/pyroeis@0.6.0",
+        "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",
@@ -4625,7 +4669,7 @@
       ]
     },
     {
-      "ref": "pkg:npm/%40datamoc/pyroeis@0.6.0",
+      "ref": "pkg:npm/%40datamoc/pyroeis@0.9.0",
       "dependsOn": [
         "pkg:npm/readline-sync@1.4.10",
         "pkg:npm/sprintf-js@1.1.3",
@@ -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
@@ -355,17 +396,34 @@ export function findBrowser(kind) {
 	return null;
 }
 
+/**
+ * Ends a browser and its helper processes. `child.kill()` reaches only the launcher: the
+ * zygote, renderers and crashpad handlers survive it holding the output pipes, which keeps
+ * the whole Node process (a test run, a CI job) alive until the runner's own timeout. On
+ * POSIX the browser is spawned as a process-group leader, so the group goes in one signal.
+ */
+function killBrowser(child) {
+	try {
+		if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, 'SIGKILL');
+		else child.kill();
+	} catch {
+		child.kill();
+	}
+	child.stdout?.destroy();
+	child.stderr?.destroy();
+}
+
 /**
  * Waits for `match` in the child's output, watching both stdout and stderr: which of the
  * two a given browser build prints its debugging endpoint on is not something to bet on.
  * The timeout message carries what was seen, because "no endpoint" alone cannot tell a
  * slow cold start from a browser that started and refused to open one.
  */
-function waitForEndpoint(child, match, timeoutMs = 30000) {
+function waitForEndpoint(child, match, timeoutMs = 90000) {
 	return new Promise((resolveEndpoint, reject) => {
 		let seen = '';
 		const timer = setTimeout(() => {
-			child.kill();
+			killBrowser(child);
 			reject(
 				new Error(
 					`browser printed no debugging endpoint within ${timeoutMs} ms; output so far:\n${seen || '(none)'}`,
@@ -388,6 +446,7 @@ function waitForEndpoint(child, match, timeoutMs = 30000) {
 		});
 		child.once('exit', () => {
 			clearTimeout(timer);
+			killBrowser(child);
 			reject(new Error(`browser exited before printing a debugging endpoint:\n${seen}`));
 		});
 	});
@@ -502,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);
@@ -534,7 +600,7 @@ export async function driveChrome(options = {}) {
 			...(options.chromeArgs ?? extraArgs),
 			'about:blank',
 		],
-		{ stdio: ['ignore', 'pipe', 'pipe'] },
+		{ stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32' },
 	);
 	await waitForEndpoint(child, parseDevToolsEndpoint);
 
@@ -598,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);
@@ -623,11 +697,7 @@ export async function driveChrome(options = {}) {
 			} catch {
 				// already closed
 			}
-			child.kill();
-			//the pipes must go: a browser's surviving helper processes can hold them (and so
-			//the whole suite) open past the main process's death
-			child.stdout?.destroy();
-			child.stderr?.destroy();
+			killBrowser(child);
 			if (ownsProfile) {
 				//a browser releases its profile files briefly after the kill, so wait for
 				//the exit and retry: a profile left behind is clutter, not a failure
@@ -676,7 +746,7 @@ export async function driveFirefox(options = {}) {
 			...(options.firefoxArgs ?? []),
 			'about:blank',
 		],
-		{ stdio: ['ignore', 'ignore', 'pipe'] },
+		{ stdio: ['ignore', 'ignore', 'pipe'], detached: process.platform !== 'win32' },
 	);
 	const { endpoint } = await waitForEndpoint(child, parseBidiEndpoint);
 	const socket = await openSocket(endpoint);
@@ -755,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);
@@ -779,7 +855,7 @@ export async function driveFirefox(options = {}) {
 			} catch {
 				// already closed
 			}
-			child.kill();
+			killBrowser(child);
 		},
 	};
 }

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[] };