@vibemancer/core 0.1.0 → 0.1.1

package/src/engine/hooks-runtime.ts

@@ -1,394 +1,394 @@
-/**
- * VIBEMANCER - HOOKS RUNTIME
- *
- * This file implements a minimal React-like hooks runtime for AI programming.
- * It supports useState, useEffect, useMemo, useRef, and useParam with entity isolation.
- *
- * RULES OF HOOKS (same as React):
- * - Hooks must be called at the top level of the bot function
- * - Hooks must be called in the same order every tick
- * - Hooks must NOT be called conditionally
- *
- * Violating these rules throws an error (detected via hook index validation).
- */
-
-import type {BotContext} from '../hooks/types.js';
-
-export interface HookState
-{
-	values: unknown[];
-	effects: {
-		callback: () => void | (() => void);
-		deps?: unknown[];
-		cleanup?: () => void;
-	}[];
-	memos: {
-		value: unknown;
-		deps?: unknown[];
-	}[];
-	/** Type of each hook call in order (for validation). */
-	hookTypes: string[];
-	/** Total hooks called on first successful tick. */
-	hookCount: number;
-	/** Whether the first tick has completed successfully (hook pattern established). */
-	initialized: boolean;
-}
-
-// Use globalThis for hooks state so that multiple copies of the hooks runtime
-// (e.g., engine template + bot bundle in sandboxed execution) share the same state.
-// Without this, bot bundles that inline their own copy of the hooks runtime would
-// have separate currentEntityId etc., causing "useParam can only be used inside
-// a bot function" errors.
-const _g = globalThis as Record<string, unknown>;
-// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- we own __vibemancer_entityHooks
-const entityHooks: Map<string, HookState> = (_g.__vibemancer_entityHooks as Map<string, HookState>)
-	?? (_g.__vibemancer_entityHooks = new Map<string, HookState>());
-
-// Accessor functions for shared mutable state on globalThis
-function _getCurrentEntityId(): string | null
-{
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- we own __vibemancer_currentEntityId
-	return (_g.__vibemancer_currentEntityId as string | null) ?? null;
-}
-function _setCurrentEntityId(id: string | null): void
-{
-	_g.__vibemancer_currentEntityId = id;
-}
-function _getCurrentHookIndex(): number
-{
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- we own __vibemancer_currentHookIndex
-	return (_g.__vibemancer_currentHookIndex as number) ?? 0;
-}
-function _setCurrentHookIndex(idx: number): void
-{
-	_g.__vibemancer_currentHookIndex = idx;
-}
-function _getCurrentBotContext(): BotContext | null
-{
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- we own __vibemancer_currentBotContext
-	return (_g.__vibemancer_currentBotContext as BotContext | null) ?? null;
-}
-function _setCurrentBotContext(ctx: BotContext | null): void
-{
-	_g.__vibemancer_currentBotContext = ctx;
-}
-
-/**
- * Get or create the hook state for an entity.
- */
-function getHookState(entityId: string): HookState
-{
-	let state = entityHooks.get(entityId);
-	if (!state)
-	{
-		state = {
-			values: [],
-			effects: [],
-			memos: [],
-			hookTypes: [],
-			hookCount: 0,
-			initialized: false,
-		};
-		entityHooks.set(entityId, state);
-	}
-	return state;
-}
-
-/**
- * Validate a hook call and return its sequential index.
- * Ensures hooks are called in the same order every tick.
- *
- * On the first tick: records the hook type at this index.
- * On subsequent ticks: validates the hook type matches.
- *
- * @param type - The hook type name (e.g., 'useState', 'useEffect', 'useParam')
- * @returns The sequential hook index
- * @throws If called outside runWithHooks or if hook order changed
- */
-export function validateHookCall(type: string): number
-{
-	if (!_getCurrentEntityId())
-	{
-		throw new Error(`${type} can only be used inside a bot function (runWithHooks)`);
-	}
-
-	const state = getHookState(_getCurrentEntityId()!);
-	const index = _getCurrentHookIndex();
-	_setCurrentHookIndex(index + 1);
-
-	if (state.initialized)
-	{
-		// Validate: not more hooks than first tick
-		if (index >= state.hookCount)
-		{
-			throw new Error(
-				`Hook "${type}" called at index ${index}, but only ${state.hookCount} hooks were registered on the first tick. ` +
-				'This likely means a hook was called conditionally. Hooks must be called in the same order every tick.',
-			);
-		}
-		// Validate: same hook type at this index
-		if (state.hookTypes[index] !== type)
-		{
-			throw new Error(
-				`Hook order changed at index ${index}: expected "${state.hookTypes[index]}", got "${type}". ` +
-				'Hooks must be called in the same order every tick.',
-			);
-		}
-	}
-	else
-	{
-		// First tick: record hook type
-		state.hookTypes[index] = type;
-	}
-
-	return index;
-}
-
-/**
- * Finalize hook count after a successful tick.
- * On first tick: establishes the hook pattern.
- * On subsequent ticks: validates the count matches.
- */
-function finalizeHookCount(entityId: string): void
-{
-	const state = entityHooks.get(entityId);
-	if (!state) return;
-
-	if (state.initialized)
-	{
-		if (_getCurrentHookIndex() < state.hookCount)
-		{
-			throw new Error(
-				`Fewer hooks were called (${_getCurrentHookIndex()}) than on the first tick (${state.hookCount}). ` +
-				'This likely means a hook was called conditionally. Hooks must be called in the same order every tick.',
-			);
-		}
-	}
-	else
-	{
-		state.hookCount = _getCurrentHookIndex();
-		state.initialized = true;
-	}
-}
-
-/**
- * Run a function with a specific entity's hook context.
- */
-export function runWithHooks<T>(entityId: string, fn: () => T): T
-{
-	const previousEntityId = _getCurrentEntityId();
-	const previousHookIndex = _getCurrentHookIndex();
-
-	_setCurrentEntityId(entityId);
-	_setCurrentHookIndex(0);
-
-	// If the first tick failed, reset hook type tracking so next attempt starts clean
-	const state = entityHooks.get(entityId);
-	if (state && !state.initialized)
-	{
-		state.hookTypes.length = 0;
-	}
-
-	try
-	{
-		const result = fn();
-		finalizeHookCount(entityId);
-		return result;
-	}
-	finally
-	{
-		_setCurrentEntityId(previousEntityId);
-		_setCurrentHookIndex(previousHookIndex);
-	}
-}
-
-/**
- * Run a bot function with full context (game state + persistence hooks).
- * Use this when you need to set BOTH the entity ID and the game context.
- */
-export function runBotWithContext<T>(entityId: string, context: BotContext, fn: () => T): T
-{
-	const previousContext = _getCurrentBotContext();
-	_setCurrentBotContext(context);
-
-	try
-	{
-		return runWithHooks(entityId, fn);
-	}
-	finally
-	{
-		_setCurrentBotContext(previousContext);
-	}
-}
-
-/**
- * Run a function with game state context only, preserving the current entity ID.
- * Use this inside wrapNewBot where the entity ID is already set by the outer runWithHooks.
- */
-export function withBotContext<T>(context: BotContext, fn: () => T): T
-{
-	const previousContext = _getCurrentBotContext();
-	_setCurrentBotContext(context);
-
-	try
-	{
-		return fn();
-	}
-	finally
-	{
-		_setCurrentBotContext(previousContext);
-	}
-}
-
-/**
- * Get the current bot context. Throws if called outside bot execution.
- */
-export function getBotContext(): BotContext
-{
-	if (!_getCurrentBotContext())
-	{
-		throw new Error('Game state hooks can only be used inside a bot function');
-	}
-	return _getCurrentBotContext()!;
-}
-
-/**
- * Persist state between ticks.
- */
-export function useState<T>(initialValue: T | (() => T)): [T, (newValue: T | ((prev: T) => T)) => void]
-{
-	const index = validateHookCall('useState');
-	const state = getHookState(_getCurrentEntityId()!);
-
-	if (state.values.length <= index)
-	{
-		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-		state.values[index] = (typeof initialValue === 'function') ? (initialValue as () => T)() : initialValue;
-	}
-
-	const setter = (newValue: T | ((prev: T) => T)): void =>
-	{
-		if (typeof newValue === 'function')
-		{
-			// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-			state.values[index] = (newValue as (prev: T) => T)(state.values[index] as T);
-		}
-		else
-		{
-			state.values[index] = newValue;
-		}
-	};
-
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-	return [state.values[index] as T, setter];
-}
-
-/**
- * React to state changes.
- */
-export function useEffect(callback: () => void | (() => void), deps?: unknown[]): void
-{
-	const index = validateHookCall('useEffect');
-	const state = getHookState(_getCurrentEntityId()!);
-
-	const oldEffect = state.effects[index];
-	const hasChanged = !oldEffect || !deps ||
-		deps.length !== oldEffect.deps?.length ||
-		!deps.every((dep, i) => dep === oldEffect.deps?.[i]);
-
-	if (hasChanged)
-	{
-		// Cleanup old effect if it exists
-		if (oldEffect?.cleanup)
-		{
-			oldEffect.cleanup();
-		}
-
-		// Run new effect
-		const cleanup = callback();
-		state.effects[index] = {
-			callback,
-			deps,
-			cleanup: typeof cleanup === 'function' ? cleanup : undefined,
-		};
-	}
-}
-
-/**
- * Memoize expensive calculations.
- */
-export function useMemo<T>(factory: () => T, deps?: unknown[]): T
-{
-	const index = validateHookCall('useMemo');
-	const state = getHookState(_getCurrentEntityId()!);
-
-	const oldMemo = state.memos[index];
-	const hasChanged = !oldMemo || !deps ||
-		deps.length !== oldMemo.deps?.length ||
-		!deps.every((dep, i) => dep === oldMemo.deps?.[i]);
-
-	if (hasChanged)
-	{
-		const value = factory();
-		state.memos[index] = {
-			value,
-			deps,
-		};
-		return value;
-	}
-
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-	return oldMemo.value as T;
-}
-
-/**
- * Mutable reference that persists across ticks.
- * Unlike useState, mutations don't need a setter - just modify .current directly.
- */
-export interface RefObject<T>
-{
-	current: T;
-}
-
-export function useRef<T>(initialValue: T): RefObject<T>
-{
-	const index = validateHookCall('useRef');
-	const state = getHookState(_getCurrentEntityId()!);
-
-	if (state.values.length <= index)
-	{
-		state.values[index] = {current: initialValue};
-	}
-
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-	return state.values[index] as RefObject<T>;
-}
-
-/**
- * Clear hook state for an entity (e.g., when it dies).
- */
-export function clearHooks(entityId: string): void
-{
-	const state = entityHooks.get(entityId);
-	if (state)
-	{
-		state.effects.forEach((effect) =>
-		{
-			if (effect.cleanup)
-			{
-				effect.cleanup();
-			}
-		});
-		entityHooks.delete(entityId);
-	}
-}
-
-/**
- * Reset all hook states (e.g., when a match restarts).
- */
-export function resetAllHooks(): void
-{
-	entityHooks.forEach((_, entityId) => clearHooks(entityId));
-	entityHooks.clear();
-}
-
+/**
+ * VIBEMANCER - HOOKS RUNTIME
+ *
+ * This file implements a minimal React-like hooks runtime for AI programming.
+ * It supports useState, useEffect, useMemo, useRef, and useParam with entity isolation.
+ *
+ * RULES OF HOOKS (same as React):
+ * - Hooks must be called at the top level of the bot function
+ * - Hooks must be called in the same order every tick
+ * - Hooks must NOT be called conditionally
+ *
+ * Violating these rules throws an error (detected via hook index validation).
+ */
+
+import type {BotContext} from '../hooks/types.js';
+
+export interface HookState
+{
+	values: unknown[];
+	effects: {
+		callback: () => void | (() => void);
+		deps?: unknown[];
+		cleanup?: () => void;
+	}[];
+	memos: {
+		value: unknown;
+		deps?: unknown[];
+	}[];
+	/** Type of each hook call in order (for validation). */
+	hookTypes: string[];
+	/** Total hooks called on first successful tick. */
+	hookCount: number;
+	/** Whether the first tick has completed successfully (hook pattern established). */
+	initialized: boolean;
+}
+
+// Use globalThis for hooks state so that multiple copies of the hooks runtime
+// (e.g., engine template + bot bundle in sandboxed execution) share the same state.
+// Without this, bot bundles that inline their own copy of the hooks runtime would
+// have separate currentEntityId etc., causing "useParam can only be used inside
+// a bot function" errors.
+const _g = globalThis as Record<string, unknown>;
+// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- we own __vibemancer_entityHooks
+const entityHooks: Map<string, HookState> = (_g.__vibemancer_entityHooks as Map<string, HookState>)
+	?? (_g.__vibemancer_entityHooks = new Map<string, HookState>());
+
+// Accessor functions for shared mutable state on globalThis
+function _getCurrentEntityId(): string | null
+{
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- we own __vibemancer_currentEntityId
+	return (_g.__vibemancer_currentEntityId as string | null) ?? null;
+}
+function _setCurrentEntityId(id: string | null): void
+{
+	_g.__vibemancer_currentEntityId = id;
+}
+function _getCurrentHookIndex(): number
+{
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- we own __vibemancer_currentHookIndex
+	return (_g.__vibemancer_currentHookIndex as number) ?? 0;
+}
+function _setCurrentHookIndex(idx: number): void
+{
+	_g.__vibemancer_currentHookIndex = idx;
+}
+function _getCurrentBotContext(): BotContext | null
+{
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- we own __vibemancer_currentBotContext
+	return (_g.__vibemancer_currentBotContext as BotContext | null) ?? null;
+}
+function _setCurrentBotContext(ctx: BotContext | null): void
+{
+	_g.__vibemancer_currentBotContext = ctx;
+}
+
+/**
+ * Get or create the hook state for an entity.
+ */
+function getHookState(entityId: string): HookState
+{
+	let state = entityHooks.get(entityId);
+	if (!state)
+	{
+		state = {
+			values: [],
+			effects: [],
+			memos: [],
+			hookTypes: [],
+			hookCount: 0,
+			initialized: false,
+		};
+		entityHooks.set(entityId, state);
+	}
+	return state;
+}
+
+/**
+ * Validate a hook call and return its sequential index.
+ * Ensures hooks are called in the same order every tick.
+ *
+ * On the first tick: records the hook type at this index.
+ * On subsequent ticks: validates the hook type matches.
+ *
+ * @param type - The hook type name (e.g., 'useState', 'useEffect', 'useParam')
+ * @returns The sequential hook index
+ * @throws If called outside runWithHooks or if hook order changed
+ */
+export function validateHookCall(type: string): number
+{
+	if (!_getCurrentEntityId())
+	{
+		throw new Error(`${type} can only be used inside a bot function (runWithHooks)`);
+	}
+
+	const state = getHookState(_getCurrentEntityId()!);
+	const index = _getCurrentHookIndex();
+	_setCurrentHookIndex(index + 1);
+
+	if (state.initialized)
+	{
+		// Validate: not more hooks than first tick
+		if (index >= state.hookCount)
+		{
+			throw new Error(
+				`Hook "${type}" called at index ${index}, but only ${state.hookCount} hooks were registered on the first tick. ` +
+				'This likely means a hook was called conditionally. Hooks must be called in the same order every tick.',
+			);
+		}
+		// Validate: same hook type at this index
+		if (state.hookTypes[index] !== type)
+		{
+			throw new Error(
+				`Hook order changed at index ${index}: expected "${state.hookTypes[index]}", got "${type}". ` +
+				'Hooks must be called in the same order every tick.',
+			);
+		}
+	}
+	else
+	{
+		// First tick: record hook type
+		state.hookTypes[index] = type;
+	}
+
+	return index;
+}
+
+/**
+ * Finalize hook count after a successful tick.
+ * On first tick: establishes the hook pattern.
+ * On subsequent ticks: validates the count matches.
+ */
+function finalizeHookCount(entityId: string): void
+{
+	const state = entityHooks.get(entityId);
+	if (!state) return;
+
+	if (state.initialized)
+	{
+		if (_getCurrentHookIndex() < state.hookCount)
+		{
+			throw new Error(
+				`Fewer hooks were called (${_getCurrentHookIndex()}) than on the first tick (${state.hookCount}). ` +
+				'This likely means a hook was called conditionally. Hooks must be called in the same order every tick.',
+			);
+		}
+	}
+	else
+	{
+		state.hookCount = _getCurrentHookIndex();
+		state.initialized = true;
+	}
+}
+
+/**
+ * Run a function with a specific entity's hook context.
+ */
+export function runWithHooks<T>(entityId: string, fn: () => T): T
+{
+	const previousEntityId = _getCurrentEntityId();
+	const previousHookIndex = _getCurrentHookIndex();
+
+	_setCurrentEntityId(entityId);
+	_setCurrentHookIndex(0);
+
+	// If the first tick failed, reset hook type tracking so next attempt starts clean
+	const state = entityHooks.get(entityId);
+	if (state && !state.initialized)
+	{
+		state.hookTypes.length = 0;
+	}
+
+	try
+	{
+		const result = fn();
+		finalizeHookCount(entityId);
+		return result;
+	}
+	finally
+	{
+		_setCurrentEntityId(previousEntityId);
+		_setCurrentHookIndex(previousHookIndex);
+	}
+}
+
+/**
+ * Run a bot function with full context (game state + persistence hooks).
+ * Use this when you need to set BOTH the entity ID and the game context.
+ */
+export function runBotWithContext<T>(entityId: string, context: BotContext, fn: () => T): T
+{
+	const previousContext = _getCurrentBotContext();
+	_setCurrentBotContext(context);
+
+	try
+	{
+		return runWithHooks(entityId, fn);
+	}
+	finally
+	{
+		_setCurrentBotContext(previousContext);
+	}
+}
+
+/**
+ * Run a function with game state context only, preserving the current entity ID.
+ * Use this inside wrapNewBot where the entity ID is already set by the outer runWithHooks.
+ */
+export function withBotContext<T>(context: BotContext, fn: () => T): T
+{
+	const previousContext = _getCurrentBotContext();
+	_setCurrentBotContext(context);
+
+	try
+	{
+		return fn();
+	}
+	finally
+	{
+		_setCurrentBotContext(previousContext);
+	}
+}
+
+/**
+ * Get the current bot context. Throws if called outside bot execution.
+ */
+export function getBotContext(): BotContext
+{
+	if (!_getCurrentBotContext())
+	{
+		throw new Error('Game state hooks can only be used inside a bot function');
+	}
+	return _getCurrentBotContext()!;
+}
+
+/**
+ * Persist state between ticks.
+ */
+export function useState<T>(initialValue: T | (() => T)): [T, (newValue: T | ((prev: T) => T)) => void]
+{
+	const index = validateHookCall('useState');
+	const state = getHookState(_getCurrentEntityId()!);
+
+	if (state.values.length <= index)
+	{
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+		state.values[index] = (typeof initialValue === 'function') ? (initialValue as () => T)() : initialValue;
+	}
+
+	const setter = (newValue: T | ((prev: T) => T)): void =>
+	{
+		if (typeof newValue === 'function')
+		{
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+			state.values[index] = (newValue as (prev: T) => T)(state.values[index] as T);
+		}
+		else
+		{
+			state.values[index] = newValue;
+		}
+	};
+
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+	return [state.values[index] as T, setter];
+}
+
+/**
+ * React to state changes.
+ */
+export function useEffect(callback: () => void | (() => void), deps?: unknown[]): void
+{
+	const index = validateHookCall('useEffect');
+	const state = getHookState(_getCurrentEntityId()!);
+
+	const oldEffect = state.effects[index];
+	const hasChanged = !oldEffect || !deps ||
+		deps.length !== oldEffect.deps?.length ||
+		!deps.every((dep, i) => dep === oldEffect.deps?.[i]);
+
+	if (hasChanged)
+	{
+		// Cleanup old effect if it exists
+		if (oldEffect?.cleanup)
+		{
+			oldEffect.cleanup();
+		}
+
+		// Run new effect
+		const cleanup = callback();
+		state.effects[index] = {
+			callback,
+			deps,
+			cleanup: typeof cleanup === 'function' ? cleanup : undefined,
+		};
+	}
+}
+
+/**
+ * Memoize expensive calculations.
+ */
+export function useMemo<T>(factory: () => T, deps?: unknown[]): T
+{
+	const index = validateHookCall('useMemo');
+	const state = getHookState(_getCurrentEntityId()!);
+
+	const oldMemo = state.memos[index];
+	const hasChanged = !oldMemo || !deps ||
+		deps.length !== oldMemo.deps?.length ||
+		!deps.every((dep, i) => dep === oldMemo.deps?.[i]);
+
+	if (hasChanged)
+	{
+		const value = factory();
+		state.memos[index] = {
+			value,
+			deps,
+		};
+		return value;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+	return oldMemo.value as T;
+}
+
+/**
+ * Mutable reference that persists across ticks.
+ * Unlike useState, mutations don't need a setter - just modify .current directly.
+ */
+export interface RefObject<T>
+{
+	current: T;
+}
+
+export function useRef<T>(initialValue: T): RefObject<T>
+{
+	const index = validateHookCall('useRef');
+	const state = getHookState(_getCurrentEntityId()!);
+
+	if (state.values.length <= index)
+	{
+		state.values[index] = {current: initialValue};
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+	return state.values[index] as RefObject<T>;
+}
+
+/**
+ * Clear hook state for an entity (e.g., when it dies).
+ */
+export function clearHooks(entityId: string): void
+{
+	const state = entityHooks.get(entityId);
+	if (state)
+	{
+		state.effects.forEach((effect) =>
+		{
+			if (effect.cleanup)
+			{
+				effect.cleanup();
+			}
+		});
+		entityHooks.delete(entityId);
+	}
+}
+
+/**
+ * Reset all hook states (e.g., when a match restarts).
+ */
+export function resetAllHooks(): void
+{
+	entityHooks.forEach((_, entityId) => clearHooks(entityId));
+	entityHooks.clear();
+}
+