@datamoc/mw_games 0.43.0 → 0.45.0

package/physics/xpbd.d.ts

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/physics/xpbd';

package/physics/xpbd.js

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/physics/xpbd';

package/physics.d.ts

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/physics';

package/physics.js

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/physics';

package/roguelike.d.ts

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/roguelike';

package/roguelike.js

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/roguelike';

package/rpg.d.ts

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/rpg';

package/rpg.js

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/rpg';

package/simulation.d.ts

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/simulation';

package/simulation.js

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/simulation';

package/skeleton.d.ts

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/skeleton';

package/skeleton.js

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/skeleton';

package/testing.d.ts

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/testing';

package/testing.js

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/testing';

package/threads.d.ts

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/threads';

package/threads.js

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/threads';

package/tools/asset-report.d.mts

@@ -1,37 +1 @@
-export interface AssetReportFile {
-	path: string;
-	raw: number;
-	gzip: number;
-	brotli: number;
-	sha256: string;
-	/** This file's gzip bytes over the page's total gzip bytes, 0 when the page is empty. */
-	share: number;
-}
-export interface AssetReportSource {
-	path: string;
-	raw: number;
-	sha256: string;
-}
-export interface AssetReportTotals {
-	files: number;
-	raw: number;
-	gzip: number;
-	brotli: number;
-	assetFiles: number;
-	assetRaw: number;
-}
-export interface AssetReport {
-	dist: string;
-	files: AssetReportFile[];
-	assets: AssetReportSource[];
-	/** Groups of source paths with byte-identical content, sorted; empty when none exist. */
-	duplicates: string[][];
-	totals: AssetReportTotals;
-}
-export function fingerprint(data: Uint8Array): string;
-export function compressedSizes(data: Uint8Array): { gzip: number; brotli: number };
-export function assetReport(options: {
-	dist: string;
-	assets?: string;
-	mime?: Record<string, string>;
-}): Promise<AssetReport>;
+export * from '@datamoc/mwg/tools/asset-report';

package/tools/asset-report.mjs

@@ -1,157 +1 @@
-#!/usr/bin/env node
-import { createHash } from 'node:crypto';
-import { gzipSync, brotliCompressSync, constants } from 'node:zlib';
-import { realpathSync, statSync } from 'node:fs';
-import { readFile, writeFile } from 'node:fs/promises';
-import { join, relative, sep, extname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { walk, DEFAULT_MIME } from './compile-resources.mjs';
-
-/**
- * Reports what a built page actually ships, so a game can see where its bytes go.
- *
- * Two halves, both deterministic (sorted paths, fixed compression settings, hashes):
- *
- *   - `files`: every file under `dist` (precompressed `.gz`/`.br`/`.xz` siblings
- *     excluded - they are derived artifacts, and the gzip/brotli columns already count
- *     them) with raw, gzip (level 9) and brotli (quality 11) weights plus its share of
- *     the compressed page, the same settings `tools/compress-dist.mjs` writes with;
- *   - `assets`: every source file the asset folder embeds (the root `credits.json`
- *     and unknown extensions excluded, exactly the files `compileResources` skips),
- *     with duplicates grouped by SHA-256 so an asset embedded twice is visible.
- *
- * Shipped as `@datamoc/mw_games/tools/asset-report` (`assetReport(options)`, what the
- * flags below map onto) and as the `mwg-assets` command.
- *
- * usage: mwg-assets <dist folder> [--assets=<dir>] [--json=<report file>]
- */
-
-const DERIVED_SIBLINGS = new Set(['.gz', '.br', '.xz']);
-
-export function fingerprint(data) {
-	return createHash('sha256').update(data).digest('hex');
-}
-
-export function compressedSizes(data) {
-	return {
-		gzip: gzipSync(data, { level: 9 }).length,
-		brotli: brotliCompressSync(data, { params: { [constants.BROTLI_PARAM_QUALITY]: 11 } }).length,
-	};
-}
-
-function isDirectory(path) {
-	try {
-		return statSync(path).isDirectory();
-	} catch {
-		return false;
-	}
-}
-
-/**
- * @param options.dist the built page folder to measure
- * @param options.assets the asset source folder to inventory (skipped when absent)
- * @param options.mime extension to MIME type, merged over the compile defaults, so a
- *   game embedding extra types reports the same set the build embeds
- * @returns the sorted files, sources, duplicate groups and totals described above
- */
-export async function assetReport({ dist, assets, mime = {} } = {}) {
-	if (!dist || !isDirectory(dist))
-		throw new Error(`assetReport needs the dist folder of a built page, got "${dist}"`);
-	if (assets !== undefined && !isDirectory(assets))
-		throw new Error(`assetReport needs a readable assets folder, got "${assets}"`);
-
-	const files = [];
-	for await (const file of walk(dist)) {
-		if (DERIVED_SIBLINGS.has(extname(file).toLowerCase())) continue;
-		const data = await readFile(file);
-		const { gzip, brotli } = compressedSizes(data);
-		files.push({
-			path: relative(dist, file).split(sep).join('/'),
-			raw: data.length,
-			gzip,
-			brotli,
-			sha256: fingerprint(data),
-			share: 0,
-		});
-	}
-	files.sort((a, b) => (a.path < b.path ? -1 : 1));
-	const totalGzip = files.reduce((sum, file) => sum + file.gzip, 0);
-	for (const file of files) file.share = totalGzip ? file.gzip / totalGzip : 0;
-
-	const sources = [];
-	const duplicates = [];
-	if (assets !== undefined) {
-		const types = { ...DEFAULT_MIME, ...mime };
-		const creditsFile = join(assets, 'credits.json');
-		const byHash = new Map();
-		for await (const file of walk(assets)) {
-			if (file === creditsFile) continue;
-			if (!types[extname(file).toLowerCase()]) continue;
-			const data = await readFile(file);
-			const sha256 = fingerprint(data);
-			const key = relative(assets, file).split(sep).join('/');
-			sources.push({ path: key, raw: data.length, sha256 });
-			const group = byHash.get(sha256) ?? [];
-			group.push(key);
-			byHash.set(sha256, group);
-		}
-		sources.sort((a, b) => (a.path < b.path ? -1 : 1));
-		for (const group of byHash.values()) if (group.length > 1) duplicates.push([...group].sort());
-		duplicates.sort((a, b) => (a[0] < b[0] ? -1 : 1));
-	}
-
-	return {
-		dist,
-		files,
-		assets: sources,
-		duplicates,
-		totals: {
-			files: files.length,
-			raw: files.reduce((sum, file) => sum + file.raw, 0),
-			gzip: totalGzip,
-			brotli: files.reduce((sum, file) => sum + file.brotli, 0),
-			assetFiles: sources.length,
-			assetRaw: sources.reduce((sum, source) => sum + source.raw, 0),
-		},
-	};
-}
-
-const kb = (n) => (n / 1024).toFixed(1) + ' KB';
-const percent = (share) => (share * 100).toFixed(1) + '%';
-
-async function main(argv) {
-	const folder = argv.find((arg) => !arg.startsWith('--'));
-	if (!folder) {
-		console.error('usage: mwg-assets <dist folder> [--assets=<dir>] [--json=<report file>]');
-		process.exit(1);
-	}
-	const value = (name) => argv.find((a) => a.startsWith(`--${name}=`))?.slice(name.length + 3);
-	const report = await assetReport({ dist: folder, assets: value('assets') });
-
-	console.log(`\n  ${report.dist}`);
-	for (const file of report.files) {
-		console.log(
-			`  ${file.path.padEnd(40)}${kb(file.raw).padStart(10)}  gz ${kb(file.gzip).padStart(10)}  br ${kb(file.brotli).padStart(10)}  ${percent(file.share).padStart(6)}`,
-		);
-	}
-	console.log(
-		`  ${report.totals.files} file(s), ${kb(report.totals.raw)} raw -> ${kb(report.totals.gzip)} gz / ${kb(report.totals.brotli)} br`,
-	);
-	if (report.assets.length) {
-		console.log(`  ${report.totals.assetFiles} embedded asset(s), ${kb(report.totals.assetRaw)} raw`);
-		for (const group of report.duplicates) console.log(`  duplicate: ${group.join(' == ')}`);
-	}
-	const json = value('json');
-	if (json) {
-		await writeFile(json, JSON.stringify(report, null, 2) + '\n', 'utf8');
-		console.log(`  report written to ${json}`);
-	}
-}
-
-//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/asset-report';

package/tools/audio.d.mts

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/tools/audio';

package/tools/audio.mjs

@@ -0,0 +1 @@
+export * from '@datamoc/mwg/tools/audio';

package/tools/audit-adoptions.d.mts

@@ -1,65 +1 @@
-export interface ManifestEntry {
-	name: string;
-	kind: string;
-	subpath: string;
-	declaringModule: string;
-}
-
-export interface ConsumerImport {
-	file: string;
-	line: number;
-	subpath: string;
-	names: string[];
-	typeOnly: boolean;
-}
-
-export interface LocalDefinition {
-	name: string;
-	file: string;
-	line: number;
-}
-
-export interface SourceFile {
-	path: string;
-	text: string;
-}
-
-export interface AdoptionBudget {
-	match: string;
-	limit: number;
-	reason: string;
-}
-
-export interface AuditorConfig {
-	reasons: Record<string, string>;
-	denySubpaths?: string[];
-	typeOnlyDirs?: string[];
-	budgets?: AdoptionBudget[];
-}
-
-export interface AdoptionFinding {
-	rule: 'unadopted' | 'stale-reason' | 'collision' | 'denied-subpath' | 'type-only' | 'budget';
-	message: string;
-	file?: string;
-	line?: number;
-}
-
-/** `<subpath> :: <name>`, the key reasons and adoption are tracked by */
-export function adoptionKey(subpath: string, name: string): string;
-
-/** every `@datamoc/mw_games/<sub>` import row in the given files */
-export function scanImports(files: SourceFile[]): ConsumerImport[];
-
-/** every top-level interface/type/class/function/const/enum the consumer defines */
-export function scanLocals(files: SourceFile[]): LocalDefinition[];
-
-/** every rule over the manifest, the import rows and locals, and the config; empty means fully accounted for */
-export function auditAdoptions(
-	manifest: ManifestEntry[],
-	imports: ConsumerImport[],
-	locals: LocalDefinition[],
-	config: AuditorConfig,
-): AdoptionFinding[];
-
-/** `file:line: [rule] message`, or `[rule] message` for manifest-level findings */
-export function formatFindings(findings: AdoptionFinding[]): string[];
+export * from '@datamoc/mwg/tools/audit-adoptions';

package/tools/audit-adoptions.mjs

@@ -1,252 +1 @@
-#!/usr/bin/env node
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-
-/**
- * The consumer adoption auditor: the mechanism behind "every export is adopted or
- * explicitly reasoned", shipped so no consumer rebuilds the gate by hand.
- *
- * A framework that ships its doctrine as prose makes every consumer rebuild the same
- * audit - which exports are used, which are deliberately not, which local definitions
- * shadow framework names, which directories may only import types, which subpaths are
- * denied, and how many files may reach past the facade - differently, and let it rot.
- * This tool is the shared checker; every value expressing *policy* (the reasons, the
- * globs, the budgets) stays in the consumer repository.
- *
- * It reads the P28 manifest (`api-surface.json`: `{ name, kind, subpath,
- * declaringModule }` per export), the consumer's own import rows and local
- * definitions (via `scanImports`/`scanLocals`, or any producer of the same shapes),
- * and a consumer-authored config:
- *
- * ```json
- * {
- * 	"reasons": {
- * 		"./board :: AlphaBetaGame": "chess engine, no board game in this project",
- * 		"local :: World": "documented collision: the game's own map container, never the framework export"
- * 	},
- * 	"denySubpaths": ["./three-d"],
- * 	"typeOnlyDirs": ["src/simulation"],
- * 	"budgets": [{ "match": "./two-d/pixi-interop", "limit": 37, "reason": "escape hatch, one reason per file" }]
- * }
- * ```
- *
- * Reasons are keyed either by export (`<subpath> :: <name>`, see `adoptionKey`) or by
- * `local :: <Name>` for a documented shadowing collision. The audit reports, with
- * `file:line` and a non-zero exit:
- *
- * - `unadopted` - a manifest export the consumer neither imports nor reasons about;
- * - `stale-reason` - a reason naming no manifest export and no local definition;
- * - `collision` - a local definition shadowing a never-imported manifest export with
- *   no `local ::` reason documenting it;
- * - `denied-subpath` - an import from a denied subpath (a denied prefix also covers
- *   its children: `./two-d` covers `./two-d/render`);
- * - `type-only` - a runtime import from a file under a type-only directory;
- * - `budget` - more importing files than a budget allows, naming the first file past
- *   the limit.
- */
-
-export function adoptionKey(subpath, name) {
-	return `${subpath} :: ${name}`;
-}
-
-function isUnder(file, dir) {
-	return file === dir || file.startsWith(`${dir}/`);
-}
-
-function subpathMatches(subpath, match) {
-	return subpath === match || subpath.startsWith(`${match}/`);
-}
-
-/**
- * Every `import ... from '@datamoc/mw_games/<sub>'` row in the given files, as
- * `{ file, line, subpath, names, typeOnly }`. `import type` rows are type-only; a
- * mixed value/type named list counts as runtime (conservative: the file still pulls
- * the module in at runtime). A default or namespace import carries no names, so it
- * adopts the whole subpath.
- */
-export function scanImports(files) {
-	const rows = [];
-	const pattern =
-		/^\s*import\s+(type\s+)?(?:\*\s+as\s+(\w+)|{([^}]*)}|(\w+))?\s*from\s*['"]@datamoc\/mw_games(\/[^'"]*)?['"]/gm;
-
-	for (const { path, text } of files) {
-		for (const match of text.matchAll(pattern)) {
-			const line = text.slice(0, match.index).split('\n').length;
-			const subpath = match[5] === undefined ? '.' : `.${match[5]}`;
-			const names = (match[3] ?? '')
-				.split(',')
-				.map((entry) =>
-					entry
-						.trim()
-						.replace(/^type\s+/, '')
-						.split(/\s+as\s+/)
-						.pop()
-						.trim(),
-				)
-				.filter(Boolean);
-			rows.push({ file: path, line, subpath, names, typeOnly: Boolean(match[1]) });
-		}
-	}
-
-	return rows;
-}
-
-/**
- * Every top-level `interface`/`type`/`class`/`function`/`const`/`enum` the consumer
- * defines itself, as `{ name, file, line }` - the shadowing candidates.
- */
-export function scanLocals(files) {
-	const locals = [];
-	const pattern = /^(?:export\s+)?(?:interface|type|class|function|const|enum)\s+([A-Za-z0-9_]+)/gm;
-
-	for (const { path, text } of files) {
-		for (const match of text.matchAll(pattern)) {
-			const line = text.slice(0, match.index).split('\n').length;
-			locals.push({ name: match[1], file: path, line });
-		}
-	}
-
-	return locals;
-}
-
-/**
- * Runs every rule over the manifest, the consumer's import rows and locals, and its
- * config. Returns findings in a stable order (rule, then message); empty means the
- * adoption is fully accounted for.
- */
-export function auditAdoptions(manifest, imports, locals, config) {
-	const findings = [];
-	const reasons = config.reasons ?? {};
-	const manifestKeys = new Set(manifest.map((entry) => adoptionKey(entry.subpath, entry.name)));
-	const importedKeys = new Set();
-	const starSubpaths = new Set();
-	for (const row of imports) {
-		for (const name of row.names) importedKeys.add(adoptionKey(row.subpath, name));
-		if (row.names.length === 0) starSubpaths.add(row.subpath);
-	}
-
-	for (const entry of manifest) {
-		const key = adoptionKey(entry.subpath, entry.name);
-		if (!importedKeys.has(key) && !starSubpaths.has(entry.subpath) && !(key in reasons)) {
-			findings.push({
-				rule: 'unadopted',
-				message: `${key} is neither imported nor reasoned (${entry.kind}, ${entry.declaringModule})`,
-			});
-		}
-	}
-
-	for (const key of Object.keys(reasons)) {
-		if (key.startsWith('local :: ')) {
-			const name = key.slice('local :: '.length);
-			if (!locals.some((local) => local.name === name)) {
-				findings.push({ rule: 'stale-reason', message: `${key} documents no local definition` });
-			}
-			continue;
-		}
-		if (!manifestKeys.has(key)) {
-			findings.push({ rule: 'stale-reason', message: `${key} names no manifest export` });
-		}
-	}
-
-	const exportedNames = new Set(manifest.map((entry) => entry.name));
-	for (const local of locals) {
-		if (!exportedNames.has(local.name)) continue;
-		const shadowed = manifest
-			.filter((entry) => entry.name === local.name)
-			.every((entry) => !importedKeys.has(adoptionKey(entry.subpath, entry.name)));
-		if (shadowed && !(`local :: ${local.name}` in reasons)) {
-			findings.push({
-				rule: 'collision',
-				message: `${local.name} shadows a never-imported framework export with no documented reason`,
-				file: local.file,
-				line: local.line,
-			});
-		}
-	}
-
-	for (const denied of config.denySubpaths ?? []) {
-		for (const row of imports) {
-			if (subpathMatches(row.subpath, denied)) {
-				findings.push({
-					rule: 'denied-subpath',
-					message: `${row.subpath} is denied by consumer config`,
-					file: row.file,
-					line: row.line,
-				});
-			}
-		}
-	}
-
-	for (const dir of config.typeOnlyDirs ?? []) {
-		for (const row of imports) {
-			if (!row.typeOnly && isUnder(row.file, dir)) {
-				findings.push({
-					rule: 'type-only',
-					message: `${row.file} may only import types, but imports ${row.subpath} at runtime`,
-					file: row.file,
-					line: row.line,
-				});
-			}
-		}
-	}
-
-	for (const budget of config.budgets ?? []) {
-		const offenders = [];
-		for (const row of imports) {
-			if (!subpathMatches(row.subpath, budget.match) || row.typeOnly) continue;
-			if (!offenders.some((offender) => offender.file === row.file)) offenders.push(row);
-		}
-		if (offenders.length > budget.limit) {
-			const firstPast = offenders[budget.limit];
-			findings.push({
-				rule: 'budget',
-				message: `${offenders.length} files import past ${budget.match} (limit ${budget.limit}: ${budget.reason})`,
-				file: firstPast.file,
-				line: firstPast.line,
-			});
-		}
-	}
-
-	findings.sort((a, b) => a.rule.localeCompare(b.rule) || a.message.localeCompare(b.message));
-	return findings;
-}
-
-/** `file:line: [rule] message`, or `[rule] message` for manifest-level findings */
-export function formatFindings(findings) {
-	return findings.map((finding) =>
-		finding.file === undefined
-			? `[${finding.rule}] ${finding.message}`
-			: `${finding.file}:${finding.line ?? 0}: [${finding.rule}] ${finding.message}`,
-	);
-}
-
-function main() {
-	const args = process.argv.slice(2);
-	const valueOf = (flag) => {
-		const index = args.indexOf(flag);
-		return index === -1 ? null : (args[index + 1] ?? null);
-	};
-	const manifestFile = valueOf('--manifest');
-	const importsFile = valueOf('--imports');
-	const localsFile = valueOf('--locals');
-	const configFile = valueOf('--config');
-
-	if (!manifestFile || !importsFile || !localsFile || !configFile) {
-		console.error(
-			'usage: mwg-audit-adoptions --manifest api-surface.json --imports imports.json --locals locals.json --config audit.json',
-		);
-		process.exitCode = 1;
-		return;
-	}
-
-	const manifest = JSON.parse(readFileSync(manifestFile, 'utf8'));
-	const imports = JSON.parse(readFileSync(importsFile, 'utf8'));
-	const locals = JSON.parse(readFileSync(localsFile, 'utf8'));
-	const config = JSON.parse(readFileSync(configFile, 'utf8'));
-	const lines = formatFindings(auditAdoptions(manifest, imports, locals, config));
-	for (const line of lines) console.log(line);
-	console.log(`${lines.length} adoption finding(s)`);
-	if (lines.length > 0) process.exitCode = 1;
-}
-
-if (process.argv[1] === fileURLToPath(import.meta.url)) main();
+export * from '@datamoc/mwg/tools/audit-adoptions';

package/tools/benchmark-browser.d.mts

@@ -1,33 +1 @@
-export interface MeasurePageOptions {
-	/** a `file://` url of the built page */
-	url: string;
-	/** frame intervals timed; at least 30, default 180 */
-	frames?: number;
-	/** fails below this mean fps; default 45 */
-	minFps?: number;
-	/** fails above this 95th-percentile frame time; default 40 ms */
-	maxP95FrameMs?: number;
-	/** a JSON history the run is appended to and compared with; none by default */
-	historyPath?: string | null;
-	/** how far below the history's best fps a run may fall; default 0.15 */
-	maxFpsRegression?: number;
-	screenshot?: string;
-}
-
-export interface MeasurePageResult {
-	page: string;
-	gameReady: boolean;
-	canvas: { width: number; height: number };
-	renderer: string;
-	fps: number;
-	averageMs: number;
-	p95FrameMs: number;
-	frames: number;
-	memoryMB: number | null;
-	screenshot: string;
-	pageErrors: string[];
-	thresholds: { minFps: number; maxP95FrameMs: number };
-}
-
-/** measures a built page's frame rate in headless Chrome and throws past its thresholds */
-export function measurePage(options: MeasurePageOptions): Promise<MeasurePageResult>;
+export * from '@datamoc/mwg/tools/benchmark-browser';