@vibemancer/core 1.0.3 → 1.0.5

package/dist/index-browser-AFWi8jxB.d.ts

@@ -0,0 +1,3077 @@
+/**
+ * VIBEMANCER - HOOKS API TYPES
+ *
+ * Types for the hooks-based bot API.
+ *
+ * UNITS REFERENCE (100 ticks = 1 second):
+ *   Position:   absolute world coordinates, 0-860 on each axis. The arena is 860x860,
+ *               but only [30, 830] is safe — the outer 30 units are lethal lava.
+ *   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
+ *
+ * This file contains all the TypeScript interfaces used by the game engine.
+ */
+/**
+ * Position in 2D space.
+ */
+interface Position {
+    x: number;
+    y: number;
+}
+/**
+ * Velocity in 2D space (units per tick).
+ */
+interface Velocity {
+    x: number;
+    y: number;
+}
+/**
+ * Wizard state.
+ */
+interface WizardState {
+    id: string;
+    position: Position;
+    rotation: number;
+    health: number;
+    maxHealth: number;
+    state: 'idle' | 'casting' | 'channeling' | 'gcd_locked';
+    castingSpell?: 'missile' | 'shield' | 'blink';
+    castProgress?: number;
+    castDuration?: number;
+    channelingSpell?: 'shield';
+    channelDuration?: number;
+    gcdRemaining?: number;
+    blinkCooldown: number;
+    velocity: Velocity;
+    lastMissileConfig?: MissileConfig;
+    warmupMultiplier?: number;
+    invincible?: boolean;
+}
+/**
+ * Projectile (missile) state.
+ */
+interface ProjectileState {
+    id: string;
+    type: 'missile';
+    ownerId: string;
+    position: Position;
+    rotation: number;
+    speed: number;
+    turnRate: number;
+    damage: number;
+    remainingTicks: number;
+}
+/**
+ * Game configuration (read-only).
+ */
+interface GameConfig {
+    arenaSize: {
+        width: number;
+        height: number;
+    };
+    tickRate: number;
+    maxTicks: number;
+}
+/**
+ * Full game state passed to wizard.
+ */
+interface GameState {
+    tick: number;
+    position: Position;
+    rotation: number;
+    health: number;
+    maxHealth: number;
+    state: WizardState['state'];
+    castingSpell?: 'missile' | 'shield' | 'blink';
+    castProgress?: number;
+    castDuration?: number;
+    channelingSpell?: 'shield';
+    channelDuration?: number;
+    gcdRemaining?: number;
+    blinkCooldown: number;
+    velocity: Velocity;
+    lastMissileConfig?: MissileConfig;
+    warmupMultiplier?: number;
+    enemies: WizardState[];
+    projectiles: ProjectileState[];
+    myProjectiles: ProjectileState[];
+    damageDealt: number;
+    damageTaken: number;
+    lastHitTick: number;
+    /** Events emitted during the most recent tick (empty for the initial state). */
+    events: SimEvent[];
+}
+/**
+ * Actions returned by wizard each tick.
+ *
+ * Movement uses world-space coordinates:
+ * - x: +100 = right, -100 = left
+ * - y: +100 = down, -100 = up
+ * - Diagonal movement is normalized (magnitude capped at 100)
+ * - No rotation tracking - just output (x, y) direction
+ */
+interface WizardActions {
+    /**
+     * Movement direction in world-space.
+     * Values are clamped to [-100, 100] range.
+     * Magnitude is normalized to max 100 for diagonal movement.
+     */
+    move: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Start a new cast (only works if state === 'idle').
+     */
+    startCast?: {
+        spell: 'missile';
+        config: MissileConfig;
+        missileAI: MissileFunction;
+        direction?: number;
+    } | {
+        spell: 'shield';
+    } | {
+        spell: 'blink';
+        target: Position;
+    };
+    /**
+     * Cancel current cast or channel (works if casting or channeling).
+     */
+    cancel?: boolean;
+    /**
+     * Update aim direction while casting a missile (degrees).
+     * The missile fires in this direction at launch, allowing tracking during cast.
+     * Only applies while state === 'casting' and castingSpell === 'missile'.
+     */
+    aimDirection?: number;
+    /**
+     * Missile 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.
+ */
+interface MissileConfig {
+    damage: number;
+    speed: number;
+    turnRate: number;
+    duration: number;
+}
+/**
+ * Missile AI function type — re-exported from hooks/types.ts.
+ */
+type MissileFunction = MissileFunction$1;
+/**
+ * Actions returned by missile each tick.
+ */
+interface MissileActions {
+    turnToward?: Position;
+    turnToAngle?: number;
+}
+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;
+/**
+ * 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: 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: 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: 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: number;
+declare const MISSILE_DAMAGE_SCALE: number;
+declare const MISSILE_DAMAGE_POWER: number;
+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.
+ * Higher turn rate = more expensive cast. Negative values clamped to 0.
+ */
+declare function effectiveTurnRateCost(turnRate: number): number;
+/**
+ * Validate and sanitize missile config.
+ * Ensures all values meet minimum requirements (Lesson #9).
+ */
+declare function validateMissileConfig(config: MissileConfig): MissileConfig;
+/**
+ * Calculate missile cast time from config.
+ *
+ * Base formula:
+ * cast_time = 0.1
+ *           + 0.226 × damage^(2/3)
+ *           + 0.12 × effectiveTurnRateCost(turnRate)
+ *           + 0.10 × (effectiveTurnRateCost(turnRate) × durationSeconds)
+ *           + 0.025 × (speed × durationSeconds - 1.5)
+ *
+ * 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: 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;
+/**
+ * Calculate how similar two missile configs are (0 to 1).
+ * Returns 1 for identical configs, 0 for very different ones.
+ * Used by the warmup system to determine cast time multiplier.
+ *
+ * Only compares speed, turnRate, and duration — these define the missile
+ * "style" (melee stab vs ranged homing vs fast snipe). Damage is excluded
+ * because varying power doesn't change playstyle.
+ */
+declare function calculateMissileSimilarity(prev: MissileConfig | undefined, current: MissileConfig): number;
+/**
+ * Calculate the cast time multiplier from the warmup system.
+ * Returns < 1 for bonus (faster), > 1 for penalty (slower), 1 for neutral.
+ *
+ * Similar to previous cast → multiplier approaches (1 - MAX_BONUS) = 0.80
+ * Very different from previous → multiplier approaches (1 + MAX_PENALTY) = 1.20
+ * No previous cast → full bonus (1 - MAX_BONUS) = 0.80
+ */
+declare function calculateWarmupMultiplier(prev: MissileConfig | undefined, current: MissileConfig): number;
+declare const MATCH_DURATION = 30000;
+declare const DEFAULT_SEED = 42;
+declare const MAX_HEALTH: number;
+declare const COLLISION_RADIUS = 5;
+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 — a stable content hash of packages/core/src.
+ *
+ * Derived by `scripts/update-engine-version.mjs` from the engine sources, so it changes
+ * only when the engine changes — NOT on every build.
+ * The same value is propagated to `packages/functions/src/engine-version.generated.ts`
+ * so cloud functions and the core engine always agree on one version.
+ *
+ * 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 = 4396905295552957;
+
+/**
+ * VIBEMANCER — BOT COMPUTE BUDGET
+ *
+ * The real-time guard, moved off the whole fight and onto each bot.
+ *
+ * Decision 0002: fight LENGTH is simulation time (`maxTicks`) and always was; "stop a bot
+ * looping forever" genuinely needs real time. Conflating both into one wall-clock timeout
+ * around the entire match meant a slow SERVER was indistinguishable from a broken bot — and
+ * matchmaking blamed the player for it, up to auto-deactivating their bot.
+ *
+ * The constraint that shapes this module: the tick loop runs INSIDE the isolate, where the
+ * only clock is `Date.now()`. There is no way to measure a bot in machine-independent units
+ * from in there. So this guard is wall-clock, and wall clock on a shared server is exactly
+ * the thing that caused the original bug.
+ *
+ * The resolution is therefore in what going over budget COSTS:
+ *
+ *   - A bot has ONE budget: total thinking time across a whole fight.
+ *   - Spend it and the bot is not called again for the rest of the fight. It stands still.
+ *   - That is never recorded as an error, so it cannot increment `consecutiveCrashes` and
+ *     cannot auto-deactivate a bot.
+ *
+ * A bot too slow to answer loses the fight it was too slow for, which is the same thing that
+ * happens to a lagging player in any real-time game. A busy server can cost someone a match;
+ * it must never cost them their bot.
+ *
+ * ## Why there is no per-tick limit
+ *
+ * There was one, briefly: overrun 50ms in a single tick and that tick's action was
+ * discarded. It had to go, and the reason is the important part of this file.
+ *
+ * This engine is DETERMINISTIC by design. Spectate re-simulates a recorded match and gates
+ * on ENGINE_VERSION precisely so that the same version and seed reproduce the same fight. A
+ * per-tick threshold breaks that: under load a single call can cross 50ms through a GC pause
+ * or a scheduler hiccup, its action is discarded, and the fight diverges. Outcomes then
+ * depend on how busy the machine was — which is the original bug, reintroduced at finer
+ * granularity by the thing meant to fix it. It was caught by a test that passed alone and
+ * failed inside a loaded run.
+ *
+ * A single cumulative budget does not have that problem in practice. Measurement still
+ * varies with load, but it only changes BEHAVIOUR at one point — exhaustion — and an honest
+ * bot never approaches it: the worst real bot measured spends 5.6s of a 45s allowance. So
+ * every legitimate fight is bit-identical to an unbudgeted one, and determinism holds.
+ *
+ * A bot that stalls inside one tick is left to the outer wall-clock backstop, which is the
+ * only thing that could ever catch it anyway: a `while(true)` cannot be interrupted from
+ * inside a single-threaded isolate, no matter what the tick loop measures.
+ *
+ * Everything here is pure arithmetic so it can be tested exhaustively. The only impure part
+ * — reading the clock — stays in the tick loop.
+ *
+ * A note on precision, because it looks broken and is not. `Date.now()` resolves to 1ms here
+ * (measured), while a typical bot call is microseconds — so nearly every individual call
+ * measures 0ms and contributes nothing. That is fine, and deliberately not "fixed": a call
+ * lasting d milliseconds (d < 1) straddles a millisecond boundary with probability d, so it
+ * reads 1 exactly that often and 0 otherwise. The expected measurement equals the true
+ * duration, which over the thousands of calls in a fight is what a cumulative budget needs.
+ * Swapping in a higher-resolution clock is not an option anyway: inside the isolate there is
+ * no other clock, and a per-call `performance.now()` would cost more than it measures.
+ */
+/** Limits applied to a single bot for one fight. */
+interface BudgetLimits {
+    /** Milliseconds a bot may spend thinking, in total, before it stops being called. */
+    totalMs: number;
+}
+/** A single bot's running spend for one fight. */
+interface BotBudgetState {
+    spentMs: number;
+    exhausted: boolean;
+}
+/**
+ * Default, sized from measurement (2026-08-30) — and resized once, after the first
+ * measurement turned out to be worthless.
+ *
+ * The first pass measured TargetDummy, a bot whose entire body is `return idle()`. Against
+ * that, a full-length 30,000-tick match costs ~196ms and any budget looks generous. Real
+ * built-in bots are nothing like it. One `fight()` — ten matches — between two of them:
+ *
+ *     Bonemancer vs Turtle       18392ms
+ *     Bonemancer vs Spellseeker  11251ms
+ *     Turtle vs Hogger           10185ms
+ *
+ * and instrumenting the calls shows bot code is 70-78% of that, one honest bot spending
+ * 5611ms in a single fight. A 20s budget, which had looked like 200x headroom, was really
+ * about 2-4x — it would have fired on innocent play the first time the server was busy,
+ * which is the exact bug it exists to prevent.
+ *
+ * Hence 45s per bot per fight: roughly 8x the honest worst case measured here. That margin
+ * is also what keeps fights deterministic, since behaviour only changes if it is reached.
+ *
+ * This exists to catch runaway code, not to make anyone optimise.
+ */
+declare const DEFAULT_BUDGET: BudgetLimits;
+/**
+ * Last-resort wall-clock backstop for a whole fight (ms).
+ *
+ * Lives here, next to the budget, because the two numbers only make sense together: the
+ * budget is what bounds bot compute, and this is only for the case no in-isolate guard can
+ * reach — a bot in `while(true)`, which cannot be interrupted from inside a single-threaded
+ * isolate no matter what the tick loop measures.
+ *
+ * One runaway bot (45s of budget) plus an honest opponent has to fit inside it, or the
+ * backstop fires first and the budget never gets to attribute anything. It is capped at 110s
+ * rather than raised further because the mcp Cloud Function's own `timeoutSeconds` is 120 —
+ * above that the platform kills the request first and nothing useful is reported.
+ *
+ * It is a single exported constant precisely because it was previously four separate
+ * literals (bundle-fight, sandbox twice, functions/fight-runner) that drifted apart.
+ */
+declare const DEFAULT_FIGHT_BACKSTOP_MS = 110000;
+/**
+ * Both bots' budgets for ONE FIGHT.
+ *
+ * The scope matters more than it looks. `fight()` is not one simulation, it is ten (five
+ * spawn distances, each played from both sides). A budget scoped to a single `simulate`
+ * would hand a runaway bot its whole total ten times over — 450 seconds of bot compute
+ * inside a 110-second backstop — and would look like it was bounding something while
+ * bounding nothing. So the budget belongs to the fight, and is carried across its matches.
+ *
+ * This is the one mutable thing in this module: `simulate` updates `states` in place as it
+ * runs so the spend survives from one match to the next.
+ */
+interface FightBudget {
+    states: [BotBudgetState, BotBudgetState];
+    limits: BudgetLimits;
+}
+/** A fresh budget for one bot at the start of a fight. */
+declare function createBudgetState(): BotBudgetState;
+/** A fresh budget covering both bots for one whole fight (all of its matches). */
+declare function createFightBudget(limits?: BudgetLimits): FightBudget;
+/** May this bot still be called at all? */
+declare function mayAct(state: BotBudgetState): boolean;
+/**
+ * Record what one call cost.
+ *
+ * A non-finite elapsed time is ignored rather than charged, and a negative one cannot refund
+ * budget — `Date.now()` can step backwards on an NTP correction or a VM migration, and that
+ * must not become a way to earn compute.
+ */
+declare function recordSpend(state: BotBudgetState, limits: BudgetLimits, elapsedMs: number): BotBudgetState;
+
+interface InternalWizardState extends WizardState {
+    missileConfig?: MissileConfig;
+    missileAI?: MissileFunction$1;
+    blinkTarget?: {
+        x: number;
+        y: number;
+    };
+    damageDealt: number;
+    damageTaken: number;
+    lastHitTick: number;
+    knockbackVx?: number;
+    knockbackVy?: number;
+    knockbackDelay?: number;
+    knockbackPendingVx?: number;
+    knockbackPendingVy?: number;
+}
+/**
+ * Initialize a new match state.
+ */
+declare function createInitialState(_seed: number, spawnDist?: number): GameState;
+/**
+ * Process one game tick.
+ */
+declare function tick(currentTick: number, wizard1AI: WizardFunction, wizard2AI: WizardFunction, config: GameConfig, wizards: InternalWizardState[], projectiles: ProjectileState[], missileAIs: Map<string, MissileFunction$1>, matchSeed: number, budgets?: {
+    states: [BotBudgetState, BotBudgetState];
+    limits: BudgetLimits;
+}): {
+    nextTick: number;
+    wizards: InternalWizardState[];
+    projectiles: ProjectileState[];
+    events: SimEvent[];
+    errors: BotError[];
+    budgets?: [BotBudgetState, BotBudgetState];
+};
+/**
+ * Get the game state from a specific player's perspective.
+ * Returns a deep clone to prevent mutation of history entries.
+ * Used for history recording where independent snapshots are needed.
+ */
+declare function getPlayerState(playerIndex: number, wizards: InternalWizardState[], projectiles: ProjectileState[], tick: number, 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. */
+type FightWinner = 'wizard-1' | 'wizard-2' | 'draw';
+/**
+ * Result of a simulation.
+ */
+/** A runtime error captured from a bot or missile AI function. */
+interface BotError {
+    tick: number;
+    entityId: string;
+    message: string;
+}
+interface SimulateResult {
+    /** 'wizard-1'/'wizard-2' = killed opponent, 'draw' = simultaneous kill, null = timeout */
+    winner: MatchWinner;
+    ticks: number;
+    finalState: GameState;
+    history: GameState[];
+    /** Runtime errors thrown by bot or missile AI functions (empty if no errors). */
+    errors: BotError[];
+}
+/**
+ * Result of a fight (best-of-5 at different spawn distances).
+ */
+interface FightResult {
+    wizard1Wins: number;
+    wizard2Wins: number;
+    draws: number;
+    /** Winner of the fight: 'wizard-1', 'wizard-2', or 'draw' (never null) */
+    winner: FightWinner;
+    /**
+     * Individual match results (one per spawn distance, non-swapped only).
+     * Used for visual playback in the web viewer. Scoring includes both sides.
+     */
+    matches: SimulateResult[];
+}
+/** Spawn distances for the 5 matches in a fight (creates butterfly effect variation) */
+declare const FIGHT_SPAWN_DISTANCES: number[];
+/**
+ * Run a fight: 10 matches (5 spawn distances × 2 sides) between two bots.
+ * Each spawn distance is played twice — once with each bot on each side —
+ * to ensure results are independent of starting position.
+ *
+ * The `matches` array contains only the 5 non-swapped matches (for visual playback).
+ * The scoring aggregates (wizard1Wins, wizard2Wins, draws) include all 10 matches.
+ *
+ * This is the standard way to determine who wins a matchup.
+ * Used by both the tournament system and the visual UI.
+ */
+declare function fight(wizard1AI: WizardFunction, wizard2AI: WizardFunction, options?: {
+    seed?: number;
+    maxTicks?: number;
+    /**
+     * Per-bot compute budget for the WHOLE fight — all ten matches share it. Omitted
+     * means unbudgeted. See bot-compute-budget.ts.
+     */
+    budgetLimits?: BudgetLimits;
+}): FightResult;
+/**
+ * Run a full match simulation.
+ *
+ * @param options.skipHistory - When true, skips recording per-tick history snapshots.
+ *   This dramatically improves performance (no deep cloning per tick) and is used
+ *   by the optimizer and fight() scoring. The returned history array will be empty
+ *   and finalState will still be populated.
+ */
+declare function simulate(wizard1AI: WizardFunction, wizard2AI: WizardFunction, options?: {
+    maxTicks?: number;
+    seed?: number;
+    spawnDistance?: number;
+    skipHistory?: boolean;
+    /**
+     * Per-bot compute budget for this match alone. Omitted means unbudgeted, which is
+     * what manual play and most tests want — the clock is then never read at all. See
+     * bot-compute-budget.ts for why exceeding it costs a bot its action rather than
+     * producing an error.
+     */
+    budgetLimits?: BudgetLimits;
+    /**
+     * A budget SHARED across every match of a fight, updated in place as this match
+     * runs. This is what `fight()` passes, because a fight is ten matches and a
+     * per-match budget would bound nothing. Takes precedence over `budgetLimits`.
+     */
+    budget?: FightBudget;
+}): SimulateResult;
+
+/**
+ * VIBEMANCER - HOOKS RUNTIME
+ *
+ * This file implements a minimal React-like hooks runtime for AI programming.
+ * It supports useState, useEffect, useMemo, useRef, and useParam with entity isolation.
+ *
+ * RULES OF HOOKS (same as React):
+ * - Hooks must be called at the top level of the bot function
+ * - Hooks must be called in the same order every tick
+ * - Hooks must NOT be called conditionally
+ *
+ * Violating these rules throws an error (detected via hook index validation).
+ */
+
+interface HookState {
+    values: unknown[];
+    effects: {
+        callback: () => void | (() => void);
+        deps?: unknown[];
+        cleanup?: () => void;
+    }[];
+    memos: {
+        value: unknown;
+        deps?: unknown[];
+    }[];
+    /** Type of each hook call in order (for validation). */
+    hookTypes: string[];
+    /** Total hooks called on first successful tick. */
+    hookCount: number;
+    /** Whether the first tick has completed successfully (hook pattern established). */
+    initialized: boolean;
+}
+/**
+ * Validate a hook call and return its sequential index.
+ * Ensures hooks are called in the same order every tick.
+ *
+ * On the first tick: records the hook type at this index.
+ * On subsequent ticks: validates the hook type matches.
+ *
+ * @param type - The hook type name (e.g., 'useState', 'useEffect', 'useParam')
+ * @returns The sequential hook index
+ * @throws If called outside runWithHooks or if hook order changed
+ */
+declare function validateHookCall(type: string): number;
+/**
+ * Run a function with a specific entity's hook context.
+ */
+declare function runWithHooks<T>(entityId: string, fn: () => T): T;
+/**
+ * Run a bot function with full context (game state + persistence hooks).
+ * Use this when you need to set BOTH the entity ID and the game context.
+ */
+declare function runWizardWithContext<T>(entityId: string, context: WizardContext, fn: () => T): T;
+/**
+ * Run a function with game state context only, preserving the current entity ID.
+ * Used by the simulation to set up WizardContext before calling hooks-style bots.
+ */
+declare function withWizardContext<T>(context: WizardContext, fn: () => T): T;
+/**
+ * Get the current bot context. Throws if called outside bot execution.
+ */
+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.
+ */
+declare function useState<T>(initialValue: T | (() => T)): [T, (newValue: T | ((prev: T) => T)) => void];
+/**
+ * React to state changes.
+ */
+declare function useEffect(callback: () => void | (() => void), deps?: unknown[]): void;
+/**
+ * Memoize expensive calculations.
+ */
+declare function useMemo<T>(factory: () => T, deps?: unknown[]): T;
+/**
+ * Mutable reference that persists across ticks.
+ * Unlike useState, mutations don't need a setter - just modify .current directly.
+ */
+interface RefObject<T> {
+    current: T;
+}
+declare function useRef<T>(initialValue: T): RefObject<T>;
+/**
+ * Clear hook state for an entity (e.g., when it dies).
+ */
+declare function clearHooks(entityId: string): void;
+/**
+ * Reset all hook states (e.g., when a match restarts).
+ */
+declare function resetAllHooks(): void;
+
+/**
+ * Move a wizard based on world-space input direction.
+ *
+ * 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;
+    y: number;
+}, deltaTicks: number): Position;
+/**
+ * Move a projectile in its current rotation direction.
+ */
+declare function moveProjectile(projectile: ProjectileState, deltaTicks: number): Position;
+/**
+ * Clamp a position to the 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.
+ * Iterates until stable: wizard push → wall clamp → re-check overlap → repeat.
+ */
+declare function resolveWizardCollision(wizard1: WizardState, wizard2: WizardState): void;
+/**
+ * Perform swept circle collision detection between a moving point (projectile) and a stationary circle (wizard).
+ * Returns true if a collision occurred during the movement from oldPos to newPos.
+ */
+declare function sweptCircleCollision(oldPos: Position, newPos: Position, radius: number, targetPos: Position, targetRadius: number): boolean;
+
+/**
+ * Start casting a spell.
+ * For missiles, applies warmup system (bonus for similar, penalty for switching).
+ */
+declare function startCast(wizard: WizardState, spell: 'missile' | 'shield' | 'blink', config?: MissileConfig): void;
+/**
+ * Cancel the current cast.
+ */
+declare function cancelCast(wizard: WizardState): void;
+/**
+ * Complete the current cast and trigger the spell effect.
+ */
+declare function completeCast(wizard: WizardState): void;
+/**
+ * Update the shield channel state.
+ */
+declare function updateShield(wizard: WizardState, deltaTicks: number): void;
+/**
+ * Calculate the current block percentage of a shield based on channel duration.
+ */
+declare function calculateShieldBlock(channelDurationTicks: number): number;
+/**
+ * Apply damage to a wizard, considering shield mitigation.
+ *
+ * Shield blocks a percentage of damage based on channel duration:
+ * - Fresh shield (0s): 90% block → 10% damage through
+ * - Decayed shield: block % decreases over time (20%/sec)
+ * - Minimum: 30% block → 70% damage through
+ *
+ * (Design doc lines 196-212)
+ */
+declare function applyDamage(wizard: WizardState, damage: number, _projectile?: ProjectileState): number;
+
+/**
+ * VIBEMANCER - MANUAL MATCH
+ *
+ * Tick-by-tick match runner used by manual play mode. Wraps the same
+ * `tick()` primitive that `simulate()` uses, so stepping forward
+ * produces the same trajectory as a batched `simulate()` with the
+ * same seed.
+ *
+ * Extra capabilities over `simulate()`:
+ * - step(N) advances N ticks at a time (default 1) — caller controls pacing
+ * - replaceMissileAI(id, ai) hot-swaps a missile's AI mid-flight (used by
+ *   the missile-guide feature in manual play)
+ * - setInvincible(wizardIndex, on) toggles damage immunity per wizard
+ */
+
+interface ManualMatchOptions {
+    seed?: number;
+    spawnDistance?: number;
+    maxTicks?: number;
+}
+interface StepResult {
+    gameState: GameState;
+    errors: BotError[];
+    done: boolean;
+}
+declare class ManualMatch {
+    private readonly wizard1AI;
+    private readonly wizard2AI;
+    private readonly seed;
+    private readonly maxTicks;
+    private readonly config;
+    private wizards;
+    private projectiles;
+    private missileAIs;
+    /** First-replacement originals for 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
+     * match completes mid-batch.
+     */
+    step(count?: number): StepResult;
+    /**
+     * 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: MissileFunction$1): void;
+    /**
+     * 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;
+    /**
+     * Set the invincibility flag for a wizard. Invincible wizards take 0
+     * damage from all sources.
+     */
+    setInvincible(wizardIndex: 0 | 1, on: boolean): void;
+    /**
+     * Get the current game state from wizard-1's perspective.
+     * Returned object is a deep clone — safe to mutate.
+     */
+    getGameState(): GameState;
+    getCurrentTick(): number;
+    isComplete(): {
+        done: boolean;
+        winner: MatchWinner;
+    };
+    getResult(): SimulateResult;
+    dispose(): void;
+    private computeWinner;
+}
+
+/**
+ * VIBEMANCER - MISSILE TEMPLATES
+ *
+ * Reusable missile config + AI factories for manual play and bot examples.
+ * Each factory clamps its inputs to rules.ts minimums and returns a pure
+ * AI function that's safe to register with the engine.
+ */
+
+interface BaseParams {
+    damage: number;
+    speed: number;
+    duration: number;
+}
+interface TurningParams extends BaseParams {
+    turnRate: number;
+}
+type StraightParams = BaseParams;
+type HomingParams = TurningParams;
+interface SpiralParams extends BaseParams {
+    spiralRadius: number;
+    spiralFreq: number;
+}
+interface SeekerParams extends TurningParams {
+    minLockDistance: number;
+}
+interface MissileTemplate {
+    config: MissileConfig;
+    ai: MissileFunction$1;
+}
+/**
+ * Fire-and-forget missile. No steering — flies in a straight line.
+ */
+declare function straightMissile(p: StraightParams): MissileTemplate;
+/**
+ * Homing missile. Steers toward the enemy each tick.
+ */
+declare function homingMissile(p: HomingParams): MissileTemplate;
+/**
+ * Spiral missile. Continuously orbits its current heading while advancing.
+ * Uses missileState.remainingTicks as a deterministic phase counter so the
+ * AI is fully pure (no closure state).
+ */
+declare function spiralMissile(p: SpiralParams): MissileTemplate;
+/**
+ * Seeker missile. Homes toward the enemy, but only when farther away than
+ * minLockDistance — closer than that, the missile coasts straight (so it
+ * doesn't whirl around a target it's about to hit).
+ */
+declare function seekerMissile(p: SeekerParams): MissileTemplate;
+
+/**
+ * Calculate the distance between two points.
+ */
+declare function distanceTo(a: Position, b: Position): number;
+/**
+ * Check if two points are within a certain range of each other.
+ */
+declare function inRange(a: Position, b: Position, range: number): boolean;
+
+/**
+ * Calculate the angle from one point to another in degrees.
+ * 0° = right, 90° = down, 180° = left, 270° = up.
+ */
+declare function angleTo(from: Position, to: Position): number;
+/**
+ * Normalize an angle to the 0-360 range.
+ */
+declare function normalizeAngle(angle: number): number;
+/**
+ * Calculate the shortest difference between two angles (-180 to +180).
+ */
+declare function angleDiff(angleA: number, angleB: number): number;
+/**
+ * Check if an angle is within a certain range of a target angle.
+ */
+declare function angleInRange(angle: number, target: number, range: number): boolean;
+
+/**
+ * Get the position after moving a certain distance in a direction.
+ */
+declare function moveInDirection(position: Position, angle: number, distance: number): Position;
+/**
+ * Predict the position after N ticks given current velocity.
+ */
+declare function predictPosition(position: Position, velocity: Velocity, ticks: number): Position;
+/**
+ * Calculate the intercept angle for a target moving at a certain velocity.
+ * Returns null if no intercept solution exists.
+ */
+declare function interceptAngle(shooterPosition: Position, targetPosition: Position, targetVelocity: Velocity, projectileSpeed: number): number | null;
+
+/**
+ * Find the nearest entity from a list.
+ */
+declare function findNearest<T extends {
+    position: Position;
+}>(from: Position, entities: T[]): T | null;
+/**
+ * Find all entities within a certain range.
+ */
+declare function findInRange<T extends {
+    position: Position;
+}>(from: Position, entities: T[], range: number): T[];
+/**
+ * Sort entities by distance (closest first).
+ */
+declare function sortByDistance<T extends {
+    position: Position;
+}>(from: Position, entities: T[]): T[];
+
+/**
+ * Seeded PRNG utilities for deterministic randomness.
+ *
+ * Each entity (wizard, missile) gets its own random sequence that:
+ * - Is deterministic: same seed = same sequence
+ * - Is isolated: one entity's calls don't affect another's
+ * - Advances state: each call produces a different value
+ */
+/**
+ * Combine two seeds into one using a simple hash.
+ */
+declare function hashCombine(a: number, b: number): number;
+/**
+ * Advance the random state using a Linear Congruential Generator.
+ * Parameters from glibc (widely tested).
+ */
+declare function nextRandom(state: number): number;
+/**
+ * Create a seeded random number generator.
+ * Returns a function that produces values in [0, 1) and advances internal state.
+ */
+declare function createRandom(seed: number): () => number;
+/**
+ * Create a deterministic seed for an entity based on match seed, entity ID, and tick.
+ * This ensures reproducibility: same match + same entity + same tick = same random sequence.
+ */
+declare function createEntitySeed(matchSeed: number, entityId: string, tick: number): number;
+
+/**
+ * VIBEMANCER - SPATIAL UTILITIES
+ *
+ * Direction vectors and arena bounds utilities.
+ */
+
+/**
+ * Normalize a vector to unit length.
+ * Returns {x: 0, y: 0} for zero-length vectors.
+ */
+declare function normalize(vector: Position): Position;
+/**
+ * Get normalized direction vector from one position toward another.
+ * Returns {x: 0, y: 0} if positions are identical.
+ */
+declare function directionTo(from: Position, to: Position): Position;
+/**
+ * Get normalized direction vector from one position away from another.
+ * Returns {x: 0, y: 0} if positions are identical.
+ */
+declare function directionAway(from: Position, to: Position): Position;
+/**
+ * Clamp a position to valid arena bounds.
+ * Note: For wizard-specific clamping with radius, use clampToArena from physics.ts
+ */
+declare function clampPositionToArena(position: Position): Position;
+/**
+ * Get the length/magnitude of a vector.
+ */
+declare function magnitude(vector: Position): number;
+
+/**
+ * VIBEMANCER - COMBAT UTILITIES
+ *
+ * Utilities for combat calculations.
+ */
+
+/**
+ * Get cast time in ticks for a missile configuration.
+ * Applies the same clamps/validation as the engine before calculating,
+ * so the result matches the actual cast time that will be used in-game.
+ *
+ * If lastMissileConfig is provided, includes warmup multiplier.
+ * Pass undefined for first cast (full warmup) or null for base time only.
+ */
+declare function getMissileCastTime(config: MissileConfig, lastMissileConfig?: MissileConfig | null): number;
+/**
+ * Calculate the position to aim at to hit a moving target.
+ * Returns the intercept point where a missile would hit the target.
+ *
+ * @param targetPos - Current target position
+ * @param targetVel - Target velocity (units per tick)
+ * @param missileSpeed - Missile speed (units per tick)
+ * @param myPos - Shooter position
+ * @returns The position to aim at
+ */
+declare function getLeadPosition(targetPos: Position, targetVel: Velocity, missileSpeed: number, myPos: Position): Position;
+/**
+ * Calculate optimal missile configuration based on target behavior.
+ */
+declare function getAdaptiveMissileConfig(targetVelocity: Position, distance: number): {
+    speed: number;
+    turnRate: number;
+    damage: number;
+    duration: number;
+};
+/**
+ * Given a cast-time budget (in ticks) and a target distance, find the best
+ * missile config that fits. Maximizes damage while ensuring the missile
+ * can reach the target and finishes casting in time.
+ *
+ * Returns null if no useful missile fits in the budget.
+ *
+ * How it works: tries several speed/turnRate templates. For each, calculates
+ * the minimum duration to reach `distance`, then solves the cast-time formula
+ * for the maximum damage that fits within `budgetTicks`.
+ *
+ * If `lastMissileConfig` is provided, accounts for warmup bonus: similar
+ * missiles cast faster, so more damage can fit in the same budget.
+ */
+/**
+ * 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;
+/**
+ * Fit a missile config that accounts for the enemy escaping during cast time.
+ *
+ * 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.
+ *
+ * @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 function fitMissileForEscapingTarget(currentDistance: number, budgetTicks: number, options?: {
+    minTurnRate?: number;
+    maxDamage?: number;
+    lastMissileConfig?: MissileConfig;
+    enemyApproaching?: boolean;
+    distanceBuffer?: number;
+    maxIterations?: number;
+}): MissileConfig | null;
+
+/**
+ * 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 function useRandom(): () => number;
+/**
+ * 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-860).
+ *
+ * Clamped to [5, 855] — the ARENA bounds minus the wizard radius, NOT the playfield. That
+ * distinction is the difference between living and dying: the playfield is [30, 830] and
+ * everything outside it is lava, so you can walk straight out of the safe area and be
+ * killed. Nothing stops you. Check against ARENA_MIN/ARENA_MAX, not against these numbers.
+ *
+ * (This previously quoted the playfield-sized bounds as the clamp, which told the reader
+ * they were safely fenced in. They are not — see docs-match-engine.test.ts.)
+ */
+declare function usePosition(): Position;
+/**
+ * Get your current velocity as {x, y} in units/tick.
+ * Max magnitude is 1 u/t when idle, 0.5 u/t when casting, 0 when channeling shield.
+ */
+declare function useVelocity(): Velocity;
+/**
+ * Get your current status:
+ * - 'idle':        free to act
+ * - 'casting':     casting a spell (missile or blink). Can move at 50% speed.
+ * - 'channeling':  channeling shield. Cannot move. Cancel anytime with cancel().
+ * - 'gcd_locked':  global cooldown after spell. Can move at full speed, but cannot cast.
+ */
+declare function useStatus(): 'idle' | 'casting' | 'channeling' | 'gcd_locked';
+/**
+ * Get ticks until you can start a new spell.
+ *
+ * Returns 0 when idle or channeling (shield can be canceled immediately).
+ * During casting: remaining cast ticks. During GCD: remaining GCD ticks.
+ *
+ * Note: 100 ticks = 1 second.
+ */
+declare function useTicksUntilReady(): number;
+/**
+ * Get current shield block multiplier.
+ *
+ * Returns 0 if not channeling shield.
+ * Returns 0.3-0.9 if channeling: starts at 0.9 (blocks 90%), decays by 0.2/sec,
+ * minimum 0.3 (blocks 30%). The remaining damage gets through:
+ * actualDamage = incomingDamage × (1 - shieldStrength).
+ */
+declare function useShieldStrength(): number;
+/**
+ * Get all projectiles currently in flight (yours and enemy's).
+ * Used for blink safety calculations and threat analysis.
+ */
+declare function useProjectiles(): ProjectileState[];
+/**
+ * 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.
+ *
+ * Cooldown scales with distance used:
+ * - 100 units → ~100 ticks (1s)
+ * - 300 units (max range) → 2000 ticks (20s)
+ *
+ * Note: 100 ticks = 1 second.
+ */
+declare function useBlinkCooldown(): number;
+/**
+ * Get currently casting spell, or null if not casting.
+ * Returns 'missile', 'shield', or 'blink'.
+ */
+declare function useCastingSpell(): 'missile' | 'shield' | 'blink' | null;
+/**
+ * Get cast progress as {current, total} in ticks, or null if not casting.
+ *
+ * current = ticks elapsed, total = ticks needed. When current >= total, spell fires.
+ * Note: 100 ticks = 1 second.
+ */
+declare function useCastProgress(): {
+    current: number;
+    total: number;
+} | null;
+/**
+ * Get enemy wizard state.
+ *
+ * Returns position, velocity, health, status, casting spell, and shield strength.
+ * Note: you cannot see the enemy's missile configs or exact cooldown timers —
+ * only their status and what's visible on the field.
+ */
+declare function useEnemy(): EnemyState;
+/**
+ * Get all your active (in-flight) projectiles.
+ * Each has position, rotation (degrees), speed (u/t), turnRate, remainingTicks.
+ */
+declare function useMyProjectiles(): ProjectileState[];
+/**
+ * Get total damage you've dealt this match.
+ */
+declare function useDamageDealt(): number;
+/**
+ * Get total damage you've taken this match.
+ */
+declare function useDamageTaken(): number;
+/**
+ * Get the tick number when you last took damage. Returns 0 if never hit.
+ * Compare with useTick() to get ticks since last hit.
+ */
+declare function useLastHitTick(): number;
+/**
+ * Get arena dimensions. Default: {width: 860, height: 860} — the FULL arena, lava included.
+ * The safe playfield is [30, 830]; the outer 30 units on every side are lethal.
+ *
+ * Wizards are clamped to [5, 855] (arena bounds minus the radius of 5), which does not keep
+ * them out of the lava.
+ */
+declare function useArenaSize(): {
+    width: number;
+    height: number;
+};
+/**
+ * Get current game tick (starts at 0, increments each tick).
+ * 100 ticks = 1 second. Match ends at 30,000 ticks (5 minutes).
+ */
+declare function useTick(): number;
+/**
+ * Get analyzed threats from all incoming enemy projectiles.
+ * Sorted by ticksToImpact (soonest first). Only includes missiles within 500 units
+ * or that are predicted to hit.
+ *
+ * Each threat includes:
+ * - ticksToImpact: ticks until hit (Infinity if will miss)
+ * - willHit: true if missile hits your current position
+ * - canDodgeLeft/Right: whether strafing perpendicular to missile heading works
+ * - canOutrun: whether moving away from missile escapes it
+ * - bestDodgeDirection: {x, y} unit vector to dodge optimally, or null if undodgeable
+ * - canBlockInTime: whether you can raise shield before impact
+ * - ticksToStartShield: when to START channeling shield to block in time
+ */
+declare function useThreats(): AnalyzedThreat[];
+/**
+ * Get the most imminent threat, or null if no threats.
+ * Shorthand for useThreats()[0].
+ */
+declare function useClosestThreat(): AnalyzedThreat | null;
+/**
+ * Get your missiles analyzed from the enemy's perspective.
+ * Useful to predict when enemy will shield/dodge your attacks.
+ */
+declare function useMyThreatsToEnemy(): AnalyzedThreat[];
+
+/**
+ * VIBEMANCER - THREAT ANALYSIS
+ *
+ * Pre-computes threat information for incoming projectiles.
+ * This handles the "subconscious" perception of missile trajectories.
+ */
+
+/**
+ * Analyze all threats from enemy projectiles.
+ *
+ * @param myPos - Current position of the wizard
+ * @param projectiles - All projectiles in the game
+ * @param myProjectiles - Only the bot's own projectiles (used for filtering)
+ * @param ticksUntilReady - Ticks until wizard can start a new action
+ * @returns Array of analyzed threats sorted by ticksToImpact (soonest first)
+ */
+declare function analyzeThreats(myPos: Position, projectiles: ProjectileState[], myProjectiles: ProjectileState[], ticksUntilReady: number): AnalyzedThreat[];
+
+/**
+ * VIBEMANCER - ACTION BUILDERS
+ *
+ * Fluent API for constructing bot actions with type-safe chaining.
+ *
+ * UNITS REFERENCE (100 ticks = 1 second):
+ *   Position:   absolute world coordinates, 0-860 on each axis (860×860 arena, of which
+ *               the outer 30 units on every side are lethal lava — playfield is [30, 830])
+ *   Movement:   direction vector, magnitude clamped to max 1 (speed in [0, 1])
+ *   Speed:      units per tick (player moves at 1.5 units/tick = 150 units/sec)
+ *   Duration:   ticks (divide by 100 for seconds)
+ *   Angles:     degrees (0°=right, 90°=down, 180°=left, 270°=up)
+ *   Damage:     raw HP removed on hit (wizard has 60 HP)
+ *   Turn rate:  degrees per tick the missile can rotate
+ */
+
+/**
+ * Channel a shield that blocks incoming damage.
+ *
+ * Starts at 90% block, decays by 20% per second, minimum 30%.
+ * Takes 20 ticks (0.2s) to activate. Movement is disabled while channeling.
+ * Cancel anytime with cancel(). Triggers 100-tick (1s) GCD after cancel.
+ *
+ * Can chain .move() — movement applies during the 20-tick cast, NOT during channel.
+ *
+ * @example
+ *   return shield();                    // shield and stay still
+ *   return shield().move(1, 0);         // move right while cast starts
+ */
+declare function shield(): ActionBuilder;
+/**
+ * Cast a missile spell.
+ *
+ * Cast time scales with damage, speed, duration, and turn rate — bigger missiles
+ * take longer to cast. While casting you move at 50% speed. After firing, 100-tick
+ * (1s) GCD before next spell.
+ *
+ * Repeated similar missiles cast 20% faster (warmup bonus). Switching styles
+ * incurs a 20% penalty.
+ *
+ * Can chain .move() for simultaneous movement while casting.
+ *
+ * @param config - Missile stats:
+ *   - damage:   HP removed on hit (1-60 typical). Also sets hitbox: radius = 2 + 0.1×damage.
+ *   - speed:    units/tick (min 1.5). Player moves at 1 u/t, so 5 = 5× player speed.
+ *   - duration: ticks the missile lives (min 10). Range ≈ speed × duration.
+ *   - turnRate: degrees/tick of homing (0 = straight line, 3 = moderate homing, 5+ = strong).
+ *              Negative = no homing + minor speed cost reduction.
+ * @param ai - Called every tick to control missile steering. 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.
+ *
+ * @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);
+ *
+ *   // 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 function missile(config: MissileConfig, ai: MissileFunction$1, direction: number): ActionBuilder;
+/**
+ * Teleport to an absolute position on the arena.
+ *
+ * Max range: 300 units from current position (clamped by engine if further).
+ * Cast time: 10 ticks (0.1s). Cooldown scales with distance:
+ *   - 100 units → 100 ticks (1s)
+ *   - 300 units → 2000 ticks (20s)
+ *
+ * Cannot chain .move() — blink IS the movement.
+ *
+ * @param x - Target X position (0-800, absolute world coordinate)
+ * @param y - Target Y position (0-800, absolute world coordinate)
+ *
+ * @example
+ *   return blink(400, 400);                              // blink to center
+ *   return blink(enemy.position.x, enemy.position.y);    // blink to enemy
+ */
+declare function blink(x: number, y: number): FinalAction;
+/**
+ * Cancel current cast or channel (e.g. stop shielding to attack).
+ *
+ * Canceling a cast/channel triggers 100-tick (1s) GCD.
+ * Can chain .move() for simultaneous movement.
+ *
+ * @example
+ *   return cancel().move(-1, 0);    // cancel and dodge left
+ */
+declare function cancel(): ActionBuilder;
+/**
+ * Move in a direction without casting any spell.
+ *
+ * This is a **direction vector**, not a target position. Values are in the
+ * range [-1, 1] where 1 = full speed. Larger values (like raw position
+ * deltas) are clamped to full speed automatically.
+ *
+ * @param x - Horizontal direction (positive = right, negative = left)
+ * @param y - Vertical direction (positive = down, negative = up)
+ *
+ * @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 function move(x: number, y: number): FinalAction;
+/**
+ * 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.
+ *
+ * @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.
+ *
+ * @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 function extractAction(finalAction: FinalAction): WizardActions;
+
+/**
+ * VIBEMANCER - PARAMETER RUNTIME
+ *
+ * Provides the useParam() hook for bots to declare tunable parameters,
+ * and the infrastructure for the optimizer to inject/discover parameter values.
+ *
+ * Design: Module-level state (JS is single-threaded, no race conditions).
+ * The optimizer sets param values before running a bot, and clears them after.
+ * During discovery, all useParam calls are recorded.
+ *
+ * ## useParam API
+ *
+ * ```typescript
+ * // Basic: just a value, no optimizer config
+ * const damage = useParam('damage', 15);
+ *
+ * // With range: optimizer searches value ± range (sliding window)
+ * const distance = useParam('distance', 350, {range: 150, min: 0});
+ *
+ * // With fixed min/max: optimizer searches [min, max] (fixed bounds)
+ * const damage = useParam('damage', 15, {min: 5, max: 25});
+ *
+ * // With all: range defines search radius, min/max clamp it
+ * const fraction = useParam('fraction', 0.25, {range: 0.2, min: 0, max: 1});
+ *
+ * // With custom step count: optimizer tests 20 values instead of default 10
+ * const distance = useParam('distance', 500, {range: 200, min: 0, steps: 20});
+ * ```
+ *
+ * - **Arg 1** `name` — unique parameter name (must be consistent across ticks)
+ * - **Arg 2** `value` — the actual value used in gameplay. This is what your bot
+ *   uses during matches. The optimizer script automatically updates this value.
+ * - **Arg 3** `config` (optional) — optimizer search configuration:
+ *   - `range` — search radius: optimizer checks `value ± range`. The auto-optimizer
+ *     rewrites `value` after each run, so the search window slides automatically.
+ *   - `min` / `max` — hard constraints (e.g., distance ≥ 0, fraction ≤ 1).
+ *     When `range` is omitted, these define fixed search bounds (old-style).
+ *   - `steps` — how many evenly-spaced values the optimizer tests per pass (default: 10).
+ *   - `substeps` — steps to use in refinement passes (passes 2+). Set to 0 to freeze
+ *     after pass 1 (ideal for boolean params). Defaults to `steps` if not specified.
+ *   - At least `range` or both `min` + `max` must be provided.
+ *
+ * Without optimizer config, useParam simply returns `value` every tick.
+ * With optimizer config, the offline optimizer script can override the value during search.
+ *
+ * ## Rules of Hooks
+ * useParam follows the same rules as useState/useEffect/etc:
+ * - Must be called at the top level of your bot function (not inside conditionals)
+ * - Must be called in the same order every tick
+ * - Violations are detected and throw errors
+ */
+
+/**
+ * Declaration of a tunable parameter, as discovered by the optimizer.
+ */
+interface ParamDeclaration {
+    name: string;
+    value: number;
+    range?: number;
+    min?: number;
+    max?: number;
+    steps: number;
+    /** Steps to use in refinement passes (passes 2+). 0 = freeze after pass 1. Defaults to `steps`. */
+    substeps?: number;
+}
+/**
+ * Declare a tunable parameter. Returns the current value (optimizer-injected or the provided value).
+ *
+ * @param name - Unique parameter name (consistent across ticks)
+ * @param value - The gameplay value. The auto-optimizer rewrites this in source code.
+ * @param config - Optional optimizer search configuration
+ * @returns The optimizer-injected value during optimization, or `value` during normal play
+ *
+ * @example
+ * // Simple: no optimizer config
+ * const damage = useParam('damage', 15);
+ *
+ * // With range: optimizer searches value ± range (sliding window)
+ * const distance = useParam('distance', 350, {range: 150, min: 0});
+ *
+ * // With fixed min/max: optimizer searches [min, max]
+ * const damage = useParam('damage', 15, {min: 5, max: 25});
+ */
+declare function useParam(name: string, value: number, config?: {
+    range?: number;
+    min?: number;
+    max?: number;
+    steps?: number;
+    substeps?: number;
+}): number;
+/**
+ * Inject parameter values for the next bot execution.
+ * The wrapped bot will read these values via useParam().
+ */
+declare function setParamValues(values: Record<string, number>): void;
+/**
+ * Clear injected parameter values. useParam() will return its provided value.
+ */
+declare function clearParamValues(): void;
+/**
+ * Start discovery mode. All subsequent useParam() calls with optimizer config
+ * will register their declarations.
+ */
+declare function startDiscovery(): void;
+/**
+ * Stop discovery mode and return all discovered parameter declarations.
+ */
+declare function stopDiscovery(): ParamDeclaration[];
+/**
+ * Wrap a bot function to inject specific parameter values.
+ * The returned function sets params before calling the bot and clears them after.
+ */
+declare function wrapWithParams(bot: WizardFunction, params: Record<string, number>): WizardFunction;
+
+/**
+ * Bot: TargetDummy
+ *
+ * BEHAVIOR: Does absolutely nothing. No movement, no spells, no AI.
+ *
+ * NAMING RATIONALE: "Target Dummy" is universal MMO player vocabulary for the
+ * practice objects found in capital cities. Every WoW/FFXIV player has beaten
+ * on a target dummy to test DPS rotations. That's exactly what this bot is —
+ * a punching bag for testing missile mechanics and baseline damage output.
+ * Nobody calls them "training dummies"; the player term is always "target dummy."
+ *
+ * STANDALONE — no tier progression. It's a test fixture, not a combatant.
+ */
+declare function TargetDummy(): FinalAction;
+
+/**
+ * Bot: Rookie
+ *
+ * BEHAVIOR: Stands perfectly still and fires straight (non-homing) missiles at
+ * the enemy. No movement, no dodging, no shielding. Knows one spell and uses
+ * it on cooldown. The wizard equivalent of an FPS player who stands in the open
+ * and holds left-click.
+ *
+ * NAMING RATIONALE: "Rookie" is the universal term for a first-timer who barely
+ * knows what they're doing. This bot is a day-one player who learned how to cast
+ * missile and nothing else. No movement, no defense, just raw "I press the button."
+ * We considered "Noob" (more accurate) but Rookie is less abrasive while conveying
+ * the same thing — a beginner who doesn't know any better.
+ *
+ * STANDALONE — no tier progression. Rookies either learn to play a real class
+ * or quit. This bot represents the rock-bottom of "at least it shoots."
+ */
+declare function Rookie(): FinalAction;
+
+/**
+ * Bot: Critter
+ *
+ * BEHAVIOR: Picks random valid actions each tick — random movement, random spells,
+ * random missile configs, random directions. Occasionally cancels its own casts.
+ * Uses engine-provided seeded random for deterministic behavior. Useful for
+ * finding edge cases in the engine, but completely useless in combat.
+ *
+ * NAMING RATIONALE: In WoW, critters are the 1-HP ambient mobs (rabbits, squirrels,
+ * prairie dogs) that wander around doing nothing useful and die to literally anything.
+ * This bot is the wizard equivalent — it flails around randomly and gets destroyed by
+ * anyone with a plan. The word "Critter" immediately tells any gamer "this thing is
+ * helpless and exists only to fill space."
+ *
+ * STANDALONE — no tier progression. Critters don't level up. However, a future
+ * "Hogger" bot could be an elite critter: same chaotic spirit but actually dangerous
+ * (like the famous WoW elite that wipes unprepared lowbies).
+ */
+declare function Critter(): FinalAction;
+
+/**
+ * Bot: Hogger
+ *
+ * BEHAVIOR: The elite critter. Chaotic and unpredictable but genuinely dangerous.
+ * Randomly varies missile configs each cast (damage 7-15, speed 3-8, random homing),
+ * moves erratically but still somewhat toward/away from the enemy, shields when
+ * in real danger, and blinks unpredictably. The randomness makes Hogger hard to
+ * predict — you never know if the next missile will be a slow tracker or a fast
+ * snipe. Unlike Critter's pure randomness, Hogger has enough combat awareness
+ * to actually win fights.
+ *
+ * NAMING RATIONALE: In WoW, Hogger is the iconic level 11 elite gnoll in Elwynn
+ * Forest who infamously kills unprepared lowbies. He's technically a basic mob
+ * but hits way harder than expected. This bot is the Critter that learned to
+ * fight — still chaotic, still a bit dumb, but capable of ending you if you
+ * underestimate it. "Hogger" is one of WoW's most recognizable references and
+ * perfectly captures "deceptively dangerous chaos."
+ *
+ * STANDALONE — no tier progression. There's only one Hogger.
+ */
+declare function Hogger(): FinalAction;
+
+/**
+ * Bot: Doombringer
+ *
+ * BEHAVIOR: Fires a single maximum-damage homing missile with infinite budget.
+ * No damage cap — goes for the biggest possible hit. Exists as a benchmark to
+ * demonstrate why lower-damage + shield play is superior. Has basic shield
+ * defense but no sophisticated tactics. One fat cast, one fat hit.
+ *
+ * STANDALONE — no tier progression. Benchmark/test bot.
+ */
+declare function Doombringer(): FinalAction;
+
+declare function Turtle(): FinalAction;
+
+/**
+ * Bot: Sentinel
+ *
+ * BEHAVIOR: Stationary tank with last-moment shielding AND two-tier offense.
+ * Like Turtle, never moves and shields at the last moment. Unlike Turtle,
+ * fires bigger missiles (damage 20) when the safe window is large enough,
+ * falling back to Turtle's fast missile (damage 12) when pressed.
+ *
+ * PROGRESSION LINE: Turtle → Sentinel → Golem
+ * - Turtle (tier 1): Stationary, fixed missiles, reactive shield timing
+ * - Sentinel (tier 2): Stationary, two-tier offense (big + fast missiles)
+ * - Golem (tier 3): Immovable fortress, perfect shield timing
+ *
+ * TIER: 2 (enhanced Turtle)
+ */
+declare function Sentinel(): FinalAction;
+
+/**
+ * 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 function Golem(): FinalAction;
+
+/**
+ * Bot: Shadowblade
+ *
+ * BEHAVIOR: Melee assassin. Blinks to the enemy, then lands devastating point-blank
+ * stab attacks (15 damage, 30u range, ~60 tick cast = 2-hit kill). Runs directly
+ * at the enemy with minimal strafe, shields undodgeable threats. The entire
+ * strategy is: get close, stab, kill. Simple and brutal.
+ *
+ * PROGRESSION LINE: Shadowblade → Nightblade → Voidblade
+ * - Shadowblade (tier 1): Offensive blink, melee stabs, basic shield
+ * - Nightblade (tier 2): + missile-aware blinks, adaptive stabs, timed defense
+ * - Voidblade (tier 3): Future — perfect assassination timing, inescapable engages
+ *
+ * TIER: 1 (base)
+ */
+declare function Shadowblade(): FinalAction;
+
+/**
+ * Bot: Nightblade
+ *
+ * BEHAVIOR: Enhanced melee assassin. Same aggressive engagement as Shadowblade —
+ * blinks directly to the enemy and stabs for 15 damage (2-hit kill). The tier 2
+ * upgrade is PREEMPTIVE DEFENSE: Nightblade watches the enemy's cast bar and
+ * shields before a point-blank missile is even launched. At melee range, missiles
+ * arrive almost instantly after launch — too fast to react. Nightblade anticipates
+ * the threat. Also has emergency blink and proper channeling management.
+ *
+ * PROGRESSION LINE: Shadowblade → Nightblade → Voidblade
+ * - Shadowblade (tier 1): Offensive blink, melee stabs, basic shield (reactive only)
+ * - Nightblade (tier 2): + preemptive shield vs enemy casts, emergency blink
+ * - Voidblade (tier 3): Future — perfect assassination timing, inescapable engages
+ *
+ * TIER: 2 (enhanced Shadowblade)
+ */
+declare function Nightblade(): FinalAction;
+
+/**
+ * Bot: Voidblade
+ *
+ * BEHAVIOR: Reactive counter-puncher. Shields everything, then fires quick stabs
+ * during enemy vulnerability windows (GCD/casting) when they can't shield back.
+ * At melee range, the shield blocks ~90% of incoming damage while Voidblade's
+ * counter-stabs land at full damage — winning through attrition.
+ *
+ * CORE LOOP (melee range):
+ *   1. Enemy casts missile → Voidblade blink-dodges (100% avoid) or shields (90% block)
+ *   2. Enemy enters GCD → Voidblade fires quick stab (lands unblocked)
+ *   3. Voidblade enters GCD → enemy recovers → repeat
+ *
+ * KEY IMPROVEMENTS OVER NIGHTBLADE:
+ * - Blink-dodge priority: avoids 100% of damage when blink available, shields as fallback
+ * - Reads enemy vulnerability to time counter-stabs perfectly
+ * - Cancel-into-defense: aborts own cast if enemy missile incoming
+ * - Punish budget: sizes stabs to fit exactly in the vulnerability window
+ *
+ * PROGRESSION LINE: Shadowblade → Nightblade → Voidblade
+ * TIER: 3 (elite Melee line)
+ */
+declare function Voidblade(): FinalAction;
+
+/**
+ * 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 Bonemancer(): FinalAction;
+
+/**
+ * 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 Lich(): FinalAction;
+
+/**
+ * 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 Archlich(): FinalAction;
+
+/**
+ * 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 Flamecaller(): FinalAction;
+
+/**
+ * Bot: Pyromancer
+ *
+ * BEHAVIOR: Adaptive homing missile specialist at long range. Maintains 400u
+ * distance, strafes to dodge, and uses fitMissileToBudget with minTurnRate 0.5
+ * to fire the highest-damage homing missile that fits in the safe window.
+ * Shields undodgeable threats, emergency blinks. A versatile ranged caster
+ * that adapts its missiles to the situation.
+ *
+ * PROGRESSION LINE: Flamecaller → Pyromancer → Infernalist
+ * - Flamecaller (tier 1): Fixed homing missiles, basic strafe and defense
+ * - Pyromancer (tier 2): + adaptive fitting, cast canceling, smart fallbacks
+ * - Infernalist (tier 3): Future — overwhelming adaptive fire
+ *
+ * TIER: 2 (enhanced Flamecaller)
+ */
+declare function Pyromancer(): FinalAction;
+
+/**
+ * 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 Infernalist(): FinalAction;
+
+/**
+ * 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 Spellshot(): 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.
+ *
+ * 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;
+
+/**
+ * Bot: Spellseeker
+ *
+ * BEHAVIOR: Elite sniper that uses intercept-aimed straight missiles during vulnerability
+ * windows. Combines Spelltracer's adaptive fitting with precise lead-position aiming
+ * and vulnerability exploitation. Straight punish missiles at sniper range are nearly
+ * unavoidable. Proactive distance control via closing rate detection.
+ *
+ * KEY IMPROVEMENTS OVER SPELLTRACER:
+ * - Intercept-aimed punish: getLeadPosition + straight missiles during vulnerability
+ * - Proactive distance blink: monitors closing rate, blinks before danger zone
+ * - Progressive cast-cancel: graduated damage thresholds
+ * - Warmup exploitation: always passes lastMissileConfig
+ *
+ * PROGRESSION LINE: Spellshot → Spelltracer → Spellseeker
+ * TIER: 3 (elite Sniper line)
+ */
+declare function Spellseeker(): 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.
+ *
+ * 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;
+
+/**
+ * Bot: Warmage
+ *
+ * BEHAVIOR: Enhanced Battlemage with adaptive missile fitting. Uses fitMissileToBudget
+ * to maximize damage within safe attack windows instead of fixed quick/heavy configs.
+ * Same close-range playstyle: shields undodgeable threats, blinks to close distance
+ * or escape, aggressive hit-trading when health allows. The adaptive fitting means
+ * every attack is optimized for the current situation — no wasted cast time.
+ *
+ * PROGRESSION LINE: Battlemage → Warmage → Archmage
+ * - Battlemage (tier 1): Quick/heavy fixed configs, cast interruption, basic defense
+ * - Warmage (tier 2): Adaptive missile fitting, optimized damage windows
+ * - Archmage (tier 3): Future — supreme duelist, perfect tactical mastery
+ *
+ * TIER: 2 (enhanced Battlemage)
+ */
+declare function Warmage(): FinalAction;
+
+/**
+ * Bot: Archmage
+ *
+ * BEHAVIOR: Versatile duelist that adapts missile choice based on distance and HP.
+ * Close range → straight missiles (no turn cost = more damage). Mid/far range → homing.
+ * Uses dual-blink aggressively (gap-close during vulnerability, escape when trade is bad).
+ * HP-aware: ahead → aggressive close range; behind → defensive ranged kiting.
+ *
+ * KEY IMPROVEMENTS OVER WARMAGE:
+ * - Range-adaptive missiles: straight close, homing far
+ * - Vulnerability-timed blinks: gap-close during enemy cast/GCD
+ * - HP-aware aggression: adjusts distance + risk tolerance based on HP differential
+ * - Progressive cast-cancel: graduated thresholds
+ *
+ * PROGRESSION LINE: Battlemage → Warmage → Archmage
+ * TIER: 3 (elite Duelist line)
+ */
+declare function Archmage(): FinalAction;
+
+/**
+ * Bot: Stormchaser
+ *
+ * BEHAVIOR: Fights aggressively while managing defense intelligently. Uses
+ * two fixed missile configs (standard homing + quick attack) with predictive
+ * homing missile AI (interceptAngle on the missile itself). Blink-dodges
+ * incoming threats, shields when blink is on cooldown. Tight distance
+ * management (350 units, ±30 band).
+ *
+ * PROGRESSION LINE: Stormchaser → Stormcaller → Stormforger
+ * - Stormchaser (tier 1): Fixed missiles, predictive homing AI, blink-dodge
+ * - Stormcaller (tier 2): + fitMissileToBudget, predictive homing, optimized damage
+ * - Stormforger (tier 3): Future — supreme berserker, perfect aggression
+ *
+ * TIER: 1 (base)
+ */
+declare function Stormchaser(): FinalAction;
+
+/**
+ * Bot: Stormcaller
+ *
+ * BEHAVIOR: Enhanced Stormchaser with adaptive missile fitting (fitMissileToBudget)
+ * AND predictive homing missiles. Combines aggressive fighting philosophy with
+ * optimized damage output. Uses budget-based missile fitting to maximize damage
+ * within safe windows. Falls back to quick missiles under pressure. Same smart
+ * trade/shield decisions as Stormchaser but with better resource usage.
+ *
+ * PROGRESSION LINE: Stormchaser → Stormcaller → Stormforger
+ * - Stormchaser (tier 1): Adaptive missiles, smart trading, aggressive defense
+ * - Stormcaller (tier 2): + fitMissileToBudget, predictive homing, optimized damage
+ * - Stormforger (tier 3): Future — supreme berserker, perfect aggression
+ *
+ * TIER: 2 (enhanced Stormchaser)
+ */
+declare function Stormcaller(): FinalAction;
+
+/**
+ * Bot: Stormforger
+ *
+ * BEHAVIOR: Enhanced Stormcaller with vulnerability exploitation. Takes the exact
+ * Stormcaller foundation (adaptive missile fitting + predictive homing) and adds
+ * a punish mode that fires fast straight missiles when the enemy is locked in
+ * GCD or cast animation. During vulnerability windows, uses getLeadPosition for
+ * accurate straight shots that arrive before the enemy can react.
+ *
+ * PROGRESSION LINE: Stormchaser → Stormcaller → Stormforger
+ * - Stormchaser (tier 1): Adaptive missiles, smart trading, aggressive defense
+ * - Stormcaller (tier 2): + fitMissileToBudget, predictive homing, optimized damage
+ * - Stormforger (tier 3): + vulnerability exploitation, punish missiles during enemy GCD
+ *
+ * TIER: 3 (elite Berserker line)
+ */
+declare function Stormforger(): 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.
+ *
+ * NAMING RATIONALE: Like a spider spinning a web of projectiles while circling its
+ * prey. The constant strafing movement pattern traces circles — spinning thread
+ * around the arena. "Spell" + "spinner" = a wizard who spins spells around the
+ * battlefield. The kiting behavior (maintaining distance while attacking) creates
+ * a web-like pattern of missiles and movement that traps opponents.
+ *
+ * PROGRESSION LINE: Spellspinner → Spellweaver → Spellbinder
+ * - Spellspinner (tier 1): Fixed homing missiles, constant strafe, basic defense
+ * - Spellweaver (tier 2): + adaptive missile fitting, more sophisticated patterns
+ * - Spellbinder (tier 3): Future — inescapable web of magic, perfect distance control
+ * The progression: spinner (raw thread) → weaver (creates patterns) → binder
+ * (constrains and traps). Each tier's projectile web becomes harder to escape.
+ *
+ * TIER: 1 (base)
+ */
+declare function Spellspinner(): 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.
+ *
+ * NAMING RATIONALE: A weaver creates intricate patterns from raw thread. Where the
+ * Spellspinner produces raw threads of magic (fixed missiles), the Spellweaver
+ * combines them into optimized patterns (adaptive fitting). The name suggests
+ * craftsmanship and sophistication — the same kiting web, but deliberately woven
+ * rather than chaotically spun.
+ *
+ * PROGRESSION LINE: Spellspinner → Spellweaver → Spellbinder
+ * - Spellspinner (tier 1): Fixed homing missiles, constant strafe, basic defense
+ * - Spellweaver (tier 2): + adaptive missile fitting, more sophisticated patterns
+ * - Spellbinder (tier 3): Future — inescapable web, perfect distance control
+ *
+ * TIER: 2 (enhanced Spellspinner)
+ */
+declare function Spellweaver(): 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.
+ *
+ * PROGRESSION LINE: Spellspinner → Spellweaver → Spellbinder
+ * - Spellspinner (tier 1): Fixed homing missiles, constant strafe, basic defense
+ * - Spellweaver (tier 2): + adaptive missile fitting, more sophisticated patterns
+ * - Spellbinder (tier 3): + vulnerability punish mode with fast straight missiles
+ *
+ * TIER: 3 (elite Spellspinner line)
+ */
+declare function Spellbinder(): FinalAction;
+
+/**
+ * Bot: Hero
+ *
+ * BEHAVIOR: Adaptive duelist that classifies the opponent's range/missile style from
+ * live visible signals (how close they hold / whether they're closing, and their active
+ * missiles) and counters by adjusting engagement distance — KITE aggressors (close /
+ * closing / fast-straight stabbers) and CLOSE on kiters/casters (far / homing missiles).
+ * This opponent-classification layer sits on top of Archmage's HP-aware, range-adaptive
+ * engine: close range → straight missiles (no turn cost = more damage), mid/far → homing,
+ * aggressive dual-blink (gap-close during vulnerability, escape when a trade is bad), and
+ * HP-aware aggression (ahead → fight closer, behind → kite at range).
+ *
+ * KEY IMPROVEMENTS OVER ARCHMAGE:
+ * - Opponent classification: reads range/missile style and counters via distance offset
+ * - Counters aggressors by kiting, counters kiters/casters by closing in
+ *
+ * INHERITED FROM ARCHMAGE:
+ * - 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
+ */
+declare function Hero(): 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):
+ *
+ * | Group      | Tier 1 (base)  | Tier 2 (enhanced) | Tier 3 (elite)  |
+ * |------------|----------------|-------------------|-----------------|
+ * | Defensive  | Turtle         | Sentinel          | Golem           |
+ * | Duelist    | Battlemage     | Warmage           | Archmage        |
+ * | Homing     | Bonemancer     | Lich              | Archlich        |
+ * | Caster     | Flamecaller    | Pyromancer        | Infernalist     |
+ * | Melee      | Shadowblade    | Nightblade        | Voidblade       |
+ * | Sniper     | Spellshot      | Spelltracer       | Spellseeker     |
+ * | Berserker  | Stormchaser    | Stormcaller       | Stormforger     |
+ * | Kiter      | Spellspinner   | Spellweaver       | Spellbinder     |
+ *
+ * Standalone: TargetDummy, Critter, Hogger, Rookie, Doombringer, 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)
+ *
+ */
+
+interface WizardEntry {
+    name: string;
+    ai: WizardFunction;
+    description: string;
+    tier?: number;
+    group: string;
+}
+interface WizardGroup {
+    label: string;
+    bots: WizardEntry[];
+}
+/**
+ * All bots organized by progression line.
+ * Each group contains bots from the same archetype, ordered by tier.
+ */
+declare const BOT_GROUPS: WizardGroup[];
+declare const ALL_BOTS: WizardEntry[];
+
+/**
+ * VIBEMANCER - OPTIMIZER UTILITIES
+ *
+ * Core functions used by the offline parameter optimizer script.
+ * These handle combo generation, range narrowing, and fight scoring.
+ *
+ * The optimizer uses multi-pass coordinate descent:
+ * - Pass 1: Coarse search across the effective range for each param
+ * - Pass 2+: Fine search zoomed into the neighborhood of the best result
+ *
+ * Parameters can define their search window two ways:
+ * - `range`: sliding window centered on current value (value ± range)
+ * - `min`/`max`: fixed bounds (old-style)
+ *
+ * Both can be combined: range defines the search radius, min/max clamp it.
+ */
+
+/**
+ * Compute the effective min/max search window for a parameter.
+ *
+ * - If `range` is set: window is `[value - range, value + range]`, clamped by optional min/max
+ * - If only `min`/`max` are set: window is `[min, max]` directly
+ * - If neither: returns `[value, value]` (no search)
+ */
+declare function getEffectiveRange(p: ParamDeclaration): {
+    min: number;
+    max: number;
+};
+/**
+ * Generate evenly-spaced candidate values for a single parameter.
+ *
+ * Divides [min, max] into `steps` evenly-spaced values. For example,
+ * min=0, max=100, steps=5 produces [0, 25, 50, 75, 100].
+ *
+ * @param min - Lower bound of search range
+ * @param max - Upper bound of search range
+ * @param steps - Number of evenly-spaced values to generate (minimum 2)
+ * @returns Array of candidate values, sorted ascending
+ */
+declare function generateCandidates(min: number, max: number, steps: number): number[];
+/**
+ * Generate all combinations (cartesian product) of candidate values for multiple params.
+ *
+ * For N params with S1, S2, ... SN steps each, produces S1 × S2 × ... × SN combinations.
+ * Each combination is a Record<string, number> mapping param name to value.
+ *
+ * @param params - Parameter declarations with search ranges and step counts
+ * @returns Array of all parameter combinations to evaluate
+ */
+declare function generateCombos(params: ParamDeclaration[]): Record<string, number>[];
+/**
+ * Narrow parameter ranges around the best combo found in the previous pass.
+ *
+ * Centers each param on its best value and shrinks the search range to one gap width.
+ * This provides finer resolution in subsequent passes. Hard min/max constraints are preserved.
+ *
+ * @param params - Original parameter declarations
+ * @param best - Best parameter combination from the previous pass
+ * @returns New parameter declarations with narrowed ranges for the next pass
+ */
+declare function narrowRange(params: ParamDeclaration[], best: Record<string, number>): ParamDeclaration[];
+/**
+ * Score a FightResult from one bot's perspective.
+ *
+ * Returns a continuous score that provides gradient information beyond binary win/loss:
+ * - Win: 3.0 base + up to 0.5 HP bonus (higher remaining HP = better)
+ * - Draw: 1.0
+ * - Loss: 0.0 base + up to 0.5 bonus for low enemy HP (closer fights = better)
+ *
+ * For a mirrored fight set (bot as wizard-1 AND wizard-2), call this twice
+ * and sum the scores for a balanced evaluation.
+ *
+ * @param result - The fight result to score
+ * @returns Continuous score in range [0, 3.5] per match
+ */
+declare function scoreFight(result: FightResult): number;
+/**
+ * Score a FightResult from wizard-2's perspective.
+ * Same scoring logic as scoreFight but with roles reversed.
+ *
+ * Use this for tournaments where both sides of a pairing need scoring.
+ */
+declare function scoreFightAsWizard2(result: FightResult): number;
+
+/**
+ * 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
+ *
+ * Provides Web Worker-based sandboxing for bot code execution in the browser.
+ * Same compiled bundles as the isolated-vm sandbox (MatchSandbox), but runs
+ * in a Web Worker instead of a V8 isolate.
+ *
+ * Architecture:
+ * - Host: creates Worker from Blob URL, communicates via postMessage
+ * - Worker: loads compiled bundle (sets globalThis.__fight/__simulate),
+ *   dispatches fight/simulate calls, posts results back
+ *
+ * Safety:
+ * - Timeout via setTimeout + worker.terminate() catches infinite loops
+ * - No memory limit (browser manages worker memory; worst case = tab crash)
+ * - Prototype freeze prevents cross-bot sabotage (same banner as isolated-vm)
+ * - No Node.js APIs available in Web Workers
+ *
+ * NOTE: This file has ZERO Node.js dependencies. It works in any JS environment.
+ */
+
+/**
+ * Minimal Worker interface for dependency injection.
+ * Matches the browser Worker API subset we need.
+ * For tests, a Node.js worker_threads adapter can implement this.
+ */
+interface WorkerLike {
+    postMessage(data: unknown): void;
+    terminate(): void;
+    addEventListener(type: string, listener: (ev: unknown) => void): void;
+    removeEventListener(type: string, listener: (ev: unknown) => void): void;
+}
+/**
+ * Factory function that creates a WorkerLike from a JavaScript code string.
+ * Default: creates a browser Web Worker via Blob URL.
+ * Override in options.createWorker for testing with Node.js worker_threads.
+ */
+type WorkerFactory = (code: string) => {
+    worker: WorkerLike;
+    cleanup?: () => void;
+};
+interface BrowserSandboxOptions {
+    /** Timeout in ms for fight/simulate calls (default: 30000). */
+    timeoutMs?: number;
+    /** Custom worker factory for dependency injection (testing). */
+    createWorker?: WorkerFactory;
+}
+/**
+ * Create the full worker script from a compiled match bundle.
+ * Appends the message-handling bootstrap to the bundle IIFE.
+ */
+declare function createWorkerScript(bundle: string): string;
+/**
+ * Browser-compatible sandboxed match runner using Web Workers.
+ *
+ * Same compiled bundles as MatchSandbox (isolated-vm), but runs in a
+ * Web Worker instead. All fight/simulate calls are async (postMessage-based).
+ *
+ * Usage:
+ * ```ts
+ * // Bundle is compiled server-side or at build time (Node.js only)
+ * const bundle = await MatchSandbox.compile(bot1, bot2);
+ *
+ * // Run in browser via Web Worker
+ * const sandbox = await BrowserMatchSandbox.fromBundle(bundle);
+ * const result = await sandbox.fight({ seed: 42 });
+ * sandbox.dispose();
+ * ```
+ */
+declare class BrowserMatchSandbox {
+    private worker;
+    private workerCleanup;
+    private timeout;
+    private disposed;
+    private nextId;
+    private pending;
+    private messageHandler;
+    private errorHandler;
+    private constructor();
+    /**
+     * Create a browser sandbox from a pre-compiled bundle string.
+     * The bundle should be the output of MatchSandbox.compile() (or equivalent IIFE
+     * that sets globalThis.__fight and globalThis.__simulate).
+     */
+    static fromBundle(bundle: string, options?: BrowserSandboxOptions): Promise<BrowserMatchSandbox>;
+    /**
+     * Wait for the worker to post {type: 'ready'}, then attach permanent handlers.
+     */
+    private waitForReady;
+    /**
+     * Extract message data from a browser MessageEvent or raw Node.js data.
+     */
+    private unwrapEvent;
+    /**
+     * Attach permanent message and error handlers for fight/simulate responses.
+     */
+    private attachHandlers;
+    /**
+     * Run a full fight (10 matches: 5 spawn distances x 2 sides).
+     * Returns a Promise because Worker communication is async.
+     */
+    fight(options?: {
+        seed?: number;
+        maxTicks?: number;
+    }): Promise<FightResult>;
+    /**
+     * Run a single simulation. Returns a Promise.
+     *
+     * @param options.params1 - useParam overrides for bot 1 (wizard-1)
+     * @param options.params2 - useParam overrides for bot 2 (wizard-2)
+     */
+    simulate(options?: {
+        seed?: number;
+        maxTicks?: number;
+        spawnDistance?: number;
+        skipHistory?: boolean;
+        params1?: Record<string, number>;
+        params2?: Record<string, number>;
+    }): Promise<SimulateResult>;
+    /**
+     * Dispose the worker and free all resources.
+     * The sandbox cannot be used after disposal.
+     */
+    dispose(): void;
+    /**
+     * Whether this sandbox has been disposed.
+     */
+    get isDisposed(): boolean;
+    /**
+     * Send a generic method call to the worker. Used by sibling sandboxes
+     * (e.g. BrowserManualMatchSandbox) that need to dispatch to method
+     * names other than fight/simulate. The worker bootstrap looks up
+     * `globalThis['__' + method]` and calls it with `options`.
+     */
+    callRaw(method: string, options: unknown): Promise<unknown>;
+    /**
+     * Send a method call to the worker and wait for the response.
+     * Times out and terminates the worker if no response within timeout.
+     */
+    private call;
+    private ensureNotDisposed;
+}
+/**
+ * One-shot browser-sandboxed fight. Creates worker, runs fight, disposes.
+ */
+declare function browserSandboxFight(bundle: string, options?: {
+    seed?: number;
+    maxTicks?: number;
+} & BrowserSandboxOptions): Promise<FightResult>;
+/**
+ * One-shot browser-sandboxed simulate. Creates worker, runs simulate, disposes.
+ */
+declare function browserSandboxSimulate(bundle: string, options?: {
+    seed?: number;
+    maxTicks?: number;
+    spawnDistance?: number;
+    skipHistory?: boolean;
+    params1?: Record<string, number>;
+    params2?: Record<string, number>;
+} & BrowserSandboxOptions): Promise<SimulateResult>;
+/**
+ * Options accepted by `__manualMatchInit` (worker-side). Mirrors
+ * `ManualMatchOptions` from manual-match.ts, but without the constructor's
+ * AI parameters since the player AI is a worker-local stub.
+ */
+interface ManualMatchInitOptions {
+    seed?: number;
+    spawnDistance?: number;
+    maxTicks?: number;
+    initialHumanActions?: WizardActions;
+}
+interface ManualMatchStepRequest {
+    humanActions?: WizardActions;
+    humanMissileTargets?: Record<string, {
+        x: number;
+        y: number;
+    }>;
+    count?: number;
+}
+/**
+ * Long-lived Web Worker sandbox holding a single ManualMatch instance.
+ *
+ * Unlike BrowserMatchSandbox (which runs one batched fight/simulate per
+ * worker), BrowserManualMatchSandbox keeps the worker alive across many
+ * step calls so the engine state and hook state persist between ticks.
+ * This is what manual play mode uses: one worker per session, disposed
+ * when the user leaves the page or starts a new match.
+ *
+ * Usage:
+ * ```ts
+ * const sandbox = await BrowserManualMatchSandbox.fromBundle(opponentBundle);
+ * await sandbox.init({seed: 42});
+ * for (let i = 0; i < 100; i++) {
+ *   await sandbox.step({humanActions: {move: {x: 100, y: 0}}, count: 1});
+ * }
+ * await sandbox.dispose();
+ * ```
+ */
+declare class BrowserManualMatchSandbox {
+    private readonly inner;
+    private constructor();
+    /**
+     * Create a manual-match sandbox from a pre-compiled bundle. The bundle
+     * must be the output of `compileManualMatchBundle()` — the regular
+     * `compileMatchBundle()` output won't work since it doesn't expose the
+     * `__manualMatch*` globals.
+     */
+    static fromBundle(bundle: string, options?: BrowserSandboxOptions): Promise<BrowserManualMatchSandbox>;
+    /**
+     * Initialize the worker-side ManualMatch instance.
+     * Returns the initial GameState (tick 0).
+     */
+    init(options?: ManualMatchInitOptions): Promise<GameState>;
+    /**
+     * Advance the match by `request.count` ticks (default 1), updating
+     * the player's human actions and any guided missile targets first.
+     */
+    step(request?: ManualMatchStepRequest): Promise<StepResult>;
+    /**
+     * 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.
+     */
+    guideMissile(projectileId: string): Promise<void>;
+    /**
+     * Restore a guided missile's original AI.
+     */
+    releaseMissile(projectileId: string): Promise<void>;
+    /**
+     * Toggle invincibility for a wizard.
+     */
+    setInvincible(wizardIndex: 0 | 1, on: boolean): Promise<void>;
+    /**
+     * Get the current game state without advancing.
+     */
+    getState(): Promise<GameState>;
+    /**
+     * Get the full SimulateResult-compatible result object (history + winner).
+     */
+    getResult(): Promise<SimulateResult>;
+    /**
+     * Dispose the worker-side ManualMatch instance. Does NOT terminate the
+     * worker — call dispose() for that.
+     */
+    resetMatch(): Promise<void>;
+    /**
+     * Terminate the worker and free all resources.
+     */
+    dispose(): void;
+    get isDisposed(): boolean;
+}
+
+/**
+ * VIBEMANCER - FIGHT STATISTICS
+ *
+ * Extracts detailed per-bot statistics from a SimulateResult history.
+ * Used by testBot().simulate() and vibemancer trace for debugging.
+ */
+
+/** Detailed statistics for one bot in a single match. */
+interface FightStats {
+    /** Total damage dealt to the opponent. */
+    damageDealt: number;
+    /** Total damage taken from the opponent. */
+    damageTaken: number;
+    /** Number of missiles launched. */
+    missilesLaunched: number;
+    /** Number of missiles that dealt damage (hit the opponent). */
+    missileHits: number;
+    /** Hit rate (0-1). NaN if no missiles fired. */
+    hitRate: number;
+    /** Number of our missiles that hit while enemy was shielding. */
+    hitsEnemyShielded: number;
+    /** Number of our missiles that hit while enemy had no shield. */
+    hitsEnemyUnshielded: number;
+    /** Total raw damage our missiles would have dealt without shields. */
+    rawDamageDealt: number;
+    /** Damage blocked by enemy shields. */
+    damageBlockedByEnemy: number;
+    /** Percentage of our raw damage blocked by enemy shields (0-1). */
+    enemyBlockRate: number;
+    /** Number of times we were hit by enemy missiles. */
+    hitsReceived: number;
+    /** Number of hits received while shield was channeling. */
+    hitsShielded: number;
+    /** Number of hits received without shield. */
+    hitsUnshielded: number;
+    /** Total raw damage that hit us (before shield reduction). */
+    rawDamageReceived: number;
+    /** Total damage blocked by shields. */
+    damageBlocked: number;
+    /** Percentage of incoming raw damage that was blocked (0-1). */
+    blockRate: number;
+    /** Ticks spent in 'casting' state. */
+    castingTicks: number;
+    /** Ticks spent channeling shield. */
+    shieldTicks: number;
+    /** Ticks spent in GCD lockout. */
+    gcdTicks: number;
+    /** Ticks spent idle (not casting, channeling, or in GCD). */
+    idleTicks: number;
+    /** Number of times shield was activated. */
+    shieldCount: number;
+    /** Number of times blink was used. */
+    blinkCount: number;
+    /** Total match duration in ticks. */
+    totalTicks: number;
+}
+/**
+ * Extract fight statistics from a SimulateResult.
+ * Returns stats for wizard-1 (the bot under test).
+ */
+declare function extractStats(result: SimulateResult): FightStats;
+/** Format stats as a human-readable summary string. */
+declare function formatStats(stats: FightStats, botName: string): string;
+
+/**
+ * VIBEMANCER - TESTING UTILITIES
+ *
+ * Helpers for writing automated tests for your bot.
+ * Import from '@vibemancer/core' in your test files.
+ *
+ * @example
+ * import {testBot} from '@vibemancer/core';
+ * import {MyWizard} from '../src/bot';
+ *
+ * test('beats TargetDummy', async () => {
+ *   const result = await testBot(MyWizard).fight('TargetDummy');
+ *   expect(result.won).toBe(true);
+ * });
+ */
+
+/** Result of a testBot().fight() call with convenience accessors. */
+interface TestFightResult {
+    /** The raw FightResult from the simulation engine. */
+    raw: FightResult;
+    /** Overall winner: 'wizard-1' | 'wizard-2' | 'draw'. */
+    winner: FightWinner;
+    /** True if your bot won the fight. */
+    won: boolean;
+    /** True if your bot lost the fight. */
+    lost: boolean;
+    /** True if the fight was a draw. */
+    drawn: boolean;
+    /** Number of individual matches your bot won (out of 10). */
+    wins: number;
+    /** Number of individual matches your bot lost (out of 10). */
+    losses: number;
+    /** Number of individual matches that were draws. */
+    draws: number;
+}
+/** Result of a testBot().simulate() call with convenience accessors. */
+interface TestSimulateResult {
+    /** The raw SimulateResult from the simulation engine. */
+    raw: SimulateResult;
+    /** Match winner. */
+    winner: MatchWinner;
+    /** True if your bot won. */
+    won: boolean;
+    /** True if your bot lost. */
+    lost: boolean;
+    /** True if the match was a draw or timeout. */
+    drawn: boolean;
+    /** Number of ticks the match lasted. */
+    ticks: number;
+    /** Your bot's remaining HP. */
+    myHealth: number;
+    /** Enemy's remaining HP. */
+    enemyHealth: number;
+    /** Detailed fight statistics (missiles, damage, shield usage, time breakdown). */
+    stats: FightStats;
+    /** Runtime errors thrown by bot or missile AI (empty if none). */
+    errors: Array<{
+        tick: number;
+        entityId: string;
+        message: string;
+    }>;
+}
+/** Builder returned by testBot(). */
+interface TestBotBuilder {
+    /**
+     * Run a full fight (10 matches) against a named built-in bot.
+     * @param opponent - Built-in bot name (e.g., 'Battlemage', 'TargetDummy').
+     */
+    fight(opponent: string, options?: {
+        seed?: number;
+    }): TestFightResult;
+    /**
+     * Run a single match against a named built-in bot.
+     * @param opponent - Built-in bot name.
+     */
+    simulate(opponent: string, options?: {
+        seed?: number;
+        spawnDistance?: number;
+        maxTicks?: number;
+    }): TestSimulateResult;
+}
+/**
+ * Create a test builder for your bot.
+ *
+ * @param bot - Your bot function (the same function you export from src/bot.ts).
+ * @returns A builder with .fight() and .simulate() methods.
+ *
+ * @example
+ * ```ts
+ * import {testBot} from '@vibemancer/core';
+ * import {MyWizard} from '../src/bot';
+ *
+ * test('beats TargetDummy', () => {
+ *   const result = testBot(MyWizard).fight('TargetDummy');
+ *   expect(result.won).toBe(true);
+ * });
+ *
+ * test('survives 10 seconds against Battlemage', () => {
+ *   const result = testBot(MyWizard).simulate('Battlemage', {maxTicks: 1000});
+ *   expect(result.myHealth).toBeGreaterThan(0);
+ * });
+ *
+ * test('kills at close range', () => {
+ *   const result = testBot(MyWizard).simulate('TargetDummy', {spawnDistance: 200});
+ *   expect(result.won).toBe(true);
+ *   expect(result.ticks).toBeLessThan(1000);
+ * });
+ * ```
+ */
+declare function testBot(bot: WizardFunction): TestBotBuilder;
+
+/**
+ * VIBEMANCER - FIGHT TRACE
+ *
+ * Extracts a structured event log from a SimulateResult history.
+ * Both bots' actions are tracked: state changes, missile launches with
+ * full config, hits, damage, dodge proximity, movement patterns.
+ *
+ * Used by:
+ * - vibemancer trace (CLI debug command)
+ * - scripts/fight-trace.ts (internal diagnostic)
+ * - User tests that want event-level analysis
+ */
+
+interface TraceEvent {
+    tick: number;
+    /** 'W1' = wizard-1, 'W2' = wizard-2 */
+    actor: 'W1' | 'W2';
+    type: TraceEventType;
+    detail: string;
+}
+type TraceEventType = 'STATE' | 'FIRE' | 'HIT' | 'HURT' | 'DEATH' | 'LAVA_DEATH' | 'SHIELD_BLOCK' | 'KNOCKBACK' | 'BLINK' | 'DODGE_START' | 'DODGE_CLOSE' | 'MOVE' | 'ERROR' | 'WARNING';
+interface TraceSummary {
+    winner: string;
+    ticks: number;
+    w1Name: string;
+    w2Name: string;
+    w1FinalHp: number;
+    w2FinalHp: number;
+    w1: TraceBotSummary;
+    w2: TraceBotSummary;
+}
+interface TraceBotSummary {
+    missilesLaunched: number;
+    hits: number;
+    damageDealt: number;
+    damageReceived: number;
+    shields: number;
+    blinks: number;
+    dodgeEncounters: number;
+    causeOfDeath: 'missile' | 'lava' | 'alive' | 'timeout';
+    movement: {
+        strafe: number;
+        approach: number;
+        retreat: number;
+        still: number;
+    };
+}
+/**
+ * Extract a structured event log from simulation history.
+ * Tracks both bots' state changes, missile launches (with full config + range),
+ * hits, damage, dodge proximity, movement patterns, and runtime errors.
+ */
+declare function extractTraceEvents(history: GameState[], errors?: BotError[]): TraceEvent[];
+/**
+ * Generate a summary from trace events and the simulation result.
+ */
+declare function summarizeTrace(events: TraceEvent[], result: SimulateResult, w1Name: string, w2Name: string): TraceSummary;
+/** Format trace events as a human-readable string. */
+declare function formatTraceEvents(events: TraceEvent[]): string;
+/** Format a full trace summary as a human-readable string. */
+declare function formatTraceSummary(summary: TraceSummary): string;
+/**
+ * Generate diagnostic tips based on trace analysis.
+ * Identifies common problems and suggests fixes.
+ * Returns an array of human-readable tips (empty if no issues found).
+ */
+declare function diagnoseTrace(events: TraceEvent[], summary: TraceSummary): string[];
+/** Format diagnostic tips as a human-readable string. */
+declare function formatDiagnosis(tips: string[]): string;
+
+export { type InternalWizardState as $, ALL_BOTS as A, BLINK_CAST_TIME as B, CASTING_MOVEMENT_MULT as C, Critter as D, DEFAULT_BUDGET as E, type FightResult as F, DEFAULT_FIGHT_BACKSTOP_MS as G, DEFAULT_SEED as H, Doombringer as I, ENGINE_VERSION as J, type EnemyState as K, FIGHT_SPAWN_DISTANCES as L, type FightBudget as M, type FightStats as N, type FightWinner as O, type FinalAction as P, Flamecaller as Q, GCD_DURATION as R, type SimulateResult as S, type GameConfig as T, type GameState as U, Golem as V, Hero as W, Hogger as X, type HomingParams as Y, type HookState as Z, Infernalist as _, ARENA_MAX as a, Spellseeker as a$, KNOCKBACK_DAMAGE_THRESHOLD as a0, KNOCKBACK_DECAY as a1, KNOCKBACK_DELAY as a2, KNOCKBACK_SPEED_PER_DAMAGE as a3, LAVA_BORDER_WIDTH as a4, Lich as a5, MATCH_DURATION as a6, MAX_HEALTH as a7, MISSILE_BASE_CAST as a8, MISSILE_BASE_RADIUS as a9, type MissileLaunchEvent as aA, type MissileOobEvent as aB, type MissileTemplate as aC, Nightblade as aD, type ParamDeclaration as aE, type Position as aF, type ProjectileState as aG, Pyromancer as aH, RULES as aI, RULESET_RANGES as aJ, type RefObject as aK, Rookie as aL, SHIELD_CAST_TIME as aM, SHIELD_DECAY_PER_SECOND as aN, SHIELD_DECAY_RATE as aO, SHIELD_MAX_BLOCK as aP, SHIELD_MAX_STRENGTH as aQ, SHIELD_MIN_BLOCK as aR, SHIELD_MIN_STRENGTH as aS, SPAWN_DISTANCE as aT, type SeekerParams as aU, Sentinel as aV, Shadowblade as aW, type ShieldBlockEvent as aX, type ShieldStartEvent as aY, type SimEvent as aZ, Spellbinder as a_, MISSILE_DAMAGE_POWER as aa, MISSILE_DAMAGE_RADIUS_SCALE as ab, MISSILE_DAMAGE_SCALE as ac, MISSILE_HOMING_COEFF as ad, MISSILE_MIN_CAST_TIME as ae, MISSILE_MIN_DAMAGE as af, MISSILE_MIN_DURATION as ag, MISSILE_MIN_SPEED as ah, MISSILE_RADIUS_PER_DAMAGE as ai, MISSILE_SPEED_DURATION_BASELINE as aj, MISSILE_SPEED_DURATION_COEFF as ak, MISSILE_TURN_DURATION_COEFF as al, MOVEMENT_SPEED as am, MOVE_SPEED as an, ManualMatch as ao, type ManualMatchInitOptions as ap, type ManualMatchOptions as aq, type ManualMatchStepRequest as ar, type MatchWinner as as, type MissileAction as at, type MissileActions as au, type MissileConfig as av, type MissileContext as aw, type MissileExpiredEvent as ax, type MissileFunction$1 as ay, type MissileHitEvent as az, ARENA_MIN as b, createBudgetState as b$, Spellshot as b0, Spellspinner as b1, Spelltracer as b2, Spellweaver as b3, type SpiralParams as b4, type StepResult as b5, Stormcaller as b6, Stormchaser as b7, Stormforger as b8, type StraightParams as b9, type WizardGroup as bA, type WizardLavaDeathEvent as bB, type WizardState as bC, type WorkerFactory as bD, type WorkerLike as bE, analyzeThreats as bF, angleDiff as bG, angleInRange as bH, angleTo as bI, applyDamage as bJ, applyRulesetOverrides as bK, blink as bL, browserSandboxFight as bM, browserSandboxSimulate as bN, calculateBlinkCooldown as bO, calculateMissileCastTime as bP, calculateMissileRadius as bQ, calculateMissileSimilarity as bR, calculateShieldBlock as bS, calculateWarmupMultiplier as bT, cancel as bU, cancelCast as bV, clampPositionToArena as bW, clampToArena as bX, clearHooks as bY, clearParamValues as bZ, completeCast as b_, TICKS_PER_SECOND as ba, TICK_DURATION_MS as bb, TargetDummy as bc, type TestBotBuilder as bd, type TestFightResult as be, type TestSimulateResult as bf, type TraceBotSummary as bg, type TraceEvent as bh, type TraceEventType as bi, type TraceSummary as bj, Turtle as bk, type Velocity as bl, Voidblade as bm, WARMUP_DURATION_TOLERANCE as bn, WARMUP_MAX_BONUS as bo, WARMUP_MAX_PENALTY as bp, WARMUP_SPEED_TOLERANCE as bq, WARMUP_TURN_TOLERANCE as br, WIZARD_HEALTH as bs, WIZARD_RADIUS as bt, Warmage as bu, type WizardActions as bv, type WizardContext as bw, type WizardDeathEvent as bx, type WizardEntry as by, type WizardFunction as bz, ARENA_SIZE as c, setParamValues as c$, createEntitySeed as c0, createFightBudget as c1, createInitialState as c2, createRandom as c3, createWorkerScript as c4, currentRuleset as c5, diagnoseTrace as c6, directionAway as c7, directionTo as c8, distanceTo as c9, idle as cA, inRange as cB, interceptAngle as cC, isBannedBotName as cD, isInLava as cE, magnitude as cF, matchesAnyBanRule as cG, mayAct as cH, missile as cI, move as cJ, moveInDirection as cK, moveProjectile as cL, moveWizard as cM, narrowRange as cN, nextRandom as cO, normalize as cP, normalizeAngle as cQ, predictPosition as cR, recordSpend as cS, resetAllHooks as cT, resetRuleset as cU, resolveWizardCollision as cV, runWithHooks as cW, runWizardWithContext as cX, scoreFight as cY, scoreFightAsWizard2 as cZ, seekerMissile as c_, effectiveTurnRateCost as ca, extractAction as cb, extractMissileAction as cc, extractStats as cd, extractTraceEvents as ce, fight as cf, findInRange as cg, findNearest as ch, fitMissileForEscapingTarget as ci, fitMissileToBudget as cj, flyStraight as ck, formatDiagnosis as cl, formatStats as cm, formatTraceEvents as cn, formatTraceSummary as co, generateCandidates as cp, generateCombos as cq, getAdaptiveMissileConfig as cr, getEffectiveRange as cs, getLeadPosition as ct, getMissileCastTime as cu, getMissileContext as cv, getPlayerState as cw, getWizardContext as cx, hashCombine as cy, homingMissile as cz, ARENA_WATER_BUFFER as d, shield as d0, simulate as d1, simulateMinDuration as d2, sortByDistance as d3, spiralMissile as d4, startCast as d5, startDiscovery as d6, stopDiscovery as d7, straightMissile as d8, summarizeTrace as d9, useRef as dA, useShieldStrength as dB, useState as dC, useStatus as dD, useThreats as dE, useTick as dF, useTicksUntilReady as dG, useVelocity as dH, validateHookCall as dI, validateMissileConfig as dJ, withMissileContext as dK, withWizardContext as dL, wrapWithParams as dM, sweptCircleCollision as da, testBot as db, tick as dc, turnToAngle as dd, turnToward as de, updateShield as df, useArenaSize as dg, useBlinkCooldown as dh, useCastProgress as di, useCastingSpell as dj, useClosestThreat as dk, useDamageDealt as dl, useDamageTaken as dm, useEffect as dn, useEnemy as dp, useHealth as dq, useLastHitTick as dr, useLastMissileConfig as ds, useMemo as dt, useMyProjectiles as du, useMyThreatsToEnemy as dv, useParam as dw, usePosition as dx, useProjectiles as dy, useRandom as dz, type ActionBuilder as e, type AnalyzedThreat as f, Archlich as g, Archmage as h, BLINK_COOLDOWN as i, BLINK_MAX_COOLDOWN as j, BLINK_MAX_RANGE as k, BLINK_MIN_COOLDOWN as l, BLINK_RANGE as m, BOT_GROUPS as n, Battlemage as o, type BlinkEvent as p, Bonemancer as q, type BotBudgetState as r, type BotError as s, BrowserManualMatchSandbox as t, BrowserMatchSandbox as u, type BrowserSandboxOptions as v, type BudgetLimits as w, COLLISION_RADIUS as x, type CastCancelEvent as y, type CastStartEvent as z };