@datamoc/mw_games 0.41.0 → 0.42.0

package/tools/compile-resources.mjs

@@ -121,6 +121,10 @@ export async function* walk(dir) {
  *   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)
+ * @param options.svgo minify embedded `.svg` assets through the optional `svgo` package (default
+ *   false - see `tools/svg-optimise.mjs`). The key never changes, only the embedded bytes, and
+ *   only when the optimised file is actually smaller. A file svgo cannot parse fails the build by
+ *   name rather than shipping unoptimised in silence.
  * @param options.soundFont subset an embedded `.sf2` or `.sf3` to the programs the embedded
  *   `.mid`/`.midi` files use (default true); `false` embeds every SoundFont whole
  * @param options.soundFontUsage explicit `{ bank, program }` list to subset to, for a
@@ -141,6 +145,7 @@ export async function compileResources({
 	toWebp: convertToWebp = false,
 	webpLossless = true,
 	webpQuality = 90,
+	svgo: optimiseSvgFiles = false,
 	soundFont = true,
 	soundFontUsage,
 } = {}) {
@@ -205,10 +210,12 @@ export async function compileResources({
 	let rawBytes = 0;
 	let embeddedBytes = 0;
 	let webpConverted = 0;
+	let svgOptimised = 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;
+	const optimiseSvg = optimiseSvgFiles ? (await import('./svg-optimise.mjs')).optimiseSvg : null;
 
 	const creditsFile = join(from, 'credits.json');
 	let credits = null;
@@ -240,6 +247,19 @@ export async function compileResources({
 			}
 		}
 
+		if (optimiseSvg && ext === '.svg') {
+			let optimised;
+			try {
+				optimised = await optimiseSvg(data);
+			} catch (error) {
+				throw new Error(`cannot optimise SVG asset ${key}: ${error.message ?? error}`);
+			}
+			if (optimised.length < data.length) {
+				bytes = optimised;
+				svgOptimised++;
+			}
+		}
+
 		if (isSoundFontKey(key)) {
 			if (usage !== undefined && soundFontTools) {
 				try {
@@ -247,7 +267,14 @@ export async function compileResources({
 				} catch (error) {
 					throw new Error(`cannot subset SoundFont asset ${key}: ${error.message ?? error}`);
 				}
-				soundFonts.push({ key, programs: usage.length, rawBytes: data.length, embeddedBytes: bytes.length });
+				soundFonts.push({
+					key,
+					programs: usage.length,
+					rawBytes: data.length,
+					embeddedBytes: bytes.length,
+					//the programs the MIDI files ask for that this font does not carry
+					missing: soundFontTools.missingSoundFontPrograms(data, usage),
+				});
 			} else {
 				soundFonts.push({ key, programs: null, rawBytes: data.length, embeddedBytes: data.length });
 			}
@@ -273,7 +300,7 @@ export async function compileResources({
 
 	if (credits) await writeFile(join(to, 'CREDITS.txt'), credits, 'utf8');
 
-	return { groups: written, rawBytes, embeddedBytes, webpConverted, skipped, credits, soundFonts };
+	return { groups: written, rawBytes, embeddedBytes, webpConverted, svgOptimised, skipped, credits, soundFonts };
 }
 
 /** the plain-text credits for a manifest, one block per entry; throws on an entry that cannot be attributed */
@@ -302,7 +329,7 @@ async function runCli() {
 	const [from, to] = args.filter((a) => !a.startsWith('--'));
 	if (!from || !to) {
 		console.error(
-			'usage: node compile-resources.mjs <asset folder> <output folder> [--to-webp] [--webp-lossy[=quality]] [--no-soundfont-subset] [--soundfont-usage=bank:program,...]',
+			'usage: node compile-resources.mjs <asset folder> <output folder> [--to-webp] [--webp-lossy[=quality]] [--svgo] [--no-soundfont-subset] [--soundfont-usage=bank:program,...]',
 		);
 		process.exit(1);
 	}
@@ -315,17 +342,19 @@ async function runCli() {
 		args.find((a) => a.startsWith('--soundfont-usage='))?.slice('--soundfont-usage='.length),
 	);
 
-	const { groups, rawBytes, embeddedBytes, webpConverted, skipped, soundFonts } = 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,
-		soundFont: !args.includes('--no-soundfont-subset'),
-		soundFontUsage,
-	});
+	const { groups, rawBytes, embeddedBytes, webpConverted, svgOptimised, skipped, soundFonts } =
+		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,
+			svgo: args.includes('--svgo'),
+			soundFont: !args.includes('--no-soundfont-subset'),
+			soundFontUsage,
+		});
 
 	const kb = (n) => (n / 1024).toFixed(1).padStart(8) + ' KB';
 	for (const { name, count, size } of groups) {
@@ -338,7 +367,14 @@ async function runCli() {
 				? `  ${font.key}: SoundFont embedded whole (${kb(font.rawBytes)}), no shipped MIDI to subset against`
 				: `  ${font.key}: SoundFont subset to ${font.programs} program(s), ${kb(font.rawBytes)} -> ${kb(font.embeddedBytes)}`,
 		);
+		if (font.missing?.length > 0) {
+			console.log(
+				`  warning: ${font.key} does not carry ${font.missing.map(({ bank, program }) => `${bank}:${program}`).join(', ')}: ` +
+					"they play the font's piano, or the built-in synthesizer with `missingProgram: 'synth'`",
+			);
+		}
 	}
+	if (args.includes('--svgo')) console.log(`  ${svgOptimised} SVG(s) optimised`);
 	if (toWebp) {
 		console.log(
 			`  ${webpConverted} image(s) converted to WebP (${webpLossless ? 'lossless' : `lossy, quality ${webpQuality}`}), ` +

package/tools/emit-page.d.mts

@@ -20,6 +20,8 @@ export interface EmitPageOptions {
 	toWebp?: boolean;
 	webpLossless?: boolean;
 	webpQuality?: number;
+	/** minify embedded `.svg` assets through the optional `svgo` package; false by default */
+	svgo?: boolean;
 	/** Subset an embedded `.sf2` to the programs the embedded `.mid`/`.midi` files use. Default true; `false` embeds every SoundFont whole. */
 	soundFont?: boolean;
 	/** Explicit `{ bank, program }` list to subset a SoundFont to, overriding the MIDI-derived list. */
@@ -42,6 +44,7 @@ export interface EmitPageResult {
 	rawBytes: number;
 	embeddedBytes: number;
 	webpConverted: number;
+	svgOptimised: number;
 	/** one entry per embedded `.sf2`: the programs kept (null when embedded whole) and the byte saving */
 	soundFonts: SoundFontEmbed[];
 	compressed: CompressRow[] | null;

package/tools/emit-page.mjs

@@ -29,7 +29,7 @@ import { withContentSecurityPolicy } from './csp.mjs';
  * usage: mwg-emit <project folder> [--dist=<dir>] [--assets=<dir>] [--no-csp] [--connect=<origin>]...
  *                 [--no-compress] [--xz]
  *                 [--single-file] [--single-file-compress[=level]]
- *                 [--single-file-brotli[=quality]] [--to-webp] [--webp-lossy[=quality]]
+ *                 [--single-file-brotli[=quality]] [--to-webp] [--webp-lossy[=quality]] [--svgo]
  *                 [--no-soundfont-subset] [--soundfont-usage=bank:program,...]
  *
  * `--dist` defaults to `<project folder>/dist` and `--assets` to `<project folder>/assets`; with
@@ -53,6 +53,9 @@ import { withContentSecurityPolicy } from './csp.mjs';
  * `--to-webp` converts `.png`/`.jpg`/`.jpeg` example assets to WebP before embedding (see
  * `tools/webp-convert.mjs`), lossless by default; `--webp-lossy[=quality]` opts into lossy
  * re-encoding instead. Needs the optional `sharp` devDependency installed.
+ *
+ * `--svgo` minifies embedded `.svg` assets (see `tools/svg-optimise.mjs`), keeping the `viewBox` and
+ * every id. Needs the optional `svgo` package installed.
  */
 
 /**
@@ -74,6 +77,7 @@ export async function emitPage({
 	toWebp = false,
 	webpLossless = true,
 	webpQuality = 90,
+	svgo = false,
 	soundFont = true,
 	soundFontUsage,
 	csp = true,
@@ -89,10 +93,11 @@ export async function emitPage({
 				toWebp,
 				webpLossless,
 				webpQuality,
+				svgo,
 				soundFont,
 				soundFontUsage,
 			})
-		: { groups: [], rawBytes: 0, embeddedBytes: 0, webpConverted: 0, soundFonts: [] };
+		: { groups: [], rawBytes: 0, embeddedBytes: 0, webpConverted: 0, svgOptimised: 0, soundFonts: [] };
 
 	const html = await readFile(join(dist, 'index.html'), 'utf8');
 	const classic = toClassicScript(html);
@@ -162,6 +167,7 @@ async function main(argv) {
 		toWebp: argv.includes('--to-webp'),
 		webpLossless: !webpLossyFlag,
 		webpQuality: webpLossyFlag?.includes('=') ? Number(webpLossyFlag.split('=')[1]) : 90,
+		svgo: argv.includes('--svgo'),
 		soundFont: !argv.includes('--no-soundfont-subset'),
 		soundFontUsage,
 		csp: argv.includes('--no-csp')
@@ -179,12 +185,19 @@ async function main(argv) {
 				`${kb(result.rawBytes)} -> ${kb(result.embeddedBytes)} embedded`,
 		);
 	}
+	if (argv.includes('--svgo')) console.log(`  ${result.svgOptimised} SVG(s) optimised`);
 	for (const font of result.soundFonts ?? []) {
 		console.log(
 			font.programs === null
 				? `  ${font.key}: SoundFont embedded whole (${kb(font.rawBytes)}), no shipped MIDI to subset against`
 				: `  ${font.key}: SoundFont subset to ${font.programs} program(s), ${kb(font.rawBytes)} -> ${kb(font.embeddedBytes)}`,
 		);
+		if (font.missing?.length > 0) {
+			console.log(
+				`  warning: ${font.key} does not carry ${font.missing.map(({ bank, program }) => `${bank}:${program}`).join(', ')}: ` +
+					"they play the font's piano, or the built-in synthesizer with `missingProgram: 'synth'`",
+			);
+		}
 	}
 	console.log('  open index.html directly - no server needed');
 	if (result.compressed) {

package/tools/svg-optimise.d.mts

@@ -0,0 +1,8 @@
+/** the svgo configuration `optimiseSvg` runs */
+export declare const SVGO_CONFIG: {
+	multipass: boolean;
+	plugins: { name: string; params: { overrides: Record<string, boolean> } }[];
+};
+
+/** the SVG bytes minified; needs the optional `svgo` package, and throws for a file that is not valid SVG */
+export declare function optimiseSvg(buffer: Buffer): Promise<Buffer>;

package/tools/svg-optimise.mjs

@@ -0,0 +1,45 @@
+/**
+ * Minifies an SVG for embedding, the SVG half of what `webp-convert` is for raster images, kept as
+ * its own module so `tools/compile-resources.mjs` never has to import an optimiser itself: it
+ * dynamically imports `svgo`, which a game that opts in installs in its own project the way it does
+ * `sharp` for WebP (`npm install --save-dev svgo`). A game that never passes `svgo: true` carries
+ * no new dependency at all.
+ *
+ * Optimising must not change what the game can see or name. Ids are left alone (`cleanupIds` is off:
+ * a `<use href="#id">`, a gradient reference or a style selector inside the file, or an id the game
+ * looks up, would break if minified), and the `viewBox` stays because svgo 4's default preset no
+ * longer removes it (a game scales a texture by it), which is why this needs svgo 4 or newer.
+ * Everything else in the default preset applies: comments, metadata, editor data, default
+ * attributes, redundant groups, path precision.
+ */
+
+/** the svgo configuration `optimiseSvg` runs, exposed so a game can see exactly what it opts into */
+export const SVGO_CONFIG = {
+	multipass: true,
+	plugins: [{ name: 'preset-default', params: { overrides: { cleanupIds: false } } }],
+};
+
+let svgoModule;
+async function loadSvgo() {
+	if (svgoModule) return svgoModule;
+	try {
+		svgoModule = await import('svgo');
+	} catch (err) {
+		throw new Error(
+			'SVG optimisation needs the optional `svgo` package, which is not installed. ' +
+				'Run `npm install --save-dev svgo` in your project to use `svgo: true`, or leave ' +
+				'it off (the default) to embed SVG files as they are.',
+			{ cause: err },
+		);
+	}
+	return svgoModule;
+}
+
+/**
+ * @param {Buffer} buffer the SVG file's bytes (UTF-8)
+ * @returns {Promise<Buffer>} the optimised SVG; svgo throws for a file that is not valid SVG
+ */
+export async function optimiseSvg(buffer) {
+	const { optimize } = await loadSvgo();
+	return Buffer.from(optimize(buffer.toString('utf8'), SVGO_CONFIG).data, 'utf8');
+}

package/tools/vite.mjs

@@ -16,6 +16,7 @@ import { buildArtifactSbom, serialize, shippedFiles } from './sbom.mjs';
  * affects the build only, so the dev server still serves the asset folder normally.
  * An embedded `.sf2` or `.sf3` is subset at build time to the programs the embedded `.mid` files
  * use (`soundFont: false` embeds it whole, `soundFontUsage` names the programs instead).
+ * `svgo: true` minifies embedded `.svg` assets (needs the optional `svgo` package).
  * At the end of the build it runs `emitPage` over the output folder with the same
  * options. A setting the game's own config gives explicitly still wins, since vite merges a
  * plugin's `config` result under the user's.

package/tools.md

@@ -23,7 +23,8 @@ by double-clicking. Run from the repo root.
 
 | tool | what it does | run |
 | --- | --- | --- |
-| `compile-resources` | Turns an asset folder into `data:` URI scripts under `window.__MWG_ASSETS__`, grouped by top-level folder. `toWebp: true` converts `.png`/`.jpg`/`.jpeg` to WebP first (lossless by default, only kept when actually smaller, key unchanged) via the optional `sharp` devDependency, dynamically imported only when used (item 350) | called by the example builds; `node tools/compile-resources.mjs <asset folder> <output folder> [--to-webp] [--webp-lossy[=quality]]` |
+| `compile-resources` | Turns an asset folder into `data:` URI scripts under `window.__MWG_ASSETS__`, grouped by top-level folder. `toWebp: true` converts `.png`/`.jpg`/`.jpeg` to WebP first (lossless by default, only kept when actually smaller, key unchanged) via the optional `sharp` devDependency, dynamically imported only when used (item 350). `svgo: true` minifies `.svg` assets through the optional `svgo` package (version 4 or newer, ids and `viewBox` kept, only kept when smaller). Each subset SoundFont's result lists the programs the game's MIDI files ask for that the font does not carry, and `mwg-emit` warns about them | called by the example builds; `node tools/compile-resources.mjs <asset folder> <output folder> [--to-webp] [--webp-lossy[=quality]] [--svgo]` |
+| `svg-optimise` | Minifies one SVG file's bytes through `svgo` with ids and the `viewBox` left alone; the standalone half of `compile-resources`'s `svgo` option (item 428). On the repository's own 30 SVGs: 13.6% smaller, worst rendered pixel difference 1 in 255 | `optimiseSvg` from `@datamoc/mw_games/tools/svg-optimise`, or `mwg-emit <folder> --svgo` |
 | `webp-convert` | Converts one raster image buffer (PNG/JPEG) to WebP, lossless by default; the standalone half of `compile-resources`'s `toWebp` option (item 350) | `node tools/webp-convert.mjs <file.png\|file.jpg> [--lossy[=quality]]` |
 | `emit-page` | Finishes a vite build so it opens from `file://` with no server: compiles the assets, rewrites the entry to a classic deferred script with the asset scripts before it, then optionally precompresses and writes a single-file variant (item 381) | `emitPage(options)` from `@datamoc/mw_games/tools/emit-page`, the `mwg-emit <folder> [--dist=] [--assets=]` command, or called by each `example:*:build` script here |
 | `init` | `mwg-init <folder>` writes a starter project (vite config using `mwgPage`, one scene, tsconfig, scripts) that builds to a double-clickable page | `npx mwg-init my-game` |
@@ -199,7 +200,8 @@ same build.
 | tool | what it does | run |
 | --- | --- | --- |
 | `roadmap-progress` | Reports CLOSED.md + ROADMAP.md completion: numbered items in batches of 25, plus the 1.0 exit checklist on its own row (checks to run, not capabilities, so they stay out of the numbered totals), optionally in a browser | `npm run roadmap:progress` |
-| `build-webpage-examples` / `build-webpage-docs` | Generate the live examples and Documentation page under `webpage/` (`REFERENCE.md` guide + TypeDoc under `documentation/api/`) | `npm run webpage:examples`, `npm run webpage:docs` |
+| `build-webpage-examples` / `build-webpage-docs` | Generate the live examples and Documentation page under `webpage/` (`REFERENCE.md` guide + TypeDoc under `documentation/api/` + the examples index) | `npm run webpage:examples`, `npm run webpage:docs` |
+| `build-example-index` | Writes `documentation/examples.html`, read from source text (no typedoc, no renderer): for each public module the symbols that carry an `@example`, each linked to its typedoc page when one exists, with the runnable `examples/` that import the module. Part of `webpage:docs`; a repository tool, not shipped (item 430) | `npm run webpage:docs`, or `node tools/build-example-index.mjs [outFile]` |
 | `make-example-diagrams` / `make-architecture-diagrams` | Rebuild the generated diagrams under `webpage/assets` (never hand-drawn) | `npm run webpage:diagrams` |
 | `api-report` | Regenerates `API_REPORT.md` from the built declarations; `--check` compares instead. A CI gate | `npm run api:report`, `npm run api:check` |
 | `project-stats` | Writes `PROJECT_STATS.json`/`PROJECT_STATS.md` and the website statistics page; `--check` compares. A CI gate | `npm run stats:write`, `npm run stats:check` |