@datamoc/mw_games 0.16.0 → 0.17.1

package/tools/emit-page.d.mts

@@ -0,0 +1,44 @@
+import type { CompileResourcesGroup } from './compile-resources.mjs';
+import type { CompressRow } from './compress-dist.mjs';
+import type { SingleFileOptions, SingleFileResult } from './single-file.mjs';
+
+export interface EmitPageOptions {
+	/** the vite output folder holding `index.html` */
+	dist: string;
+	/** the asset source folder compiled into `dist/assets/*.js`; omit for a game with no assets */
+	assets?: string;
+	/** maps an asset path to its script's name; defaults to one script per top-level folder */
+	groupBy?: (key: string) => string;
+	/** write `.gz`/`.br` siblings for a server to negotiate; default true */
+	compress?: boolean;
+	/** also write `.xz`, where the system `xz` binary exists */
+	xz?: boolean;
+	/** also write `standalone.html` with every script inlined */
+	singleFile?: boolean | Omit<SingleFileOptions, 'dist'>;
+	toWebp?: boolean;
+	webpLossless?: boolean;
+	webpQuality?: number;
+	/** the page's Content-Security-Policy: on by default, `false` to leave it out */
+	csp?: boolean | CspOptions;
+}
+
+export interface CspOptions {
+	/** origins the game connects to (`NewsClient`, `TelemetryClient`, `LockstepClient`...) */
+	connect?: string[];
+	/** keep `'unsafe-eval'`, which Pixi 8 needs unless the game imports `pixi.js/unsafe-eval`; default true */
+	eval?: boolean;
+}
+
+export interface EmitPageResult {
+	dist: string;
+	entry: string;
+	groups: CompileResourcesGroup[];
+	rawBytes: number;
+	embeddedBytes: number;
+	webpConverted: number;
+	compressed: CompressRow[] | null;
+	single: SingleFileResult | null;
+}
+
+/** finishes a vite build as a page that opens from `file://` */
+export function emitPage(options: EmitPageOptions): Promise<EmitPageResult>;

package/tools/emit-page.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+import { readFile, writeFile, rm, stat } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import { join, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { compileResources } from './compile-resources.mjs';
+import { compressDist } from './compress-dist.mjs';
+import { toClassicScript } from './classic-html.mjs';
+import { buildSingleFile } from './single-file.mjs';
+import { withContentSecurityPolicy } from './csp.mjs';
+
+/**
+ * Turns a vite build into a folder that opens by double-clicking.
+ *
+ * Two things have to change from what vite emits:
+ *
+ *   - its entry tag is `<script type="module" crossorigin>`, and both attributes stop a
+ *     `file://` page from running the script. The bundle is a plain IIFE, so the tag is
+ *     rewritten as a classic script - with `defer`, because a module tag was implicitly
+ *     deferred and a classic one is not: without it the scripts run from `<head>` before
+ *     the body exists, and the game finds no canvas;
+ *   - the assets have to be compiled into scripts and listed in the page, because a
+ *     `file://` page cannot read a directory to discover them.
+ *
+ * Shipped as `@datamoc/mw_games/tools/emit-page` (`emitPage(options)`, the function every flag
+ * below maps onto) and as the `mwg-emit` command; `@datamoc/mw_games/tools/vite`'s `mwgPage()`
+ * plugin calls `emitPage` at the end of `vite build`, so a game needs neither by hand.
+ *
+ * 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]]
+ *
+ * `--dist` defaults to `<project folder>/dist` and `--assets` to `<project folder>/assets`; with
+ * no assets folder at all, the page is rewritten and nothing is compiled.
+ *
+ * After the page is rewritten, precompressed `.gz`/`.br` siblings are written next to
+ * the text files (see `tools/compress-dist.mjs`): the `file://` page keeps loading the
+ * originals, while a server in front of the same folder can serve the smaller files.
+ * `--no-compress` (or `MWG_NO_COMPRESS=1`) skips that pass; `--xz` also writes `.xz`
+ * archives where the system `xz` binary exists.
+ *
+ * `--single-file` additionally writes `dist/standalone.html` (see `tools/single-file.mjs`):
+ * every script the page loads, inlined into one file with no sibling `.js` at all.
+ * `--single-file-compress[=level]` gzips each inlined script; `--single-file-brotli[=quality]`
+ * compresses with brotli instead (smaller, needs a newer browser - see `single-file.mjs`'s own
+ * doc comment), unpacked either way at load with the browser's own `DecompressionStream`. Both
+ * are additive - the regular multi-file `index.html` this function already writes is untouched
+ * - so the build-options matrix (multi-file/single-file, compressed/not, gzip/brotli) is a
+ * choice per build, not a fork of the pipeline.
+ *
+ * `--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.
+ */
+
+/**
+ * Finishes a vite build in `dist` as a page that opens from `file://`: compiles `assets` into
+ * scripts under `dist/assets`, rewrites the module entry tag to a classic deferred one with the
+ * asset scripts before it, writes a Content-Security-Policy into the page (`csp`, see
+ * `tools/csp.mjs`; `false` leaves it out, `{ connect: [...] }` declares the endpoints a game
+ * talks to), removes vite's `.vite` metadata, then optionally precompresses and writes a
+ * single-file variant. Returns what it did, for a caller to report.
+ */
+export async function emitPage({
+	dist,
+	assets,
+	groupBy,
+	compress = true,
+	xz = false,
+	singleFile = false,
+	toWebp = false,
+	webpLossless = true,
+	webpQuality = 90,
+	csp = true,
+}) {
+	if (!dist) throw new Error('emitPage needs the dist folder of a vite build');
+	const compiled = assets
+		? await compileResources({ from: assets, to: join(dist, 'assets'), groupBy, toWebp, webpLossless, webpQuality })
+		: { groups: [], rawBytes: 0, embeddedBytes: 0, webpConverted: 0 };
+
+	const html = await readFile(join(dist, 'index.html'), 'utf8');
+	const classic = toClassicScript(html);
+	if (!classic) {
+		throw new Error('no <script type="module"> entry tag found in the vite output - did the build succeed?');
+	}
+	const tag = `<script defer src="${classic.src}"></script>`;
+	const assetTags = compiled.groups.map((g) => `\t<script defer src="./assets/${g.name}.js"></script>`).join('\n');
+	//defer preserves document order, so the asset scripts still run before the game does
+	const page = assetTags ? classic.html.replace(tag, `${assetTags}\n\t${tag}`) : classic.html;
+	const cspOptions = csp === true ? {} : csp;
+	await writeFile(join(dist, 'index.html'), cspOptions ? withContentSecurityPolicy(page, cspOptions) : page, 'utf8');
+
+	//vite leaves a .vite folder of build metadata that the shipped folder does not need
+	await rm(join(dist, '.vite'), { recursive: true, force: true });
+
+	const compressed = compress ? await compressDist(dist, { xz }) : null;
+	const single = singleFile ? await buildSingleFile({ dist, ...(singleFile === true ? {} : singleFile) }) : null;
+	if (single && cspOptions) {
+		//a compressed standalone page unpacks each script and inserts it inline, so the scripts
+		//the multi-file page loads by src are allowed by hash as well
+		const sources = [...page.matchAll(/<script[^>]*\bsrc="\.\/([^"]+)"[^>]*><\/script>/g)].map((m) => m[1]);
+		const scripts = await Promise.all(sources.map((source) => readFile(join(dist, source), 'utf8')));
+		const standalone = await readFile(single.path, 'utf8');
+		await writeFile(single.path, withContentSecurityPolicy(standalone, { ...cspOptions, scripts }), 'utf8');
+	}
+	return { dist, entry: classic.src, ...compiled, compressed, single };
+}
+
+const kb = (n) => (n / 1024).toFixed(1) + ' KB';
+
+async function main(argv) {
+	const folder = argv.find((arg) => !arg.startsWith('--'));
+	if (!folder) {
+		console.error('usage: mwg-emit <project folder> [--dist=<dir>] [--assets=<dir>] [options]');
+		process.exit(1);
+	}
+	const option = (name) => argv.find((a) => a === `--${name}` || a.startsWith(`--${name}=`));
+	const value = (name) => option(name)?.split('=').slice(1).join('=') || undefined;
+	const root = resolvePath(folder);
+	const dist = resolvePath(value('dist') ?? join(root, 'dist'));
+	const assetsDir = resolvePath(value('assets') ?? join(root, 'assets'));
+	const hasAssets = (await stat(assetsDir).catch(() => null))?.isDirectory() ?? false;
+
+	const webpLossyFlag = option('webp-lossy');
+	const brotliFlag = option('single-file-brotli');
+	const compressFlag = option('single-file-compress');
+	const levelFlag = brotliFlag ?? compressFlag;
+	const singleFile = argv.includes('--single-file') && {
+		compress: Boolean(brotliFlag || compressFlag),
+		algorithm: brotliFlag ? 'brotli' : 'gzip',
+		level: levelFlag?.includes('=') ? Number(levelFlag.split('=')[1]) : undefined,
+	};
+
+	const result = await emitPage({
+		dist,
+		assets: hasAssets ? assetsDir : undefined,
+		//a flat assets folder becomes one script, whatever its subfolders
+		groupBy: () => 'assets',
+		compress: !(argv.includes('--no-compress') || process.env.MWG_NO_COMPRESS === '1'),
+		xz: argv.includes('--xz'),
+		singleFile,
+		toWebp: argv.includes('--to-webp'),
+		webpLossless: !webpLossyFlag,
+		webpQuality: webpLossyFlag?.includes('=') ? Number(webpLossyFlag.split('=')[1]) : 90,
+		csp: argv.includes('--no-csp')
+			? false
+			: { connect: argv.filter((a) => a.startsWith('--connect=')).map((a) => a.slice('--connect='.length)) },
+	});
+
+	console.log(`\n  ${dist}`);
+	console.log(
+		`  index.html + ${result.entry} + ${result.groups.length} asset script(s), ${kb(result.rawBytes)} of assets`,
+	);
+	if (argv.includes('--to-webp')) {
+		console.log(
+			`  ${result.webpConverted} image(s) converted to WebP (${webpLossyFlag ? 'lossy' : 'lossless'}), ` +
+				`${kb(result.rawBytes)} -> ${kb(result.embeddedBytes)} embedded`,
+		);
+	}
+	console.log('  open index.html directly - no server needed');
+	if (result.compressed) {
+		for (const row of result.compressed) {
+			const parts = [`${row.file}: ${kb(row.raw)}`];
+			if (row.gzip) parts.push(`gz ${kb(row.gzip)}`);
+			if (row.brotli) parts.push(`br ${kb(row.brotli)}`);
+			if (row.xz) parts.push(`xz ${kb(row.xz)}`);
+			console.log('  ' + parts.join(', '));
+		}
+	} else {
+		console.log('  (compression skipped)');
+	}
+	if (result.single) {
+		const { algorithm, level } = singleFile;
+		console.log(
+			`\n  ${result.single.path}`,
+			`\n  ${result.single.scripts} script(s) inlined, ${kb(result.single.rawBytes)} raw -> ${kb(result.single.embeddedBytes)} embedded` +
+				(singleFile.compress
+					? ` (${algorithm} level ${level ?? (algorithm === 'brotli' ? 11 : 9)})`
+					: ' (uncompressed)'),
+		);
+		console.log('  one file, no server, no sibling script - open it directly');
+	}
+}
+
+//realpath, since an npm `bin` shim reaches this file through a symlink
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url))
+	await main(process.argv.slice(2));

package/tools/extract-rgssad.d.mts

@@ -0,0 +1,5 @@
+/** where an archive entry lands under `outDir`; throws when its name would escape `outDir` */
+export function entryPath(outDir: string, fileName: string): string;
+
+/** extracts every entry of an RPG Maker XP/VX `.rgssad` archive under `outDir`; resolves to the file count */
+export function extractRgssad(archivePath: string, outDir: string): Promise<number>;

package/tools/extract-rgssad.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as glue from './vendored/rgssad-wasm/rgssad_wasm_bg.js';
+
+/**
+ * Extracts an RPG Maker XP/VX `.rgssad` archive to plain files, through the vendored
+ * `rgssad-wasm` decoder (MIT, see `vendored/rgssad-wasm/README.md`). A format tool, for someone
+ * porting a game whose archive they own; nothing a player receives. Shipped as
+ * `@datamoc/mw_games/tools/extract-rgssad` and `mwg-extract-rgssad <archive> <outDir>` (item 389).
+ *
+ * Entry names come from the archive, so they are untrusted: each is normalised (RPG Maker writes
+ * `\\` separators) and refused unless it resolves inside `outDir`, the check that stops an entry
+ * named `..\\..\\anything` from writing outside the folder asked for.
+ */
+
+// Resolved relative to this script's own location, not the caller's cwd.
+const here = path.dirname(fileURLToPath(import.meta.url));
+let ready = null;
+
+function decoder() {
+	ready ??= WebAssembly.instantiate(fs.readFileSync(path.join(here, 'vendored/rgssad-wasm/rgssad_wasm_bg.wasm')), {
+		'./rgssad_wasm_bg.js': glue,
+	}).then(({ instance }) => {
+		glue.__wbg_set_wasm(instance.exports);
+		if (instance.exports.__wbindgen_start) instance.exports.__wbindgen_start();
+	});
+	return ready;
+}
+
+/** where an archive entry lands under `outDir`, or a thrown error when its name escapes it */
+export function entryPath(outDir, fileName) {
+	const root = path.resolve(outDir);
+	const target = path.resolve(root, fileName.replace(/\\/g, '/'));
+	if (target !== root && !target.startsWith(root + path.sep))
+		throw new Error(`rgssad entry "${fileName}" would be written outside ${root}`);
+	return target;
+}
+
+/** extracts every entry of `archivePath` under `outDir`; returns how many files were written */
+export async function extractRgssad(archivePath, outDir) {
+	await decoder();
+	const data = fs.readFileSync(archivePath);
+	const reader = new glue.Reader(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength));
+	let count = 0;
+	for (let entry = reader.readEntry(); entry != null; entry = reader.readEntry()) {
+		const outPath = entryPath(outDir, entry.fileName);
+		fs.mkdirSync(path.dirname(outPath), { recursive: true });
+		fs.writeFileSync(outPath, Buffer.from(entry.data));
+		count++;
+	}
+	return count;
+}
+
+//realpath, since an npm `bin` shim reaches this file through a symlink
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+	const [, , archivePath, outDir] = process.argv;
+	if (!archivePath || !outDir) {
+		console.error('usage: mwg-extract-rgssad <archive.rgssad> <outDir>');
+		process.exit(1);
+	}
+	console.log(`Extracted ${await extractRgssad(archivePath, outDir)} files to ${outDir}`);
+}

package/tools/find-chrome.d.mts

@@ -0,0 +1,7 @@
+import type { Browser } from 'playwright-core';
+
+/** the Chrome or Chromium to drive: the platform's usual install, then Playwright's own, then PATH */
+export function findChrome(): Promise<string>;
+
+/** headless Chrome set up for `file://` pages; `CHROME_PATH` names the executable, `argsEnv` names the variable holding extra flags */
+export function launchChrome(options?: { argsEnv?: string }): Promise<Browser>;

package/tools/find-chrome.mjs

@@ -0,0 +1,104 @@
+import { access, readdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * `playwright-core`, loaded on first use: it is an optional peer of the published package, so a
+ * game that never runs a browser check does not need it installed.
+ */
+async function playwright() {
+	try {
+		return await import('playwright-core');
+	} catch {
+		throw new Error('the browser checks need playwright-core: npm install --save-dev playwright-core');
+	}
+}
+
+/**
+ * The browser to drive: the platform's usual Chrome (or, on Windows, Edge), then a Chromium that
+ * Playwright itself installed (`PLAYWRIGHT_BROWSERS_PATH`, common in CI images and containers),
+ * then whatever is on PATH. `CHROME_PATH` overrides all of them in `launchChrome`.
+ */
+export async function findChrome() {
+	const candidates =
+		process.platform === 'win32'
+			? [
+					'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+					'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+					'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+				]
+			: process.platform === 'darwin'
+				? [
+						'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+						'/Applications/Chromium.app/Contents/MacOS/Chromium',
+					]
+				: ['/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser'];
+
+	for (const candidate of candidates) {
+		try {
+			await access(candidate);
+			return candidate;
+		} catch {}
+	}
+	const bundled = await playwrightChromium();
+	if (bundled) return bundled;
+	return process.platform === 'win32' ? 'chrome.exe' : 'google-chrome';
+}
+
+/**
+ * The newest Chromium under Playwright's browsers folder, whatever revision it is: the one
+ * `playwright-core` would pick is often not the one a CI image or container installed.
+ */
+async function playwrightChromium() {
+	const roots = [
+		process.env.PLAYWRIGHT_BROWSERS_PATH,
+		process.platform === 'win32'
+			? join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'ms-playwright')
+			: process.platform === 'darwin'
+				? join(homedir(), 'Library', 'Caches', 'ms-playwright')
+				: join(homedir(), '.cache', 'ms-playwright'),
+	].filter(Boolean);
+	const inside = [
+		'chrome-linux64/chrome',
+		'chrome-linux/chrome',
+		'chrome-win64/chrome.exe',
+		'chrome-win/chrome.exe',
+		'chrome-mac-arm64/Chromium.app/Contents/MacOS/Chromium',
+		'chrome-mac/Chromium.app/Contents/MacOS/Chromium',
+	];
+	for (const root of roots) {
+		const revisions = (await readdir(root).catch(() => []))
+			.filter((name) => /^chromium-\d+$/.test(name))
+			.sort((a, b) => Number(b.slice(9)) - Number(a.slice(9)));
+		for (const revision of revisions)
+			for (const path of inside) {
+				const candidate = join(root, revision, path);
+				if (
+					await access(candidate).then(
+						() => true,
+						() => false,
+					)
+				)
+					return candidate;
+			}
+	}
+	return null;
+}
+
+/**
+ * Launches headless Chrome for a page loaded from `file://`, the way every tool here wants it:
+ * the same discovery, `--allow-file-access-from-files`, and machine-specific flags read from
+ * `argsEnv` (a runner with no GPU passes `--use-gl=angle --use-angle=swiftshader` that way,
+ * since that is a property of the machine rather than of the tool). Each caller keeps its own
+ * page setup and assertions; this is the launch they all had in common.
+ */
+export async function launchChrome({ argsEnv = 'MWG_BENCHMARK_CHROME_ARGS' } = {}) {
+	const executablePath = process.env.CHROME_PATH ?? (await findChrome());
+	const extraArgs = (process.env[argsEnv] ?? '').split(' ').filter(Boolean);
+	const { chromium } = await playwright();
+	return chromium.launch({
+		executablePath,
+		headless: true,
+		args: ['--allow-file-access-from-files', ...extraArgs],
+	});
+}

package/tools/i18n-edit.d.mts

@@ -0,0 +1,29 @@
+import type { Catalog } from '@datamoc/mw_games/i18n';
+import type { MarkdownSpan } from '@datamoc/mw_games/two-d/ui';
+
+export interface LoadedCatalogFile {
+	catalog: Catalog;
+	format: 'json' | 'ftl';
+	typography: boolean | undefined;
+}
+
+export interface SerializedTarget {
+	text: string;
+	flattened: number;
+}
+
+export function loadCatalogFile(path: string): Promise<LoadedCatalogFile>;
+export function serializeTarget(targetPath: string, catalog: Catalog): SerializedTarget;
+export function spansToAnsi(spans: readonly MarkdownSpan[]): string;
+export function truncateAnsi(ansi: string, width: number): string;
+export function placeholderSummary(baseText: string, targetText: string): string;
+export function expectedPlaceholders(baseText: string): string;
+
+export interface PlayerCandidate {
+	cmd: string;
+	args: string[];
+	shell?: boolean;
+}
+
+export function playerCandidates(cuePath: string, platform?: NodeJS.Platform): PlayerCandidate[];
+export function main(argv?: string[]): Promise<void>;