@datamoc/mw_games 0.10.0 → 0.12.0

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}]`),
+	);
+}