@datamoc/mw_games 0.43.0 → 0.45.0

package/tools/sbom.mjs

@@ -1,340 +1 @@
-#!/usr/bin/env node
-import { createHash } from 'node:crypto';
-import { readFileSync, realpathSync } from 'node:fs';
-import { readFile, writeFile } from 'node:fs/promises';
-import { join, relative, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const OUTPUT = 'sbom.cdx.json';
-/** this tool's own package, named in every document's `metadata.tools` whichever project it describes */
-const TOOL = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
-const SPEC_VERSION = '1.6';
-
-const HASH_ALGORITHMS = { sha512: 'SHA-512', sha384: 'SHA-384', sha256: 'SHA-256', sha1: 'SHA-1' };
-
-/** the RFC 4122 DNS namespace, undashed because it is only ever fed to the hash as bytes */
-const DNS_NAMESPACE = '6ba7b8109dad11d180b400c04fd430c8';
-
-/**
- * Package URL for an npm package, the SBOM's `bom-ref` as well. A scoped name's `@` is
- * percent-encoded but its `/` is not, which is what the purl spec's own npm examples do
- * (`pkg:npm/%40angular/animation@12.3.1`).
- */
-export function purlFor(name, version) {
-	const encoded = name.startsWith('@') ? `%40${name.slice(1)}` : name;
-	return `pkg:npm/${encoded}@${version}`;
-}
-
-/**
- * npm's `integrity` field (`sha512-<base64>`, sometimes several space-separated) as CycloneDX
- * hashes. CycloneDX carries a hash as lowercase hex, so the base64 is decoded and re-encoded.
- */
-export function hashesFromIntegrity(integrity) {
-	if (typeof integrity !== 'string') return [];
-	const hashes = [];
-	for (const part of integrity.split(/\s+/)) {
-		const dash = part.indexOf('-');
-		if (dash < 0) continue;
-		const alg = HASH_ALGORITHMS[part.slice(0, dash).toLowerCase()];
-		if (alg === undefined) continue;
-		hashes.push({ alg, content: Buffer.from(part.slice(dash + 1), 'base64').toString('hex') });
-	}
-	return hashes;
-}
-
-/** an SPDX id stays an `id`; anything with spaces or an expression stays a `name` instead */
-function licenseFor(license) {
-	if (typeof license !== 'string' || license.trim() === '') return undefined;
-	const value = license.trim();
-	return /^[A-Za-z0-9.+-]+$/.test(value) ? { license: { id: value } } : { license: { name: value } };
-}
-
-/** the package a lockfile location holds: `node_modules/@scope/name` is `@scope/name` */
-function nameFromLocation(location) {
-	const marker = 'node_modules/';
-	return location.slice(location.lastIndexOf(marker) + marker.length);
-}
-
-/** node resolution over a lockfile: the nearest `node_modules/<name>` at or above `location` */
-function resolveDependency(packages, location, name) {
-	let dir = location;
-	for (;;) {
-		const candidate = dir === '' ? `node_modules/${name}` : `${dir}/node_modules/${name}`;
-		if (packages[candidate] !== undefined) return candidate;
-		if (dir === '') return undefined;
-		const marker = dir.lastIndexOf('/node_modules/');
-		dir = marker < 0 ? '' : dir.slice(0, marker);
-	}
-}
-
-function scopeOf(entry) {
-	if (entry.dev === true) return 'excluded';
-	if (entry.optional === true) return 'optional';
-	return 'required';
-}
-
-/** required beats optional beats excluded when one purl is reachable more than one way */
-const SCOPE_RANK = { required: 0, optional: 1, excluded: 2 };
-
-/**
- * A version-5 (RFC 4122 name-based) UUID in the DNS namespace. The same name always hashes to the
- * same UUID, which is what lets `serialNumber` below be derived instead of invented; twelve lines
- * of SHA-1 beats a dependency for the one UUID this tool will ever need.
- */
-function uuidv5(name) {
-	const bytes = createHash('sha1')
-		.update(Buffer.from(DNS_NAMESPACE, 'hex'))
-		.update(name, 'utf8')
-		.digest()
-		.subarray(0, 16);
-	bytes[6] = (bytes[6] & 0x0f) | 0x50; // version 5
-	bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC 4122 variant
-	const hex = bytes.toString('hex');
-	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}
-
-/**
- * Builds a CycloneDX document from `package.json` and `package-lock.json` alone, so the SBOM is
- * reproducible and needs no network access. Every locked package is a component (dev-only ones
- * marked `excluded`, since they are not part of a published install) and the lockfile's own
- * resolution is turned into the dependency graph. Output is deterministic: components and edges
- * are sorted and `serialNumber` is a UUID derived from the document's own content rather than
- * from the clock, so the committed file can be checked for drift the way `API_REPORT.md` and
- * `PROJECT_STATS.json` already are: two BOMs that share a serial are the same BOM, and any change
- * to a component, a hash or an edge produces a new one.
- *
- * `metadata.timestamp` is deliberately absent. A generation time stamped into a committed file is
- * either a drift-check failure on every run or one stale moment every later read is dated to,
- * while `CHANGELOG.md` already dates each version.
- *
- * `type` is the described component's CycloneDX type: `'library'` for this framework,
- * `'application'` for a game (`mwg-sbom` picks it from whether the project is `private`).
- */
-export function buildSbom(packageJson, lockfile, { type = 'library' } = {}) {
-	const packages = lockfile.packages ?? {};
-	const rootPurl = purlFor(packageJson.name, packageJson.version);
-
-	const byPurl = new Map();
-	for (const [location, entry] of Object.entries(packages)) {
-		if (location === '' || entry.link === true || typeof entry.version !== 'string') continue;
-		const name = typeof entry.name === 'string' ? entry.name : nameFromLocation(location);
-		const purl = purlFor(name, entry.version);
-		const scope = scopeOf(entry);
-		const existing = byPurl.get(purl);
-		if (existing !== undefined) {
-			if (SCOPE_RANK[scope] < SCOPE_RANK[existing.scope]) existing.scope = scope;
-			continue;
-		}
-		const component = { type: 'library', 'bom-ref': purl, name, version: entry.version, purl, scope };
-		const hashes = hashesFromIntegrity(entry.integrity);
-		if (hashes.length > 0) component.hashes = hashes;
-		const licenses = licenseFor(entry.license);
-		if (licenses !== undefined) component.licenses = [licenses];
-		byPurl.set(purl, component);
-	}
-
-	const components = [...byPurl.values()].sort((a, b) => (a.purl < b.purl ? -1 : a.purl > b.purl ? 1 : 0));
-
-	const edges = new Map();
-	const addEdge = (from, to) => {
-		if (!edges.has(from)) edges.set(from, new Set());
-		edges.get(from).add(to);
-	};
-	for (const [location, entry] of Object.entries(packages)) {
-		if (location !== '' && (entry.link === true || typeof entry.version !== 'string')) continue;
-		const from =
-			location === ''
-				? rootPurl
-				: purlFor(typeof entry.name === 'string' ? entry.name : nameFromLocation(location), entry.version);
-		const declared = {
-			...(entry.dependencies ?? {}),
-			...(entry.devDependencies ?? {}),
-			...(entry.optionalDependencies ?? {}),
-			...(entry.peerDependencies ?? {}),
-		};
-		for (const name of Object.keys(declared)) {
-			const target = resolveDependency(packages, location, name);
-			const targetEntry = target === undefined ? undefined : packages[target];
-			if (targetEntry === undefined || typeof targetEntry.version !== 'string') continue;
-			const targetName = typeof targetEntry.name === 'string' ? targetEntry.name : nameFromLocation(target);
-			addEdge(from, purlFor(targetName, targetEntry.version));
-		}
-	}
-
-	const refs = [rootPurl, ...components.map((component) => component['bom-ref'])];
-	const dependencies = [...new Set(refs)]
-		.sort()
-		.map((ref) => ({ ref, dependsOn: [...(edges.get(ref) ?? [])].sort() }));
-
-	return document(packageJson, type, components, dependencies);
-}
-
-/** the envelope both builders share, with the content-derived serial */
-function document(packageJson, type, components, dependencies) {
-	const rootPurl = purlFor(packageJson.name, packageJson.version);
-	const rootLicenses = licenseFor(packageJson.license);
-	const metadata = {
-		tools: {
-			components: [{ type: 'application', group: 'datamoc', name: 'tools/sbom.mjs', version: TOOL.version }],
-		},
-		component: {
-			type,
-			'bom-ref': rootPurl,
-			name: packageJson.name,
-			version: packageJson.version,
-			purl: rootPurl,
-			...(typeof packageJson.description === 'string' ? { description: packageJson.description } : {}),
-			...(rootLicenses === undefined ? {} : { licenses: [rootLicenses] }),
-		},
-	};
-	return {
-		bomFormat: 'CycloneDX',
-		specVersion: SPEC_VERSION,
-		serialNumber: `urn:uuid:${uuidv5(JSON.stringify({ metadata, components, dependencies }))}`,
-		version: 1,
-		metadata,
-		components,
-		dependencies,
-	};
-}
-
-/**
- * The package a bundled module came from: the last `node_modules/<name>` (or `<@scope/name>`) in
- * its path, with the directory holding that package's `package.json`. Null for the game's own
- * source and for bundler-virtual modules.
- */
-export function packageOfModule(id) {
-	const path = id.replace(/^\0/, '').split('?')[0].split(sep).join('/');
-	const marker = path.lastIndexOf('/node_modules/');
-	if (marker < 0) return null;
-	const parts = path.slice(marker + '/node_modules/'.length).split('/');
-	const name = parts[0].startsWith('@') ? `${parts[0]}/${parts[1]}` : parts[0];
-	if (!name || name.startsWith('.')) return null;
-	return { name, dir: `${path.slice(0, marker)}/node_modules/${name}` };
-}
-
-/**
- * The SBOM of what a build actually ships, rather than of `node_modules` (item 380): a game is
- * one tree-shaken bundle, so the lockfile lists tooling that never reaches a player and cannot say
- * which packages did. `modules` are the bundle's module ids (vite's module graph, collected by
- * `mwgPage()`), each package they come from becomes a `required` library component with its
- * version and licence read from its own `package.json`, and `files` are the shipped files as
- * `file` components carrying their SHA-256.
- *
- * @param {{ packageJson: object, modules: string[], files: { path: string, sha256: string }[] }} input
- */
-export function buildArtifactSbom({ packageJson, modules, files }) {
-	const packages = new Map();
-	for (const id of modules) {
-		const found = packageOfModule(id);
-		if (!found || packages.has(found.dir)) continue;
-		let manifest;
-		try {
-			manifest = JSON.parse(readFileSync(join(found.dir, 'package.json'), 'utf8'));
-		} catch {
-			continue;
-		}
-		packages.set(found.dir, {
-			name: manifest.name ?? found.name,
-			version: manifest.version,
-			license: manifest.license,
-		});
-	}
-	const libraries = new Map();
-	for (const { name, version, license } of packages.values()) {
-		if (typeof version !== 'string') continue;
-		const purl = purlFor(name, version);
-		const licenses = licenseFor(license);
-		libraries.set(purl, {
-			type: 'library',
-			'bom-ref': purl,
-			name,
-			version,
-			purl,
-			scope: 'required',
-			...(licenses === undefined ? {} : { licenses: [licenses] }),
-		});
-	}
-	const fileComponents = [...files]
-		.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
-		.map(({ path, sha256 }) => ({
-			type: 'file',
-			'bom-ref': `file:${path}`,
-			name: path,
-			hashes: [{ alg: 'SHA-256', content: sha256 }],
-		}));
-	const components = [...[...libraries.values()].sort((a, b) => (a.purl < b.purl ? -1 : 1)), ...fileComponents];
-	const rootPurl = purlFor(packageJson.name, packageJson.version);
-	const dependencies = [{ ref: rootPurl, dependsOn: [...libraries.keys()].sort() }];
-	return document(packageJson, 'application', components, dependencies);
-}
-
-/** SHA-256 of every file under `dist` a player receives: precompressed siblings and the SBOM itself left out */
-export async function shippedFiles(dist) {
-	const { walk } = await import('./compile-resources.mjs');
-	const files = [];
-	for await (const file of walk(dist)) {
-		const path = relative(dist, file).split(sep).join('/');
-		if (/\.(gz|br|xz)$/.test(path) || path.endsWith('.cdx.json')) continue;
-		files.push({
-			path,
-			sha256: createHash('sha256')
-				.update(await readFile(file))
-				.digest('hex'),
-		});
-	}
-	return files;
-}
-
-/** the exact committed bytes: two-space JSON and a trailing newline */
-export function serialize(bom) {
-	return `${JSON.stringify(bom, null, 2)}\n`;
-}
-
-async function readJson(path) {
-	return JSON.parse(await readFile(path, 'utf8'));
-}
-
-/**
- * `mwg-sbom [project folder] [--out=<file>] [--check]`: the lockfile SBOM of any npm project,
- * this framework included (`npm run sbom` here). A `private` project is described as an
- * `application`, anything else as a `library`. `--check` compares instead of writing, for CI.
- */
-async function main(argv) {
-	if (argv.includes('--help') || argv.includes('-h')) {
-		console.log('usage: mwg-sbom [project folder] [--out=<file>] [--check]');
-		return;
-	}
-	const root = resolve(argv.find((arg) => !arg.startsWith('--')) ?? '.');
-	const out = resolve(root, argv.find((arg) => arg.startsWith('--out='))?.slice(6) ?? OUTPUT);
-	const packageJson = await readJson(join(root, 'package.json'));
-	const bom = buildSbom(packageJson, await readJson(join(root, 'package-lock.json')), {
-		type: packageJson.private === true ? 'application' : 'library',
-	});
-	const json = serialize(bom);
-	const name = relative(root, out) || out;
-	const summary = `CycloneDX ${SPEC_VERSION}, ${bom.components.length} components`;
-
-	if (argv.includes('--check')) {
-		const committed = await readFile(out, 'utf8').catch(() => undefined);
-		//CRLF is a Windows checkout's doing, not a difference in the BOM itself (and a missing
-		//file still reads as out of date: '' never equals the serialized BOM)
-		if ((committed ?? '').replace(/\r\n/g, '\n') !== json.replace(/\r\n/g, '\n')) {
-			console.error(`${name} is out of date with package-lock.json. Run "npm run sbom" and commit the result.`);
-			process.exitCode = 1;
-		} else {
-			console.log(`${name} matches package-lock.json (${summary}).`);
-		}
-	} else {
-		await writeFile(out, json, 'utf8');
-		console.log(`wrote ${name} (${summary})`);
-	}
-}
-
-//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))
-	main(process.argv.slice(2)).catch((error) => {
-		console.error(error);
-		process.exitCode = 1;
-	});
+export * from '@datamoc/mwg/tools/sbom';

package/tools/single-file.d.mts

@@ -1,33 +1 @@
-/** Options for {@link buildSingleFile}. */
-export interface SingleFileOptions {
-	/** Path to the folder `emit-page.mjs` already wrote. */
-	dist: string;
-	/** Compress each inlined script before embedding it (default false). */
-	compress?: boolean;
-	/** Algorithm used when `compress` is set (default 'gzip'). */
-	algorithm?: 'gzip' | 'brotli';
-	/** gzip level 1-9, or brotli quality 0-11 (default 9 for gzip, 11 for brotli). */
-	level?: number;
-	/** Show a splash screen while the embedded scripts decode (default true). */
-	splash?: boolean;
-	/**
-	 * Output file *name*, written inside `dist` (default `standalone.html`). A name, not a
-	 * path: one containing a separator is refused with a thrown error rather than joined
-	 * onto `dist`. Additive, so `dist/index.html` is left as it was.
-	 */
-	output?: string;
-}
-
-/** What {@link buildSingleFile} wrote. */
-export interface SingleFileResult {
-	/** Path of the written file: `dist` joined with `output`. */
-	path: string;
-	/** How many `<script src>` payloads were inlined. */
-	scripts: number;
-	/** Total size of that script code before compression. */
-	rawBytes: number;
-	/** Total length of the base64 payloads actually embedded, so after compression. */
-	embeddedBytes: number;
-}
-
-export function buildSingleFile(options: SingleFileOptions): Promise<SingleFileResult>;
+export * from '@datamoc/mwg/tools/single-file';

package/tools/single-file.mjs

@@ -1,239 +1 @@
-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`) - a name, not a path: one containing a separator is refused rather than
- *   joined onto `dist`. 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)}`);
-	}
-	if (/[\\/]/.test(output)) {
-		throw new Error(
-			'buildSingleFile: `output` is a file name written inside `dist`, not a path, so it cannot ' +
-				`contain a separator - got ${JSON.stringify(output)}`,
-		);
-	}
-
-	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);
-
-async function runCli() {
-	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');
-}
-
-//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 * from '@datamoc/mwg/tools/single-file';