@datamoc/mw_games 0.9.1 → 0.11.0

package/dist/version.d.ts

@@ -9,5 +9,5 @@
  * this from `package.json` automatically, chosen because this project's own build already
  * has no step before `tsc`/`vite` that this would need to run ahead of.
  */
-export declare const version = "0.9.1";
+export declare const version = "0.11.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO,UAAU,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO,WAAW,CAAC"}

package/dist/version.js

@@ -9,5 +9,5 @@
  * this from `package.json` automatically, chosen because this project's own build already
  * has no step before `tsc`/`vite` that this would need to run ahead of.
  */
-export const version = '0.9.1';
+export const version = '0.11.0';
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@datamoc/mw_games",
-	"version": "0.9.1",
+	"version": "0.11.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.",
 	"license": "MPL-2.0",
 	"repository": {
@@ -39,12 +39,17 @@
 	"files": [
 		"dist",
 		"tools/compile-resources.mjs",
+		"tools/compile-resources.d.mts",
+		"tools/webp-convert.mjs",
+		"tools/webp-convert.d.mts",
 		"tools/extract-html.mjs",
 		"tools/extract-html.d.mts",
 		"tools/compress-dist.mjs",
 		"tools/compress-dist.d.mts",
 		"tools/classic-html.mjs",
 		"tools/classic-html.d.mts",
+		"tools/single-file.mjs",
+		"tools/single-file.d.mts",
 		"tools/mwl.mjs",
 		"LICENSE",
 		"CHANGELOG.md",
@@ -131,6 +136,7 @@
 		},
 		"./tools/compile-resources": "./tools/compile-resources.mjs",
 		"./tools/compress-dist": "./tools/compress-dist.mjs",
+		"./tools/webp-convert": "./tools/webp-convert.mjs",
 		"./two-d": {
 			"types": "./dist/two-d/index.d.ts",
 			"import": "./dist/two-d/index.js"
@@ -290,6 +296,7 @@
 		"pixi.js": "^8.20.1",
 		"playwright-core": "^1.62.1",
 		"prettier": "^3.9.6",
+		"sharp": "^0.35.4",
 		"typescript": "^7.0.2",
 		"vite": "^8.2.2",
 		"ws": "^8.21.3"

package/tools/compile-resources.d.mts

@@ -0,0 +1,29 @@
+export const DEFAULT_MIME: Record<string, string>;
+
+export function walk(dir: string): AsyncGenerator<string>;
+
+export interface CompileResourcesOptions {
+	from: string;
+	to: string;
+	mime?: Record<string, string>;
+	groupBy?: (key: string) => string;
+	toWebp?: boolean;
+	webpLossless?: boolean;
+	webpQuality?: number;
+}
+
+export interface CompileResourcesGroup {
+	name: string;
+	count: number;
+	size: number;
+}
+
+export interface CompileResourcesResult {
+	groups: CompileResourcesGroup[];
+	rawBytes: number;
+	embeddedBytes: number;
+	webpConverted: number;
+	skipped: number;
+}
+
+export function compileResources(options: CompileResourcesOptions): Promise<CompileResourcesResult>;

package/tools/compile-resources.mjs

@@ -1,5 +1,6 @@
 import { readdir, readFile, mkdir, writeFile, rm } from 'node:fs/promises';
 import { join, extname, relative, sep, dirname, basename } from 'node:path';
+import { WEBP_CONVERTIBLE_EXTENSIONS } from './webp-convert.mjs';
 
 /**
  * Turns a folder of assets into scripts a `file://` page can load.
@@ -56,9 +57,27 @@ export async function* walk(dir) {
  * @param options.to folder to write the generated scripts into
  * @param options.mime extension to MIME type, merged over the defaults
  * @param options.groupBy how to name the script an asset lands in; defaults to its top folder
+ * @param options.toWebp convert `.png`/`.jpg`/`.jpeg` assets to WebP before embedding
+ *   (default false - see `tools/webp-convert.mjs`). The asset's *key* never changes (a game
+ *   still calls `load('tiles.png')` in both dev and built modes; dev mode serves the literal
+ *   file from disk, unconverted), only the embedded `data:` URI's bytes and MIME type do, and
+ *   only when the WebP result is actually smaller - a conversion that would not save
+ *   anything is silently skipped rather than embedded anyway.
+ * @param options.webpLossless use WebP's lossless mode when converting (default true - a
+ *   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)
  * @returns the group names, in the order the page should load them
  */
-export async function compileResources({ from, to, mime = {}, groupBy } = {}) {
+export async function compileResources({
+	from,
+	to,
+	mime = {},
+	groupBy,
+	toWebp: convertToWebp = false,
+	webpLossless = true,
+	webpQuality = 90,
+} = {}) {
 	if (!from || !to) throw new Error('compileResources needs both `from` and `to`');
 
 	const types = { ...DEFAULT_MIME, ...mime };
@@ -70,9 +89,16 @@ export async function compileResources({ from, to, mime = {}, groupBy } = {}) {
 	const groups = new Map();
 	let skipped = 0;
 	let rawBytes = 0;
+	let embeddedBytes = 0;
+	let webpConverted = 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;
 
 	for await (const file of walk(from)) {
-		const type = types[extname(file).toLowerCase()];
+		const ext = extname(file).toLowerCase();
+		const type = types[ext];
 		if (!type) {
 			skipped++;
 			continue;
@@ -81,10 +107,22 @@ export async function compileResources({ from, to, mime = {}, groupBy } = {}) {
 		const key = relative(from, file).split(sep).join('/');
 		const data = await readFile(file);
 
+		let mimeType = type;
+		let bytes = data;
+		if (toWebp && WEBP_CONVERTIBLE_EXTENSIONS.has(ext)) {
+			const webp = await toWebp(data, { lossless: webpLossless, quality: webpQuality });
+			if (webp.length < data.length) {
+				mimeType = 'image/webp';
+				bytes = webp;
+				webpConverted++;
+			}
+		}
+
 		const name = group(key);
 		if (!groups.has(name)) groups.set(name, {});
-		groups.get(name)[key] = `data:${type};base64,${data.toString('base64')}`;
+		groups.get(name)[key] = `data:${mimeType};base64,${bytes.toString('base64')}`;
 		rawBytes += data.length;
+		embeddedBytes += bytes.length;
 	}
 
 	const written = [];
@@ -98,7 +136,7 @@ export async function compileResources({ from, to, mime = {}, groupBy } = {}) {
 		written.push({ name, count: Object.keys(assets).length, size: js.length });
 	}
 
-	return { groups: written, rawBytes, skipped };
+	return { groups: written, rawBytes, embeddedBytes, webpConverted, skipped };
 }
 
 // ---------------------------------------------------------------- CLI
@@ -106,17 +144,27 @@ export async function compileResources({ from, to, mime = {}, groupBy } = {}) {
 const isMain = process.argv[1] && import.meta.url.endsWith(basename(process.argv[1]));
 
 if (isMain) {
-	const [from, to] = process.argv.slice(2);
+	const args = process.argv.slice(2);
+	const [from, to] = args.filter((a) => !a.startsWith('--'));
 	if (!from || !to) {
-		console.error('usage: node compile-resources.mjs <asset folder> <output folder>');
+		console.error(
+			'usage: node compile-resources.mjs <asset folder> <output folder> [--to-webp] [--webp-lossy[=quality]]',
+		);
 		process.exit(1);
 	}
+	const toWebp = args.includes('--to-webp');
+	const lossyFlag = args.find((a) => a === '--webp-lossy' || a.startsWith('--webp-lossy='));
+	const webpLossless = !lossyFlag;
+	const webpQuality = lossyFlag && lossyFlag.includes('=') ? Number(lossyFlag.split('=')[1]) : 90;
 
-	const { groups, rawBytes, skipped } = await compileResources({
+	const { groups, rawBytes, embeddedBytes, webpConverted, skipped } = 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,
 	});
 
 	const kb = (n) => (n / 1024).toFixed(1).padStart(8) + ' KB';
@@ -124,6 +172,12 @@ if (isMain) {
 		console.log(`  ${join(relative(process.cwd(), to), name + '.js').padEnd(40)}${kb(size)}  (${count} files)`);
 	}
 	console.log(`  ${groups.length} script(s), ${kb(rawBytes)} of assets` + (skipped ? `, ${skipped} skipped` : ''));
+	if (toWebp) {
+		console.log(
+			`  ${webpConverted} image(s) converted to WebP (${webpLossless ? 'lossless' : `lossy, quality ${webpQuality}`}), ` +
+				`${kb(rawBytes)} -> ${kb(embeddedBytes)} embedded`,
+		);
+	}
 }
 
 export { dirname };

package/tools/single-file.d.mts

@@ -0,0 +1,17 @@
+export interface SingleFileOptions {
+	dist: string;
+	compress?: boolean;
+	algorithm?: 'gzip' | 'brotli';
+	level?: number;
+	splash?: boolean;
+	output?: string;
+}
+
+export interface SingleFileResult {
+	path: string;
+	scripts: number;
+	rawBytes: number;
+	embeddedBytes: number;
+}
+
+export function buildSingleFile(options: SingleFileOptions): Promise<SingleFileResult>;

package/tools/single-file.mjs

@@ -0,0 +1,224 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join, basename, resolve } from 'node:path';
+import { gzipSync, brotliCompressSync, constants } from 'node:zlib';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Turns an `emit-page.mjs` output folder (`index.html` + sibling asset/bundle `.js` files)
+ * into one genuinely standalone HTML file with no sibling script at all - roadmap item 349,
+ * the "single-file" leg of the build-options matrix `emit-page.mjs --single-file` exposes.
+ *
+ * The existing multi-file output already opens by double-clicking (that's the whole point of
+ * `tools/compile-resources.mjs` and `tools/classic-html.mjs`), but it is still an `index.html`
+ * plus N `.js` files that have to travel together. This inlines every `<script src>` the page
+ * loads directly into the page, in the same order, so the folder can be reduced to one file
+ * before it is shared or archived.
+ *
+ * Compression (`compress: true`) compresses each script's source before it is
+ * base64-embedded, and unpacks it at load with the browser's own `DecompressionStream` - a
+ * real Web Streams API, not a shipped decoder. That beats a pure-JS decompressor such as
+ * `js-lzma` (the roadmap item's other candidate) on every axis that matters here: it adds
+ * zero bytes to the page, needs no license or maintenance, and both algorithms below are
+ * exactly what `tools/compress-dist.mjs` already writes for the server-negotiated path, so the
+ * project only carries one compression story either way.
+ *
+ * `algorithm: 'gzip'` (the default) is the safer choice for browser reach: `compress: false`
+ * has no requirement beyond base64, which every browser this project targets can decode, and
+ * gzip's `DecompressionStream('gzip')` has been available since May 2023. `algorithm:
+ * 'brotli'` compresses further for the same reason `compress-dist.mjs` prefers it over gzip
+ * when a server can negotiate it, and needs `DecompressionStream('br')` - an option this
+ * repo's roadmap (item 350) took up expecting broad support, but a real Chrome (153, tested
+ * directly in this repo's own verification pass) still throws
+ * `Unsupported compression format: 'br'` for both `'br'` and `'brotli'`, so treat brotli here
+ * as an advanced, narrower-reach option rather than a safe default until that is re-verified
+ * against current browsers - `algorithm: 'gzip'` stays the one every browser this project
+ * targets can actually decode today. Either way, the bootstrap throws a clear, actionable
+ * error rather than silently failing when the browser's `DecompressionStream` does not support
+ * the chosen format.
+ *
+ * Decoding is async even when uncompressed (kept uniform, and `atob` on a very large payload
+ * still benefits from not blocking the parser), so a splash screen (`splash: true`, the
+ * default) covers the page until every script has run. It is deliberately minimal - inline
+ * styles and a CSS spinner, no asset of its own - since this is a framework-level fallback a
+ * game is free to replace, not a themed loading screen.
+ *
+ * @param {object} options
+ * @param {string} options.dist path to the folder `emit-page.mjs` already wrote
+ * @param {boolean} [options.compress] compress each inlined script (default false)
+ * @param {'gzip'|'brotli'} [options.algorithm] compression algorithm when `compress` is set
+ *   (default 'gzip')
+ * @param {number} [options.level] gzip level 1-9, or brotli quality 0-11, when `compress` is
+ *   set (default 9 for gzip, 11 for brotli)
+ * @param {boolean} [options.splash] show a splash screen while scripts decode (default true)
+ * @param {string} [options.output] output file name, written inside `dist` (default
+ *   `standalone.html`) - additive, so the existing multi-file `index.html` is untouched
+ * @returns {Promise<{path: string, scripts: number, rawBytes: number, embeddedBytes: number}>}
+ */
+export async function buildSingleFile({
+	dist,
+	compress = false,
+	algorithm = 'gzip',
+	level,
+	splash = true,
+	output = 'standalone.html',
+} = {}) {
+	if (!dist) throw new Error('buildSingleFile needs a `dist` folder');
+	if (algorithm !== 'gzip' && algorithm !== 'brotli') {
+		throw new Error(`buildSingleFile: algorithm must be 'gzip' or 'brotli', got ${JSON.stringify(algorithm)}`);
+	}
+
+	const htmlPath = join(dist, 'index.html');
+	const html = await readFile(htmlPath, 'utf8');
+
+	const scriptTag = /[ \t]*<script\b[^>]*\bsrc="([^"]+)"[^>]*><\/script>\n?/g;
+	const sources = [];
+	let firstMatchIndex = -1;
+	let match;
+	while ((match = scriptTag.exec(html))) {
+		if (firstMatchIndex === -1) firstMatchIndex = match.index;
+		sources.push(match[1]);
+	}
+	if (sources.length === 0) {
+		throw new Error(`${htmlPath}: no <script src="..."> tags found - is this an emit-page.mjs output folder?`);
+	}
+
+	const compressBytes = (buf) =>
+		algorithm === 'brotli'
+			? brotliCompressSync(buf, { params: { [constants.BROTLI_PARAM_QUALITY]: level ?? 11 } })
+			: gzipSync(buf, { level: level ?? 9 });
+
+	let rawBytes = 0;
+	let embeddedBytes = 0;
+	const payloads = [];
+	for (const src of sources) {
+		const filePath = join(dist, src.replace(/^\.\//, ''));
+		const code = await readFile(filePath, 'utf8');
+		rawBytes += Buffer.byteLength(code, 'utf8');
+		const bytes = compress ? compressBytes(Buffer.from(code, 'utf8')) : Buffer.from(code, 'utf8');
+		const b64 = bytes.toString('base64');
+		embeddedBytes += b64.length;
+		payloads.push({ name: basename(src), b64 });
+	}
+
+	const withoutScripts = html.replace(scriptTag, '').replace(/\n{3,}/g, '\n\n');
+	const bootstrap = renderBootstrap(payloads, compress ? algorithm : 'none');
+	const splashCss = splash ? renderSplashStyle() : '';
+	const splashHtml = splash ? renderSplashMarkup() : '';
+
+	let page = withoutScripts;
+	page = page.includes('</head>') ? page.replace('</head>', `${splashCss}</head>`) : splashCss + page;
+	page = page.replace(/(<body[^>]*>)/, `$1\n${splashHtml}`);
+	page = page.replace(/<\/body>/, `\t${bootstrap}\n</body>`);
+
+	const outPath = join(dist, output);
+	await writeFile(outPath, page, 'utf8');
+
+	return { path: outPath, scripts: payloads.length, rawBytes, embeddedBytes };
+}
+
+function renderSplashStyle() {
+	return (
+		'\t<style id="mwg-splash-style">\n' +
+		'\t\t#mwg-splash{position:fixed;inset:0;display:flex;align-items:center;justify-content:center;' +
+		'flex-direction:column;gap:12px;background:#14161c;color:#eee;font:14px sans-serif;z-index:9999}\n' +
+		'\t\t#mwg-splash .mwg-spinner{width:28px;height:28px;border-radius:50%;' +
+		'border:3px solid rgba(255,255,255,0.25);border-top-color:#fff;animation:mwg-spin 0.8s linear infinite}\n' +
+		'\t\t@keyframes mwg-spin{to{transform:rotate(360deg)}}\n' +
+		'\t</style>\n'
+	);
+}
+
+function renderSplashMarkup() {
+	return '\t<div id="mwg-splash"><div class="mwg-spinner"></div><div>Loading...</div></div>\n';
+}
+
+function renderBootstrap(payloads, algorithm) {
+	const json = JSON.stringify(payloads);
+	// 'none' | 'gzip' | 'brotli' -> the DecompressionStream format string, or '' for uncompressed
+	const streamFormat = algorithm === 'brotli' ? 'br' : algorithm === 'gzip' ? 'gzip' : '';
+	return (
+		'<script>\n' +
+		'(function(){\n' +
+		// Seeded synchronously, before any decoding starts: several examples' own dev/build
+		// detection scripts (see examples/*/index.html) check `window.__MWG_ASSETS__` at
+		// DOMContentLoaded to tell a built page from the unbuilt dev template, a check that only
+		// works because the multi-file build's asset script is a *deferred* <script src>, which
+		// finishes before that event. This bootstrap decodes asynchronously instead, so without
+		// this line those checks would fire too early and show a false "not built" notice. The
+		// compiled asset script itself creates this object with the same `||` guard once it
+		// actually runs (see tools/compile-resources.mjs) - this only moves that existence
+		// earlier, not the entries themselves, which are still filled in strictly before the
+		// game bundle that reads them executes.
+		'\twindow.__MWG_ASSETS__=window.__MWG_ASSETS__||{};\n' +
+		`\tvar PAYLOADS=${json};\n` +
+		`\tvar FORMAT=${JSON.stringify(streamFormat)};\n` +
+		'\tfunction b64ToBytes(b64){var bin=atob(b64);var bytes=new Uint8Array(bin.length);' +
+		'for(var i=0;i<bin.length;i++)bytes[i]=bin.charCodeAt(i);return bytes;}\n' +
+		'\tfunction decodeText(bytes){\n' +
+		'\t\tif(!FORMAT)return Promise.resolve(new TextDecoder().decode(bytes));\n' +
+		// `new DecompressionStream(FORMAT)` throws *synchronously* (a TypeError) when the browser
+		// does not support the requested format - it does not reject a promise. A brotli build on
+		// a browser without DecompressionStream("br") support hits exactly this: without the
+		// try/catch here that throw would escape decodeText's caller entirely, skip the
+		// .catch(...) below, and leave the splash screen stuck forever instead of failing visibly.
+		'\t\ttry{\n' +
+		'\t\t\tif(typeof DecompressionStream==="undefined")throw new Error(' +
+		'"mwg standalone build: this browser has no DecompressionStream, needed to unpack the compressed bundle. ' +
+		'Use the multi-file build instead.");\n' +
+		'\t\t\tvar stream=new Blob([bytes]).stream().pipeThrough(new DecompressionStream(FORMAT));\n' +
+		'\t\t\treturn new Response(stream).arrayBuffer().then(function(buf){return new TextDecoder().decode(buf);});\n' +
+		'\t\t}catch(err){\n' +
+		'\t\t\treturn Promise.reject(err);\n' +
+		'\t\t}\n' +
+		'\t}\n' +
+		'\tfunction removeSplash(){var el=document.getElementById("mwg-splash");if(el&&el.parentNode)el.parentNode.removeChild(el);}\n' +
+		'\tfunction runNext(i){\n' +
+		'\t\tif(i>=PAYLOADS.length){removeSplash();return;}\n' +
+		'\t\tvar p=PAYLOADS[i];\n' +
+		'\t\tdecodeText(b64ToBytes(p.b64)).then(function(code){\n' +
+		'\t\t\tvar s=document.createElement("script");s.text=code;document.body.appendChild(s);\n' +
+		'\t\t\trunNext(i+1);\n' +
+		'\t\t}).catch(function(err){\n' +
+		'\t\t\tremoveSplash();\n' +
+		'\t\t\tconsole.error("mwg standalone build failed to load "+p.name, err);\n' +
+		'\t\t});\n' +
+		'\t}\n' +
+		'\trunNext(0);\n' +
+		'})();\n' +
+		'</script>'
+	);
+}
+
+// ---------------------------------------------------------------- CLI
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+	const args = process.argv.slice(2);
+	const dist = args[0];
+	if (!dist || dist.startsWith('--')) {
+		console.error(
+			'usage: node tools/single-file.mjs <dist folder> [--compress[=level]] [--brotli[=quality]] ' +
+				'[--no-splash] [--output name.html]',
+		);
+		process.exit(1);
+	}
+	const brotliFlag = args.find((a) => a === '--brotli' || a.startsWith('--brotli='));
+	const compressFlag = args.find((a) => a === '--compress' || a.startsWith('--compress='));
+	const compress = Boolean(brotliFlag || compressFlag);
+	const algorithm = brotliFlag ? 'brotli' : 'gzip';
+	const levelFlag = brotliFlag ?? compressFlag;
+	const level = levelFlag && levelFlag.includes('=') ? Number(levelFlag.split('=')[1]) : undefined;
+	const splash = !args.includes('--no-splash');
+	const outputIndex = args.indexOf('--output');
+	const output = outputIndex !== -1 ? args[outputIndex + 1] : 'standalone.html';
+
+	const result = await buildSingleFile({ dist: resolve(dist), compress, algorithm, level, splash, output });
+	const kb = (n) => (n / 1024).toFixed(1) + ' KB';
+	console.log(`\n  ${result.path}`);
+	console.log(
+		`  ${result.scripts} script(s) inlined, ${kb(result.rawBytes)} raw -> ${kb(result.embeddedBytes)} embedded` +
+			(compress ? ` (${algorithm} level ${level ?? (algorithm === 'brotli' ? 11 : 9)})` : ' (uncompressed)'),
+	);
+	console.log('  one file, no server, no sibling script - open it directly');
+}

package/tools/webp-convert.d.mts

@@ -0,0 +1,8 @@
+export interface ToWebpOptions {
+	lossless?: boolean;
+	quality?: number;
+}
+
+export function toWebp(buffer: Buffer, options?: ToWebpOptions): Promise<Buffer>;
+
+export const WEBP_CONVERTIBLE_EXTENSIONS: Set<string>;

package/tools/webp-convert.mjs

@@ -0,0 +1,90 @@
+import { readFile, writeFile, stat } from 'node:fs/promises';
+import { extname, basename, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Converts a raster image buffer to WebP - roadmap item 350's "convert pictures to WebP"
+ * half, kept as its own module so `tools/compile-resources.mjs` (a published, shipped tool -
+ * see `package.json`'s `files`/`exports`) never has to import an image codec itself. This file
+ * is *not* shipped: it dynamically imports `sharp`, a devDependency of this repo, so a game
+ * that never opts into WebP conversion carries no new dependency at all. A game that does want
+ * it installs `sharp` in its own project the same way this repo does.
+ *
+ * `lossless` (default true) uses WebP's real lossless mode (VP8L), which is what a pixel-art
+ * tileset's exact colours need - not "high quality lossy", which is still a DCT approximation
+ * at any quality setting. Lossy mode (`lossless: false`, with `quality`) is available for
+ * photographic source art where the extra size saving is worth it, but it is never the
+ * default: this project does not silently trade fidelity for size.
+ */
+
+let sharpModule;
+async function loadSharp() {
+	if (sharpModule) return sharpModule;
+	try {
+		sharpModule = (await import('sharp')).default;
+	} catch (err) {
+		throw new Error(
+			'WebP conversion needs the optional `sharp` package, which is not installed. ' +
+				'Run `npm install --save-dev sharp` in your project to use toWebp, or pass ' +
+				'`toWebp: false` (the default) to skip WebP conversion entirely.',
+			{ cause: err },
+		);
+	}
+	return sharpModule;
+}
+
+/**
+ * @param {Buffer} buffer source image bytes (PNG or JPEG)
+ * @param {object} [options]
+ * @param {boolean} [options.lossless] use WebP's lossless mode (default true)
+ * @param {number} [options.quality] 0-100, used only when `lossless` is false (default 90)
+ * @returns {Promise<Buffer>} WebP-encoded image bytes
+ */
+export async function toWebp(buffer, { lossless = true, quality = 90 } = {}) {
+	const sharp = await loadSharp();
+	return sharp(buffer)
+		.webp(lossless ? { lossless: true } : { quality })
+		.toBuffer();
+}
+
+/**
+ * The extensions `compileResources`'s `toWebp` option will attempt to convert. `.gif` (frame
+ * animation, which WebP would need to be re-authored to preserve) and `.svg` (already vector,
+ * so there is nothing raster to convert) are deliberately left out, along with `.webp` itself.
+ */
+export const WEBP_CONVERTIBLE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg']);
+
+// ---------------------------------------------------------------- CLI
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+	const args = process.argv.slice(2);
+	const input = args.find((a) => !a.startsWith('--'));
+	if (!input) {
+		console.error('usage: node tools/webp-convert.mjs <file.png|file.jpg> [--lossy[=quality]]');
+		process.exit(1);
+	}
+	const lossyFlag = args.find((a) => a === '--lossy' || a.startsWith('--lossy='));
+	const lossless = !lossyFlag;
+	const quality = lossyFlag && lossyFlag.includes('=') ? Number(lossyFlag.split('=')[1]) : 90;
+
+	const inPath = resolve(input);
+	if (!WEBP_CONVERTIBLE_EXTENSIONS.has(extname(inPath).toLowerCase())) {
+		console.error(`${input}: not a convertible image (expected .png, .jpg or .jpeg)`);
+		process.exit(1);
+	}
+	const source = await readFile(inPath);
+	const converted = await toWebp(source, { lossless, quality });
+	const outPath = resolve(dirname(inPath), basename(inPath, extname(inPath)) + '.webp');
+	await writeFile(outPath, converted);
+
+	const { size: sourceSize } = await stat(inPath);
+	const kb = (n) => (n / 1024).toFixed(1) + ' KB';
+	const pct = Math.round((100 * (sourceSize - converted.length)) / sourceSize);
+	console.log(`  ${outPath}`);
+	console.log(
+		`  ${kb(sourceSize)} -> ${kb(converted.length)} (${pct >= 0 ? '-' : '+'}${Math.abs(pct)}%)` +
+			(lossless ? ' [lossless]' : ` [lossy, quality ${quality}]`),
+	);
+}