@vibemancer/core 0.1.0

package/dist/index-browser.d.ts

@@ -0,0 +1,2602 @@
+/**
+ * VIBEMANCER - TYPES
+ *
+ * This file contains all the TypeScript interfaces used by the game engine.
+ */
+/**
+ * Position in 2D space.
+ */
+interface Position {
+    x: number;
+    y: number;
+}
+/**
+ * Velocity in 2D space (units per tick).
+ */
+interface Velocity {
+    x: number;
+    y: number;
+}
+/**
+ * Wizard state.
+ */
+interface WizardState {
+    id: string;
+    position: Position;
+    rotation: number;
+    health: number;
+    maxHealth: number;
+    state: 'idle' | 'casting' | 'channeling' | 'gcd_locked';
+    castingSpell?: 'missile' | 'shield' | 'blink';
+    castProgress?: number;
+    castDuration?: number;
+    channelingSpell?: 'shield';
+    channelDuration?: number;
+    gcdRemaining?: number;
+    blinkCooldown: number;
+    velocity: Velocity;
+    lastMissileConfig?: MissileConfig;
+    warmupMultiplier?: number;
+    invincible?: boolean;
+}
+/**
+ * Projectile (missile) state.
+ */
+interface ProjectileState {
+    id: string;
+    type: 'missile';
+    ownerId: string;
+    position: Position;
+    rotation: number;
+    speed: number;
+    turnRate: number;
+    damage: number;
+    remainingTicks: number;
+}
+/**
+ * Game configuration (read-only).
+ */
+interface GameConfig {
+    arenaSize: {
+        width: number;
+        height: number;
+    };
+    tickRate: number;
+    maxTicks: number;
+}
+/**
+ * Full game state passed to wizard.
+ */
+interface GameState {
+    tick: number;
+    position: Position;
+    rotation: number;
+    health: number;
+    maxHealth: number;
+    state: WizardState['state'];
+    castingSpell?: 'missile' | 'shield' | 'blink';
+    castProgress?: number;
+    castDuration?: number;
+    channelingSpell?: 'shield';
+    channelDuration?: number;
+    gcdRemaining?: number;
+    blinkCooldown: number;
+    velocity: Velocity;
+    lastMissileConfig?: MissileConfig;
+    warmupMultiplier?: number;
+    enemies: WizardState[];
+    projectiles: ProjectileState[];
+    myProjectiles: ProjectileState[];
+    damageDealt: number;
+    damageTaken: number;
+    lastHitTick: number;
+}
+/**
+ * Actions returned by wizard each tick.
+ *
+ * Movement uses world-space coordinates:
+ * - x: +100 = right, -100 = left
+ * - y: +100 = down, -100 = up
+ * - Diagonal movement is normalized (magnitude capped at 100)
+ * - No rotation tracking - just output (x, y) direction
+ */
+interface WizardActions {
+    /**
+     * Movement direction in world-space.
+     * Values are clamped to [-100, 100] range.
+     * Magnitude is normalized to max 100 for diagonal movement.
+     */
+    move: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Start a new cast (only works if state === 'idle').
+     */
+    startCast?: {
+        spell: 'missile';
+        config: MissileConfig;
+        missileAI: MissileAIFunction;
+        direction?: number;
+    } | {
+        spell: 'shield';
+    } | {
+        spell: 'blink';
+        target: Position;
+    };
+    /**
+     * Cancel current cast or channel (works if casting or channeling).
+     */
+    cancel?: boolean;
+    /**
+     * Update aim direction while casting a missile (degrees).
+     * The missile fires in this direction at launch, allowing tracking during cast.
+     * Only applies while state === 'casting' and castingSpell === 'missile'.
+     */
+    aimDirection?: number;
+}
+/**
+ * Missile configuration.
+ */
+interface MissileConfig {
+    damage: number;
+    speed: number;
+    turnRate: number;
+    duration: number;
+}
+/**
+ * Missile AI function type.
+ */
+type MissileAIFunction = (props: {
+    missileState: ProjectileState;
+    worldState: GameState;
+    random: () => number;
+}) => MissileActions;
+/**
+ * Actions returned by missile each tick.
+ */
+interface MissileActions {
+    turnToward?: Position;
+}
+/**
+ * Main wizard function type.
+ */
+type WizardFunction = (props: {
+    state: GameState;
+    config: GameConfig;
+    random: () => number;
+}) => WizardActions;
+
+/**
+ * VIBEMANCER - GAME RULES
+ *
+ * This is the single source of truth for all game constants.
+ * All game logic imports from here. Read this to understand the game.
+ */
+
+declare const TICKS_PER_SECOND = 100;
+declare const TICK_DURATION_MS = 10;
+declare const WIZARD_HEALTH = 60;
+declare const WIZARD_RADIUS = 5;
+declare const MOVEMENT_SPEED = 1;
+declare const CASTING_MOVEMENT_MULT = 0.5;
+declare const GCD_DURATION = 100;
+declare const SHIELD_CAST_TIME = 20;
+declare const SHIELD_MAX_BLOCK = 0.9;
+declare const SHIELD_DECAY_PER_SECOND = 0.2;
+declare const SHIELD_MIN_BLOCK = 0.3;
+declare const BLINK_CAST_TIME = 10;
+declare const BLINK_RANGE = 300;
+declare const BLINK_MAX_COOLDOWN = 2000;
+declare const BLINK_MIN_COOLDOWN = 100;
+/** @deprecated Use BLINK_MAX_COOLDOWN */
+declare const BLINK_COOLDOWN = 2000;
+declare const ARENA_WIDTH = 800;
+declare const ARENA_HEIGHT = 800;
+declare const ARENA_SIZE = 800;
+declare const SPAWN_DISTANCE = 600;
+declare const MISSILE_MIN_DAMAGE = 1;
+declare const MISSILE_MIN_SPEED = 1.5;
+declare const MISSILE_MIN_DURATION = 10;
+declare const MISSILE_MIN_CAST_TIME = 0.1;
+declare const MISSILE_BASE_RADIUS = 2;
+declare const MISSILE_DAMAGE_RADIUS_SCALE = 0.1;
+/**
+ * Calculate missile hitbox radius based on damage.
+ */
+declare function calculateMissileRadius(damage: number): number;
+declare const MISSILE_BASE_CAST = 0.1;
+declare const MISSILE_DAMAGE_SCALE = 0.226;
+declare const MISSILE_DAMAGE_POWER: number;
+declare const MISSILE_HOMING_COEFF = 0.12;
+declare const MISSILE_TURN_DURATION_COEFF = 0.1;
+declare const MISSILE_SPEED_DURATION_BASELINE = 1.5;
+declare const MISSILE_SPEED_DURATION_COEFF = 0.025;
+/**
+ * Maps turnRate to effective cost for the cast time formula.
+ * - Positive: linear (unchanged behavior)
+ * - Negative: diminishing returns via -|t|/(1+|t|), saturating at -1.
+ *   turnRate -0.5 → -0.33, -1 → -0.5, -5 → -0.83, -10 → -0.91
+ *   Big cast speed gains from 0 to -1, worthwhile to -5, negligible after.
+ *   No hard floor — the curve naturally caps the benefit.
+ */
+declare function effectiveTurnRateCost(turnRate: number): number;
+/**
+ * Validate and sanitize missile config.
+ * Ensures all values meet minimum requirements (Lesson #9).
+ */
+declare function validateMissileConfig(config: MissileConfig): MissileConfig;
+/**
+ * Calculate missile cast time from config.
+ *
+ * Base formula:
+ * cast_time = 0.1
+ *           + 0.226 × damage^(2/3)
+ *           + 0.12 × effectiveTurnRateCost(turnRate)
+ *           + 0.10 × (effectiveTurnRateCost(turnRate) × durationSeconds)
+ *           + 0.025 × (speed × durationSeconds - 1.5)
+ *
+ * effectiveTurnRateCost: linear for positive, -ln(1+|t|) for negative (diminishing returns).
+ *
+ * If lastMissileConfig is a MissileConfig, applies warmup multiplier:
+ * - Similar to previous: up to 20% faster
+ * - Very different: up to 20% slower (switching penalty)
+ */
+declare function calculateMissileCastTime(config: MissileConfig, lastMissileConfig?: MissileConfig | undefined | null): number;
+declare const WARMUP_MAX_BONUS = 0.2;
+declare const WARMUP_MAX_PENALTY = 0.2;
+declare const WARMUP_SPEED_TOLERANCE = 3;
+declare const WARMUP_TURN_TOLERANCE = 1;
+declare const WARMUP_DURATION_TOLERANCE = 50;
+/**
+ * Calculate how similar two missile configs are (0 to 1).
+ * Returns 1 for identical configs, 0 for very different ones.
+ * Used by the warmup system to determine cast time multiplier.
+ *
+ * Only compares speed, turnRate, and duration — these define the missile
+ * "style" (melee stab vs ranged homing vs fast snipe). Damage is excluded
+ * because varying power doesn't change playstyle.
+ */
+declare function calculateMissileSimilarity(prev: MissileConfig | undefined, current: MissileConfig): number;
+/**
+ * Calculate the cast time multiplier from the warmup system.
+ * Returns < 1 for bonus (faster), > 1 for penalty (slower), 1 for neutral.
+ *
+ * Similar to previous cast → multiplier approaches (1 - MAX_BONUS) = 0.80
+ * Very different from previous → multiplier approaches (1 + MAX_PENALTY) = 1.20
+ * No previous cast → full bonus (1 - MAX_BONUS) = 0.80
+ */
+declare function calculateWarmupMultiplier(prev: MissileConfig | undefined, current: MissileConfig): number;
+declare const MATCH_DURATION = 30000;
+declare const MAX_HEALTH = 60;
+declare const COLLISION_RADIUS = 5;
+declare const MOVE_SPEED = 1;
+declare const MISSILE_RADIUS_PER_DAMAGE = 0.1;
+declare const SHIELD_MAX_STRENGTH = 0.9;
+declare const SHIELD_MIN_STRENGTH = 0.3;
+declare const SHIELD_DECAY_RATE = 0.2;
+declare const BLINK_MAX_RANGE = 300;
+/**
+ * Calculate blink cooldown based on distance traveled.
+ * Short blinks get short cooldowns, full-range blinks get the maximum.
+ */
+declare function calculateBlinkCooldown(distance: number): number;
+declare const ARENA_WATER_BUFFER = 200;
+
+/**
+ * Engine version — milliseconds since the Unix epoch.
+ *
+ * Bumped automatically by `scripts/update-engine-version.mjs` on every build.
+ * The same value is propagated to `packages/functions/src/engine-version.generated.ts`
+ * so cloud functions and the core engine always agree on a single version per deploy.
+ *
+ * Used to gate spectator replays: a recorded match can only be re-simulated when
+ * the runtime engine version matches the version that produced the match.
+ */
+declare const ENGINE_VERSION = 1777556890699;
+
+interface InternalWizardState extends WizardState {
+    missileConfig?: MissileConfig;
+    missileAI?: MissileAIFunction;
+    blinkTarget?: {
+        x: number;
+        y: number;
+    };
+    damageDealt: number;
+    damageTaken: number;
+    lastHitTick: number;
+}
+/**
+ * Initialize a new match state.
+ */
+declare function createInitialState(_seed: number, spawnDist?: number): GameState;
+/**
+ * Process one game tick.
+ */
+declare function tick(currentTick: number, wizard1AI: WizardFunction, wizard2AI: WizardFunction, config: GameConfig, wizards: InternalWizardState[], projectiles: ProjectileState[], missileAIs: Map<string, MissileAIFunction>, matchSeed: number): {
+    nextTick: number;
+    wizards: InternalWizardState[];
+    projectiles: ProjectileState[];
+    errors: BotError[];
+};
+/**
+ * Get the game state from a specific player's perspective.
+ * Returns a deep clone to prevent mutation of history entries.
+ * Used for history recording where independent snapshots are needed.
+ */
+declare function getPlayerState(playerIndex: number, wizards: InternalWizardState[], projectiles: ProjectileState[], tick: number): GameState;
+/** Winner of a single match: a wizard ID, 'draw' (simultaneous kill), or null (timeout). */
+type MatchWinner = 'wizard-1' | 'wizard-2' | 'draw' | null;
+/** Winner of a fight (aggregate): a wizard ID or 'draw'. Never null. */
+type FightWinner = 'wizard-1' | 'wizard-2' | 'draw';
+/**
+ * Result of a simulation.
+ */
+/** A runtime error captured from a bot or missile AI function. */
+interface BotError {
+    tick: number;
+    entityId: string;
+    message: string;
+}
+interface SimulateResult {
+    /** 'wizard-1'/'wizard-2' = killed opponent, 'draw' = simultaneous kill, null = timeout */
+    winner: MatchWinner;
+    ticks: number;
+    finalState: GameState;
+    history: GameState[];
+    /** Runtime errors thrown by bot or missile AI functions (empty if no errors). */
+    errors: BotError[];
+}
+/**
+ * Result of a fight (best-of-5 at different spawn distances).
+ */
+interface FightResult {
+    wizard1Wins: number;
+    wizard2Wins: number;
+    draws: number;
+    /** Winner of the fight: 'wizard-1', 'wizard-2', or 'draw' (never null) */
+    winner: FightWinner;
+    /**
+     * Individual match results (one per spawn distance, non-swapped only).
+     * Used for visual playback in the web viewer. Scoring includes both sides.
+     */
+    matches: SimulateResult[];
+}
+/** Spawn distances for the 5 matches in a fight (creates butterfly effect variation) */
+declare const FIGHT_SPAWN_DISTANCES: number[];
+/**
+ * Run a fight: 10 matches (5 spawn distances × 2 sides) between two bots.
+ * Each spawn distance is played twice — once with each bot on each side —
+ * to ensure results are independent of starting position.
+ *
+ * The `matches` array contains only the 5 non-swapped matches (for visual playback).
+ * The scoring aggregates (wizard1Wins, wizard2Wins, draws) include all 10 matches.
+ *
+ * This is the standard way to determine who wins a matchup.
+ * Used by both the tournament system and the visual UI.
+ */
+declare function fight(wizard1AI: WizardFunction, wizard2AI: WizardFunction, options?: {
+    seed?: number;
+    maxTicks?: number;
+}): FightResult;
+/**
+ * Run a full match simulation.
+ *
+ * @param options.skipHistory - When true, skips recording per-tick history snapshots.
+ *   This dramatically improves performance (no deep cloning per tick) and is used
+ *   by the optimizer and fight() scoring. The returned history array will be empty
+ *   and finalState will still be populated.
+ */
+declare function simulate(wizard1AI: WizardFunction, wizard2AI: WizardFunction, options?: {
+    maxTicks?: number;
+    seed?: number;
+    spawnDistance?: number;
+    skipHistory?: boolean;
+}): SimulateResult;
+
+/**
+ * VIBEMANCER - HOOKS API TYPES
+ *
+ * Types for the hooks-based bot API.
+ *
+ * UNITS REFERENCE (100 ticks = 1 second):
+ *   Position:   absolute world coordinates, 0-800 on each axis (800×800 arena)
+ *   Velocity:   units per tick on each axis (player max speed = 1 u/t)
+ *   Health:     hit points (max 60)
+ *   Ticks:      game ticks (10ms each, 100/sec). Divide by 100 for seconds.
+ *   Angles:     degrees (0°=right, 90°=down, 180°=left, 270°=up)
+ */
+
+/**
+ * Enemy wizard state as seen by your bot.
+ *
+ * Note: you cannot see the enemy's missile configs, cooldown timers, or
+ * damage history — only what's visible on the battlefield.
+ */
+interface EnemyState {
+    /** Enemy position in world coordinates (0-800). */
+    position: Position;
+    /** Enemy velocity in units/tick. */
+    velocity: Velocity;
+    /** Enemy current HP (0-60). */
+    health: number;
+    /** Enemy status: 'idle', 'casting', 'channeling' (shield), or 'gcd_locked'. */
+    status: 'idle' | 'casting' | 'channeling' | 'gcd_locked';
+    /** Which spell enemy is casting, or null. */
+    castingSpell: 'missile' | 'shield' | 'blink' | null;
+    /** Enemy shield block multiplier (0 if not shielding, 0.3-0.9 if shielding). */
+    shieldStrength: number;
+}
+/**
+ * Pre-computed analysis of an incoming enemy projectile.
+ *
+ * All timing values are in ticks (100 ticks = 1 second).
+ * Dodge directions are relative to missile heading, not world axes.
+ */
+interface AnalyzedThreat {
+    /** Unique projectile ID. */
+    id: string;
+    /** Raw projectile state (position, rotation in degrees, speed in u/t, turnRate, remainingTicks). */
+    projectile: ProjectileState;
+    /** Ticks until missile hits your current position. Infinity if predicted to miss. */
+    ticksToImpact: number;
+    /** Whether the missile will hit if you stand still. */
+    willHit: boolean;
+    /** Whether strafing left (perpendicular to missile heading) avoids it. */
+    canDodgeLeft: boolean;
+    /** Whether strafing right (perpendicular to missile heading) avoids it. */
+    canDodgeRight: boolean;
+    /** Whether moving directly away from the missile avoids it. */
+    canOutrun: boolean;
+    /** Optimal dodge direction as a unit vector {x, y}, or null if undodgeable. */
+    bestDodgeDirection: Position | null;
+    /** Whether you can channel shield before the missile arrives. */
+    canBlockInTime: boolean;
+    /** Ticks from now when you should START channeling shield to block in time. */
+    ticksToStartShield: number;
+}
+/**
+ * Final action that can be returned from a bot.
+ * Cannot be further chained.
+ */
+interface FinalAction {
+    /** Internal: extract the WizardActions */
+    readonly _toAction: () => WizardActions;
+}
+/**
+ * Action builder that allows chaining .move() for simultaneous movement.
+ * Returned by shield(), missile(), and cancel().
+ */
+interface ActionBuilder extends FinalAction {
+    /**
+     * Add movement to this action (e.g., move while casting).
+     * Direction vector, not absolute position. Auto-normalized.
+     * Positive X = right, positive Y = down.
+     */
+    move(x: number, y: number): FinalAction;
+}
+/**
+ * Bot function type for the hooks API.
+ * Called every tick. Read state with hooks, return an action.
+ */
+type BotFunction = () => FinalAction;
+/**
+ * Internal context for game state hooks.
+ */
+interface BotContext {
+    entityId: string;
+    tick: number;
+    position: Position;
+    velocity: Velocity;
+    health: number;
+    maxHealth: number;
+    state: 'idle' | 'casting' | 'channeling' | 'gcd_locked';
+    castingSpell?: 'missile' | 'shield' | 'blink';
+    castProgress?: number;
+    castDuration?: number;
+    channelingSpell?: 'shield';
+    channelDuration?: number;
+    gcdRemaining?: number;
+    blinkCooldown: number;
+    enemies: Array<{
+        id: string;
+        position: Position;
+        velocity: Velocity;
+        health: number;
+        state: 'idle' | 'casting' | 'channeling' | 'gcd_locked';
+        castingSpell?: 'missile' | 'shield' | 'blink';
+        channelingSpell?: 'shield';
+        channelDuration?: number;
+    }>;
+    projectiles: ProjectileState[];
+    myProjectiles: ProjectileState[];
+    arenaWidth: number;
+    arenaHeight: number;
+    damageDealt: number;
+    damageTaken: number;
+    lastHitTick: number;
+}
+
+/**
+ * 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).
+ */
+
+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;
+}
+/**
+ * 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
+ */
+declare function validateHookCall(type: string): number;
+/**
+ * Run a function with a specific entity's hook context.
+ */
+declare function runWithHooks<T>(entityId: string, fn: () => T): T;
+/**
+ * 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.
+ */
+declare function runBotWithContext<T>(entityId: string, context: BotContext, fn: () => T): T;
+/**
+ * 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.
+ */
+declare function withBotContext<T>(context: BotContext, fn: () => T): T;
+/**
+ * Get the current bot context. Throws if called outside bot execution.
+ */
+declare function getBotContext(): BotContext;
+/**
+ * Persist state between ticks.
+ */
+declare function useState<T>(initialValue: T | (() => T)): [T, (newValue: T | ((prev: T) => T)) => void];
+/**
+ * React to state changes.
+ */
+declare function useEffect(callback: () => void | (() => void), deps?: unknown[]): void;
+/**
+ * Memoize expensive calculations.
+ */
+declare function useMemo<T>(factory: () => T, deps?: unknown[]): T;
+/**
+ * Mutable reference that persists across ticks.
+ * Unlike useState, mutations don't need a setter - just modify .current directly.
+ */
+interface RefObject<T> {
+    current: T;
+}
+declare function useRef<T>(initialValue: T): RefObject<T>;
+/**
+ * Clear hook state for an entity (e.g., when it dies).
+ */
+declare function clearHooks(entityId: string): void;
+/**
+ * Reset all hook states (e.g., when a match restarts).
+ */
+declare function resetAllHooks(): void;
+
+/**
+ * Move a wizard based on world-space input direction.
+ *
+ * Movement model (from design doc):
+ * - x: +100 = right, -100 = left
+ * - y: +100 = down, -100 = up
+ * - Values are clamped to [-100, 100]
+ * - Diagonal movement is normalized (magnitude capped at 100)
+ * - No rotation tracking - just output (x, y) direction
+ */
+declare function moveWizard(wizard: WizardState, move: {
+    x: number;
+    y: number;
+}, deltaTicks: number): Position;
+/**
+ * Move a projectile in its current rotation direction.
+ */
+declare function moveProjectile(projectile: ProjectileState, deltaTicks: number): Position;
+/**
+ * Clamp a position to the arena boundaries.
+ */
+declare function clampToArena(position: Position, radius: number): Position;
+/**
+ * Resolve body collision between two wizards.
+ * Pushes both apart equally so they don't overlap. Neither is blocked — they just can't stack.
+ * Iterates until stable: wizard push → wall clamp → re-check overlap → repeat.
+ */
+declare function resolveWizardCollision(wizard1: WizardState, wizard2: WizardState): void;
+/**
+ * Perform swept circle collision detection between a moving point (projectile) and a stationary circle (wizard).
+ * Returns true if a collision occurred during the movement from oldPos to newPos.
+ */
+declare function sweptCircleCollision(oldPos: Position, newPos: Position, radius: number, targetPos: Position, targetRadius: number): boolean;
+
+/**
+ * Start casting a spell.
+ * For missiles, applies warmup system (bonus for similar, penalty for switching).
+ */
+declare function startCast(wizard: WizardState, spell: 'missile' | 'shield' | 'blink', config?: MissileConfig): void;
+/**
+ * Cancel the current cast.
+ */
+declare function cancelCast(wizard: WizardState): void;
+/**
+ * Complete the current cast and trigger the spell effect.
+ */
+declare function completeCast(wizard: WizardState): void;
+/**
+ * Update the shield channel state.
+ */
+declare function updateShield(wizard: WizardState, deltaTicks: number): void;
+/**
+ * Calculate the current block percentage of a shield based on channel duration.
+ */
+declare function calculateShieldBlock(channelDurationTicks: number): number;
+/**
+ * Apply damage to a wizard, considering shield mitigation.
+ *
+ * Shield blocks a percentage of damage based on channel duration:
+ * - Fresh shield (0s): 90% block → 10% damage through
+ * - Decayed shield: block % decreases over time (20%/sec)
+ * - Minimum: 30% block → 70% damage through
+ *
+ * (Design doc lines 196-212)
+ */
+declare function applyDamage(wizard: WizardState, damage: number, _projectile?: ProjectileState): number;
+
+/**
+ * VIBEMANCER - MANUAL MATCH
+ *
+ * Tick-by-tick match runner used by manual play mode. Wraps the same
+ * `tick()` primitive that `simulate()` uses, so stepping forward
+ * produces the same trajectory as a batched `simulate()` with the
+ * same seed.
+ *
+ * Extra capabilities over `simulate()`:
+ * - step(N) advances N ticks at a time (default 1) — caller controls pacing
+ * - replaceMissileAI(id, ai) hot-swaps a missile's AI mid-flight (used by
+ *   the missile-hijack feature in manual play)
+ * - setInvincible(wizardIndex, on) toggles damage immunity per wizard
+ */
+
+interface ManualMatchOptions {
+    seed?: number;
+    spawnDistance?: number;
+    maxTicks?: number;
+}
+interface StepResult {
+    gameState: GameState;
+    errors: BotError[];
+    done: boolean;
+}
+declare class ManualMatch {
+    private readonly wizard1AI;
+    private readonly wizard2AI;
+    private readonly seed;
+    private readonly maxTicks;
+    private readonly config;
+    private wizards;
+    private projectiles;
+    private missileAIs;
+    /** First-replacement originals for hijacked missiles. Used by restoreMissileAI. */
+    private originalMissileAIs;
+    private currentTick;
+    private done;
+    private allErrors;
+    private history;
+    constructor(wizard1AI: WizardFunction, wizard2AI: WizardFunction, options?: ManualMatchOptions);
+    /**
+     * Advance the match by `count` ticks (default 1). Stops early if the
+     * match completes mid-batch.
+     */
+    step(count?: number): StepResult;
+    /**
+     * Hot-swap a missile's AI function. Used by the missile-hijack feature
+     * in manual play. The first replacement remembers the original AI so
+     * `restoreMissileAI` can put it back. Subsequent replacements update
+     * the active AI but leave the remembered original alone.
+     *
+     * No-op if the projectile id doesn't exist.
+     */
+    replaceMissileAI(projectileId: string, ai: MissileAIFunction): void;
+    /**
+     * Restore a previously hijacked missile's original AI function.
+     * No-op if the projectile id doesn't exist or was never hijacked.
+     */
+    restoreMissileAI(projectileId: string): void;
+    /**
+     * Set the invincibility flag for a wizard. Invincible wizards take 0
+     * damage from all sources.
+     */
+    setInvincible(wizardIndex: 0 | 1, on: boolean): void;
+    /**
+     * Get the current game state from wizard-1's perspective.
+     * Returned object is a deep clone — safe to mutate.
+     */
+    getGameState(): GameState;
+    getCurrentTick(): number;
+    isComplete(): {
+        done: boolean;
+        winner: MatchWinner;
+    };
+    getResult(): SimulateResult;
+    dispose(): void;
+    private computeWinner;
+}
+
+/**
+ * VIBEMANCER - MISSILE TEMPLATES
+ *
+ * Reusable missile config + AI factories for manual play and bot examples.
+ * Each factory clamps its inputs to rules.ts minimums and returns a pure
+ * AI function that's safe to register with the engine.
+ */
+
+interface BaseParams {
+    damage: number;
+    speed: number;
+    duration: number;
+}
+interface TurningParams extends BaseParams {
+    turnRate: number;
+}
+type StraightParams = BaseParams;
+type HomingParams = TurningParams;
+type AntiHomingParams = TurningParams;
+interface SpiralParams extends BaseParams {
+    spiralRadius: number;
+    spiralFreq: number;
+}
+interface SeekerParams extends TurningParams {
+    minLockDistance: number;
+}
+interface MissileTemplate {
+    config: MissileConfig;
+    ai: MissileAIFunction;
+}
+/**
+ * Fire-and-forget missile. No steering — flies in a straight line.
+ */
+declare function straightMissile(p: StraightParams): MissileTemplate;
+/**
+ * Homing missile. Steers toward the enemy each tick.
+ */
+declare function homingMissile(p: HomingParams): MissileTemplate;
+/**
+ * Anti-homing missile. Steers AWAY from the enemy — useful as a feint or
+ * area-denial pattern.
+ */
+declare function antiHomingMissile(p: AntiHomingParams): MissileTemplate;
+/**
+ * Spiral missile. Continuously orbits its current heading while advancing.
+ * Uses missileState.remainingTicks as a deterministic phase counter so the
+ * AI is fully pure (no closure state).
+ */
+declare function spiralMissile(p: SpiralParams): MissileTemplate;
+/**
+ * Seeker missile. Homes toward the enemy, but only when farther away than
+ * minLockDistance — closer than that, the missile coasts straight (so it
+ * doesn't whirl around a target it's about to hit).
+ */
+declare function seekerMissile(p: SeekerParams): MissileTemplate;
+
+/**
+ * Calculate the distance between two points.
+ */
+declare function distanceTo(a: Position, b: Position): number;
+/**
+ * Check if two points are within a certain range of each other.
+ */
+declare function inRange(a: Position, b: Position, range: number): boolean;
+
+/**
+ * Calculate the angle from one point to another in degrees.
+ * 0° = right, 90° = down, 180° = left, 270° = up.
+ */
+declare function angleTo(from: Position, to: Position): number;
+/**
+ * Normalize an angle to the 0-360 range.
+ */
+declare function normalizeAngle(angle: number): number;
+/**
+ * Calculate the shortest difference between two angles (-180 to +180).
+ */
+declare function angleDiff(angleA: number, angleB: number): number;
+/**
+ * Check if an angle is within a certain range of a target angle.
+ */
+declare function angleInRange(angle: number, target: number, range: number): boolean;
+
+/**
+ * Get the position after moving a certain distance in a direction.
+ */
+declare function moveInDirection(position: Position, angle: number, distance: number): Position;
+/**
+ * Predict the position after N ticks given current velocity.
+ */
+declare function predictPosition(position: Position, velocity: Velocity, ticks: number): Position;
+/**
+ * Calculate the intercept angle for a target moving at a certain velocity.
+ * Returns null if no intercept solution exists.
+ */
+declare function interceptAngle(shooterPosition: Position, targetPosition: Position, targetVelocity: Velocity, projectileSpeed: number): number | null;
+
+/**
+ * Find the nearest entity from a list.
+ */
+declare function findNearest<T extends {
+    position: Position;
+}>(from: Position, entities: T[]): T | null;
+/**
+ * Find all entities within a certain range.
+ */
+declare function findInRange<T extends {
+    position: Position;
+}>(from: Position, entities: T[], range: number): T[];
+/**
+ * Sort entities by distance (closest first).
+ */
+declare function sortByDistance<T extends {
+    position: Position;
+}>(from: Position, entities: T[]): T[];
+
+/**
+ * Seeded PRNG utilities for deterministic randomness.
+ *
+ * Each entity (wizard, missile) gets its own random sequence that:
+ * - Is deterministic: same seed = same sequence
+ * - Is isolated: one entity's calls don't affect another's
+ * - Advances state: each call produces a different value
+ */
+/**
+ * Combine two seeds into one using a simple hash.
+ */
+declare function hashCombine(a: number, b: number): number;
+/**
+ * Advance the random state using a Linear Congruential Generator.
+ * Parameters from glibc (widely tested).
+ */
+declare function nextRandom(state: number): number;
+/**
+ * Create a seeded random number generator.
+ * Returns a function that produces values in [0, 1) and advances internal state.
+ */
+declare function createRandom(seed: number): () => number;
+/**
+ * Create a deterministic seed for an entity based on match seed, entity ID, and tick.
+ * This ensures reproducibility: same match + same entity + same tick = same random sequence.
+ */
+declare function createEntitySeed(matchSeed: number, entityId: string, tick: number): number;
+
+/**
+ * VIBEMANCER - SPATIAL UTILITIES
+ *
+ * Direction vectors and arena bounds utilities.
+ */
+
+/**
+ * Normalize a vector to unit length.
+ * Returns {x: 0, y: 0} for zero-length vectors.
+ */
+declare function normalize(vector: Position): Position;
+/**
+ * Get normalized direction vector from one position toward another.
+ * Returns {x: 0, y: 0} if positions are identical.
+ */
+declare function directionTo(from: Position, to: Position): Position;
+/**
+ * Get normalized direction vector from one position away from another.
+ * Returns {x: 0, y: 0} if positions are identical.
+ */
+declare function directionAway(from: Position, to: Position): Position;
+/**
+ * Clamp a position to valid arena bounds.
+ * Note: For wizard-specific clamping with radius, use clampToArena from physics.ts
+ */
+declare function clampPositionToArena(position: Position): Position;
+/**
+ * Get the length/magnitude of a vector.
+ */
+declare function magnitude(vector: Position): number;
+
+/**
+ * VIBEMANCER - COMBAT UTILITIES
+ *
+ * Utilities for combat calculations.
+ */
+
+/**
+ * Get cast time in ticks for a missile configuration.
+ * Applies the same clamps/validation as the engine before calculating,
+ * so the result matches the actual cast time that will be used in-game.
+ *
+ * If lastMissileConfig is provided, includes warmup multiplier.
+ * Pass undefined for first cast (full warmup) or null for base time only.
+ */
+declare function getMissileCastTime(config: MissileConfig, lastMissileConfig?: MissileConfig | null): number;
+/**
+ * Calculate the position to aim at to hit a moving target.
+ * Returns the intercept point where a missile would hit the target.
+ *
+ * @param targetPos - Current target position
+ * @param targetVel - Target velocity (units per tick)
+ * @param missileSpeed - Missile speed (units per tick)
+ * @param myPos - Shooter position
+ * @returns The position to aim at
+ */
+declare function getLeadPosition(targetPos: Position, targetVel: Velocity, missileSpeed: number, myPos: Position): Position;
+/**
+ * Calculate optimal missile configuration based on target behavior.
+ */
+declare function getAdaptiveMissileConfig(targetVelocity: Position, distance: number): {
+    speed: number;
+    turnRate: number;
+    damage: number;
+    duration: number;
+};
+/**
+ * Given a cast-time budget (in ticks) and a target distance, find the best
+ * missile config that fits. Maximizes damage while ensuring the missile
+ * can reach the target and finishes casting in time.
+ *
+ * Returns null if no useful missile fits in the budget.
+ *
+ * How it works: tries several speed/turnRate templates. For each, calculates
+ * the minimum duration to reach `distance`, then solves the cast-time formula
+ * for the maximum damage that fits within `budgetTicks`.
+ *
+ * If `lastMissileConfig` is provided, accounts for warmup bonus: similar
+ * missiles cast faster, so more damage can fit in the same budget.
+ */
+declare function fitMissileToBudget(budgetTicks: number, distance: number, options?: {
+    minTurnRate?: number;
+    maxDamage?: number;
+    lastMissileConfig?: MissileConfig;
+}): MissileConfig | null;
+
+/**
+ * Bot: TargetDummy
+ *
+ * BEHAVIOR: Does absolutely nothing. No movement, no spells, no AI.
+ *
+ * NAMING RATIONALE: "Target Dummy" is universal MMO player vocabulary for the
+ * practice objects found in capital cities. Every WoW/FFXIV player has beaten
+ * on a target dummy to test DPS rotations. That's exactly what this bot is —
+ * a punching bag for testing missile mechanics and baseline damage output.
+ * Nobody calls them "training dummies"; the player term is always "target dummy."
+ *
+ * STANDALONE — no tier progression. It's a test fixture, not a combatant.
+ */
+declare const TargetDummy: WizardFunction;
+
+/**
+ * Bot: Rookie
+ *
+ * BEHAVIOR: Stands perfectly still and fires straight (non-homing) missiles at
+ * the enemy. No movement, no dodging, no shielding. Knows one spell and uses
+ * it on cooldown. The wizard equivalent of an FPS player who stands in the open
+ * and holds left-click.
+ *
+ * NAMING RATIONALE: "Rookie" is the universal term for a first-timer who barely
+ * knows what they're doing. This bot is a day-one player who learned how to cast
+ * missile and nothing else. No movement, no defense, just raw "I press the button."
+ * We considered "Noob" (more accurate) but Rookie is less abrasive while conveying
+ * the same thing — a beginner who doesn't know any better.
+ *
+ * STANDALONE — no tier progression. Rookies either learn to play a real class
+ * or quit. This bot represents the rock-bottom of "at least it shoots."
+ */
+declare const Rookie: WizardFunction;
+
+/**
+ * Bot: Critter
+ *
+ * BEHAVIOR: Picks random valid actions each tick — random movement, random spells,
+ * random missile configs, random directions. Occasionally cancels its own casts.
+ * Uses engine-provided seeded random for deterministic behavior. Useful for
+ * finding edge cases in the engine, but completely useless in combat.
+ *
+ * NAMING RATIONALE: In WoW, critters are the 1-HP ambient mobs (rabbits, squirrels,
+ * prairie dogs) that wander around doing nothing useful and die to literally anything.
+ * This bot is the wizard equivalent — it flails around randomly and gets destroyed by
+ * anyone with a plan. The word "Critter" immediately tells any gamer "this thing is
+ * helpless and exists only to fill space."
+ *
+ * STANDALONE — no tier progression. Critters don't level up. However, a future
+ * "Hogger" bot could be an elite critter: same chaotic spirit but actually dangerous
+ * (like the famous WoW elite that wipes unprepared lowbies).
+ */
+declare const Critter: WizardFunction;
+
+/**
+ * Bot: Hogger
+ *
+ * BEHAVIOR: The elite critter. Chaotic and unpredictable but genuinely dangerous.
+ * Randomly varies missile configs each cast (damage 7-15, speed 3-8, random homing),
+ * moves erratically but still somewhat toward/away from the enemy, shields when
+ * in real danger, and blinks unpredictably. The randomness makes Hogger hard to
+ * predict — you never know if the next missile will be a slow tracker or a fast
+ * snipe. Unlike Critter's pure randomness, Hogger has enough combat awareness
+ * to actually win fights.
+ *
+ * NAMING RATIONALE: In WoW, Hogger is the iconic level 11 elite gnoll in Elwynn
+ * Forest who infamously kills unprepared lowbies. He's technically a basic mob
+ * but hits way harder than expected. This bot is the Critter that learned to
+ * fight — still chaotic, still a bit dumb, but capable of ending you if you
+ * underestimate it. "Hogger" is one of WoW's most recognizable references and
+ * perfectly captures "deceptively dangerous chaos."
+ *
+ * STANDALONE — no tier progression. There's only one Hogger.
+ */
+declare const Hogger: WizardFunction;
+
+/**
+ * Bot: Doombringer
+ *
+ * BEHAVIOR: Fires a single maximum-damage homing missile with infinite budget.
+ * No damage cap — goes for the biggest possible hit. Exists as a benchmark to
+ * demonstrate why lower-damage + shield play is superior. Has basic shield
+ * defense but no sophisticated tactics. One fat cast, one fat hit.
+ *
+ * STANDALONE — no tier progression. Benchmark/test bot.
+ */
+declare const Doombringer: WizardFunction;
+
+declare const Turtle: WizardFunction;
+
+/**
+ * Bot: Sentinel
+ *
+ * BEHAVIOR: Stationary tank with last-moment shielding AND two-tier offense.
+ * Like Turtle, never moves and shields at the last moment. Unlike Turtle,
+ * fires bigger missiles (damage 20) when the safe window is large enough,
+ * falling back to Turtle's fast missile (damage 12) when pressed.
+ *
+ * PROGRESSION LINE: Turtle → Sentinel → Golem
+ * - Turtle (tier 1): Stationary, fixed missiles, reactive shield timing
+ * - Sentinel (tier 2): Stationary, two-tier offense (big + fast missiles)
+ * - Golem (tier 3): Immovable fortress, perfect shield timing
+ *
+ * TIER: 2 (enhanced Turtle)
+ */
+declare const Sentinel: WizardFunction;
+
+/**
+ * Bot: Golem
+ *
+ * BEHAVIOR: Stationary fortress with perfect shield timing and devastating
+ * counterattacks during enemy vulnerability windows. Reads enemy cast/GCD
+ * state to time punish missiles that land when the enemy can't shield.
+ * Handles multi-missile volleys by holding shield through consecutive impacts.
+ * Uses progressive cast-cancel thresholds for optimal damage trading.
+ *
+ * KEY IMPROVEMENTS OVER SENTINEL:
+ * - Counterattack punish: fires during enemy cast/GCD recovery
+ * - Multi-threat volley awareness: holds shield through consecutive hits
+ * - Progressive cast-cancel: graduated damage thresholds
+ * - Perfect shield timing: uses ticksToStartShield precisely
+ *
+ * PROGRESSION LINE: Turtle → Sentinel → Golem
+ * TIER: 3 (elite Defensive line)
+ */
+declare const Golem: WizardFunction;
+
+/**
+ * Bot: Shadowblade
+ *
+ * BEHAVIOR: Melee assassin. Blinks to the enemy, then lands devastating point-blank
+ * stab attacks (15 damage, 30u range, ~60 tick cast = 2-hit kill). Runs directly
+ * at the enemy with minimal strafe, shields undodgeable threats. The entire
+ * strategy is: get close, stab, kill. Simple and brutal.
+ *
+ * PROGRESSION LINE: Shadowblade → Nightblade → Voidblade
+ * - Shadowblade (tier 1): Offensive blink, melee stabs, basic shield
+ * - Nightblade (tier 2): + missile-aware blinks, adaptive stabs, timed defense
+ * - Voidblade (tier 3): Future — perfect assassination timing, inescapable engages
+ *
+ * TIER: 1 (base)
+ */
+declare const Shadowblade: WizardFunction;
+
+/**
+ * Bot: Nightblade
+ *
+ * BEHAVIOR: Enhanced melee assassin. Same aggressive engagement as Shadowblade —
+ * blinks directly to the enemy and stabs for 15 damage (2-hit kill). The tier 2
+ * upgrade is PREEMPTIVE DEFENSE: Nightblade watches the enemy's cast bar and
+ * shields before a point-blank missile is even launched. At melee range, missiles
+ * arrive almost instantly after launch — too fast to react. Nightblade anticipates
+ * the threat. Also has emergency blink and proper channeling management.
+ *
+ * PROGRESSION LINE: Shadowblade → Nightblade → Voidblade
+ * - Shadowblade (tier 1): Offensive blink, melee stabs, basic shield (reactive only)
+ * - Nightblade (tier 2): + preemptive shield vs enemy casts, emergency blink
+ * - Voidblade (tier 3): Future — perfect assassination timing, inescapable engages
+ *
+ * TIER: 2 (enhanced Shadowblade)
+ */
+declare const Nightblade: WizardFunction;
+
+/**
+ * Bot: Voidblade
+ *
+ * BEHAVIOR: Reactive counter-puncher. Shields everything, then fires quick stabs
+ * during enemy vulnerability windows (GCD/casting) when they can't shield back.
+ * At melee range, the shield blocks ~90% of incoming damage while Voidblade's
+ * counter-stabs land at full damage — winning through attrition.
+ *
+ * CORE LOOP (melee range):
+ *   1. Enemy casts missile → Voidblade blink-dodges (100% avoid) or shields (90% block)
+ *   2. Enemy enters GCD → Voidblade fires quick stab (lands unblocked)
+ *   3. Voidblade enters GCD → enemy recovers → repeat
+ *
+ * KEY IMPROVEMENTS OVER NIGHTBLADE:
+ * - Blink-dodge priority: avoids 100% of damage when blink available, shields as fallback
+ * - Reads enemy vulnerability to time counter-stabs perfectly
+ * - Cancel-into-defense: aborts own cast if enemy missile incoming
+ * - Punish budget: sizes stabs to fit exactly in the vulnerability window
+ *
+ * PROGRESSION LINE: Shadowblade → Nightblade → Voidblade
+ * TIER: 3 (elite Melee line)
+ */
+declare const Voidblade: WizardFunction;
+
+/**
+ * Bot: Bonemancer
+ *
+ * BEHAVIOR: Stands still and fires slow, homing missiles constantly. Every missile
+ * tracks the enemy with turnRate 2 — they curve relentlessly toward the target.
+ * No movement, no shields, just an unending stream of seeking projectiles. The
+ * missiles are slow (speed 3) but long-lived (300 ticks) and will chase you across
+ * the entire arena.
+ *
+ * NAMING RATIONALE: Named after Diablo 2's Bone Necromancer ("Bonemancer"), whose
+ * signature spell Bone Spirit is a slow-moving, auto-tracking projectile that hunts
+ * enemies relentlessly. That's exactly what this bot does — it stands in place and
+ * spams seeking missiles. The homing behavior is the key identity: these aren't
+ * aimed shots, they're heat-seeking spirits that chase you down. Every D2 player
+ * knows the Bonemancer — it's one of the most iconic builds.
+ *
+ * PROGRESSION LINE: Bonemancer → Lich → Archlich
+ * - Bonemancer (tier 1): Stationary, spams slow homing missiles
+ * - Lich (tier 2): Future — enhanced homing with adaptive missiles and defense
+ * - Archlich (tier 3): Future — master of tracking magic, undodgeable death swarm
+ * The progression follows the D2 necromancer power fantasy: from bone apprentice
+ * to undead overlord, each tier's missiles become harder to escape.
+ *
+ * TIER: 1 (base)
+ */
+declare const Bonemancer: WizardFunction;
+
+/**
+ * Bot: Lich
+ *
+ * BEHAVIOR: Homing missile specialist with strong-tracking adaptive missiles.
+ * Uses fitMissileToBudget with minTurnRate 1.0 — higher than other bots (0.5) —
+ * producing missiles with superior tracking at the cost of some damage/speed.
+ * Strafing launches missiles from different angles, creating multi-angle pressure.
+ *
+ * Shields undodgeable/critical threats, emergency blinks. Cancels missile cast
+ * only for lethal incoming damage.
+ *
+ * KEY DIFFERENCES FROM BONEMANCER:
+ * - Bonemancer: stationary, no defense, fixed d=7/s=3/t=2/dur=300
+ * - Lich: mobile, full defense, adaptive strong-tracking homing missiles
+ *
+ * PROGRESSION LINE: Bonemancer → Lich → Archlich
+ * - Bonemancer (tier 1): Stationary, spams fixed slow homing missiles, no defense
+ * - Lich (tier 2): Mobile + defense, adaptive strong-tracking missiles (minTurnRate 1.0)
+ * - Archlich (tier 3): Future — converging web patterns, impossible to escape
+ *
+ * TIER: 2 (enhanced Bonemancer)
+ */
+declare const Lich: WizardFunction;
+
+/**
+ * Bot: Archlich
+ *
+ * BEHAVIOR: Lich's proven core (mobile homing specialist) plus vulnerability
+ * exploitation. Defense, movement, and standard offense are identical to Lich.
+ * The T3 advantage: when the enemy is locked in GCD/cast, fires fast straight
+ * punish missiles that land during the vulnerability window.
+ *
+ * PROGRESSION LINE: Bonemancer → Lich → Archlich
+ * TIER: 3 (elite Homing line)
+ */
+declare const Archlich: WizardFunction;
+
+/**
+ * Bot: Flamecaller
+ *
+ * BEHAVIOR: Long-range homing missile caster with fixed missile config.
+ * Maintains 350u distance, strafes to dodge, and fires standard homing
+ * missiles (d=10, s=5, t=1, dur=180). Shields undodgeable threats,
+ * emergency blinks. A straightforward ranged caster that trades
+ * consistency for adaptability.
+ *
+ * PROGRESSION LINE: Flamecaller → Pyromancer → Infernalist
+ * - Flamecaller (tier 1): Fixed homing missiles, basic strafe and defense
+ * - Pyromancer (tier 2): + adaptive fitting, cast canceling, smart fallbacks
+ * - Infernalist (tier 3): Future — overwhelming adaptive fire
+ *
+ * TIER: 1 (base)
+ */
+declare const Flamecaller: WizardFunction;
+
+/**
+ * Bot: Pyromancer
+ *
+ * BEHAVIOR: Adaptive homing missile specialist at long range. Maintains 400u
+ * distance, strafes to dodge, and uses fitMissileToBudget with minTurnRate 0.5
+ * to fire the highest-damage homing missile that fits in the safe window.
+ * Shields undodgeable threats, emergency blinks. A versatile ranged caster
+ * that adapts its missiles to the situation.
+ *
+ * PROGRESSION LINE: Flamecaller → Pyromancer → Infernalist
+ * - Flamecaller (tier 1): Fixed homing missiles, basic strafe and defense
+ * - Pyromancer (tier 2): + adaptive fitting, cast canceling, smart fallbacks
+ * - Infernalist (tier 3): Future — overwhelming adaptive fire
+ *
+ * TIER: 2 (enhanced Flamecaller)
+ */
+declare const Pyromancer: WizardFunction;
+
+/**
+ * Bot: Infernalist
+ *
+ * BEHAVIOR: Rapid-fire caster that exploits warmup bonus for accelerating DPS.
+ * Fires consistent homing missiles to build warmup, punishes vulnerability windows
+ * with warmup-boosted fast casts. Proactive blink kiting when enemy closes.
+ *
+ * KEY IMPROVEMENTS OVER PYROMANCER:
+ * - Warmup exploitation: always passes lastMissileConfig for bonus
+ * - Punish mode: straight missiles during enemy vulnerability
+ * - Proactive blink kiting: monitors closing rate
+ * - Progressive cast-cancel: graduated thresholds
+ *
+ * PROGRESSION LINE: Flamecaller → Pyromancer → Infernalist
+ * TIER: 3 (elite Caster line)
+ */
+declare const Infernalist: WizardFunction;
+
+/**
+ * Bot: Spellshot
+ *
+ * BEHAVIOR: Uses interceptAngle to calculate where the enemy will be and fires
+ * fast, non-homing missiles (speed 8, turnRate 0) along the predicted path.
+ * Strafes at medium range (300-400), shields undodgeable threats, emergency
+ * blinks when shield isn't available. The key mechanic is PREDICTION — these
+ * missiles don't track, they go exactly where you calculated the enemy would be.
+ *
+ * NAMING RATIONALE: "Spellshot" — a spell that is a single, precisely aimed shot.
+ * Like a sniper's "called shot" but magical. The defining feature is the intercept
+ * calculation: this bot doesn't fire tracking missiles, it calculates the exact
+ * angle needed to hit a moving target. "Shot" implies precision, singular impact,
+ * and skill-based aiming — everything this bot is about.
+ *
+ * PROGRESSION LINE: Spellshot → Spelltracer → Spellseeker
+ * - Spellshot (tier 1): Basic intercept prediction, non-homing missiles
+ * - Spelltracer (tier 2): Future — predictive homing (missiles that lead AND track)
+ * - Spellseeker (tier 3): Future — perfect prediction, multi-angle attacks
+ * The naming progression: shot (single bullet) → tracer (bullet that tracks a path)
+ * → seeker (actively hunts). Each tier adds more intelligence to the projectile,
+ * evolving from "I calculate where you'll be" to "my missile calculates where you'll be."
+ *
+ * NOTE: A separate future archetype "Spellslinger" (volume-of-fire) is reserved
+ * for a rapid-fire bot that prioritizes quantity over prediction.
+ *
+ * TIER: 1 (base)
+ */
+declare const Spellshot: WizardFunction;
+
+/**
+ * Bot: Spelltracer
+ *
+ * BEHAVIOR: Enhanced ranged sniper with adaptive missile fitting and intercept
+ * prediction. Uses fitMissileToBudget to find the highest-damage fast missile
+ * that fits the safe window, then fires it along the predicted intercept angle.
+ * Maintains medium-long range (300-450), shields undodgeable threats with proper
+ * timing, emergency blinks, and distance blinks when cornered. The key mechanic
+ * is still PREDICTION — but now with adaptive damage optimization.
+ *
+ * PROGRESSION LINE: Spellshot → Spelltracer → Spellseeker
+ * - Spellshot (tier 1): Fixed config intercept prediction, non-homing missiles
+ * - Spelltracer (tier 2): + adaptive fitting, timed defense, distance management
+ * - Spellseeker (tier 3): Future — perfect prediction, multi-angle attacks
+ *
+ * TIER: 2 (enhanced Spellshot)
+ */
+declare const Spelltracer: WizardFunction;
+
+/**
+ * Bot: Spellseeker
+ *
+ * BEHAVIOR: Elite sniper that uses intercept-aimed straight missiles during vulnerability
+ * windows. Combines Spelltracer's adaptive fitting with precise lead-position aiming
+ * and vulnerability exploitation. Straight punish missiles at sniper range are nearly
+ * unavoidable. Proactive distance control via closing rate detection.
+ *
+ * KEY IMPROVEMENTS OVER SPELLTRACER:
+ * - Intercept-aimed punish: getLeadPosition + straight missiles during vulnerability
+ * - Proactive distance blink: monitors closing rate, blinks before danger zone
+ * - Progressive cast-cancel: graduated damage thresholds
+ * - Warmup exploitation: always passes lastMissileConfig
+ *
+ * PROGRESSION LINE: Spellshot → Spelltracer → Spellseeker
+ * TIER: 3 (elite Sniper line)
+ */
+declare const Spellseeker: WizardFunction;
+
+/**
+ * Bot: Battlemage
+ *
+ * BEHAVIOR: Balanced mid-range duelist. Shields undodgeable threats, interrupts
+ * enemy casts with quick missiles, saves blink for emergencies OR gap-closing.
+ * Switches between quick (10 dmg, fast) and heavy (15 dmg, slow) missile configs
+ * based on safety window and range. Will aggressively trade hits when health allows.
+ * The unique trait is cast-interruption: fires quick missiles specifically when the
+ * enemy is casting, punishing long cast times.
+ *
+ * PROGRESSION LINE: Battlemage → Warmage → Archmage
+ * - Battlemage (tier 1): Quick/heavy fixed configs, cast interruption, basic defense
+ * - Warmage (tier 2): Adaptive missile fitting (fitMissileToBudget), smarter attacks
+ * - Archmage (tier 3): Future — supreme duelist, perfect tactical mastery
+ *
+ * TIER: 1 (base)
+ */
+declare const Battlemage: WizardFunction;
+
+/**
+ * Bot: Warmage
+ *
+ * BEHAVIOR: Enhanced Battlemage with adaptive missile fitting. Uses fitMissileToBudget
+ * to maximize damage within safe attack windows instead of fixed quick/heavy configs.
+ * Same close-range playstyle: shields undodgeable threats, blinks to close distance
+ * or escape, aggressive hit-trading when health allows. The adaptive fitting means
+ * every attack is optimized for the current situation — no wasted cast time.
+ *
+ * PROGRESSION LINE: Battlemage → Warmage → Archmage
+ * - Battlemage (tier 1): Quick/heavy fixed configs, cast interruption, basic defense
+ * - Warmage (tier 2): Adaptive missile fitting, optimized damage windows
+ * - Archmage (tier 3): Future — supreme duelist, perfect tactical mastery
+ *
+ * TIER: 2 (enhanced Battlemage)
+ */
+declare const Warmage: WizardFunction;
+
+/**
+ * Bot: Archmage
+ *
+ * BEHAVIOR: Versatile duelist that adapts missile choice based on distance and HP.
+ * Close range → straight missiles (no turn cost = more damage). Mid/far range → homing.
+ * Uses dual-blink aggressively (gap-close during vulnerability, escape when trade is bad).
+ * HP-aware: ahead → aggressive close range; behind → defensive ranged kiting.
+ *
+ * KEY IMPROVEMENTS OVER WARMAGE:
+ * - Range-adaptive missiles: straight close, homing far
+ * - Vulnerability-timed blinks: gap-close during enemy cast/GCD
+ * - HP-aware aggression: adjusts distance + risk tolerance based on HP differential
+ * - Progressive cast-cancel: graduated thresholds
+ *
+ * PROGRESSION LINE: Battlemage → Warmage → Archmage
+ * TIER: 3 (elite Duelist line)
+ */
+declare const Archmage: WizardFunction;
+
+/**
+ * Bot: Stormchaser
+ *
+ * BEHAVIOR: Fights aggressively while managing defense intelligently. Uses
+ * two fixed missile configs (standard homing + quick attack) with predictive
+ * homing missile AI (interceptAngle on the missile itself). Blink-dodges
+ * incoming threats, shields when blink is on cooldown. Tight distance
+ * management (350 units, ±30 band).
+ *
+ * PROGRESSION LINE: Stormchaser → Stormcaller → Stormforger
+ * - Stormchaser (tier 1): Fixed missiles, predictive homing AI, blink-dodge
+ * - Stormcaller (tier 2): + fitMissileToBudget, predictive homing, optimized damage
+ * - Stormforger (tier 3): Future — supreme berserker, perfect aggression
+ *
+ * TIER: 1 (base)
+ */
+declare const Stormchaser: WizardFunction;
+
+/**
+ * Bot: Stormcaller
+ *
+ * BEHAVIOR: Enhanced Stormchaser with adaptive missile fitting (fitMissileToBudget)
+ * AND predictive homing missiles. Combines aggressive fighting philosophy with
+ * optimized damage output. Uses budget-based missile fitting to maximize damage
+ * within safe windows. Falls back to quick missiles under pressure. Same smart
+ * trade/shield decisions as Stormchaser but with better resource usage.
+ *
+ * PROGRESSION LINE: Stormchaser → Stormcaller → Stormforger
+ * - Stormchaser (tier 1): Adaptive missiles, smart trading, aggressive defense
+ * - Stormcaller (tier 2): + fitMissileToBudget, predictive homing, optimized damage
+ * - Stormforger (tier 3): Future — supreme berserker, perfect aggression
+ *
+ * TIER: 2 (enhanced Stormchaser)
+ */
+declare const Stormcaller: WizardFunction;
+
+/**
+ * Bot: Stormforger
+ *
+ * BEHAVIOR: Enhanced Stormcaller with vulnerability exploitation. Takes the exact
+ * Stormcaller foundation (adaptive missile fitting + predictive homing) and adds
+ * a punish mode that fires fast straight missiles when the enemy is locked in
+ * GCD or cast animation. During vulnerability windows, uses getLeadPosition for
+ * accurate straight shots that arrive before the enemy can react.
+ *
+ * PROGRESSION LINE: Stormchaser → Stormcaller → Stormforger
+ * - Stormchaser (tier 1): Adaptive missiles, smart trading, aggressive defense
+ * - Stormcaller (tier 2): + fitMissileToBudget, predictive homing, optimized damage
+ * - Stormforger (tier 3): + vulnerability exploitation, punish missiles during enemy GCD
+ *
+ * TIER: 3 (elite Berserker line)
+ */
+declare const Stormforger: WizardFunction;
+
+/**
+ * Bot: Spellspinner
+ *
+ * BEHAVIOR: Maintains medium range (350 units), strafes constantly to dodge
+ * missiles, and fires homing missiles (damage 10, speed 4, turnRate 2). Heavy
+ * emphasis on movement — 80% strafe intensity when not dodging, 100% when dodging.
+ * Shields only undodgeable threats, emergency blinks when shield isn't available.
+ * The constant circular strafing motion traces patterns like thread being spun.
+ *
+ * NAMING RATIONALE: Like a spider spinning a web of projectiles while circling its
+ * prey. The constant strafing movement pattern traces circles — spinning thread
+ * around the arena. "Spell" + "spinner" = a wizard who spins spells around the
+ * battlefield. The kiting behavior (maintaining distance while attacking) creates
+ * a web-like pattern of missiles and movement that traps opponents.
+ *
+ * PROGRESSION LINE: Spellspinner → Spellweaver → Spellbinder
+ * - Spellspinner (tier 1): Fixed homing missiles, constant strafe, basic defense
+ * - Spellweaver (tier 2): + adaptive missile fitting, more sophisticated patterns
+ * - Spellbinder (tier 3): Future — inescapable web of magic, perfect distance control
+ * The progression: spinner (raw thread) → weaver (creates patterns) → binder
+ * (constrains and traps). Each tier's projectile web becomes harder to escape.
+ *
+ * TIER: 1 (base)
+ */
+declare const Spellspinner: WizardFunction;
+
+/**
+ * Bot: Spellweaver
+ *
+ * BEHAVIOR: Enhanced Spellspinner with adaptive missile fitting. Same medium-range
+ * kiting playstyle — maintains distance, strafes heavily — but uses fitMissileToBudget
+ * to maximize damage within safe attack windows. Always uses homing missiles since
+ * kiting means enemies are always moving. More sophisticated than Spellspinner's
+ * fixed damage/speed/turnRate configuration.
+ *
+ * NAMING RATIONALE: A weaver creates intricate patterns from raw thread. Where the
+ * Spellspinner produces raw threads of magic (fixed missiles), the Spellweaver
+ * combines them into optimized patterns (adaptive fitting). The name suggests
+ * craftsmanship and sophistication — the same kiting web, but deliberately woven
+ * rather than chaotically spun.
+ *
+ * PROGRESSION LINE: Spellspinner → Spellweaver → Spellbinder
+ * - Spellspinner (tier 1): Fixed homing missiles, constant strafe, basic defense
+ * - Spellweaver (tier 2): + adaptive missile fitting, more sophisticated patterns
+ * - Spellbinder (tier 3): Future — inescapable web, perfect distance control
+ *
+ * TIER: 2 (enhanced Spellspinner)
+ */
+declare const Spellweaver: WizardFunction;
+
+/**
+ * Bot: Spellbinder
+ *
+ * BEHAVIOR: Enhanced Spellweaver with vulnerability exploitation. Same medium-range
+ * kiting playstyle — maintains distance, strafes heavily, uses fitMissileToBudget
+ * for adaptive homing missiles. The T3 upgrade adds a punish mode that fires fast
+ * straight missiles timed to land while the enemy is locked in a cast or GCD,
+ * when they cannot shield. Defense, movement, and standard offense are identical
+ * to Spellweaver.
+ *
+ * NAMING RATIONALE: A binder constrains and locks down opponents. Where the
+ * Spellweaver optimizes missile patterns (adaptive fitting), the Spellbinder
+ * reads the enemy's state and punishes vulnerability windows — binding them
+ * to their commitments with unavoidable damage.
+ *
+ * PROGRESSION LINE: Spellspinner → Spellweaver → Spellbinder
+ * - Spellspinner (tier 1): Fixed homing missiles, constant strafe, basic defense
+ * - Spellweaver (tier 2): + adaptive missile fitting, more sophisticated patterns
+ * - Spellbinder (tier 3): + vulnerability punish mode with fast straight missiles
+ *
+ * TIER: 3 (elite Spellspinner line)
+ */
+declare const Spellbinder: WizardFunction;
+
+/**
+ * VIBEMANCER - BOT REGISTRY
+ *
+ * Single source of truth for all bots, ordered from weakest to strongest.
+ * Run the tournament test to determine the correct ordering.
+ *
+ * To reorder: run `npx vitest run tests/bots/tournament.test.ts`
+ * and update the list below based on the results.
+ *
+ * BOT NAMING SCHEME (3-tier progression):
+ *
+ * | Group      | Tier 1 (base)  | Tier 2 (enhanced) | Tier 3 (elite)  |
+ * |------------|----------------|-------------------|-----------------|
+ * | Defensive  | Turtle         | Sentinel          | Golem           |
+ * | Duelist    | Battlemage     | Warmage           | Archmage        |
+ * | Homing     | Bonemancer     | Lich              | Archlich        |
+ * | Caster     | Flamecaller    | Pyromancer        | Infernalist     |
+ * | Melee      | Shadowblade    | Nightblade        | Voidblade       |
+ * | Sniper     | Spellshot      | Spelltracer       | Spellseeker     |
+ * | Berserker  | Stormchaser    | Stormcaller       | Stormforger     |
+ * | Kiter      | Spellspinner   | Spellweaver       | Spellbinder     |
+ *
+ * Standalone: TargetDummy, Critter, Hogger, Rookie, Doombringer
+ * Reserved: Spellslinger (future volume-of-fire archetype)
+ *
+ */
+
+interface BotEntry {
+    name: string;
+    ai: WizardFunction;
+    description: string;
+    tier?: number;
+    group: string;
+}
+interface BotGroup {
+    label: string;
+    bots: BotEntry[];
+}
+/**
+ * All bots organized by progression line.
+ * Each group contains bots from the same archetype, ordered by tier.
+ */
+declare const BOT_GROUPS: BotGroup[];
+declare const ALL_BOTS: BotEntry[];
+
+/**
+ * VIBEMANCER - STATE HOOKS
+ *
+ * React-style hooks for reading game state.
+ * These handle the "subconscious" perception that humans do instinctively.
+ *
+ * UNITS REFERENCE (100 ticks = 1 second):
+ *   Position:   absolute world coordinates, 0-800 on each axis (800×800 arena)
+ *   Velocity:   units per tick on each axis (player max speed = 1 u/t)
+ *   Health:     hit points (max 60)
+ *   Ticks:      game ticks (10ms each, 100/sec). Divide by 100 for seconds.
+ *   Shield:     block multiplier 0.0-0.9 (0.9 = blocks 90% damage)
+ */
+
+/**
+ * Get your current health (0-60). Wizard dies at 0.
+ */
+declare function useHealth(): number;
+/**
+ * Get your current position as {x, y} in world coordinates (0-800).
+ * Position is clamped to [5, 795] (arena bounds minus wizard radius).
+ */
+declare function usePosition(): Position;
+/**
+ * Get your current velocity as {x, y} in units/tick.
+ * Max magnitude is 1 u/t when idle, 0.5 u/t when casting, 0 when channeling shield.
+ */
+declare function useVelocity(): Velocity;
+/**
+ * Get your current status:
+ * - 'idle':        free to act
+ * - 'casting':     casting a spell (missile or blink). Can move at 50% speed.
+ * - 'channeling':  channeling shield. Cannot move. Cancel anytime with cancel().
+ * - 'gcd_locked':  global cooldown after spell. Can move at full speed, but cannot cast.
+ */
+declare function useStatus(): 'idle' | 'casting' | 'channeling' | 'gcd_locked';
+/**
+ * Get ticks until you can start a new spell.
+ *
+ * Returns 0 when idle or channeling (shield can be canceled immediately).
+ * During casting: remaining cast ticks. During GCD: remaining GCD ticks.
+ *
+ * Note: 100 ticks = 1 second.
+ */
+declare function useTicksUntilReady(): number;
+/**
+ * Get current shield block multiplier.
+ *
+ * Returns 0 if not channeling shield.
+ * Returns 0.3-0.9 if channeling: starts at 0.9 (blocks 90%), decays by 0.2/sec,
+ * minimum 0.3 (blocks 30%). The remaining damage gets through:
+ * actualDamage = incomingDamage × (1 - shieldStrength).
+ */
+declare function useShieldStrength(): number;
+/**
+ * Get blink cooldown remaining in ticks. Returns 0 if ready to blink.
+ *
+ * Cooldown scales with distance used:
+ * - 100 units → ~100 ticks (1s)
+ * - 300 units (max range) → 2000 ticks (20s)
+ *
+ * Note: 100 ticks = 1 second.
+ */
+declare function useBlinkCooldown(): number;
+/**
+ * Get currently casting spell, or null if not casting.
+ * Returns 'missile', 'shield', or 'blink'.
+ */
+declare function useCastingSpell(): 'missile' | 'shield' | 'blink' | null;
+/**
+ * Get cast progress as {current, total} in ticks, or null if not casting.
+ *
+ * current = ticks elapsed, total = ticks needed. When current >= total, spell fires.
+ * Note: 100 ticks = 1 second.
+ */
+declare function useCastProgress(): {
+    current: number;
+    total: number;
+} | null;
+/**
+ * Get enemy wizard state.
+ *
+ * Returns position, velocity, health, status, casting spell, and shield strength.
+ * Note: you cannot see the enemy's missile configs or exact cooldown timers —
+ * only their status and what's visible on the field.
+ */
+declare function useEnemy(): EnemyState;
+/**
+ * Get all your active (in-flight) projectiles.
+ * Each has position, rotation (degrees), speed (u/t), turnRate, remainingTicks.
+ */
+declare function useMyProjectiles(): ProjectileState[];
+/**
+ * Get total damage you've dealt this match.
+ */
+declare function useDamageDealt(): number;
+/**
+ * Get total damage you've taken this match.
+ */
+declare function useDamageTaken(): number;
+/**
+ * Get the tick number when you last took damage. Returns 0 if never hit.
+ * Compare with useTick() to get ticks since last hit.
+ */
+declare function useLastHitTick(): number;
+/**
+ * Get arena dimensions. Default: {width: 800, height: 800}.
+ * Wizards are clamped to [5, 795] on each axis (radius = 5).
+ */
+declare function useArenaSize(): {
+    width: number;
+    height: number;
+};
+/**
+ * Get current game tick (starts at 0, increments each tick).
+ * 100 ticks = 1 second. Match ends at 30,000 ticks (5 minutes).
+ */
+declare function useTick(): number;
+/**
+ * Get analyzed threats from all incoming enemy projectiles.
+ * Sorted by ticksToImpact (soonest first). Only includes missiles within 500 units
+ * or that are predicted to hit.
+ *
+ * Each threat includes:
+ * - ticksToImpact: ticks until hit (Infinity if will miss)
+ * - willHit: true if missile hits your current position
+ * - canDodgeLeft/Right: whether strafing perpendicular to missile heading works
+ * - canOutrun: whether moving away from missile escapes it
+ * - bestDodgeDirection: {x, y} unit vector to dodge optimally, or null if undodgeable
+ * - canBlockInTime: whether you can raise shield before impact
+ * - ticksToStartShield: when to START channeling shield to block in time
+ */
+declare function useThreats(): AnalyzedThreat[];
+/**
+ * Get the most imminent threat, or null if no threats.
+ * Shorthand for useThreats()[0].
+ */
+declare function useClosestThreat(): AnalyzedThreat | null;
+/**
+ * Get your missiles analyzed from the enemy's perspective.
+ * Useful to predict when enemy will shield/dodge your attacks.
+ */
+declare function useMyThreatsToEnemy(): AnalyzedThreat[];
+
+/**
+ * VIBEMANCER - THREAT ANALYSIS
+ *
+ * Pre-computes threat information for incoming projectiles.
+ * This handles the "subconscious" perception of missile trajectories.
+ */
+
+/**
+ * Analyze all threats from enemy projectiles.
+ *
+ * @param myPos - Current position of the wizard
+ * @param projectiles - All projectiles in the game
+ * @param myProjectiles - Only the bot's own projectiles (used for filtering)
+ * @param ticksUntilReady - Ticks until wizard can start a new action
+ * @returns Array of analyzed threats sorted by ticksToImpact (soonest first)
+ */
+declare function analyzeThreats(myPos: Position, projectiles: ProjectileState[], myProjectiles: ProjectileState[], ticksUntilReady: number): AnalyzedThreat[];
+
+/**
+ * VIBEMANCER - ACTION BUILDERS
+ *
+ * Fluent API for constructing bot actions with type-safe chaining.
+ *
+ * UNITS REFERENCE (100 ticks = 1 second):
+ *   Position:   absolute world coordinates, 0-800 on each axis (800×800 arena)
+ *   Movement:   direction vector, magnitude auto-normalized to max 100
+ *   Speed:      units per tick (player moves at 1 unit/tick = 100 units/sec)
+ *   Duration:   ticks (divide by 100 for seconds)
+ *   Angles:     degrees (0°=right, 90°=down, 180°=left, 270°=up)
+ *   Damage:     raw HP removed on hit (wizard has 60 HP)
+ *   Turn rate:  degrees per tick the missile can rotate
+ */
+
+/**
+ * Channel a shield that blocks incoming damage.
+ *
+ * Starts at 90% block, decays by 20% per second, minimum 30%.
+ * Takes 20 ticks (0.2s) to activate. Movement is disabled while channeling.
+ * Cancel anytime with cancel(). Triggers 100-tick (1s) GCD after cancel.
+ *
+ * Can chain .move() — movement applies during the 20-tick cast, NOT during channel.
+ *
+ * @example
+ *   return shield();                    // shield and stay still
+ *   return shield().move(100, 0);       // move right while cast starts
+ */
+declare function shield(): ActionBuilder;
+/**
+ * Cast a missile spell.
+ *
+ * Cast time scales with damage, speed, duration, and turn rate — bigger missiles
+ * take longer to cast. While casting you move at 50% speed. After firing, 100-tick
+ * (1s) GCD before next spell.
+ *
+ * Repeated similar missiles cast 20% faster (warmup bonus). Switching styles
+ * incurs a 20% penalty.
+ *
+ * Can chain .move() for simultaneous movement while casting.
+ *
+ * @param config - Missile stats:
+ *   - damage:   HP removed on hit (1-60 typical). Also sets hitbox: radius = 2 + 0.1×damage.
+ *   - speed:    units/tick (min 1.5). Player moves at 1 u/t, so 5 = 5× player speed.
+ *   - duration: ticks the missile lives (min 10). Range ≈ speed × duration.
+ *   - turnRate: degrees/tick of homing (0 = straight line, 3 = moderate homing, 5+ = strong).
+ *              Negative = no homing + minor speed cost reduction.
+ * @param ai - Called every tick to control missile steering. Receives:
+ *   - missileState: the missile's position, rotation (degrees), speed, remainingTicks
+ *   - worldState:   full game state (all wizards, projectiles)
+ *   - random():     seeded PRNG [0, 1)
+ *   Return { turnToward: {x, y} } to home toward a position, or {} to fly straight.
+ * @param direction - Launch angle in degrees (0°=right, 90°=down, 180°=left, 270°=up).
+ *   Tip: use Math.atan2(dy, dx) * (180 / Math.PI) to aim at a target.
+ *
+ * @example
+ *   // Straight missile aimed at enemy
+ *   const angle = Math.atan2(dy, dx) * (180 / Math.PI);
+ *   return missile({damage: 15, speed: 6, duration: 200, turnRate: 0}, () => ({}), angle);
+ *
+ *   // Homing missile that tracks enemy
+ *   return missile(
+ *     {damage: 10, speed: 5, duration: 300, turnRate: 3},
+ *     ({worldState}) => ({turnToward: worldState.enemies[0]?.position}),
+ *     angle,
+ *   );
+ */
+declare function missile(config: MissileConfig, ai: MissileAIFunction, direction: number): ActionBuilder;
+/**
+ * Teleport to an absolute position on the arena.
+ *
+ * Max range: 300 units from current position (clamped by engine if further).
+ * Cast time: 10 ticks (0.1s). Cooldown scales with distance:
+ *   - 100 units → 100 ticks (1s)
+ *   - 300 units → 2000 ticks (20s)
+ *
+ * Cannot chain .move() — blink IS the movement.
+ *
+ * @param x - Target X position (0-800, absolute world coordinate)
+ * @param y - Target Y position (0-800, absolute world coordinate)
+ *
+ * @example
+ *   return blink(400, 400);                              // blink to center
+ *   return blink(enemy.position.x, enemy.position.y);    // blink to enemy
+ */
+declare function blink(x: number, y: number): FinalAction;
+/**
+ * Cancel current cast or channel (e.g. stop shielding to attack).
+ *
+ * Canceling a cast/channel triggers 100-tick (1s) GCD.
+ * Can chain .move() for simultaneous movement.
+ *
+ * @example
+ *   return cancel().move(-100, 0);  // cancel and dodge left
+ */
+declare function cancel(): ActionBuilder;
+/**
+ * Move in a direction without casting any spell.
+ *
+ * This is a **direction vector**, not a target position. The engine normalizes
+ * the magnitude to max 100, then moves at 1 unit/tick (100 units/sec).
+ * Positive X = right, positive Y = down.
+ *
+ * To move toward a target position, subtract your position:
+ *   move(target.x - myPos.x, target.y - myPos.y)
+ *
+ * @param x - Horizontal direction (positive = right, negative = left)
+ * @param y - Vertical direction (positive = down, negative = up)
+ *
+ * @example
+ *   return move(100, 0);                                       // move right
+ *   return move(enemy.position.x - myPos.x, enemy.position.y - myPos.y);  // move toward enemy
+ */
+declare function move(x: number, y: number): FinalAction;
+/**
+ * Do nothing — no action, no movement.
+ */
+declare function idle(): FinalAction;
+/**
+ * Extract WizardActions from a FinalAction.
+ * Used by the engine to get the actual action.
+ */
+declare function extractAction(finalAction: FinalAction): WizardActions;
+
+/**
+ * VIBEMANCER - BOT WRAPPER
+ *
+ * Utilities to convert between old-style (WizardFunction) and new-style (BotFunction) bots.
+ */
+
+/**
+ * Convert a new-style bot (using hooks) to an old-style bot (WizardFunction).
+ *
+ * This allows new bots to work with the existing simulation.
+ *
+ * @example
+ * const NewBot: BotFunction = () => {
+ *   const health = useHealth();
+ *   return health < 10 ? shield() : idle();
+ * };
+ *
+ * // Convert to work with simulate()
+ * const oldStyleBot = wrapNewBot(NewBot);
+ * simulate(oldStyleBot, opponent);
+ */
+declare function wrapNewBot(newBot: BotFunction): WizardFunction;
+/**
+ * Type guard to check if a bot is a new-style BotFunction.
+ * New-style bots have 0 parameters, old-style bots have at least 1.
+ */
+declare function isNewStyleBot(bot: WizardFunction | BotFunction): bot is BotFunction;
+
+/**
+ * VIBEMANCER - PARAMETER RUNTIME
+ *
+ * Provides the useParam() hook for bots to declare tunable parameters,
+ * and the infrastructure for the optimizer to inject/discover parameter values.
+ *
+ * Design: Module-level state (JS is single-threaded, no race conditions).
+ * The optimizer sets param values before running a bot, and clears them after.
+ * During discovery, all useParam calls are recorded.
+ *
+ * ## useParam API
+ *
+ * ```typescript
+ * // Basic: just a value, no optimizer config
+ * const damage = useParam('damage', 15);
+ *
+ * // With range: optimizer searches value ± range (sliding window)
+ * const distance = useParam('distance', 350, {range: 150, min: 0});
+ *
+ * // With fixed min/max: optimizer searches [min, max] (fixed bounds)
+ * const damage = useParam('damage', 15, {min: 5, max: 25});
+ *
+ * // With all: range defines search radius, min/max clamp it
+ * const fraction = useParam('fraction', 0.25, {range: 0.2, min: 0, max: 1});
+ *
+ * // With custom step count: optimizer tests 20 values instead of default 10
+ * const distance = useParam('distance', 500, {range: 200, min: 0, steps: 20});
+ * ```
+ *
+ * - **Arg 1** `name` — unique parameter name (must be consistent across ticks)
+ * - **Arg 2** `value` — the actual value used in gameplay. This is what your bot
+ *   uses during matches. The optimizer script automatically updates this value.
+ * - **Arg 3** `config` (optional) — optimizer search configuration:
+ *   - `range` — search radius: optimizer checks `value ± range`. The auto-optimizer
+ *     rewrites `value` after each run, so the search window slides automatically.
+ *   - `min` / `max` — hard constraints (e.g., distance ≥ 0, fraction ≤ 1).
+ *     When `range` is omitted, these define fixed search bounds (old-style).
+ *   - `steps` — how many evenly-spaced values the optimizer tests per pass (default: 10).
+ *   - `substeps` — steps to use in refinement passes (passes 2+). Set to 0 to freeze
+ *     after pass 1 (ideal for boolean params). Defaults to `steps` if not specified.
+ *   - At least `range` or both `min` + `max` must be provided.
+ *
+ * Without optimizer config, useParam simply returns `value` every tick.
+ * With optimizer config, the offline optimizer script can override the value during search.
+ *
+ * ## Rules of Hooks
+ * useParam follows the same rules as useState/useEffect/etc:
+ * - Must be called at the top level of your bot function (not inside conditionals)
+ * - Must be called in the same order every tick
+ * - Violations are detected and throw errors
+ */
+
+/**
+ * Declaration of a tunable parameter, as discovered by the optimizer.
+ */
+interface ParamDeclaration {
+    name: string;
+    value: number;
+    range?: number;
+    min?: number;
+    max?: number;
+    steps: number;
+    /** Steps to use in refinement passes (passes 2+). 0 = freeze after pass 1. Defaults to `steps`. */
+    substeps?: number;
+}
+/**
+ * Declare a tunable parameter. Returns the current value (optimizer-injected or the provided value).
+ *
+ * @param name - Unique parameter name (consistent across ticks)
+ * @param value - The gameplay value. The auto-optimizer rewrites this in source code.
+ * @param config - Optional optimizer search configuration
+ * @returns The optimizer-injected value during optimization, or `value` during normal play
+ *
+ * @example
+ * // Simple: no optimizer config
+ * const damage = useParam('damage', 15);
+ *
+ * // With range: optimizer searches value ± range (sliding window)
+ * const distance = useParam('distance', 350, {range: 150, min: 0});
+ *
+ * // With fixed min/max: optimizer searches [min, max]
+ * const damage = useParam('damage', 15, {min: 5, max: 25});
+ */
+declare function useParam(name: string, value: number, config?: {
+    range?: number;
+    min?: number;
+    max?: number;
+    steps?: number;
+    substeps?: number;
+}): number;
+/**
+ * Inject parameter values for the next bot execution.
+ * The wrapped bot will read these values via useParam().
+ */
+declare function setParamValues(values: Record<string, number>): void;
+/**
+ * Clear injected parameter values. useParam() will return its provided value.
+ */
+declare function clearParamValues(): void;
+/**
+ * Start discovery mode. All subsequent useParam() calls with optimizer config
+ * will register their declarations.
+ */
+declare function startDiscovery(): void;
+/**
+ * Stop discovery mode and return all discovered parameter declarations.
+ */
+declare function stopDiscovery(): ParamDeclaration[];
+/**
+ * Wrap a bot function to inject specific parameter values.
+ * The returned function sets params before calling the bot and clears them after.
+ */
+declare function wrapWithParams(bot: WizardFunction, params: Record<string, number>): WizardFunction;
+
+/**
+ * VIBEMANCER - OPTIMIZER UTILITIES
+ *
+ * Core functions used by the offline parameter optimizer script.
+ * These handle combo generation, range narrowing, and fight scoring.
+ *
+ * The optimizer uses multi-pass coordinate descent:
+ * - Pass 1: Coarse search across the effective range for each param
+ * - Pass 2+: Fine search zoomed into the neighborhood of the best result
+ *
+ * Parameters can define their search window two ways:
+ * - `range`: sliding window centered on current value (value ± range)
+ * - `min`/`max`: fixed bounds (old-style)
+ *
+ * Both can be combined: range defines the search radius, min/max clamp it.
+ */
+
+/**
+ * Compute the effective min/max search window for a parameter.
+ *
+ * - If `range` is set: window is `[value - range, value + range]`, clamped by optional min/max
+ * - If only `min`/`max` are set: window is `[min, max]` directly
+ * - If neither: returns `[value, value]` (no search)
+ */
+declare function getEffectiveRange(p: ParamDeclaration): {
+    min: number;
+    max: number;
+};
+/**
+ * Generate evenly-spaced candidate values for a single parameter.
+ *
+ * Divides [min, max] into `steps` evenly-spaced values. For example,
+ * min=0, max=100, steps=5 produces [0, 25, 50, 75, 100].
+ *
+ * @param min - Lower bound of search range
+ * @param max - Upper bound of search range
+ * @param steps - Number of evenly-spaced values to generate (minimum 2)
+ * @returns Array of candidate values, sorted ascending
+ */
+declare function generateCandidates(min: number, max: number, steps: number): number[];
+/**
+ * Generate all combinations (cartesian product) of candidate values for multiple params.
+ *
+ * For N params with S1, S2, ... SN steps each, produces S1 × S2 × ... × SN combinations.
+ * Each combination is a Record<string, number> mapping param name to value.
+ *
+ * @param params - Parameter declarations with search ranges and step counts
+ * @returns Array of all parameter combinations to evaluate
+ */
+declare function generateCombos(params: ParamDeclaration[]): Record<string, number>[];
+/**
+ * Narrow parameter ranges around the best combo found in the previous pass.
+ *
+ * Centers each param on its best value and shrinks the search range to one gap width.
+ * This provides finer resolution in subsequent passes. Hard min/max constraints are preserved.
+ *
+ * @param params - Original parameter declarations
+ * @param best - Best parameter combination from the previous pass
+ * @returns New parameter declarations with narrowed ranges for the next pass
+ */
+declare function narrowRange(params: ParamDeclaration[], best: Record<string, number>): ParamDeclaration[];
+/**
+ * Score a FightResult from one bot's perspective.
+ *
+ * Returns a continuous score that provides gradient information beyond binary win/loss:
+ * - Win: 3.0 base + up to 0.5 HP bonus (higher remaining HP = better)
+ * - Draw: 1.0
+ * - Loss: 0.0 base + up to 0.5 bonus for low enemy HP (closer fights = better)
+ *
+ * For a mirrored fight set (bot as wizard-1 AND wizard-2), call this twice
+ * and sum the scores for a balanced evaluation.
+ *
+ * @param result - The fight result to score
+ * @returns Continuous score in range [0, 3.5] per match
+ */
+declare function scoreFight(result: FightResult): number;
+/**
+ * Score a FightResult from wizard-2's perspective.
+ * Same scoring logic as scoreFight but with roles reversed.
+ *
+ * Use this for tournaments where both sides of a pairing need scoring.
+ */
+declare function scoreFightAsWizard2(result: FightResult): number;
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+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.
+ */
+type WorkerFactory = (code: string) => {
+    worker: WorkerLike;
+    cleanup?: () => void;
+};
+/**
+ * Options for browser sandbox creation.
+ */
+interface BrowserSandboxOptions {
+    /** Timeout in ms for fight/simulate calls (default: 30000). */
+    timeoutMs?: number;
+    /** Custom worker factory for dependency injection (testing). */
+    createWorker?: WorkerFactory;
+}
+/**
+ * Create the full worker script from a compiled match bundle.
+ * Appends the message-handling bootstrap to the bundle IIFE.
+ */
+declare function createWorkerScript(bundle: string): string;
+/**
+ * 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();
+ * ```
+ */
+declare class BrowserMatchSandbox {
+    private worker;
+    private workerCleanup;
+    private timeout;
+    private disposed;
+    private nextId;
+    private pending;
+    private messageHandler;
+    private errorHandler;
+    private constructor();
+    /**
+     * 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 fromBundle(bundle: string, options?: BrowserSandboxOptions): Promise<BrowserMatchSandbox>;
+    /**
+     * Wait for the worker to post {type: 'ready'}, then attach permanent handlers.
+     */
+    private waitForReady;
+    /**
+     * Extract message data from a browser MessageEvent or raw Node.js data.
+     */
+    private unwrapEvent;
+    /**
+     * Attach permanent message and error handlers for fight/simulate responses.
+     */
+    private attachHandlers;
+    /**
+     * Run a full fight (10 matches: 5 spawn distances x 2 sides).
+     * Returns a Promise because Worker communication is async.
+     */
+    fight(options?: {
+        seed?: number;
+        maxTicks?: number;
+    }): 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)
+     */
+    simulate(options?: {
+        seed?: number;
+        maxTicks?: number;
+        spawnDistance?: number;
+        skipHistory?: boolean;
+        params1?: Record<string, number>;
+        params2?: Record<string, number>;
+    }): Promise<SimulateResult>;
+    /**
+     * Dispose the worker and free all resources.
+     * The sandbox cannot be used after disposal.
+     */
+    dispose(): void;
+    /**
+     * Whether this sandbox has been disposed.
+     */
+    get isDisposed(): boolean;
+    /**
+     * 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>;
+    /**
+     * 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;
+    private ensureNotDisposed;
+}
+/**
+ * One-shot browser-sandboxed fight. Creates worker, runs fight, disposes.
+ */
+declare function browserSandboxFight(bundle: string, options?: {
+    seed?: number;
+    maxTicks?: number;
+} & BrowserSandboxOptions): Promise<FightResult>;
+/**
+ * One-shot browser-sandboxed simulate. Creates worker, runs simulate, disposes.
+ */
+declare function browserSandboxSimulate(bundle: string, options?: {
+    seed?: number;
+    maxTicks?: number;
+    spawnDistance?: number;
+    skipHistory?: boolean;
+    params1?: Record<string, number>;
+    params2?: Record<string, number>;
+} & BrowserSandboxOptions): Promise<SimulateResult>;
+/**
+ * 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.
+ */
+interface ManualMatchInitOptions {
+    seed?: number;
+    spawnDistance?: number;
+    maxTicks?: number;
+    initialHumanActions?: WizardActions;
+}
+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();
+ * ```
+ */
+declare class BrowserManualMatchSandbox {
+    private readonly inner;
+    private constructor();
+    /**
+     * 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 fromBundle(bundle: string, options?: BrowserSandboxOptions): Promise<BrowserManualMatchSandbox>;
+    /**
+     * Initialize the worker-side ManualMatch instance.
+     * Returns the initial GameState (tick 0).
+     */
+    init(options?: ManualMatchInitOptions): Promise<GameState>;
+    /**
+     * Advance the match by `request.count` ticks (default 1), updating
+     * the player's human actions and any hijacked missile targets first.
+     */
+    step(request?: ManualMatchStepRequest): 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.
+     */
+    hijackMissile(projectileId: string): Promise<void>;
+    /**
+     * Restore a hijacked missile's original AI.
+     */
+    releaseMissile(projectileId: string): Promise<void>;
+    /**
+     * Toggle invincibility for a wizard.
+     */
+    setInvincible(wizardIndex: 0 | 1, on: boolean): Promise<void>;
+    /**
+     * Get the current game state without advancing.
+     */
+    getState(): Promise<GameState>;
+    /**
+     * Get the full SimulateResult-compatible result object (history + winner).
+     */
+    getResult(): Promise<SimulateResult>;
+    /**
+     * Dispose the worker-side ManualMatch instance. Does NOT terminate the
+     * worker — call dispose() for that.
+     */
+    resetMatch(): Promise<void>;
+    /**
+     * Terminate the worker and free all resources.
+     */
+    dispose(): void;
+    get isDisposed(): boolean;
+}
+
+/**
+ * VIBEMANCER - FIGHT STATISTICS
+ *
+ * Extracts detailed per-bot statistics from a SimulateResult history.
+ * Used by testBot().simulate() and vibemancer trace for debugging.
+ */
+
+/** Detailed statistics for one bot in a single match. */
+interface FightStats {
+    /** Total damage dealt to the opponent. */
+    damageDealt: number;
+    /** Total damage taken from the opponent. */
+    damageTaken: number;
+    /** Number of missiles launched. */
+    missilesLaunched: number;
+    /** Number of missiles that dealt damage (hit the opponent). */
+    missileHits: number;
+    /** Hit rate (0-1). NaN if no missiles fired. */
+    hitRate: number;
+    /** Number of our missiles that hit while enemy was shielding. */
+    hitsEnemyShielded: number;
+    /** Number of our missiles that hit while enemy had no shield. */
+    hitsEnemyUnshielded: number;
+    /** Total raw damage our missiles would have dealt without shields. */
+    rawDamageDealt: number;
+    /** Damage blocked by enemy shields. */
+    damageBlockedByEnemy: number;
+    /** Percentage of our raw damage blocked by enemy shields (0-1). */
+    enemyBlockRate: number;
+    /** Number of times we were hit by enemy missiles. */
+    hitsReceived: number;
+    /** Number of hits received while shield was channeling. */
+    hitsShielded: number;
+    /** Number of hits received without shield. */
+    hitsUnshielded: number;
+    /** Total raw damage that hit us (before shield reduction). */
+    rawDamageReceived: number;
+    /** Total damage blocked by shields. */
+    damageBlocked: number;
+    /** Percentage of incoming raw damage that was blocked (0-1). */
+    blockRate: number;
+    /** Ticks spent in 'casting' state. */
+    castingTicks: number;
+    /** Ticks spent channeling shield. */
+    shieldTicks: number;
+    /** Ticks spent in GCD lockout. */
+    gcdTicks: number;
+    /** Ticks spent idle (not casting, channeling, or in GCD). */
+    idleTicks: number;
+    /** Number of times shield was activated. */
+    shieldCount: number;
+    /** Number of times blink was used. */
+    blinkCount: number;
+    /** Total match duration in ticks. */
+    totalTicks: number;
+}
+/**
+ * Extract fight statistics from a SimulateResult.
+ * Returns stats for wizard-1 (the bot under test).
+ */
+declare function extractStats(result: SimulateResult): FightStats;
+/** Format stats as a human-readable summary string. */
+declare function formatStats(stats: FightStats, botName: string): string;
+
+/**
+ * VIBEMANCER - TESTING UTILITIES
+ *
+ * Helpers for writing automated tests for your bot.
+ * Import from '@vibemancer/core' in your test files.
+ *
+ * @example
+ * import {testBot} from '@vibemancer/core';
+ * import {MyWizard} from '../src/bot';
+ *
+ * test('beats TargetDummy', async () => {
+ *   const result = await testBot(MyWizard).fight('TargetDummy');
+ *   expect(result.won).toBe(true);
+ * });
+ */
+
+/** Result of a testBot().fight() call with convenience accessors. */
+interface TestFightResult {
+    /** The raw FightResult from the simulation engine. */
+    raw: FightResult;
+    /** Overall winner: 'wizard-1' | 'wizard-2' | 'draw'. */
+    winner: FightWinner;
+    /** True if your bot won the fight. */
+    won: boolean;
+    /** True if your bot lost the fight. */
+    lost: boolean;
+    /** True if the fight was a draw. */
+    drawn: boolean;
+    /** Number of individual matches your bot won (out of 10). */
+    wins: number;
+    /** Number of individual matches your bot lost (out of 10). */
+    losses: number;
+    /** Number of individual matches that were draws. */
+    draws: number;
+}
+/** Result of a testBot().simulate() call with convenience accessors. */
+interface TestSimulateResult {
+    /** The raw SimulateResult from the simulation engine. */
+    raw: SimulateResult;
+    /** Match winner. */
+    winner: MatchWinner;
+    /** True if your bot won. */
+    won: boolean;
+    /** True if your bot lost. */
+    lost: boolean;
+    /** True if the match was a draw or timeout. */
+    drawn: boolean;
+    /** Number of ticks the match lasted. */
+    ticks: number;
+    /** Your bot's remaining HP. */
+    myHealth: number;
+    /** Enemy's remaining HP. */
+    enemyHealth: number;
+    /** Detailed fight statistics (missiles, damage, shield usage, time breakdown). */
+    stats: FightStats;
+    /** Runtime errors thrown by bot or missile AI (empty if none). */
+    errors: Array<{
+        tick: number;
+        entityId: string;
+        message: string;
+    }>;
+}
+/** Builder returned by testBot(). */
+interface TestBotBuilder {
+    /**
+     * Run a full fight (10 matches) against a named built-in bot.
+     * @param opponent - Built-in bot name (e.g., 'Battlemage', 'TargetDummy').
+     */
+    fight(opponent: string, options?: {
+        seed?: number;
+    }): TestFightResult;
+    /**
+     * Run a single match against a named built-in bot.
+     * @param opponent - Built-in bot name.
+     */
+    simulate(opponent: string, options?: {
+        seed?: number;
+        spawnDistance?: number;
+        maxTicks?: number;
+    }): TestSimulateResult;
+}
+/**
+ * Create a test builder for your bot.
+ *
+ * @param bot - Your bot function (the same function you export from src/bot.ts).
+ * @returns A builder with .fight() and .simulate() methods.
+ *
+ * @example
+ * ```ts
+ * import {testBot} from '@vibemancer/core';
+ * import {MyWizard} from '../src/bot';
+ *
+ * test('beats TargetDummy', () => {
+ *   const result = testBot(MyWizard).fight('TargetDummy');
+ *   expect(result.won).toBe(true);
+ * });
+ *
+ * test('survives 10 seconds against Battlemage', () => {
+ *   const result = testBot(MyWizard).simulate('Battlemage', {maxTicks: 1000});
+ *   expect(result.myHealth).toBeGreaterThan(0);
+ * });
+ *
+ * test('kills at close range', () => {
+ *   const result = testBot(MyWizard).simulate('TargetDummy', {spawnDistance: 200});
+ *   expect(result.won).toBe(true);
+ *   expect(result.ticks).toBeLessThan(1000);
+ * });
+ * ```
+ */
+declare function testBot(bot: WizardFunction | BotFunction): TestBotBuilder;
+
+/**
+ * VIBEMANCER - FIGHT TRACE
+ *
+ * Extracts a structured event log from a SimulateResult history.
+ * Both bots' actions are tracked: state changes, missile launches with
+ * full config, hits, damage, dodge proximity, movement patterns.
+ *
+ * Used by:
+ * - vibemancer trace (CLI debug command)
+ * - scripts/fight-trace.ts (internal diagnostic)
+ * - User tests that want event-level analysis
+ */
+
+interface TraceEvent {
+    tick: number;
+    /** 'W1' = wizard-1, 'W2' = wizard-2 */
+    actor: 'W1' | 'W2';
+    type: TraceEventType;
+    detail: string;
+}
+type TraceEventType = 'STATE' | 'FIRE' | 'HIT' | 'HURT' | 'DODGE_START' | 'DODGE_CLOSE' | 'MOVE' | 'ERROR' | 'WARNING';
+interface TraceSummary {
+    winner: string;
+    ticks: number;
+    w1Name: string;
+    w2Name: string;
+    w1FinalHp: number;
+    w2FinalHp: number;
+    w1: TraceBotSummary;
+    w2: TraceBotSummary;
+}
+interface TraceBotSummary {
+    missilesLaunched: number;
+    hits: number;
+    damageDealt: number;
+    damageReceived: number;
+    shields: number;
+    blinks: number;
+    dodgeEncounters: number;
+    movement: {
+        strafe: number;
+        approach: number;
+        retreat: number;
+        still: number;
+    };
+}
+/**
+ * Extract a structured event log from simulation history.
+ * Tracks both bots' state changes, missile launches (with full config + range),
+ * hits, damage, dodge proximity, movement patterns, and runtime errors.
+ */
+declare function extractTraceEvents(history: GameState[], errors?: BotError[]): TraceEvent[];
+/**
+ * Generate a summary from trace events and the simulation result.
+ */
+declare function summarizeTrace(events: TraceEvent[], result: SimulateResult, w1Name: string, w2Name: string): TraceSummary;
+/** Format trace events as a human-readable string. */
+declare function formatTraceEvents(events: TraceEvent[]): string;
+/** Format a full trace summary as a human-readable string. */
+declare function formatTraceSummary(summary: TraceSummary): string;
+/**
+ * Generate diagnostic tips based on trace analysis.
+ * Identifies common problems and suggests fixes.
+ * Returns an array of human-readable tips (empty if no issues found).
+ */
+declare function diagnoseTrace(events: TraceEvent[], summary: TraceSummary): string[];
+/** Format diagnostic tips as a human-readable string. */
+declare function formatDiagnosis(tips: string[]): string;
+
+export { ALL_BOTS, ARENA_HEIGHT, ARENA_SIZE, ARENA_WATER_BUFFER, ARENA_WIDTH, type ActionBuilder, type AnalyzedThreat, type AntiHomingParams, Archlich, Archmage, BLINK_CAST_TIME, BLINK_COOLDOWN, BLINK_MAX_COOLDOWN, BLINK_MAX_RANGE, BLINK_MIN_COOLDOWN, BLINK_RANGE, BOT_GROUPS, Battlemage, Bonemancer, type BotContext, type BotEntry, type BotError, type BotFunction, type BotGroup, BrowserManualMatchSandbox, BrowserMatchSandbox, type BrowserSandboxOptions, CASTING_MOVEMENT_MULT, COLLISION_RADIUS, Critter, Doombringer, ENGINE_VERSION, type EnemyState, FIGHT_SPAWN_DISTANCES, type FightResult, type FightStats, type FightWinner, type FinalAction, Flamecaller, GCD_DURATION, type GameConfig, type GameState, Golem, Hogger, type HomingParams, type HookState, Infernalist, type InternalWizardState, Lich, MATCH_DURATION, MAX_HEALTH, MISSILE_BASE_CAST, MISSILE_BASE_RADIUS, MISSILE_DAMAGE_POWER, MISSILE_DAMAGE_RADIUS_SCALE, MISSILE_DAMAGE_SCALE, MISSILE_HOMING_COEFF, MISSILE_MIN_CAST_TIME, MISSILE_MIN_DAMAGE, MISSILE_MIN_DURATION, MISSILE_MIN_SPEED, MISSILE_RADIUS_PER_DAMAGE, MISSILE_SPEED_DURATION_BASELINE, MISSILE_SPEED_DURATION_COEFF, MISSILE_TURN_DURATION_COEFF, MOVEMENT_SPEED, MOVE_SPEED, ManualMatch, type ManualMatchInitOptions, type ManualMatchOptions, type ManualMatchStepRequest, type MatchWinner, type MissileAIFunction, type MissileActions, type MissileConfig, type MissileTemplate, Nightblade, type ParamDeclaration, type Position, type ProjectileState, Pyromancer, type RefObject, Rookie, SHIELD_CAST_TIME, SHIELD_DECAY_PER_SECOND, SHIELD_DECAY_RATE, SHIELD_MAX_BLOCK, SHIELD_MAX_STRENGTH, SHIELD_MIN_BLOCK, SHIELD_MIN_STRENGTH, SPAWN_DISTANCE, type SeekerParams, Sentinel, Shadowblade, type SimulateResult, Spellbinder, Spellseeker, Spellshot, Spellspinner, Spelltracer, Spellweaver, type SpiralParams, type StepResult, Stormcaller, Stormchaser, Stormforger, type StraightParams, TICKS_PER_SECOND, TICK_DURATION_MS, TargetDummy, type TestBotBuilder, type TestFightResult, type TestSimulateResult, type TraceBotSummary, type TraceEvent, type TraceEventType, type TraceSummary, Turtle, type Velocity, Voidblade, WARMUP_DURATION_TOLERANCE, WARMUP_MAX_BONUS, WARMUP_MAX_PENALTY, WARMUP_SPEED_TOLERANCE, WARMUP_TURN_TOLERANCE, WIZARD_HEALTH, WIZARD_RADIUS, Warmage, type WizardActions, type WizardFunction, type WizardState, type WorkerFactory, type WorkerLike, analyzeThreats, angleDiff, angleInRange, angleTo, antiHomingMissile, applyDamage, blink, browserSandboxFight, browserSandboxSimulate, calculateBlinkCooldown, calculateMissileCastTime, calculateMissileRadius, calculateMissileSimilarity, calculateShieldBlock, calculateWarmupMultiplier, cancel, cancelCast, clampPositionToArena, clampToArena, clearHooks, clearParamValues, completeCast, createEntitySeed, createInitialState, createRandom, createWorkerScript, diagnoseTrace, directionAway, directionTo, distanceTo, effectiveTurnRateCost, extractAction, extractStats, extractTraceEvents, fight, findInRange, findNearest, fitMissileToBudget, formatDiagnosis, formatStats, formatTraceEvents, formatTraceSummary, generateCandidates, generateCombos, getAdaptiveMissileConfig, getBotContext, getEffectiveRange, getLeadPosition, getMissileCastTime, getPlayerState, hashCombine, homingMissile, idle, inRange, interceptAngle, isNewStyleBot, magnitude, missile, move, moveInDirection, moveProjectile, moveWizard, narrowRange, nextRandom, normalize, normalizeAngle, predictPosition, resetAllHooks, resolveWizardCollision, runBotWithContext, runWithHooks, scoreFight, scoreFightAsWizard2, seekerMissile, setParamValues, shield, simulate, sortByDistance, spiralMissile, startCast, startDiscovery, stopDiscovery, straightMissile, summarizeTrace, sweptCircleCollision, testBot, tick, updateShield, useArenaSize, useBlinkCooldown, useCastProgress, useCastingSpell, useClosestThreat, useDamageDealt, useDamageTaken, useEffect, useEnemy, useHealth, useLastHitTick, useMemo, useMyProjectiles, useMyThreatsToEnemy, useParam, usePosition, useRef, useShieldStrength, useState, useStatus, useThreats, useTick, useTicksUntilReady, useVelocity, validateHookCall, validateMissileConfig, withBotContext, wrapNewBot, wrapWithParams };