@vibemancer/core 0.1.0

package/src/engine/sandbox-browser.ts

@@ -0,0 +1,671 @@
+/**
+ * VIBEMANCER — BROWSER SANDBOX
+ *
+ * Provides Web Worker-based sandboxing for bot code execution in the browser.
+ * Same compiled bundles as the isolated-vm sandbox (MatchSandbox), but runs
+ * in a Web Worker instead of a V8 isolate.
+ *
+ * Architecture:
+ * - Host: creates Worker from Blob URL, communicates via postMessage
+ * - Worker: loads compiled bundle (sets globalThis.__fight/__simulate),
+ *   dispatches fight/simulate calls, posts results back
+ *
+ * Safety:
+ * - Timeout via setTimeout + worker.terminate() catches infinite loops
+ * - No memory limit (browser manages worker memory; worst case = tab crash)
+ * - Prototype freeze prevents cross-bot sabotage (same banner as isolated-vm)
+ * - No Node.js APIs available in Web Workers
+ *
+ * NOTE: This file has ZERO Node.js dependencies. It works in any JS environment.
+ */
+
+import type {GameState, MissileAIFunction, ProjectileState, WizardActions} from '../types.js';
+import type {BotError, FightResult, MatchWinner, SimulateResult} from './simulation.js';
+import type {StepResult} from './manual-match.js';
+
+// ============================================================
+// WORKER PROTOCOL
+// ============================================================
+
+/**
+ * Minimal Worker interface for dependency injection.
+ * Matches the browser Worker API subset we need.
+ * For tests, a Node.js worker_threads adapter can implement this.
+ */
+export interface WorkerLike
+{
+	postMessage(data: unknown): void;
+	terminate(): void;
+	addEventListener(type: string, listener: (ev: unknown) => void): void;
+	removeEventListener(type: string, listener: (ev: unknown) => void): void;
+}
+
+/**
+ * Factory function that creates a WorkerLike from a JavaScript code string.
+ * Default: creates a browser Web Worker via Blob URL.
+ * Override in options.createWorker for testing with Node.js worker_threads.
+ */
+export type WorkerFactory = (code: string) => {worker: WorkerLike; cleanup?: () => void};
+
+/**
+ * Options for browser sandbox creation.
+ */
+export interface BrowserSandboxOptions
+{
+	/** Timeout in ms for fight/simulate calls (default: 30000). */
+	timeoutMs?: number;
+	/** Custom worker factory for dependency injection (testing). */
+	createWorker?: WorkerFactory;
+}
+
+// ============================================================
+// WORKER BOOTSTRAP
+// ============================================================
+
+/**
+ * JavaScript bootstrap code appended to the compiled bundle.
+ * Runs inside the worker after the IIFE sets up the relevant globals
+ * (e.g., __fight/__simulate for fight bundles, __manualMatchInit/Step/etc
+ * for manual-play bundles).
+ *
+ * The dispatcher is generic: any method name `foo` resolves to
+ * `globalThis.__foo`. This allows new bundle types to expose new method
+ * names without changing the bootstrap.
+ *
+ * Environment-adaptive: works in both browser Web Workers and
+ * Node.js worker_threads (for testing).
+ */
+const WORKER_BOOTSTRAP = `
+;(function() {
+	var _port = null;
+	try { _port = require('worker_threads').parentPort; } catch(e) {}
+
+	function send(data) {
+		if (_port) _port.postMessage(data);
+		else self.postMessage(data);
+	}
+
+	function listen(fn) {
+		if (_port) _port.on('message', fn);
+		else self.addEventListener('message', function(e) { fn(e.data); });
+	}
+
+	listen(function(data) {
+		if (data && data.method) {
+			try {
+				var fn = globalThis['__' + data.method];
+				if (typeof fn !== 'function') {
+					throw new Error('Unknown sandbox method: ' + data.method);
+				}
+				var result = fn(data.options);
+				send({id: data.id, result: result});
+			} catch(err) {
+				send({id: data.id, error: (err && err.message) || String(err)});
+			}
+		}
+	});
+
+	send({type: 'ready'});
+})();
+`;
+
+/**
+ * Create the full worker script from a compiled match bundle.
+ * Appends the message-handling bootstrap to the bundle IIFE.
+ */
+export function createWorkerScript(bundle: string): string
+{
+	return bundle + '\n' + WORKER_BOOTSTRAP;
+}
+
+// ============================================================
+// BROWSER MATCH SANDBOX
+// ============================================================
+
+interface PendingCall
+{
+	resolve: (value: unknown) => void;
+	reject: (error: Error) => void;
+	timer: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Browser-compatible sandboxed match runner using Web Workers.
+ *
+ * Same compiled bundles as MatchSandbox (isolated-vm), but runs in a
+ * Web Worker instead. All fight/simulate calls are async (postMessage-based).
+ *
+ * Usage:
+ * ```ts
+ * // Bundle is compiled server-side or at build time (Node.js only)
+ * const bundle = await MatchSandbox.compile(bot1, bot2);
+ *
+ * // Run in browser via Web Worker
+ * const sandbox = await BrowserMatchSandbox.fromBundle(bundle);
+ * const result = await sandbox.fight({ seed: 42 });
+ * sandbox.dispose();
+ * ```
+ */
+export class BrowserMatchSandbox
+{
+	private worker: WorkerLike;
+	private workerCleanup: (() => void) | undefined;
+	private timeout: number;
+	private disposed = false;
+	private nextId = 0;
+	private pending = new Map<number, PendingCall>();
+	private messageHandler: ((ev: unknown) => void) | null = null;
+	private errorHandler: ((ev: unknown) => void) | null = null;
+
+	private constructor(
+		worker: WorkerLike,
+		workerCleanup: (() => void) | undefined,
+		timeout: number,
+	)
+	{
+		this.worker = worker;
+		this.workerCleanup = workerCleanup;
+		this.timeout = timeout;
+	}
+
+	/**
+	 * Create a browser sandbox from a pre-compiled bundle string.
+	 * The bundle should be the output of MatchSandbox.compile() (or equivalent IIFE
+	 * that sets globalThis.__fight and globalThis.__simulate).
+	 */
+	static async fromBundle(
+		bundle: string,
+		options?: BrowserSandboxOptions,
+	): Promise<BrowserMatchSandbox>
+	{
+		const timeout = options?.timeoutMs ?? 30000;
+		const code = createWorkerScript(bundle);
+
+		let worker: WorkerLike;
+		let cleanup: (() => void) | undefined;
+
+		if (options?.createWorker)
+		{
+			const created = options.createWorker(code);
+			worker = created.worker;
+			cleanup = created.cleanup;
+		}
+		else
+		{
+			// Browser default: Blob URL Worker
+			// Uses globalThis to avoid TypeScript error in Node.js builds (no DOM lib)
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- runtime browser check
+			const BrowserWorker = (globalThis as Record<string, unknown>).Worker as
+				{new (url: string | URL): WorkerLike} | undefined;
+			if (!BrowserWorker)
+			{
+				throw new Error(
+					'Web Worker API not available. Pass a createWorker factory for Node.js usage.',
+				);
+			}
+			const blob = new Blob([code], {type: 'application/javascript'});
+			const blobUrl = URL.createObjectURL(blob);
+			cleanup = (): void => URL.revokeObjectURL(blobUrl);
+			worker = new BrowserWorker(blobUrl);
+		}
+
+		const sandbox = new BrowserMatchSandbox(worker, cleanup, timeout);
+
+		try
+		{
+			await sandbox.waitForReady(timeout);
+		}
+		catch(error)
+		{
+			sandbox.dispose();
+			throw error;
+		}
+
+		return sandbox;
+	}
+
+	/**
+	 * Wait for the worker to post {type: 'ready'}, then attach permanent handlers.
+	 */
+	private waitForReady(timeout: number): Promise<void>
+	{
+		return new Promise<void>((resolve, reject) =>
+		{
+			const timer = setTimeout(() =>
+			{
+				reject(new Error('Worker initialization timed out'));
+			}, timeout);
+
+			const readyListener = (ev: unknown): void =>
+			{
+				// Unwrap MessageEvent (browser) or raw data (Node.js adapter)
+				const data = this.unwrapEvent(ev);
+				if (data && typeof data === 'object' && 'type' in data && data.type === 'ready')
+				{
+					clearTimeout(timer);
+					this.worker.removeEventListener('message', readyListener);
+					this.attachHandlers();
+					resolve();
+				}
+			};
+
+			this.worker.addEventListener('message', readyListener);
+		});
+	}
+
+	/**
+	 * Extract message data from a browser MessageEvent or raw Node.js data.
+	 */
+	private unwrapEvent(ev: unknown): Record<string, unknown> | null
+	{
+		if (ev == null) return null;
+		if (typeof ev !== 'object') return null;
+
+		// Browser MessageEvent has .data
+		const maybeEvent = ev as {data?: unknown};
+		const raw = maybeEvent.data !== undefined ? maybeEvent.data : ev;
+
+		if (raw != null && typeof raw === 'object')
+		{
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- runtime type-checked above
+			return raw as Record<string, unknown>;
+		}
+		return null;
+	}
+
+	/**
+	 * Attach permanent message and error handlers for fight/simulate responses.
+	 */
+	private attachHandlers(): void
+	{
+		this.messageHandler = (ev: unknown): void =>
+		{
+			const data = this.unwrapEvent(ev);
+			if (!data || data.id == null) return;
+
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- id is always a number from our protocol
+			const id = data.id as number;
+			const handler = this.pending.get(id);
+			if (!handler) return;
+
+			clearTimeout(handler.timer);
+			this.pending.delete(id);
+
+			if (data.error)
+			{
+				handler.reject(new Error(String(data.error)));
+			}
+			else
+			{
+				handler.resolve(data.result);
+			}
+		};
+
+		this.errorHandler = (ev: unknown): void =>
+		{
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- ErrorEvent shape from Worker
+			const message = (ev as {message?: string}).message ?? 'Worker error';
+			// Reject all pending calls
+			for (const [, handler] of this.pending)
+			{
+				clearTimeout(handler.timer);
+				handler.reject(new Error(message));
+			}
+			this.pending.clear();
+		};
+
+		this.worker.addEventListener('message', this.messageHandler);
+		this.worker.addEventListener('error', this.errorHandler);
+	}
+
+	// ============================================================
+	// PUBLIC API
+	// ============================================================
+
+	/**
+	 * Run a full fight (10 matches: 5 spawn distances x 2 sides).
+	 * Returns a Promise because Worker communication is async.
+	 */
+	async fight(options?: {seed?: number; maxTicks?: number}): Promise<FightResult>
+	{
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- worker returns FightResult shape
+		return this.call('fight', options ?? {}) as Promise<FightResult>;
+	}
+
+	/**
+	 * Run a single simulation. Returns a Promise.
+	 *
+	 * @param options.params1 - useParam overrides for bot 1 (wizard-1)
+	 * @param options.params2 - useParam overrides for bot 2 (wizard-2)
+	 */
+	async simulate(options?: {
+		seed?: number;
+		maxTicks?: number;
+		spawnDistance?: number;
+		skipHistory?: boolean;
+		params1?: Record<string, number>;
+		params2?: Record<string, number>;
+	}): Promise<SimulateResult>
+	{
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- worker returns SimulateResult shape
+		return this.call('simulate', options ?? {}) as Promise<SimulateResult>;
+	}
+
+	/**
+	 * Dispose the worker and free all resources.
+	 * The sandbox cannot be used after disposal.
+	 */
+	dispose(): void
+	{
+		if (!this.disposed)
+		{
+			this.disposed = true;
+
+			// Reject all pending calls
+			for (const [, handler] of this.pending)
+			{
+				clearTimeout(handler.timer);
+				handler.reject(new Error('BrowserMatchSandbox has been disposed'));
+			}
+			this.pending.clear();
+
+			// Remove event listeners
+			if (this.messageHandler)
+			{
+				this.worker.removeEventListener('message', this.messageHandler);
+			}
+			if (this.errorHandler)
+			{
+				this.worker.removeEventListener('error', this.errorHandler);
+			}
+
+			// Terminate worker
+			this.worker.terminate();
+
+			// Clean up Blob URL (or other resources)
+			this.workerCleanup?.();
+		}
+	}
+
+	/**
+	 * Whether this sandbox has been disposed.
+	 */
+	get isDisposed(): boolean
+	{
+		return this.disposed;
+	}
+
+	// ============================================================
+	// INTERNAL
+	// ============================================================
+
+	/**
+	 * Send a generic method call to the worker. Used by sibling sandboxes
+	 * (e.g. BrowserManualMatchSandbox) that need to dispatch to method
+	 * names other than fight/simulate. The worker bootstrap looks up
+	 * `globalThis['__' + method]` and calls it with `options`.
+	 */
+	callRaw(method: string, options: unknown): Promise<unknown>
+	{
+		return this.call(method, options);
+	}
+
+	/**
+	 * Send a method call to the worker and wait for the response.
+	 * Times out and terminates the worker if no response within timeout.
+	 */
+	private call(method: string, options: unknown): Promise<unknown>
+	{
+		this.ensureNotDisposed();
+		const id = this.nextId++;
+
+		return new Promise((resolve, reject) =>
+		{
+			const timer = setTimeout(() =>
+			{
+				this.pending.delete(id);
+				// Worker is stuck — terminate and clean up all resources
+				this.worker.terminate();
+				this.workerCleanup?.();
+				this.disposed = true;
+				reject(new Error(`BrowserMatchSandbox timed out after ${this.timeout}ms`));
+			}, this.timeout);
+
+			this.pending.set(id, {resolve, reject, timer});
+			this.worker.postMessage({id, method, options});
+		});
+	}
+
+	private ensureNotDisposed(): void
+	{
+		if (this.disposed)
+		{
+			throw new Error('BrowserMatchSandbox has been disposed');
+		}
+	}
+}
+
+// ============================================================
+// CONVENIENCE FUNCTIONS
+// ============================================================
+
+/**
+ * One-shot browser-sandboxed fight. Creates worker, runs fight, disposes.
+ */
+export async function browserSandboxFight(
+	bundle: string,
+	options?: {seed?: number; maxTicks?: number} & BrowserSandboxOptions,
+): Promise<FightResult>
+{
+	const sandbox = await BrowserMatchSandbox.fromBundle(bundle, options);
+	try
+	{
+		return await sandbox.fight({seed: options?.seed, maxTicks: options?.maxTicks});
+	}
+	finally
+	{
+		sandbox.dispose();
+	}
+}
+
+/**
+ * One-shot browser-sandboxed simulate. Creates worker, runs simulate, disposes.
+ */
+export async function browserSandboxSimulate(
+	bundle: string,
+	options?: {
+		seed?: number;
+		maxTicks?: number;
+		spawnDistance?: number;
+		skipHistory?: boolean;
+		params1?: Record<string, number>;
+		params2?: Record<string, number>;
+	} & BrowserSandboxOptions,
+): Promise<SimulateResult>
+{
+	const sandbox = await BrowserMatchSandbox.fromBundle(bundle, options);
+	try
+	{
+		return await sandbox.simulate({
+			seed: options?.seed,
+			maxTicks: options?.maxTicks,
+			spawnDistance: options?.spawnDistance,
+			skipHistory: options?.skipHistory,
+			params1: options?.params1,
+			params2: options?.params2,
+		});
+	}
+	finally
+	{
+		sandbox.dispose();
+	}
+}
+
+// ============================================================
+// BROWSER MANUAL-MATCH SANDBOX
+// ============================================================
+
+/**
+ * Options accepted by `__manualMatchInit` (worker-side). Mirrors
+ * `ManualMatchOptions` from manual-match.ts, but without the constructor's
+ * AI parameters since the player AI is a worker-local stub.
+ */
+export interface ManualMatchInitOptions
+{
+	seed?: number;
+	spawnDistance?: number;
+	maxTicks?: number;
+	initialHumanActions?: WizardActions;
+}
+
+export interface ManualMatchStepRequest
+{
+	humanActions?: WizardActions;
+	humanMissileTargets?: Record<string, {x: number; y: number}>;
+	count?: number;
+}
+
+/**
+ * Long-lived Web Worker sandbox holding a single ManualMatch instance.
+ *
+ * Unlike BrowserMatchSandbox (which runs one batched fight/simulate per
+ * worker), BrowserManualMatchSandbox keeps the worker alive across many
+ * step calls so the engine state and hook state persist between ticks.
+ * This is what manual play mode uses: one worker per session, disposed
+ * when the user leaves the page or starts a new match.
+ *
+ * Usage:
+ * ```ts
+ * const sandbox = await BrowserManualMatchSandbox.fromBundle(opponentBundle);
+ * await sandbox.init({seed: 42});
+ * for (let i = 0; i < 100; i++) {
+ *   await sandbox.step({humanActions: {move: {x: 100, y: 0}}, count: 1});
+ * }
+ * await sandbox.dispose();
+ * ```
+ */
+export class BrowserManualMatchSandbox
+{
+	private readonly inner: BrowserMatchSandbox;
+
+	private constructor(inner: BrowserMatchSandbox)
+	{
+		this.inner = inner;
+	}
+
+	/**
+	 * Create a manual-match sandbox from a pre-compiled bundle. The bundle
+	 * must be the output of `compileManualMatchBundle()` — the regular
+	 * `compileMatchBundle()` output won't work since it doesn't expose the
+	 * `__manualMatch*` globals.
+	 */
+	static async fromBundle(
+		bundle: string,
+		options?: BrowserSandboxOptions,
+	): Promise<BrowserManualMatchSandbox>
+	{
+		const inner = await BrowserMatchSandbox.fromBundle(bundle, options);
+		return new BrowserManualMatchSandbox(inner);
+	}
+
+	/**
+	 * Initialize the worker-side ManualMatch instance.
+	 * Returns the initial GameState (tick 0).
+	 */
+	async init(options?: ManualMatchInitOptions): Promise<GameState>
+	{
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- worker returns GameState shape
+		return this.inner.callRaw('manualMatchInit', options ?? {}) as Promise<GameState>;
+	}
+
+	/**
+	 * Advance the match by `request.count` ticks (default 1), updating
+	 * the player's human actions and any hijacked missile targets first.
+	 */
+	async step(request: ManualMatchStepRequest = {}): Promise<StepResult>
+	{
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- worker returns StepResult shape
+		return this.inner.callRaw('manualMatchStep', request) as Promise<StepResult>;
+	}
+
+	/**
+	 * Replace a missile's AI with a worker-local hijack stub that reads
+	 * from `latestHumanMissileTargets[projectileId]`. Subsequent step()
+	 * calls with `humanMissileTargets` populated for this id steer the
+	 * missile.
+	 */
+	async hijackMissile(projectileId: string): Promise<void>
+	{
+		await this.inner.callRaw('manualMatchHijack', {projectileId});
+	}
+
+	/**
+	 * Restore a hijacked missile's original AI.
+	 */
+	async releaseMissile(projectileId: string): Promise<void>
+	{
+		await this.inner.callRaw('manualMatchRelease', {projectileId});
+	}
+
+	/**
+	 * Toggle invincibility for a wizard.
+	 */
+	async setInvincible(wizardIndex: 0 | 1, on: boolean): Promise<void>
+	{
+		await this.inner.callRaw('manualMatchSetInvincible', {wizardIndex, on});
+	}
+
+	/**
+	 * Get the current game state without advancing.
+	 */
+	async getState(): Promise<GameState>
+	{
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- worker returns GameState shape
+		return this.inner.callRaw('manualMatchGetState', {}) as Promise<GameState>;
+	}
+
+	/**
+	 * Get the full SimulateResult-compatible result object (history + winner).
+	 */
+	async getResult(): Promise<SimulateResult>
+	{
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- worker returns SimulateResult shape
+		return this.inner.callRaw('manualMatchGetResult', {}) as Promise<SimulateResult>;
+	}
+
+	/**
+	 * Dispose the worker-side ManualMatch instance. Does NOT terminate the
+	 * worker — call dispose() for that.
+	 */
+	async resetMatch(): Promise<void>
+	{
+		await this.inner.callRaw('manualMatchDispose', {});
+	}
+
+	/**
+	 * Terminate the worker and free all resources.
+	 */
+	dispose(): void
+	{
+		this.inner.dispose();
+	}
+
+	get isDisposed(): boolean
+	{
+		return this.inner.isDisposed;
+	}
+}
+
+/**
+ * Re-import-friendly types (re-exported here so consumers don't need to
+ * cherry-pick from internal modules).
+ */
+export type {
+	BotError,
+	GameState,
+	MatchWinner,
+	MissileAIFunction,
+	ProjectileState,
+	StepResult,
+	WizardActions,
+};