@vibemancer/core 0.1.4 → 0.1.6

package/dist/index-browser.d.ts

@@ -1,3 +1,178 @@
+/**
+ * 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;
+    /** Cast progress in ticks (0 if not casting). */
+    castProgress: number;
+    /** Total cast duration in ticks (0 if not casting). */
+    castDuration: number;
+    /** Remaining GCD ticks (0 if not in GCD). */
+    gcdRemaining: number;
+    /** Duration the enemy has been channeling in ticks (0 if not channeling). */
+    channelDuration: number;
+    /** 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;
+}
+/**
+ * Wizard function type for the hooks API.
+ * Called every tick. Read state with hooks, return an action.
+ */
+type WizardFunction = () => FinalAction;
+/**
+ * Internal context for game state hooks.
+ */
+interface WizardContext {
+    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;
+    lastMissileConfig?: MissileConfig;
+    enemies: Array<{
+        id: string;
+        position: Position;
+        velocity: Velocity;
+        health: number;
+        state: 'idle' | 'casting' | 'channeling' | 'gcd_locked';
+        castingSpell?: 'missile' | 'shield' | 'blink';
+        castProgress?: number;
+        castDuration?: number;
+        gcdRemaining?: number;
+        channelingSpell?: 'shield';
+        channelDuration?: number;
+    }>;
+    projectiles: ProjectileState[];
+    myProjectiles: ProjectileState[];
+    arenaWidth: number;
+    arenaHeight: number;
+    damageDealt: number;
+    damageTaken: number;
+    lastHitTick: number;
+    random: () => number;
+}
+/**
+ * Context available to missile AI functions via getMissileContext().
+ * Provides missile state, the full game state from the owner's perspective,
+ * and a seeded PRNG.
+ */
+interface MissileContext {
+    /** Missile position in world coordinates. */
+    position: Position;
+    /** Missile heading in degrees (0=right, 90=down). */
+    rotation: number;
+    /** Missile speed in units/tick. */
+    speed: number;
+    /** Missile turn rate in degrees/tick. */
+    turnRate: number;
+    /** Missile damage on hit. */
+    damage: number;
+    /** Ticks remaining before the missile expires. */
+    remainingTicks: number;
+    /** ID of the wizard who owns this missile. */
+    ownerId: string;
+    /** Full game state from the missile owner's perspective. */
+    worldState: GameState;
+    /** Seeded PRNG [0, 1). Deterministic per missile per tick. */
+    random: () => number;
+}
+/**
+ * Action returned by a missile AI function.
+ * Call turnToward(x, y) to steer, or flyStraight() to coast.
+ */
+interface MissileAction {
+    /** Internal: extract the MissileActions */
+    readonly _toMissileAction: () => MissileActions;
+}
+/**
+ * Missile AI function type for the hooks API.
+ * Called every tick for each in-flight missile.
+ * Read state with getMissileContext(), return a MissileAction.
+ */
+type MissileFunction$1 = () => MissileAction;
+
 /**
  * VIBEMANCER - TYPES
  *
@@ -90,6 +265,8 @@ interface GameState {
     damageDealt: number;
     damageTaken: number;
     lastHitTick: number;
+    /** Events emitted during the most recent tick (empty for the initial state). */
+    events: SimEvent[];
 }
 /**
  * Actions returned by wizard each tick.
@@ -116,7 +293,7 @@ interface WizardActions {
     startCast?: {
         spell: 'missile';
         config: MissileConfig;
-        missileAI: MissileAIFunction;
+        missileAI: MissileFunction;
         direction?: number;
     } | {
         spell: 'shield';
@@ -134,6 +311,22 @@ interface WizardActions {
      * Only applies while state === 'casting' and castingSpell === 'missile'.
      */
     aimDirection?: number;
+    /**
+     * Missile guide — manual play mode only. Takes direct control of a
+     * specific missile using WASD/joystick input. While active, the wizard
+     * is invulnerable and frozen (move ignored), and the missile steers
+     * using its turnRate toward the given direction.
+     *
+     * direction: {x, y} → converted to target angle via atan2(y, x)
+     * direction: null   → missile flies straight (no steering input)
+     */
+    missileGuide?: {
+        missileId: string;
+        direction: {
+            x: number;
+            y: number;
+        } | null;
+    } | null;
 }
 /**
  * Missile configuration.
@@ -145,80 +338,184 @@ interface MissileConfig {
     duration: number;
 }
 /**
- * Missile AI function type.
+ * Missile AI function type — re-exported from hooks/types.ts.
  */
-type MissileAIFunction = (props: {
-    missileState: ProjectileState;
-    worldState: GameState;
-    random: () => number;
-}) => MissileActions;
+type MissileFunction = MissileFunction$1;
 /**
  * Actions returned by missile each tick.
  */
 interface MissileActions {
     turnToward?: Position;
+    turnToAngle?: number;
 }
-/**
- * Main wizard function type.
- */
-type WizardFunction = (props: {
-    state: GameState;
-    config: GameConfig;
-    random: () => number;
-}) => WizardActions;
+interface MissileHitEvent {
+    type: 'missile-hit';
+    position: Position;
+    damage: number;
+    actualDamage: number;
+    speed: number;
+    ownerId: string;
+    targetId: string;
+}
+interface MissileExpiredEvent {
+    type: 'missile-expired';
+    position: Position;
+}
+interface MissileOobEvent {
+    type: 'missile-oob';
+    position: Position;
+}
+interface BlinkEvent {
+    type: 'blink';
+    wizardId: string;
+    from: Position;
+    to: Position;
+}
+interface ShieldStartEvent {
+    type: 'shield-start';
+    wizardId: string;
+    position: Position;
+}
+interface CastStartEvent {
+    type: 'cast-start';
+    wizardId: string;
+    position: Position;
+    spell: 'missile' | 'shield' | 'blink';
+}
+interface WizardDeathEvent {
+    type: 'wizard-death';
+    wizardId: string;
+    position: Position;
+}
+interface WizardLavaDeathEvent {
+    type: 'wizard-lava-death';
+    wizardId: string;
+    position: Position;
+}
+interface CastCancelEvent {
+    type: 'cast-cancel';
+    wizardId: string;
+    position: Position;
+    spell: 'missile' | 'shield' | 'blink';
+}
+interface MissileLaunchEvent {
+    type: 'missile-launch';
+    position: Position;
+    damage: number;
+    speed: number;
+    ownerId: string;
+    rotation: number;
+}
+interface ShieldBlockEvent {
+    type: 'shield-block';
+    wizardId: string;
+    position: Position;
+    damageBlocked: number;
+    damageThrough: number;
+}
+type SimEvent = MissileHitEvent | MissileExpiredEvent | MissileOobEvent | MissileLaunchEvent | BlinkEvent | ShieldStartEvent | ShieldBlockEvent | CastStartEvent | CastCancelEvent | WizardDeathEvent | WizardLavaDeathEvent;
 
 /**
  * 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.
+ *
+ * SWEEPABLE CONSTANTS — the balance-search ruleset:
+ * Every combat-balance constant lives on the mutable `RULES` object. The engine
+ * and bots read `RULES.X` so the balance-search optimizer can override any of
+ * them at runtime via applyRulesetOverrides() — object property reads are live
+ * across every module and survive bundling (unlike a reassigned `let`, which
+ * esbuild/Vite snapshot at the import site). Structural constants (arena size,
+ * tick rate, hitbox radius, missile floors) stay plain `const`.
+ *
+ * The UPPER_CASE named exports below (WIZARD_HEALTH, SHIELD_CAST_TIME, …) are
+ * default SNAPSHOTS for external/UI/MCP consumers that only need the factory
+ * value. They do NOT track overrides — anything that must respond to a sweep
+ * reads `RULES.X`.
  */
 
 declare const TICKS_PER_SECOND = 100;
 declare const TICK_DURATION_MS = 10;
-declare const WIZARD_HEALTH = 60;
+/**
+ * The mutable ruleset: the single source of truth for every sweepable combat
+ * constant. Engine + bots read these via `RULES.X`. Override with
+ * applyRulesetOverrides(); restore with resetRuleset().
+ */
+declare const RULES: {
+    WIZARD_HEALTH: number;
+    MOVEMENT_SPEED: number;
+    CASTING_MOVEMENT_MULT: number;
+    GCD_DURATION: number;
+    SHIELD_CAST_TIME: number;
+    SHIELD_MAX_BLOCK: number;
+    SHIELD_DECAY_PER_SECOND: number;
+    SHIELD_MIN_BLOCK: number;
+    BLINK_CAST_TIME: number;
+    BLINK_RANGE: number;
+    BLINK_MAX_COOLDOWN: number;
+    BLINK_MIN_COOLDOWN: number;
+    KNOCKBACK_DAMAGE_THRESHOLD: number;
+    KNOCKBACK_SPEED_PER_DAMAGE: number;
+    KNOCKBACK_DELAY: number;
+    KNOCKBACK_DECAY: number;
+    MISSILE_MIN_CAST_TIME: number;
+    MISSILE_BASE_RADIUS: number;
+    MISSILE_DAMAGE_RADIUS_SCALE: number;
+    MISSILE_BASE_CAST: number;
+    MISSILE_DAMAGE_SCALE: number;
+    MISSILE_DAMAGE_POWER: number;
+    MISSILE_HOMING_COEFF: number;
+    MISSILE_TURN_DURATION_COEFF: number;
+    MISSILE_SPEED_DURATION_BASELINE: number;
+    MISSILE_SPEED_DURATION_COEFF: number;
+    WARMUP_MAX_BONUS: number;
+    WARMUP_MAX_PENALTY: number;
+};
+declare const WIZARD_HEALTH: number;
 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;
+declare const MOVEMENT_SPEED: number;
+declare const CASTING_MOVEMENT_MULT: number;
+declare const GCD_DURATION: number;
+declare const SHIELD_CAST_TIME: number;
+declare const SHIELD_MAX_BLOCK: number;
+declare const SHIELD_DECAY_PER_SECOND: number;
+declare const SHIELD_MIN_BLOCK: number;
+declare const BLINK_CAST_TIME: number;
+declare const BLINK_RANGE: number;
+declare const BLINK_MAX_COOLDOWN: number;
+declare const BLINK_MIN_COOLDOWN: number;
 /** @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 BLINK_COOLDOWN: number;
+declare const KNOCKBACK_DAMAGE_THRESHOLD: number;
+declare const KNOCKBACK_SPEED_PER_DAMAGE: number;
+declare const KNOCKBACK_DELAY: number;
+declare const KNOCKBACK_DECAY: number;
+declare const ARENA_SIZE = 860;
+declare const LAVA_BORDER_WIDTH = 30;
+declare const ARENA_MIN = 30;
+declare const ARENA_MAX: number;
 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;
+declare const MISSILE_MIN_CAST_TIME: number;
+declare const MISSILE_BASE_RADIUS: number;
+declare const MISSILE_DAMAGE_RADIUS_SCALE: number;
 /**
  * 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_BASE_CAST: number;
+declare const MISSILE_DAMAGE_SCALE: number;
 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;
+declare const MISSILE_HOMING_COEFF: number;
+declare const MISSILE_TURN_DURATION_COEFF: number;
+declare const MISSILE_SPEED_DURATION_BASELINE: number;
+declare const MISSILE_SPEED_DURATION_COEFF: number;
 /**
  * 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.
+ * Higher turn rate = more expensive cast. Negative values clamped to 0.
  */
 declare function effectiveTurnRateCost(turnRate: number): number;
 /**
@@ -236,15 +533,15 @@ declare function validateMissileConfig(config: MissileConfig): MissileConfig;
  *           + 0.10 × (effectiveTurnRateCost(turnRate) × durationSeconds)
  *           + 0.025 × (speed × durationSeconds - 1.5)
  *
- * effectiveTurnRateCost: linear for positive, -ln(1+|t|) for negative (diminishing returns).
+ * turnRate is clamped to >= 0. Cost is linear.
  *
  * 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_MAX_BONUS: number;
+declare const WARMUP_MAX_PENALTY: number;
 declare const WARMUP_SPEED_TOLERANCE = 3;
 declare const WARMUP_TURN_TOLERANCE = 1;
 declare const WARMUP_DURATION_TOLERANCE = 50;
@@ -268,20 +565,35 @@ declare function calculateMissileSimilarity(prev: MissileConfig | undefined, cur
  */
 declare function calculateWarmupMultiplier(prev: MissileConfig | undefined, current: MissileConfig): number;
 declare const MATCH_DURATION = 30000;
-declare const MAX_HEALTH = 60;
+declare const MAX_HEALTH: number;
 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;
+declare const MOVE_SPEED: number;
+declare const MISSILE_RADIUS_PER_DAMAGE: number;
+declare const SHIELD_MAX_STRENGTH: number;
+declare const SHIELD_MIN_STRENGTH: number;
+declare const SHIELD_DECAY_RATE: number;
+declare const BLINK_MAX_RANGE: number;
 /**
  * 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;
+/**
+ * Search bounds for each sweepable constant. The current value is the start.
+ * Every key here is read by the engine/bots through `RULES.X`, so overrides
+ * take effect across the whole simulation.
+ */
+declare const RULESET_RANGES: Record<string, {
+    min: number;
+    max: number;
+}>;
+/** Merge overrides onto the RULES object and apply them globally. */
+declare function applyRulesetOverrides(overrides: Record<string, number>): void;
+/** Restore all swept constants to their factory defaults. */
+declare function resetRuleset(): void;
+/** Current value of every sweepable constant (the optimizer's starting point). */
+declare function currentRuleset(): Record<string, number>;
 
 /**
  * Engine version — milliseconds since the Unix epoch.
@@ -293,11 +605,11 @@ declare const ARENA_WATER_BUFFER = 200;
  * 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 = 1777687052301;
+declare const ENGINE_VERSION = 1782047842068;
 
 interface InternalWizardState extends WizardState {
     missileConfig?: MissileConfig;
-    missileAI?: MissileAIFunction;
+    missileAI?: MissileFunction$1;
     blinkTarget?: {
         x: number;
         y: number;
@@ -305,6 +617,11 @@ interface InternalWizardState extends WizardState {
     damageDealt: number;
     damageTaken: number;
     lastHitTick: number;
+    knockbackVx?: number;
+    knockbackVy?: number;
+    knockbackDelay?: number;
+    knockbackPendingVx?: number;
+    knockbackPendingVy?: number;
 }
 /**
  * Initialize a new match state.
@@ -313,10 +630,11 @@ declare function createInitialState(_seed: number, spawnDist?: number): GameStat
 /**
  * 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): {
+declare function tick(currentTick: number, wizard1AI: WizardFunction, wizard2AI: WizardFunction, config: GameConfig, wizards: InternalWizardState[], projectiles: ProjectileState[], missileAIs: Map<string, MissileFunction$1>, matchSeed: number): {
     nextTick: number;
     wizards: InternalWizardState[];
     projectiles: ProjectileState[];
+    events: SimEvent[];
     errors: BotError[];
 };
 /**
@@ -324,7 +642,7 @@ declare function tick(currentTick: number, wizard1AI: WizardFunction, wizard2AI:
  * 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;
+declare function getPlayerState(playerIndex: number, wizards: InternalWizardState[], projectiles: ProjectileState[], tick: number, events?: SimEvent[]): 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. */
@@ -395,190 +713,76 @@ declare function simulate(wizard1AI: WizardFunction, wizard2AI: WizardFunction,
 }): SimulateResult;
 
 /**
- * VIBEMANCER - HOOKS API TYPES
+ * VIBEMANCER - HOOKS RUNTIME
  *
- * Types for the hooks-based bot API.
+ * This file implements a minimal React-like hooks runtime for AI programming.
+ * It supports useState, useEffect, useMemo, useRef, and useParam with entity isolation.
  *
- * 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)
+ * 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;
+}
 /**
- * Enemy wizard state as seen by your bot.
+ * Validate a hook call and return its sequential index.
+ * Ensures hooks are called in the same order every tick.
  *
- * Note: you cannot see the enemy's missile configs, cooldown timers, or
- * damage history — only what's visible on the battlefield.
+ * 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
  */
-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;
-}
+declare function validateHookCall(type: string): 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.
+ * 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;
+declare function runWizardWithContext<T>(entityId: string, context: WizardContext, 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.
+ * Used by the simulation to set up WizardContext before calling hooks-style bots.
  */
-declare function withBotContext<T>(context: BotContext, fn: () => T): T;
+declare function withWizardContext<T>(context: WizardContext, fn: () => T): T;
 /**
  * Get the current bot context. Throws if called outside bot execution.
  */
-declare function getBotContext(): BotContext;
+declare function getWizardContext(): WizardContext;
+/**
+ * Run a function with missile context set, preserving the current entity ID.
+ * Used by the simulation to set up MissileContext before calling hooks-style missile AIs.
+ */
+declare function withMissileContext<T>(context: MissileContext, fn: () => T): T;
+/**
+ * Get the current missile context. Throws if called outside missile AI execution.
+ */
+declare function getMissileContext(): MissileContext;
 /**
  * Persist state between ticks.
  */
@@ -611,12 +815,8 @@ 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
+ * Any vector works: direction is preserved, speed is clamped to [0, 1].
+ * (0.5, 0) = half speed right. (300, 200) = full speed at 33.7°.
  */
 declare function moveWizard(wizard: WizardState, move: {
     x: number;
@@ -627,9 +827,15 @@ declare function moveWizard(wizard: WizardState, move: {
  */
 declare function moveProjectile(projectile: ProjectileState, deltaTicks: number): Position;
 /**
- * Clamp a position to the arena boundaries.
+ * Clamp a position to the full arena bounds (0-860).
+ * No playfield clamping — wizards CAN walk/blink into lava.
  */
 declare function clampToArena(position: Position, radius: number): Position;
+/**
+ * Check if a position is in the lava zone (outside the playfield).
+ * Lava zones: [0, ARENA_MIN] and [ARENA_MAX, ARENA_SIZE] on each axis.
+ */
+declare function isInLava(position: Position, radius: number): boolean;
 /**
  * Resolve body collision between two wizards.
  * Pushes both apart equally so they don't overlap. Neither is blocked — they just can't stack.
@@ -686,7 +892,7 @@ declare function applyDamage(wizard: WizardState, damage: number, _projectile?:
  * 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)
+ *   the missile-guide feature in manual play)
  * - setInvincible(wizardIndex, on) toggles damage immunity per wizard
  */
 
@@ -709,12 +915,14 @@ declare class ManualMatch {
     private wizards;
     private projectiles;
     private missileAIs;
-    /** First-replacement originals for hijacked missiles. Used by restoreMissileAI. */
+    /** First-replacement originals for guided missiles. Used by restoreMissileAI. */
     private originalMissileAIs;
     private currentTick;
     private done;
+    private deathTick;
     private allErrors;
     private history;
+    private lastTickEvents;
     constructor(wizard1AI: WizardFunction, wizard2AI: WizardFunction, options?: ManualMatchOptions);
     /**
      * Advance the match by `count` ticks (default 1). Stops early if the
@@ -722,17 +930,17 @@ declare class ManualMatch {
      */
     step(count?: number): StepResult;
     /**
-     * Hot-swap a missile's AI function. Used by the missile-hijack feature
+     * Hot-swap a missile's AI function. Used by the missile-guide 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;
+    replaceMissileAI(projectileId: string, ai: MissileFunction$1): void;
     /**
-     * Restore a previously hijacked missile's original AI function.
-     * No-op if the projectile id doesn't exist or was never hijacked.
+     * Restore a previously guided missile's original AI function.
+     * No-op if the projectile id doesn't exist or was never guided.
      */
     restoreMissileAI(projectileId: string): void;
     /**
@@ -773,7 +981,6 @@ interface TurningParams extends BaseParams {
 }
 type StraightParams = BaseParams;
 type HomingParams = TurningParams;
-type AntiHomingParams = TurningParams;
 interface SpiralParams extends BaseParams {
     spiralRadius: number;
     spiralFreq: number;
@@ -783,7 +990,7 @@ interface SeekerParams extends TurningParams {
 }
 interface MissileTemplate {
     config: MissileConfig;
-    ai: MissileAIFunction;
+    ai: MissileFunction$1;
 }
 /**
  * Fire-and-forget missile. No steering — flies in a straight line.
@@ -793,11 +1000,6 @@ 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
@@ -979,1041 +1181,1087 @@ declare function getAdaptiveMissileConfig(targetVelocity: Position, distance: nu
  * If `lastMissileConfig` is provided, accounts for warmup bonus: similar
  * missiles cast faster, so more damage can fit in the same budget.
  */
+/**
+ * Simulate a missile trajectory to find the minimum duration (ticks) needed
+ * to reach a target at the given distance. Works for all turnRate values:
+ * positive (homing) and zero (straight).
+ *
+ * The simulation starts the missile aimed directly at the target and steps
+ * through the trajectory tick by tick. For homing, the missile tracks the
+ * target each tick matching the engine's steering physics.
+ */
+/**
+ * Simulate a missile trajectory to find the minimum duration (ticks) needed
+ * to reach a target at the given distance. Works for straight (turnRate=0)
+ * and homing (turnRate>0) missiles.
+ *
+ * The missile starts aimed directly at the target at (dist, 0) and steps
+ * through the trajectory tick by tick. For homing, the missile tracks the
+ * target each tick matching the engine's steering physics.
+ *
+ * Returns 500 if the missile cannot reach the target within 500 ticks.
+ */
+declare function simulateMinDuration(speed: number, turnRateDeg: number, dist: number, collisionRadius?: number): number;
 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.
+ * Fit a missile config that accounts for the enemy escaping during cast time.
  *
- * 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."
+ * During casting, the caster moves at CASTING_MOVEMENT_MULT speed while
+ * the enemy moves at full MOVEMENT_SPEED. This means the effective distance
+ * at launch is larger than the current distance. This function iteratively
+ * converges on a missile config whose range covers the escape distance.
  *
- * STANDALONE — no tier progression. It's a test fixture, not a combatant.
+ * @param currentDistance - Current distance to enemy
+ * @param budgetTicks - Maximum cast time budget in ticks
+ * @param options - Same options as fitMissileToBudget, plus:
+ *   - enemyApproaching: if true, enemy is moving toward caster (reduces escape)
+ *   - distanceBuffer: flat units added to target distance for safety margin (default 20)
+ *   - maxIterations: convergence iterations (default 5)
  */
-declare const TargetDummy: WizardFunction;
+declare function fitMissileForEscapingTarget(currentDistance: number, budgetTicks: number, options?: {
+    minTurnRate?: number;
+    maxDamage?: number;
+    lastMissileConfig?: MissileConfig;
+    enemyApproaching?: boolean;
+    distanceBuffer?: number;
+    maxIterations?: number;
+}): MissileConfig | null;
 
 /**
- * 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."
+ * Get a seeded random number generator. Returns a function that produces
+ * deterministic values in [0, 1) — same seed + same tick = same sequence.
+ * Use this instead of Math.random() so replays are deterministic.
  */
-declare const Rookie: WizardFunction;
-
+declare function useRandom(): () => number;
 /**
- * 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).
+ * Get your current health (0-60). Wizard dies at 0.
  */
-declare const Critter: WizardFunction;
-
+declare function useHealth(): number;
 /**
- * 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.
+ * Get your current position as {x, y} in world coordinates (0-800).
+ * Position is clamped to [5, 795] (arena bounds minus wizard radius).
  */
-declare const Hogger: WizardFunction;
-
+declare function usePosition(): Position;
 /**
- * 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.
+ * 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 const Doombringer: WizardFunction;
-
-declare const Turtle: WizardFunction;
-
+declare function useVelocity(): Velocity;
 /**
- * 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.
+ * 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.
  *
- * 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
+ * Returns 0 when idle or channeling (shield can be canceled immediately).
+ * During casting: remaining cast ticks. During GCD: remaining GCD ticks.
  *
- * TIER: 2 (enhanced Turtle)
+ * Note: 100 ticks = 1 second.
  */
-declare const Sentinel: WizardFunction;
-
+declare function useTicksUntilReady(): number;
 /**
- * Bot: Golem
+ * Get current shield block multiplier.
  *
- * 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)
+ * 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 const Golem: WizardFunction;
-
+declare function useShieldStrength(): number;
 /**
- * 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)
+ * Get all projectiles currently in flight (yours and enemy's).
+ * Used for blink safety calculations and threat analysis.
  */
-declare const Shadowblade: WizardFunction;
-
+declare function useProjectiles(): ProjectileState[];
 /**
- * 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.
+ * Get the config of the last missile you fired, or undefined if none fired yet.
+ * Used for the warmup system: consecutive similar missiles cast faster.
+ */
+declare function useLastMissileConfig(): MissileConfig | undefined;
+/**
+ * Get blink cooldown remaining in ticks. Returns 0 if ready to blink.
  *
- * 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
+ * Cooldown scales with distance used:
+ * - 100 units → ~100 ticks (1s)
+ * - 300 units (max range) → 2000 ticks (20s)
  *
- * TIER: 2 (enhanced Shadowblade)
+ * Note: 100 ticks = 1 second.
  */
-declare const Nightblade: WizardFunction;
-
+declare function useBlinkCooldown(): number;
 /**
- * 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.
+ * 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.
  *
- * 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
+ * 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.
  *
- * 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
+ * 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.
  *
- * PROGRESSION LINE: Shadowblade → Nightblade → Voidblade
- * TIER: 3 (elite Melee line)
+ * 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 const Voidblade: WizardFunction;
+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[];
 
 /**
- * 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.
+ * VIBEMANCER - THREAT ANALYSIS
  *
- * TIER: 1 (base)
+ * Pre-computes threat information for incoming projectiles.
+ * This handles the "subconscious" perception of missile trajectories.
  */
-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
+ * Analyze all threats from enemy projectiles.
  *
- * TIER: 2 (enhanced Bonemancer)
+ * @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 const Lich: WizardFunction;
+declare function analyzeThreats(myPos: Position, projectiles: ProjectileState[], myProjectiles: ProjectileState[], ticksUntilReady: number): AnalyzedThreat[];
 
 /**
- * Bot: Archlich
+ * VIBEMANCER - ACTION BUILDERS
  *
- * 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.
+ * Fluent API for constructing bot actions with type-safe chaining.
  *
- * PROGRESSION LINE: Bonemancer → Lich → Archlich
- * TIER: 3 (elite Homing line)
+ * UNITS REFERENCE (100 ticks = 1 second):
+ *   Position:   absolute world coordinates, 0-800 on each axis (800×800 arena)
+ *   Movement:   direction vector, magnitude clamped to max 1 (speed in [0, 1])
+ *   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
  */
-declare const Archlich: WizardFunction;
 
 /**
- * Bot: Flamecaller
+ * Channel a shield that blocks incoming damage.
  *
- * 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.
+ * 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.
  *
- * 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
+ * Can chain .move() — movement applies during the 20-tick cast, NOT during channel.
  *
- * TIER: 1 (base)
+ * @example
+ *   return shield();                    // shield and stay still
+ *   return shield().move(1, 0);         // move right while cast starts
  */
-declare const Flamecaller: WizardFunction;
-
+declare function shield(): ActionBuilder;
 /**
- * Bot: Pyromancer
+ * Cast a missile spell.
  *
- * 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.
+ * 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.
  *
- * 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
+ * Repeated similar missiles cast 20% faster (warmup bonus). Switching styles
+ * incurs a 20% penalty.
  *
- * TIER: 2 (enhanced Flamecaller)
- */
-declare const Pyromancer: WizardFunction;
-
-/**
- * Bot: Infernalist
+ * Can chain .move() for simultaneous movement while casting.
  *
- * 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.
+ * @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. Use getMissileContext()
+ *   to read the missile's state (position, rotation, speed, etc.), the full game
+ *   state (worldState), and a seeded PRNG (random). Return turnToward(x, y) to home
+ *   toward a position, or flyStraight() 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.
  *
- * 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
+ * @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}, () => flyStraight(), angle);
  *
- * PROGRESSION LINE: Flamecaller → Pyromancer → Infernalist
- * TIER: 3 (elite Caster line)
+ *   // Homing missile that tracks enemy
+ *   return missile(
+ *     {damage: 10, speed: 5, duration: 300, turnRate: 3},
+ *     () => {
+ *       const ctx = getMissileContext();
+ *       const enemy = ctx.worldState.enemies[0];
+ *       return enemy ? turnToward(enemy.position.x, enemy.position.y) : flyStraight();
+ *     },
+ *     angle,
+ *   );
  */
-declare const Infernalist: WizardFunction;
-
+declare function missile(config: MissileConfig, ai: MissileFunction$1, direction: number): ActionBuilder;
 /**
- * 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.
+ * Teleport to an absolute position on the arena.
  *
- * 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.
+ * 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)
  *
- * 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."
+ * Cannot chain .move() — blink IS the movement.
  *
- * NOTE: A separate future archetype "Spellslinger" (volume-of-fire) is reserved
- * for a rapid-fire bot that prioritizes quantity over prediction.
+ * @param x - Target X position (0-800, absolute world coordinate)
+ * @param y - Target Y position (0-800, absolute world coordinate)
  *
- * TIER: 1 (base)
+ * @example
+ *   return blink(400, 400);                              // blink to center
+ *   return blink(enemy.position.x, enemy.position.y);    // blink to enemy
  */
-declare const Spellshot: WizardFunction;
-
+declare function blink(x: number, y: number): FinalAction;
 /**
- * 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.
+ * Cancel current cast or channel (e.g. stop shielding to attack).
  *
- * 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
+ * Canceling a cast/channel triggers 100-tick (1s) GCD.
+ * Can chain .move() for simultaneous movement.
  *
- * TIER: 2 (enhanced Spellshot)
+ * @example
+ *   return cancel().move(-1, 0);    // cancel and dodge left
  */
-declare const Spelltracer: WizardFunction;
-
+declare function cancel(): ActionBuilder;
 /**
- * Bot: Spellseeker
+ * Move in a direction without casting any spell.
  *
- * 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.
+ * This is a **direction vector**, not a target position. Values are in the
+ * range [-1, 1] where 1 = full speed. Larger values (like raw position
+ * deltas) are clamped to full speed automatically.
  *
- * 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
+ * @param x - Horizontal direction (positive = right, negative = left)
+ * @param y - Vertical direction (positive = down, negative = up)
  *
- * PROGRESSION LINE: Spellshot → Spelltracer → Spellseeker
- * TIER: 3 (elite Sniper line)
+ * @example
+ *   return move(1, 0);                                         // move right at full speed
+ *   return move(dx / dist, dy / dist);                         // normalized unit vector = full speed
+ *   return move(enemy.position.x - myPos.x, enemy.position.y - myPos.y);  // raw delta = clamped to full speed
  */
-declare const Spellseeker: WizardFunction;
-
+declare function move(x: number, y: number): FinalAction;
 /**
- * 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.
+ * Do nothing — no action, no movement.
+ */
+declare function idle(): FinalAction;
+/**
+ * Steer the missile toward a world position.
+ * The engine clamps the actual turn to the missile's turnRate.
  *
- * 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
+ * @param x - Target X position (world coordinates)
+ * @param y - Target Y position (world coordinates)
+ */
+declare function turnToward(x: number, y: number): MissileAction;
+/**
+ * Steer the missile toward a specific angle (degrees).
+ * The engine clamps the actual turn to the missile's turnRate.
  *
- * TIER: 1 (base)
+ * @param degrees - Target rotation in degrees (0=right, 90=down, 180=left, 270=up)
+ */
+declare function turnToAngle(degrees: number): MissileAction;
+/**
+ * Fly straight — no steering this tick.
+ */
+declare function flyStraight(): MissileAction;
+/**
+ * Extract MissileActions from a MissileAction.
+ * Used by the engine to get the actual missile action.
+ */
+declare function extractMissileAction(action: MissileAction): MissileActions;
+/**
+ * Extract WizardActions from a FinalAction.
+ * Used by the engine to get the actual action.
  */
-declare const Battlemage: WizardFunction;
+declare function extractAction(finalAction: FinalAction): WizardActions;
 
 /**
- * Bot: Warmage
+ * VIBEMANCER - PARAMETER RUNTIME
  *
- * 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.
+ * Provides the useParam() hook for bots to declare tunable parameters,
+ * and the infrastructure for the optimizer to inject/discover parameter values.
  *
- * 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
+ * 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.
  *
- * TIER: 2 (enhanced Battlemage)
- */
-declare const Warmage: WizardFunction;
-
-/**
- * Bot: Archmage
+ * ## useParam API
  *
- * 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.
+ * ```typescript
+ * // Basic: just a value, no optimizer config
+ * const damage = useParam('damage', 15);
  *
- * 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
+ * // With range: optimizer searches value ± range (sliding window)
+ * const distance = useParam('distance', 350, {range: 150, min: 0});
  *
- * PROGRESSION LINE: Battlemage → Warmage → Archmage
- * TIER: 3 (elite Duelist line)
+ * // 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
  */
-declare const Archmage: WizardFunction;
 
 /**
- * Bot: Stormchaser
+ * 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).
  *
- * 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).
+ * @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
  *
- * 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
+ * @example
+ * // Simple: no optimizer config
+ * const damage = useParam('damage', 15);
  *
- * TIER: 1 (base)
+ * // 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 const Stormchaser: WizardFunction;
+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;
 
 /**
- * Bot: Stormcaller
+ * Bot: TargetDummy
  *
- * 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.
+ * BEHAVIOR: Does absolutely nothing. No movement, no spells, no AI.
  *
- * 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
+ * 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."
  *
- * TIER: 2 (enhanced Stormchaser)
+ * STANDALONE — no tier progression. It's a test fixture, not a combatant.
  */
-declare const Stormcaller: WizardFunction;
+declare function TargetDummy(): FinalAction;
 
 /**
- * Bot: Stormforger
+ * Bot: Rookie
  *
- * 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.
+ * 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.
  *
- * 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
+ * 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.
  *
- * TIER: 3 (elite Berserker line)
+ * 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 Stormforger: WizardFunction;
+declare function Rookie(): FinalAction;
 
 /**
- * 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.
+ * Bot: Critter
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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."
  *
- * TIER: 1 (base)
+ * 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 Spellspinner: WizardFunction;
+declare function Critter(): FinalAction;
 
 /**
- * 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.
+ * Bot: Hogger
  *
- * 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.
+ * 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.
  *
- * 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
+ * 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."
  *
- * TIER: 2 (enhanced Spellspinner)
+ * STANDALONE — no tier progression. There's only one Hogger.
  */
-declare const Spellweaver: WizardFunction;
+declare function Hogger(): FinalAction;
 
 /**
- * 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.
+ * Bot: Doombringer
  *
- * 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
+ * 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.
  *
- * TIER: 3 (elite Spellspinner line)
+ * STANDALONE — no tier progression. Benchmark/test bot.
  */
-declare const Spellbinder: WizardFunction;
+declare function Doombringer(): FinalAction;
+
+declare function Turtle(): FinalAction;
 
 /**
- * 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):
+ * Bot: Sentinel
  *
- * | 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     |
+ * 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.
  *
- * Standalone: TargetDummy, Critter, Hogger, Rookie, Doombringer
- * Reserved: Spellslinger (future volume-of-fire archetype)
+ * 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 function Sentinel(): FinalAction;
 
-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.
+ * 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 BOT_GROUPS: BotGroup[];
-declare const ALL_BOTS: BotEntry[];
+declare function Golem(): FinalAction;
 
 /**
- * VIBEMANCER - STATE HOOKS
+ * Bot: Shadowblade
  *
- * React-style hooks for reading game state.
- * These handle the "subconscious" perception that humans do instinctively.
+ * 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.
  *
- * 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)
+ * 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 function Shadowblade(): FinalAction;
 
 /**
- * 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.
+ * Bot: Nightblade
  *
- * Returns 0 when idle or channeling (shield can be canceled immediately).
- * During casting: remaining cast ticks. During GCD: remaining GCD ticks.
+ * 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.
  *
- * Note: 100 ticks = 1 second.
- */
-declare function useTicksUntilReady(): number;
-/**
- * Get current shield block multiplier.
+ * 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
  *
- * 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).
+ * TIER: 2 (enhanced Shadowblade)
  */
-declare function useShieldStrength(): number;
+declare function Nightblade(): FinalAction;
+
 /**
- * Get blink cooldown remaining in ticks. Returns 0 if ready to blink.
+ * Bot: Voidblade
  *
- * Cooldown scales with distance used:
- * - 100 units → ~100 ticks (1s)
- * - 300 units (max range) → 2000 ticks (20s)
+ * 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.
  *
- * 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.
+ * 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
  *
- * 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.
+ * 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
  *
- * 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.
+ * PROGRESSION LINE: Shadowblade → Nightblade → Voidblade
+ * TIER: 3 (elite Melee line)
  */
-declare function useDamageDealt(): number;
+declare function Voidblade(): FinalAction;
+
 /**
- * Get total damage you've taken this match.
+ * 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 function useDamageTaken(): number;
+declare function Bonemancer(): FinalAction;
+
 /**
- * Get the tick number when you last took damage. Returns 0 if never hit.
- * Compare with useTick() to get ticks since last hit.
+ * 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 function useLastHitTick(): number;
+declare function Lich(): FinalAction;
+
 /**
- * Get arena dimensions. Default: {width: 800, height: 800}.
- * Wizards are clamped to [5, 795] on each axis (radius = 5).
+ * 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 function useArenaSize(): {
-    width: number;
-    height: number;
-};
+declare function Archlich(): FinalAction;
+
 /**
- * Get current game tick (starts at 0, increments each tick).
- * 100 ticks = 1 second. Match ends at 30,000 ticks (5 minutes).
+ * 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 function useTick(): number;
+declare function Flamecaller(): FinalAction;
+
 /**
- * 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.
+ * Bot: Pyromancer
  *
- * 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
+ * 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 function useThreats(): AnalyzedThreat[];
+declare function Pyromancer(): FinalAction;
+
 /**
- * Get the most imminent threat, or null if no threats.
- * Shorthand for useThreats()[0].
+ * 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 function useClosestThreat(): AnalyzedThreat | null;
+declare function Infernalist(): FinalAction;
+
 /**
- * Get your missiles analyzed from the enemy's perspective.
- * Useful to predict when enemy will shield/dodge your attacks.
+ * 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 function useMyThreatsToEnemy(): AnalyzedThreat[];
+declare function Spellshot(): FinalAction;
 
 /**
- * VIBEMANCER - THREAT ANALYSIS
+ * Bot: Spelltracer
  *
- * Pre-computes threat information for incoming projectiles.
- * This handles the "subconscious" perception of missile trajectories.
+ * 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 function Spelltracer(): FinalAction;
 
 /**
- * Analyze all threats from enemy projectiles.
+ * Bot: Spellseeker
  *
- * @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)
+ * 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 function analyzeThreats(myPos: Position, projectiles: ProjectileState[], myProjectiles: ProjectileState[], ticksUntilReady: number): AnalyzedThreat[];
+declare function Spellseeker(): FinalAction;
 
 /**
- * VIBEMANCER - ACTION BUILDERS
+ * Bot: Battlemage
  *
- * Fluent API for constructing bot actions with type-safe chaining.
+ * 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.
  *
- * 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
+ * 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 function Battlemage(): FinalAction;
 
 /**
- * Channel a shield that blocks incoming damage.
+ * Bot: Warmage
  *
- * 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.
+ * 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.
  *
- * Can chain .move() — movement applies during the 20-tick cast, NOT during channel.
+ * 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
  *
- * @example
- *   return shield();                    // shield and stay still
- *   return shield().move(100, 0);       // move right while cast starts
+ * TIER: 2 (enhanced Battlemage)
  */
-declare function shield(): ActionBuilder;
+declare function Warmage(): FinalAction;
+
 /**
- * Cast a missile spell.
+ * Bot: Archmage
  *
- * 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.
+ * 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.
  *
- * Repeated similar missiles cast 20% faster (warmup bonus). Switching styles
- * incurs a 20% penalty.
+ * 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
  *
- * Can chain .move() for simultaneous movement while casting.
+ * PROGRESSION LINE: Battlemage → Warmage → Archmage
+ * TIER: 3 (elite Duelist line)
+ */
+declare function Archmage(): FinalAction;
+
+/**
+ * Bot: Stormchaser
  *
- * @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.
+ * 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).
  *
- * @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);
+ * 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
  *
- *   // Homing missile that tracks enemy
- *   return missile(
- *     {damage: 10, speed: 5, duration: 300, turnRate: 3},
- *     ({worldState}) => ({turnToward: worldState.enemies[0]?.position}),
- *     angle,
- *   );
+ * TIER: 1 (base)
  */
-declare function missile(config: MissileConfig, ai: MissileAIFunction, direction: number): ActionBuilder;
+declare function Stormchaser(): FinalAction;
+
 /**
- * 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)
+ * Bot: Stormcaller
  *
- * Cannot chain .move() — blink IS the movement.
+ * 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.
  *
- * @param x - Target X position (0-800, absolute world coordinate)
- * @param y - Target Y position (0-800, absolute world coordinate)
+ * 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
  *
- * @example
- *   return blink(400, 400);                              // blink to center
- *   return blink(enemy.position.x, enemy.position.y);    // blink to enemy
+ * TIER: 2 (enhanced Stormchaser)
  */
-declare function blink(x: number, y: number): FinalAction;
+declare function Stormcaller(): FinalAction;
+
 /**
- * Cancel current cast or channel (e.g. stop shielding to attack).
+ * Bot: Stormforger
  *
- * Canceling a cast/channel triggers 100-tick (1s) GCD.
- * Can chain .move() for simultaneous movement.
+ * 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.
  *
- * @example
- *   return cancel().move(-100, 0);  // cancel and dodge left
+ * 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 function cancel(): ActionBuilder;
+declare function Stormforger(): FinalAction;
+
 /**
- * Move in a direction without casting any spell.
+ * Bot: Spellspinner
  *
- * 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.
+ * 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.
  *
- * To move toward a target position, subtract your position:
- *   move(target.x - myPos.x, target.y - myPos.y)
+ * 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.
  *
- * @param x - Horizontal direction (positive = right, negative = left)
- * @param y - Vertical direction (positive = down, negative = up)
+ * 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.
  *
- * @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.
+ * TIER: 1 (base)
  */
-declare function extractAction(finalAction: FinalAction): WizardActions;
+declare function Spellspinner(): FinalAction;
 
 /**
- * VIBEMANCER - BOT WRAPPER
+ * Bot: Spellweaver
  *
- * 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).
+ * 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.
  *
- * This allows new bots to work with the existing simulation.
+ * 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.
  *
- * @example
- * const NewBot: BotFunction = () => {
- *   const health = useHealth();
- *   return health < 10 ? shield() : idle();
- * };
+ * 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
  *
- * // 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.
+ * TIER: 2 (enhanced Spellspinner)
  */
-declare function isNewStyleBot(bot: WizardFunction | BotFunction): bot is BotFunction;
+declare function Spellweaver(): FinalAction;
 
 /**
- * VIBEMANCER - PARAMETER RUNTIME
- *
- * Provides the useParam() hook for bots to declare tunable parameters,
- * and the infrastructure for the optimizer to inject/discover parameter values.
+ * Bot: Spellbinder
  *
- * 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.
+ * 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.
  *
- * ## useParam API
+ * 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.
  *
- * ```typescript
- * // Basic: just a value, no optimizer config
- * const damage = useParam('damage', 15);
+ * 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
  *
- * // With range: optimizer searches value ± range (sliding window)
- * const distance = useParam('distance', 350, {range: 150, min: 0});
+ * TIER: 3 (elite Spellspinner line)
+ */
+declare function Spellbinder(): FinalAction;
+
+/**
+ * VIBEMANCER - BOT REGISTRY
  *
- * // With fixed min/max: optimizer searches [min, max] (fixed bounds)
- * const damage = useParam('damage', 15, {min: 5, max: 25});
+ * Single source of truth for all bots, ordered from weakest to strongest.
+ * Run the tournament test to determine the correct ordering.
  *
- * // With all: range defines search radius, min/max clamp it
- * const fraction = useParam('fraction', 0.25, {range: 0.2, min: 0, max: 1});
+ * To reorder: run `npx vitest run tests/bots/tournament.test.ts`
+ * and update the list below based on the results.
  *
- * // With custom step count: optimizer tests 20 values instead of default 10
- * const distance = useParam('distance', 500, {range: 200, min: 0, steps: 20});
- * ```
+ * BOT NAMING SCHEME (3-tier progression):
  *
- * - **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.
+ * | 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     |
  *
- * Without optimizer config, useParam simply returns `value` every tick.
- * With optimizer config, the offline optimizer script can override the value during search.
+ * Standalone: TargetDummy, Critter, Hogger, Rookie, Doombringer, Hero
+ *   (Hero is the adaptive SHOWCASE — the #1 reference bot users build their own to beat.
+ *    Deliberately kept as a single isolated bot, NOT a tier line: writing adaptive bots is
+ *    the game, so the roster ships one exemplar and players make the rest.)
+ * Reserved: Spellslinger (future volume-of-fire archetype)
  *
- * ## 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 {
+interface WizardEntry {
     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;
+    ai: WizardFunction;
+    description: string;
+    tier?: number;
+    group: string;
+}
+interface WizardGroup {
+    label: string;
+    bots: WizardEntry[];
 }
 /**
- * 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.
+ * All bots organized by progression line.
+ * Each group contains bots from the same archetype, ordered by tier.
  */
-declare function wrapWithParams(bot: WizardFunction, params: Record<string, number>): WizardFunction;
+declare const BOT_GROUPS: WizardGroup[];
+declare const ALL_BOTS: WizardEntry[];
 
 /**
  * VIBEMANCER - OPTIMIZER UTILITIES
@@ -2099,6 +2347,34 @@ declare function scoreFight(result: FightResult): number;
  */
 declare function scoreFightAsWizard2(result: FightResult): number;
 
+/**
+ * Bot-name filter — the single source of truth for which bot names are
+ * disallowed. Called everywhere a bot name is served or displayed (matchmaker,
+ * upload, handle/botname selectors, leaderboard, CLI) so the rule is consistent.
+ *
+ * Deliberately a pure function over stateless rules: nothing is written to the
+ * bot, so adding a rule hides matching bots everywhere at once, and REMOVING a
+ * rule brings them straight back — no data to migrate or un-flag. Editing the
+ * lists below is a (rare) release; the bots themselves are never mutated.
+ *
+ * On a takedown (trademark / defamation / illegal content), add the exact name
+ * to BANNED_EXACT, or a pattern to BANNED_PATTERNS for a family of names.
+ *
+ * FULL RUNBOOK (read this before banning anything): docs/BANNING_BOT_NAMES.md
+ * — it explains the why, the exact-match semantics, and the release steps
+ * required for the change to reach the (published-core) Cloud Functions.
+ */
+/**
+ * Pure matcher — exported for testing. Returns true if `name` matches any of the
+ * given exact names or patterns (case-insensitive, trimmed).
+ */
+declare function matchesAnyBanRule(name: string, exact: ReadonlySet<string>, patterns: readonly RegExp[]): boolean;
+/**
+ * True if a bot name is disallowed. Call this at every surface that serves or
+ * displays bot names; never persist the result onto the bot.
+ */
+declare function isBannedBotName(name: string): boolean;
+
 /**
  * VIBEMANCER — BROWSER SANDBOX
  *
@@ -2317,18 +2593,18 @@ declare class BrowserManualMatchSandbox {
     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.
+     * the player's human actions and any guided missile targets first.
      */
     step(request?: ManualMatchStepRequest): Promise<StepResult>;
     /**
-     * Replace a missile's AI with a worker-local hijack stub that reads
+     * Replace a missile's AI with a worker-local guide stub that reads
      * from `latestHumanMissileTargets[projectileId]`. Subsequent step()
      * calls with `humanMissileTargets` populated for this id steer the
      * missile.
      */
-    hijackMissile(projectileId: string): Promise<void>;
+    guideMissile(projectileId: string): Promise<void>;
     /**
-     * Restore a hijacked missile's original AI.
+     * Restore a guided missile's original AI.
      */
     releaseMissile(projectileId: string): Promise<void>;
     /**
@@ -2528,7 +2804,7 @@ interface TestBotBuilder {
  * });
  * ```
  */
-declare function testBot(bot: WizardFunction | BotFunction): TestBotBuilder;
+declare function testBot(bot: WizardFunction): TestBotBuilder;
 
 /**
  * VIBEMANCER - FIGHT TRACE
@@ -2550,7 +2826,7 @@ interface TraceEvent {
     type: TraceEventType;
     detail: string;
 }
-type TraceEventType = 'STATE' | 'FIRE' | 'HIT' | 'HURT' | 'DODGE_START' | 'DODGE_CLOSE' | 'MOVE' | 'ERROR' | 'WARNING';
+type TraceEventType = 'STATE' | 'FIRE' | 'HIT' | 'HURT' | 'DEATH' | 'LAVA_DEATH' | 'SHIELD_BLOCK' | 'KNOCKBACK' | 'BLINK' | 'DODGE_START' | 'DODGE_CLOSE' | 'MOVE' | 'ERROR' | 'WARNING';
 interface TraceSummary {
     winner: string;
     ticks: number;
@@ -2569,6 +2845,7 @@ interface TraceBotSummary {
     shields: number;
     blinks: number;
     dodgeEncounters: number;
+    causeOfDeath: 'missile' | 'lava' | 'alive' | 'timeout';
     movement: {
         strafe: number;
         approach: number;
@@ -2599,4 +2876,4 @@ declare function diagnoseTrace(events: TraceEvent[], summary: TraceSummary): str
 /** 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 };
+export { ALL_BOTS, ARENA_MAX, ARENA_MIN, ARENA_SIZE, ARENA_WATER_BUFFER, type ActionBuilder, type AnalyzedThreat, Archlich, Archmage, BLINK_CAST_TIME, BLINK_COOLDOWN, BLINK_MAX_COOLDOWN, BLINK_MAX_RANGE, BLINK_MIN_COOLDOWN, BLINK_RANGE, BOT_GROUPS, Battlemage, type BlinkEvent, Bonemancer, type BotError, BrowserManualMatchSandbox, BrowserMatchSandbox, type BrowserSandboxOptions, CASTING_MOVEMENT_MULT, COLLISION_RADIUS, type CastCancelEvent, type CastStartEvent, 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, KNOCKBACK_DAMAGE_THRESHOLD, KNOCKBACK_DECAY, KNOCKBACK_DELAY, KNOCKBACK_SPEED_PER_DAMAGE, LAVA_BORDER_WIDTH, 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 MissileAction, type MissileActions, type MissileConfig, type MissileContext, type MissileExpiredEvent, type MissileFunction$1 as MissileFunction, type MissileHitEvent, type MissileLaunchEvent, type MissileOobEvent, type MissileTemplate, Nightblade, type ParamDeclaration, type Position, type ProjectileState, Pyromancer, RULES, RULESET_RANGES, 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 ShieldBlockEvent, type ShieldStartEvent, type SimEvent, 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 WizardContext, type WizardDeathEvent, type WizardEntry, type WizardFunction, type WizardGroup, type WizardLavaDeathEvent, type WizardState, type WorkerFactory, type WorkerLike, analyzeThreats, angleDiff, angleInRange, angleTo, applyDamage, applyRulesetOverrides, blink, browserSandboxFight, browserSandboxSimulate, calculateBlinkCooldown, calculateMissileCastTime, calculateMissileRadius, calculateMissileSimilarity, calculateShieldBlock, calculateWarmupMultiplier, cancel, cancelCast, clampPositionToArena, clampToArena, clearHooks, clearParamValues, completeCast, createEntitySeed, createInitialState, createRandom, createWorkerScript, currentRuleset, diagnoseTrace, directionAway, directionTo, distanceTo, effectiveTurnRateCost, extractAction, extractMissileAction, extractStats, extractTraceEvents, fight, findInRange, findNearest, fitMissileForEscapingTarget, fitMissileToBudget, flyStraight, formatDiagnosis, formatStats, formatTraceEvents, formatTraceSummary, generateCandidates, generateCombos, getAdaptiveMissileConfig, getEffectiveRange, getLeadPosition, getMissileCastTime, getMissileContext, getPlayerState, getWizardContext, hashCombine, homingMissile, idle, inRange, interceptAngle, isBannedBotName, isInLava, magnitude, matchesAnyBanRule, missile, move, moveInDirection, moveProjectile, moveWizard, narrowRange, nextRandom, normalize, normalizeAngle, predictPosition, resetAllHooks, resetRuleset, resolveWizardCollision, runWithHooks, runWizardWithContext, scoreFight, scoreFightAsWizard2, seekerMissile, setParamValues, shield, simulate, simulateMinDuration, sortByDistance, spiralMissile, startCast, startDiscovery, stopDiscovery, straightMissile, summarizeTrace, sweptCircleCollision, testBot, tick, turnToAngle, turnToward, updateShield, useArenaSize, useBlinkCooldown, useCastProgress, useCastingSpell, useClosestThreat, useDamageDealt, useDamageTaken, useEffect, useEnemy, useHealth, useLastHitTick, useLastMissileConfig, useMemo, useMyProjectiles, useMyThreatsToEnemy, useParam, usePosition, useProjectiles, useRandom, useRef, useShieldStrength, useState, useStatus, useThreats, useTick, useTicksUntilReady, useVelocity, validateHookCall, validateMissileConfig, withMissileContext, withWizardContext, wrapWithParams };