@datamoc/mw_games 0.10.0 → 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.10.0";
+export declare const version = "0.11.0";
 //# sourceMappingURL=version.d.ts.map

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.10.0';
+export const version = '0.11.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@datamoc/mw_games",
-	"version": "0.10.0",
+	"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,6 +39,9 @@
 	"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",
@@ -133,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"
@@ -292,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

@@ -1,6 +1,7 @@
 export interface SingleFileOptions {
 	dist: string;
 	compress?: boolean;
+	algorithm?: 'gzip' | 'brotli';
 	level?: number;
 	splash?: boolean;
 	output?: string;

package/tools/single-file.mjs

@@ -1,6 +1,6 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { join, basename, resolve } from 'node:path';
-import { gzipSync } from 'node:zlib';
+import { gzipSync, brotliCompressSync, constants } from 'node:zlib';
 import { fileURLToPath } from 'node:url';
 
 /**
@@ -14,16 +14,27 @@ import { fileURLToPath } from 'node:url';
  * 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`) gzips each script's source before it is base64-embedded, and
- * unpacks it at load with the browser's own `DecompressionStream('gzip')` - 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 gzip is exactly what `tools/compress-dist.mjs`
- * already uses for the server-negotiated path, so the project only carries one compression
- * story. The one real cost is browser support: `DecompressionStream` is unavailable on Safari
- * before 16.4 and a handful of older engines, where the bootstrap throws a clear error rather
- * than silently failing - `compress: false` (the default) has no such requirement, since it is
- * just base64, which every browser this project targets can decode.
+ * 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
@@ -33,15 +44,28 @@ import { fileURLToPath } from 'node:url';
  *
  * @param {object} options
  * @param {string} options.dist path to the folder `emit-page.mjs` already wrote
- * @param {boolean} [options.compress] gzip each inlined script (default false)
- * @param {number} [options.level] gzip level 1-9 when `compress` is set (default 9)
+ * @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, level = 9, splash = true, output = 'standalone.html' } = {}) {
+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');
@@ -58,6 +82,11 @@ export async function buildSingleFile({ dist, compress = false, level = 9, splas
 		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 = [];
@@ -65,14 +94,14 @@ export async function buildSingleFile({ dist, compress = false, level = 9, splas
 		const filePath = join(dist, src.replace(/^\.\//, ''));
 		const code = await readFile(filePath, 'utf8');
 		rawBytes += Buffer.byteLength(code, 'utf8');
-		const bytes = compress ? gzipSync(Buffer.from(code, 'utf8'), { level }) : Buffer.from(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);
+	const bootstrap = renderBootstrap(payloads, compress ? algorithm : 'none');
 	const splashCss = splash ? renderSplashStyle() : '';
 	const splashHtml = splash ? renderSplashMarkup() : '';
 
@@ -103,8 +132,10 @@ function renderSplashMarkup() {
 	return '\t<div id="mwg-splash"><div class="mwg-spinner"></div><div>Loading...</div></div>\n';
 }
 
-function renderBootstrap(payloads, compress) {
+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' +
@@ -120,16 +151,25 @@ function renderBootstrap(payloads, compress) {
 		// game bundle that reads them executes.
 		'\twindow.__MWG_ASSETS__=window.__MWG_ASSETS__||{};\n' +
 		`\tvar PAYLOADS=${json};\n` +
-		`\tvar COMPRESSED=${compress ? 'true' : 'false'};\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(!COMPRESSED)return Promise.resolve(new TextDecoder().decode(bytes));\n' +
-		'\t\tif(typeof DecompressionStream==="undefined")return Promise.reject(new Error(' +
+		'\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\tvar stream=new Blob([bytes]).stream().pipeThrough(new DecompressionStream("gzip"));\n' +
-		'\t\treturn new Response(stream).arrayBuffer().then(function(buf){return new TextDecoder().decode(buf);});\n' +
+		'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' +
@@ -158,23 +198,27 @@ if (isMain) {
 	const dist = args[0];
 	if (!dist || dist.startsWith('--')) {
 		console.error(
-			'usage: node tools/single-file.mjs <dist folder> [--compress[=level]] [--no-splash] [--output name.html]',
+			'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(compressFlag);
-	const level = compressFlag && compressFlag.includes('=') ? Number(compressFlag.split('=')[1]) : 9;
+	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, level, splash, output });
+	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 ? ` (gzip level ${level})` : ' (uncompressed)'),
+			(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}]`),
+	);
+}