@datamoc/mw_games 0.44.2 → 0.46.0

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';

package/tools/benchmark-browser.mjs

@@ -1,169 +1 @@
-#!/usr/bin/env node
-import { statSync, realpathSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { launchChrome } from './find-chrome.mjs';
-import { waitForGame } from './browser-smoke.mjs';
-import { readHistory, appendHistory, bestSeen } from './benchmark-history.mjs';
-
-/**
- * Measures a built page's frame rate in headless Chrome: `frames` frame intervals timed with
- * `requestAnimationFrame`, their mean as fps and their 95th percentile, and Chrome's JS heap
- * where it reports one. Throws when the page is not a ready game on Pixi's (or Babylon's)
- * WebGL/WebGPU path, when it logs an error, when it misses `minFps` or `maxP95FrameMs`, or, with
- * a `historyPath`, when it falls more than `maxFpsRegression` below the best fps that history
- * has seen (a fixed gate alone cannot see a slow decline that never quite crosses it). The run is
- * appended to that history either way.
- *
- * Shipped for a game (item 387) as `@datamoc/mw_games/tools/benchmark-browser` and
- * `mwg-bench <page | dist>`; this repository runs it through `npm run benchmark:*`. A CI runner
- * has no GPU, so Chrome there is told which software WebGL path to take through
- * `MWG_BENCHMARK_CHROME_ARGS` (`--use-gl=angle --use-angle=swiftshader`), a property of the
- * machine rather than of the page.
- */
-export async function measurePage({
-	url,
-	frames = 180,
-	minFps = 45,
-	maxP95FrameMs = 40,
-	historyPath = null,
-	maxFpsRegression = 0.15,
-	screenshot = join(tmpdir(), `mwg-browser-benchmark-${process.pid}.png`),
-}) {
-	if (!Number.isInteger(frames) || frames < 30) throw new Error('frames must be an integer of at least 30');
-	const browser = await launchChrome();
-	try {
-		const page = await browser.newPage({ viewport: { width: 1280, height: 720 }, deviceScaleFactor: 1 });
-		const pageErrors = [];
-		page.on('pageerror', (error) => pageErrors.push(error.message));
-		page.on('console', (message) => {
-			if (message.type() === 'error') pageErrors.push(message.text());
-		});
-		await page.goto(url, { waitUntil: 'load' });
-		await waitForGame(page, url, pageErrors);
-
-		const state = await page.evaluate(() => {
-			const canvas = document.querySelector('canvas');
-			const app = window.__PIXI_APP__;
-			const babylon = window.__MWG_3D__;
-			return {
-				gameReady: Boolean(window.__MWG__ || babylon),
-				canvas: { width: canvas?.width ?? 0, height: canvas?.height ?? 0 },
-				renderer: babylon?.engine?.isWebGPU
-					? 'webgpu'
-					: babylon?.engine?.webGLVersion > 0
-						? 'webgl'
-						: String(app?.renderer?.name ?? 'unknown').toLowerCase(),
-				webGLVersion: babylon?.engine?.webGLVersion ?? null,
-				meshes: babylon?.scene?.meshes?.length ?? null,
-			};
-		});
-		const metrics = await page.evaluate(async (count) => {
-			const samples = [];
-			let previous;
-			await new Promise((resolve) => {
-				const frame = (now) => {
-					if (previous !== undefined) samples.push(now - previous);
-					previous = now;
-					if (samples.length >= count) resolve();
-					else requestAnimationFrame(frame);
-				};
-				requestAnimationFrame(frame);
-			});
-			samples.sort((a, b) => a - b);
-			const averageMs = samples.reduce((sum, value) => sum + value, 0) / samples.length;
-			const p95FrameMs = samples[Math.min(samples.length - 1, Math.floor(samples.length * 0.95))];
-			//`performance.memory` is a non-standard Chrome extension: null everywhere else,
-			//reported as such rather than guessed at
-			const memory = performance.memory;
-			const memoryMB = memory ? memory.usedJSHeapSize / (1024 * 1024) : null;
-			return { averageMs, p95FrameMs, fps: 1000 / averageMs, frames: samples.length, memoryMB };
-		}, frames);
-
-		await page.screenshot({ path: screenshot, type: 'png' });
-		const result = {
-			page: url,
-			...state,
-			...metrics,
-			screenshot,
-			pageErrors,
-			thresholds: { minFps, maxP95FrameMs },
-		};
-
-		if (!['webgl', 'webgpu'].includes(state.renderer)) {
-			throw new Error(`browser benchmark requires WebGL or WebGPU, got ${state.renderer}`);
-		}
-		if (pageErrors.length) throw new Error(`browser benchmark page errors: ${pageErrors.join('; ')}`);
-		if (metrics.fps < minFps || metrics.p95FrameMs > maxP95FrameMs) {
-			throw Object.assign(
-				new Error(
-					`browser performance threshold failed: ${metrics.fps.toFixed(1)} FPS, p95 ${metrics.p95FrameMs.toFixed(2)} ms`,
-				),
-				{ result },
-			);
-		}
-
-		if (historyPath) {
-			const history = await readHistory(historyPath);
-			const bestPriorFps = bestSeen(history, (entry) => entry.fps);
-			await appendHistory(historyPath, history, {
-				timestamp: new Date().toISOString(),
-				fps: metrics.fps,
-				p95FrameMs: metrics.p95FrameMs,
-				memoryMB: metrics.memoryMB,
-			});
-			if (bestPriorFps !== null && metrics.fps < bestPriorFps * (1 - maxFpsRegression)) {
-				throw Object.assign(
-					new Error(
-						`browser performance regressed against history: ${metrics.fps.toFixed(1)} FPS now vs ` +
-							`${bestPriorFps.toFixed(1)} FPS best-seen (${historyPath})`,
-					),
-					{ result },
-				);
-			}
-		}
-		return result;
-	} finally {
-		await browser.close();
-	}
-}
-
-/**
- * `mwg-bench <page | dist> [--frames=180] [--min-fps=45] [--max-p95=40] [--history=<file>]`,
- * each option also read from `MWG_BENCHMARK_FRAMES`, `MWG_BENCHMARK_MIN_FPS`,
- * `MWG_BENCHMARK_MAX_P95_MS` and `MWG_BENCHMARK_MAX_FPS_REGRESSION`. The history defaults to
- * `benchmark-results/<page>.json`, named by the page so two pages keep separate histories.
- */
-async function main(argv) {
-	if (argv.includes('--help') || argv.includes('-h')) {
-		console.log(
-			'usage: mwg-bench <page.html | dist folder> [--frames=180] [--min-fps=45] [--max-p95=40] [--history=<file>]',
-		);
-		return;
-	}
-	const value = (name, env, fallback) =>
-		argv.find((a) => a.startsWith(`--${name}=`))?.split('=')[1] ?? process.env[env] ?? fallback;
-	const target = argv.find((arg) => !arg.startsWith('--')) ?? 'examples/dungeon/dist/index.html';
-	const relativePage = statSync(target).isDirectory() ? join(target, 'index.html') : target;
-	const slug = relativePage.replace(/[\\/]/g, '-').replace(/\.html$/, '');
-	try {
-		const result = await measurePage({
-			url: pathToFileURL(resolve(relativePage)).href,
-			frames: Number(value('frames', 'MWG_BENCHMARK_FRAMES', 180)),
-			minFps: Number(value('min-fps', 'MWG_BENCHMARK_MIN_FPS', 45)),
-			maxP95FrameMs: Number(value('max-p95', 'MWG_BENCHMARK_MAX_P95_MS', 40)),
-			maxFpsRegression: Number(process.env.MWG_BENCHMARK_MAX_FPS_REGRESSION ?? 0.15),
-			historyPath: resolve(value('history', 'MWG_BENCHMARK_HISTORY', join('benchmark-results', `${slug}.json`))),
-		});
-		console.log(JSON.stringify(result, null, 2));
-	} catch (error) {
-		if (error?.result) console.log(JSON.stringify(error.result, null, 2));
-		console.error(error instanceof Error ? error.message : error);
-		process.exitCode = 1;
-	}
-}
-
-//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));
+export * from '@datamoc/mwg/tools/benchmark-browser';

package/tools/benchmark-history.d.mts

@@ -1,8 +1 @@
-/** a benchmark's recorded runs, or `[]` when none has been recorded yet */
-export function readHistory<T = Record<string, unknown>>(historyPath: string): Promise<T[]>;
-
-/** appends `entry` to `history` and writes the last 50 runs back */
-export function appendHistory<T>(historyPath: string, history: T[], entry: T): Promise<void>;
-
-/** the best value of `metric` across `history`, or null when it is empty */
-export function bestSeen<T>(history: readonly T[], metric: (entry: T) => number): number | null;
+export * from '@datamoc/mwg/tools/benchmark-history';

package/tools/benchmark-history.mjs

@@ -1,31 +1 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname } from 'node:path';
-
-const maxHistoryEntries = 50;
-
-/**
- * Per-benchmark history: read what a prior run of the same benchmark recorded, append what
- * this run measured, and detect a regression against the best one seen so far. Shared by
- * `benchmark-browser.mjs` (fps/p95/memory) and `benchmark-simulation.mjs` (commands/steps per
- * second) - the two started as separate copies of the same read/append/compare logic before
- * this module existed to hold it once.
- */
-export async function readHistory(historyPath) {
-	try {
-		return JSON.parse(await readFile(historyPath, 'utf8'));
-	} catch {
-		return []; //no prior run recorded yet - not an error, just nothing to compare against
-	}
-}
-
-/** appends `entry` to `history` (already loaded by the caller) and persists the result */
-export async function appendHistory(historyPath, history, entry) {
-	history.push(entry);
-	await mkdir(dirname(historyPath), { recursive: true });
-	await writeFile(historyPath, JSON.stringify(history.slice(-maxHistoryEntries), null, 2));
-}
-
-/** the best value of `metric` seen across `history`, or null if it is empty */
-export function bestSeen(history, metric) {
-	return history.length > 0 ? Math.max(...history.map((entry) => metric(entry))) : null;
-}
+export * from '@datamoc/mwg/tools/benchmark-history';

package/tools/browser-driver.d.mts

@@ -1,122 +1 @@
-export interface ServedDir {
-	url: string;
-	port: number;
-	/**
-	 * Presses and releases one key through the engine's trusted input channel (P41): a
-	 * named key from the table (`Enter`, `Escape`, `ArrowUp`, ...), or a single character
-	 * that types itself. `holdMs` parks between the down and the up.
-	 */
-	press(key: string, holdMs?: number): Promise<void>;
-	close(): Promise<void>;
-}
-
-export interface CdpMouseEvent {
-	type: 'mouseMoved' | 'mousePressed' | 'mouseReleased';
-	x: number;
-	y: number;
-	button: 'none' | 'left';
-	buttonValue?: number;
-	clickCount?: number;
-	buttons: number;
-}
-
-export interface BidiPointerAction {
-	type: 'pointer';
-	id: string;
-	parameters: { pointerType: 'mouse' };
-	actions: (
-		| { type: 'pointerMove'; x: number; y: number }
-		| { type: 'pointerDown'; button: number }
-		| { type: 'pointerUp'; button: number }
-	)[];
-}
-
-export interface BrowserDriver {
-	kind: 'chrome-cdp' | 'firefox-bidi';
-	goto(url: string): Promise<void>;
-	waitReady(url: string, timeoutMs?: number): Promise<void>;
-	evaluate<T>(expression: string): Promise<T>;
-	script<Args extends unknown[], T>(fn: (...args: Args) => T | Promise<T>, ...args: Args): Promise<T>;
-	tap(xFraction: number, yFraction: number): Promise<void>;
-	/** presses at one canvas fraction, moves to another with the button held in `steps` moves (default 8), releases */
-	drag(fromX: number, fromY: number, toX: number, toY: number, steps?: number): Promise<void>;
-	screenshot(): Promise<Buffer>;
-	consoleErrors(): string[];
-	close(): Promise<void>;
-}
-
-export interface DriveOptions {
-	executable?: string;
-	chromeArgs?: string[];
-	firefoxArgs?: string[];
-	profileDir?: string;
-	/**
-	 * The inner page viewport, applied through each engine's protocol call (CDP
-	 * `Emulation.setDeviceMetricsOverride`, BiDi `browsingContext.setViewport`) rather
-	 * than window flags, whose outer size is what a consumer's compensation kept
-	 * rediscovering (P41).
-	 */
-	viewport?: { width: number; height: number };
-	/** show the browser window instead of running headless, for watching a driven run */
-	headed?: boolean;
-}
-
-/** the readiness predicate browser-smoke's waitForGame waits on, as page JS */
-export function readinessExpression(): string;
-
-/** an OS-chosen free port, so Windows' excluded-port ranges cannot bite */
-export function pickFreePort(): Promise<number>;
-
-/** serves root over HTTP on an OS-chosen free port */
-export function serveDir(root: string): Promise<ServedDir>;
-
-/** the ws:// endpoint Chrome prints as DevTools listening on ..., or null */
-export function parseDevToolsEndpoint(stderr: string): string | null;
-
-/** the ws:// endpoint Firefox prints as WebDriver BiDi listening on ..., or null */
-export function parseBidiEndpoint(stderr: string): string | null;
-
-/** the CDP Input.dispatchMouseEvent sequence a tap is, at CSS pixels */
-export function buildTapSequence(x: number, y: number): CdpMouseEvent[];
-
-/** the CDP Input.dispatchMouseEvent sequence a drag is: press, held moves, release, at CSS pixels */
-export function buildDragSequence(
-	x1: number,
-	y1: number,
-	x2: number,
-	y2: number,
-	steps?: number,
-): Record<string, unknown>[];
-
-/** the in-page synthetic pointer drag, the Firefox path (see pageTapSource) */
-export function pageDragSource(x1: number, y1: number, x2: number, y2: number, steps?: number): string;
-
-/** the BiDi input.performActions pointer half of a tap, at CSS pixels */
-export function buildPointerActions(x: number, y: number): BidiPointerAction[];
-
-/** everything a named key's press needs per protocol: DOM `code`, Windows VK, the typed character, the WebDriver key value; null for the unmapped */
-export function keyInfoOf(key: string): { code: string; vk: number; bidi: string; text?: string } | null;
-
-/** the CDP `Input.dispatchKeyEvent` pair one press is */
-export function cdpKeySequence(key: string): unknown[] | null;
-
-/** the BiDi `input.performActions` key sequence one press is, with the hold as a pause */
-export function bidiKeyActions(key: string, holdMs?: number): unknown[] | null;
-
-/**
- * The in-page synthetic pointer sequence a tap is, as page JS - the Firefox tap path,
- * because the BiDi pointer actions do not reach Pixi 8's canvas EventSystem (P41).
- */
-export function pageTapSource(x: number, y: number): string;
-
-/** unwraps a WebDriver BiDi remote value into plain JSON */
-export function unwrapRemoteValue(node: unknown): unknown;
-
-/** locates a browser executable without a driver install, or null when neither yields anything */
-export function findBrowser(kind: 'chrome' | 'firefox'): string | null;
-
-/** drives headless Chrome over CDP */
-export function driveChrome(options?: DriveOptions): Promise<BrowserDriver>;
-
-/** drives headless Firefox over WebDriver BiDi, with the same surface as driveChrome */
-export function driveFirefox(options?: DriveOptions): Promise<BrowserDriver>;
+export * from '@datamoc/mwg/tools/browser-driver';