@vibemancer/core 1.0.10 → 1.0.12

package/src/hooks/state-hooks.ts

@@ -1,407 +1,413 @@
-/**
- * VIBEMANCER - STATE HOOKS
- *
- * React-style hooks for reading game state.
- * These handle the "subconscious" perception that humans do instinctively.
- *
- * UNITS REFERENCE (100 ticks = 1 second):
- *   Position:   absolute world coordinates, 0-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.
- *   Shield:     block multiplier 0.0-0.9 (0.9 = blocks 90% damage)
- */
-
-import {Position, Velocity, ProjectileState} from '../types.js';
-import {getWizardContext, useMemo} from '../engine/hooks-runtime.js';
-import {RULES, TICKS_PER_SECOND} from '../rules.js';
-import type {EnemyState, AnalyzedThreat} from './types.js';
-import {analyzeThreats} from './threat-analysis.js';
-
-// ============================================================
-// SELF STATE HOOKS
-// ============================================================
-
-/**
- * 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.
- */
-export function useRandom(): () => number
-{
-	return getWizardContext().random;
-}
-
-/**
- * Get your current health (0-60). Wizard dies at 0.
- */
-export function useHealth(): number
-{
-	return getWizardContext().health;
-}
-
-/**
- * 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.
- *
- * And the number you actually need is neither of those. Lava is tested against your EDGE,
- * not your centre (`isInLava` checks `x + WIZARD_RADIUS > ARENA_MAX`), and this returns your
- * CENTRE — so with a radius of 5 you die once your centre passes 825. The safe range to
- * steer by is [35, 825]. Aiming for 828 because "the playfield is [30, 830]" is fatal, which
- * is exactly what a real fight trace showed: LAVA_DEATH at (826, 430).
- *
- * (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.)
- */
-export function usePosition(): Position
-{
-	const ctx = getWizardContext();
-	return {x: ctx.position.x, y: ctx.position.y};
-}
-
-/**
- * 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.
- */
-export function useVelocity(): Velocity
-{
-	const ctx = getWizardContext();
-	return {x: ctx.velocity.x, y: ctx.velocity.y};
-}
-
-/**
- * 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.
- */
-export function useStatus(): 'idle' | 'casting' | 'channeling' | 'gcd_locked'
-{
-	return getWizardContext().state;
-}
-
-/**
- * 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.
- */
-export function useTicksUntilReady(): number
-{
-	const ctx = getWizardContext();
-
-	switch (ctx.state)
-	{
-		case 'idle':
-			return 0;
-		case 'casting':
-			// Remaining cast time
-			if (ctx.castDuration !== undefined && ctx.castProgress !== undefined)
-			{
-				return ctx.castDuration - ctx.castProgress;
-			}
-			return 0;
-		case 'channeling':
-			// Can cancel anytime, so 0
-			return 0;
-		case 'gcd_locked':
-			return ctx.gcdRemaining ?? 0;
-		default:
-			return 0;
-	}
-}
-
-/**
- * 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).
- */
-export function useShieldStrength(): number
-{
-	const ctx = getWizardContext();
-
-	if (ctx.state !== 'channeling' || ctx.channelingSpell !== 'shield')
-	{
-		return 0;
-	}
-
-	// Calculate shield strength based on channel duration
-	const channelDuration = ctx.channelDuration ?? 0;
-	const decayPerTick = RULES.SHIELD_DECAY_PER_SECOND / TICKS_PER_SECOND;
-	const strength = RULES.SHIELD_MAX_BLOCK - (channelDuration * decayPerTick);
-	return Math.max(RULES.SHIELD_MIN_BLOCK, strength);
-}
-
-/**
- * Get all projectiles currently in flight (yours and enemy's).
- * Used for blink safety calculations and threat analysis.
- */
-export function useProjectiles(): ProjectileState[]
-{
-	return getWizardContext().projectiles;
-}
-
-/**
- * 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.
- */
-export function useLastMissileConfig(): import('../types.js').MissileConfig | undefined
-{
-	return getWizardContext().lastMissileConfig;
-}
-
-/**
- * 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.
- */
-export function useBlinkCooldown(): number
-{
-	return getWizardContext().blinkCooldown;
-}
-
-/**
- * Get currently casting spell, or null if not casting.
- * Returns 'missile', 'shield', or 'blink'.
- */
-export function useCastingSpell(): 'missile' | 'shield' | 'blink' | null
-{
-	const ctx = getWizardContext();
-	if (ctx.state !== 'casting')
-	{
-		return null;
-	}
-	return ctx.castingSpell ?? 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.
- */
-export function useCastProgress(): {current: number; total: number} | null
-{
-	const ctx = getWizardContext();
-	if (ctx.state !== 'casting')
-	{
-		return null;
-	}
-	if (ctx.castProgress === undefined || ctx.castDuration === undefined)
-	{
-		return null;
-	}
-	return {current: ctx.castProgress, total: ctx.castDuration};
-}
-
-// ============================================================
-// ENEMY STATE HOOK
-// ============================================================
-
-/**
- * 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.
- */
-export function useEnemy(): EnemyState
-{
-	const ctx = getWizardContext();
-	const enemy = ctx.enemies[0];
-
-	if (!enemy)
-	{
-		// No enemy - return default state
-		return {
-			position: {x: 0, y: 0},
-			velocity: {x: 0, y: 0},
-			health: 0,
-			status: 'idle',
-			castingSpell: null,
-			castProgress: 0,
-			castDuration: 0,
-			gcdRemaining: 0,
-			channelDuration: 0,
-			shieldStrength: 0,
-		};
-	}
-
-	// Calculate enemy shield strength
-	let shieldStrength = 0;
-	if (enemy.state === 'channeling' && enemy.channelingSpell === 'shield')
-	{
-		const channelDuration = enemy.channelDuration ?? 0;
-		const decayPerTick = RULES.SHIELD_DECAY_PER_SECOND / TICKS_PER_SECOND;
-		shieldStrength = Math.max(RULES.SHIELD_MIN_BLOCK, RULES.SHIELD_MAX_BLOCK - (channelDuration * decayPerTick));
-	}
-
-	return {
-		position: {x: enemy.position.x, y: enemy.position.y},
-		velocity: {x: enemy.velocity.x, y: enemy.velocity.y},
-		health: enemy.health,
-		status: enemy.state,
-		castingSpell: enemy.state === 'casting' ? (enemy.castingSpell ?? null) : null,
-		castProgress: enemy.castProgress ?? 0,
-		castDuration: enemy.castDuration ?? 0,
-		gcdRemaining: enemy.gcdRemaining ?? 0,
-		channelDuration: enemy.channelDuration ?? 0,
-		shieldStrength,
-	};
-}
-
-// ============================================================
-// PROJECTILE HOOKS
-// ============================================================
-
-/**
- * Get all your active (in-flight) projectiles.
- * Each has position, rotation (degrees), speed (u/t), turnRate, remainingTicks.
- */
-export function useMyProjectiles(): ProjectileState[]
-{
-	return getWizardContext().myProjectiles;
-}
-
-// ============================================================
-// COMBAT TRACKING HOOKS
-// ============================================================
-
-/**
- * Get total damage you've dealt this match.
- */
-export function useDamageDealt(): number
-{
-	return getWizardContext().damageDealt;
-}
-
-/**
- * Get total damage you've taken this match.
- */
-export function useDamageTaken(): number
-{
-	return getWizardContext().damageTaken;
-}
-
-/**
- * Get the tick number when you last took damage. Returns 0 if never hit.
- * Compare with useTick() to get ticks since last hit.
- */
-export function useLastHitTick(): number
-{
-	return getWizardContext().lastHitTick;
-}
-
-// ============================================================
-// ARENA HOOKS
-// ============================================================
-
-/**
- * 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.
- */
-export function useArenaSize(): {width: number; height: number}
-{
-	const ctx = getWizardContext();
-	return {width: ctx.arenaWidth, height: ctx.arenaHeight};
-}
-
-/**
- * Get current game tick (starts at 0, increments each tick).
- * 100 ticks = 1 second. Match ends at 30,000 ticks (5 minutes).
- */
-export function useTick(): number
-{
-	return getWizardContext().tick;
-}
-
-// ============================================================
-// THREAT ANALYSIS HOOKS
-// ============================================================
-
-/**
- * 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
- */
-export function useThreats(): AnalyzedThreat[]
-{
-	const ctx = getWizardContext();
-	const ticksUntilReady = useTicksUntilReady();
-
-	// Memoize to avoid recalculating every call
-	return useMemo(() =>
-	{
-		return analyzeThreats(
-			ctx.position,
-			ctx.projectiles,
-			ctx.myProjectiles,
-			ticksUntilReady,
-		);
-	}, [ctx.projectiles, ctx.myProjectiles, ctx.position.x, ctx.position.y, ticksUntilReady]);
-}
-
-/**
- * Get the most imminent threat, or null if no threats.
- * Shorthand for useThreats()[0].
- */
-export function useClosestThreat(): AnalyzedThreat | null
-{
-	const threats = useThreats();
-	return threats[0] ?? null;
-}
-
-/**
- * Get your missiles analyzed from the enemy's perspective.
- * Useful to predict when enemy will shield/dodge your attacks.
- */
-export function useMyThreatsToEnemy(): AnalyzedThreat[]
-{
-	const ctx = getWizardContext();
-	const enemy = ctx.enemies[0];
-
-	if (!enemy)
-	{
-		return [];
-	}
-
-	// Memoize to avoid recalculating every call
-	return useMemo(() =>
-	{
-		// Analyze from enemy's perspective
-		// Pass empty array for "enemy's own projectiles" since we're analyzing our missiles as threats TO them
-		return analyzeThreats(
-			enemy.position,
-			ctx.myProjectiles, // Our projectiles are their threats
-			[], // Enemy has no "own projectiles" in this context
-			0, // We don't know enemy's ticksUntilReady
-		);
-	}, [ctx.myProjectiles, enemy.position.x, enemy.position.y]);
-}
+/**
+ * VIBEMANCER - STATE HOOKS
+ *
+ * React-style hooks for reading game state.
+ * These handle the "subconscious" perception that humans do instinctively.
+ *
+ * UNITS REFERENCE (100 ticks = 1 second):
+ *   Position:   absolute world coordinates, 0-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.
+ *   Shield:     block multiplier 0.0-0.9 (0.9 = blocks 90% damage)
+ */
+
+import {Position, Velocity, ProjectileState} from '../types.js';
+import {getWizardContext, useMemo} from '../engine/hooks-runtime.js';
+import {RULES, TICKS_PER_SECOND} from '../rules.js';
+import type {EnemyState, AnalyzedThreat} from './types.js';
+import {analyzeThreats} from './threat-analysis.js';
+
+// ============================================================
+// SELF STATE HOOKS
+// ============================================================
+
+/**
+ * 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.
+ */
+export function useRandom(): () => number
+{
+	return getWizardContext().random;
+}
+
+/**
+ * Get your current health (0-60). Wizard dies at 0.
+ */
+export function useHealth(): number
+{
+	return getWizardContext().health;
+}
+
+/**
+ * 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.
+ *
+ * And the number you actually need is neither of those. Lava is tested against your EDGE,
+ * not your centre (`isInLava` checks `x + WIZARD_RADIUS > ARENA_MAX`), and this returns your
+ * CENTRE — so with a radius of 5 you die once your centre passes 825. The safe range to
+ * steer by is [35, 825]. Aiming for 828 because "the playfield is [30, 830]" is fatal, which
+ * is exactly what a real fight trace showed: LAVA_DEATH at (826, 430).
+ *
+ * (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.)
+ */
+export function usePosition(): Position
+{
+	const ctx = getWizardContext();
+	return {x: ctx.position.x, y: ctx.position.y};
+}
+
+/**
+ * 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.
+ */
+export function useVelocity(): Velocity
+{
+	const ctx = getWizardContext();
+	return {x: ctx.velocity.x, y: ctx.velocity.y};
+}
+
+/**
+ * Get your current status:
+ * - 'idle':        free to act
+ * - 'casting':     casting a spell (missile, blink OR shield). Can move at 33% speed.
+ * - 'channeling':  channeling shield. Cannot move. Cancel anytime with cancel().
+ * - 'gcd_locked':  global cooldown after spell. Can move at full speed, but cannot cast.
+ */
+export function useStatus(): 'idle' | 'casting' | 'channeling' | 'gcd_locked'
+{
+	return getWizardContext().state;
+}
+
+/**
+ * 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.
+ */
+export function useTicksUntilReady(): number
+{
+	const ctx = getWizardContext();
+
+	switch (ctx.state)
+	{
+		case 'idle':
+			return 0;
+		case 'casting':
+			// Remaining cast time
+			if (ctx.castDuration !== undefined && ctx.castProgress !== undefined)
+			{
+				return ctx.castDuration - ctx.castProgress;
+			}
+			return 0;
+		case 'channeling':
+			// Can cancel anytime, so 0
+			return 0;
+		case 'gcd_locked':
+			return ctx.gcdRemaining ?? 0;
+		default:
+			return 0;
+	}
+}
+
+/**
+ * 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).
+ */
+export function useShieldStrength(): number
+{
+	const ctx = getWizardContext();
+
+	if (ctx.state !== 'channeling' || ctx.channelingSpell !== 'shield')
+	{
+		return 0;
+	}
+
+	// Calculate shield strength based on channel duration
+	const channelDuration = ctx.channelDuration ?? 0;
+	const decayPerTick = RULES.SHIELD_DECAY_PER_SECOND / TICKS_PER_SECOND;
+	const strength = RULES.SHIELD_MAX_BLOCK - (channelDuration * decayPerTick);
+	return Math.max(RULES.SHIELD_MIN_BLOCK, strength);
+}
+
+/**
+ * Get all projectiles currently in flight (yours and enemy's).
+ * Used for blink safety calculations and threat analysis.
+ */
+export function useProjectiles(): ProjectileState[]
+{
+	return getWizardContext().projectiles;
+}
+
+/**
+ * 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.
+ */
+export function useLastMissileConfig(): import('../types.js').MissileConfig | undefined
+{
+	return getWizardContext().lastMissileConfig;
+}
+
+/**
+ * Get blink cooldown remaining in ticks. Returns 0 if ready to blink.
+ *
+ * Cooldown scales with distance used:
+ * - 10 units → 100 ticks (1s); 100 units → 667 ticks; 300 → 2000 (20s)
+ * - The cooldown scales with DISTANCE, so a micro-blink is cheap and a full-range one is
+ *   not. This said 100 units → ~100 ticks, which understated it by 6.7x.
+ * - 300 units (max range) → 2000 ticks (20s)
+ *
+ * Note: 100 ticks = 1 second.
+ */
+export function useBlinkCooldown(): number
+{
+	return getWizardContext().blinkCooldown;
+}
+
+/**
+ * Get currently casting spell, or null if not casting.
+ * Returns 'missile', 'shield', or 'blink'.
+ */
+export function useCastingSpell(): 'missile' | 'shield' | 'blink' | null
+{
+	const ctx = getWizardContext();
+	if (ctx.state !== 'casting')
+	{
+		return null;
+	}
+	return ctx.castingSpell ?? 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.
+ */
+export function useCastProgress(): {current: number; total: number} | null
+{
+	const ctx = getWizardContext();
+	if (ctx.state !== 'casting')
+	{
+		return null;
+	}
+	if (ctx.castProgress === undefined || ctx.castDuration === undefined)
+	{
+		return null;
+	}
+	return {current: ctx.castProgress, total: ctx.castDuration};
+}
+
+// ============================================================
+// ENEMY STATE HOOK
+// ============================================================
+
+/**
+ * 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.
+ */
+export function useEnemy(): EnemyState
+{
+	const ctx = getWizardContext();
+	const enemy = ctx.enemies[0];
+
+	if (!enemy)
+	{
+		// No enemy - return default state
+		return {
+			position: {x: 0, y: 0},
+			velocity: {x: 0, y: 0},
+			health: 0,
+			status: 'idle',
+			castingSpell: null,
+			castProgress: 0,
+			castDuration: 0,
+			gcdRemaining: 0,
+			channelDuration: 0,
+			shieldStrength: 0,
+		};
+	}
+
+	// Calculate enemy shield strength
+	let shieldStrength = 0;
+	if (enemy.state === 'channeling' && enemy.channelingSpell === 'shield')
+	{
+		const channelDuration = enemy.channelDuration ?? 0;
+		const decayPerTick = RULES.SHIELD_DECAY_PER_SECOND / TICKS_PER_SECOND;
+		shieldStrength = Math.max(RULES.SHIELD_MIN_BLOCK, RULES.SHIELD_MAX_BLOCK - (channelDuration * decayPerTick));
+	}
+
+	return {
+		position: {x: enemy.position.x, y: enemy.position.y},
+		velocity: {x: enemy.velocity.x, y: enemy.velocity.y},
+		health: enemy.health,
+		status: enemy.state,
+		castingSpell: enemy.state === 'casting' ? (enemy.castingSpell ?? null) : null,
+		castProgress: enemy.castProgress ?? 0,
+		castDuration: enemy.castDuration ?? 0,
+		gcdRemaining: enemy.gcdRemaining ?? 0,
+		channelDuration: enemy.channelDuration ?? 0,
+		shieldStrength,
+	};
+}
+
+// ============================================================
+// PROJECTILE HOOKS
+// ============================================================
+
+/**
+ * Get all your active (in-flight) projectiles.
+ * Each has position, rotation (degrees), speed (u/t), turnRate, remainingTicks.
+ */
+export function useMyProjectiles(): ProjectileState[]
+{
+	return getWizardContext().myProjectiles;
+}
+
+// ============================================================
+// COMBAT TRACKING HOOKS
+// ============================================================
+
+/**
+ * Get total damage you've dealt this match.
+ */
+export function useDamageDealt(): number
+{
+	return getWizardContext().damageDealt;
+}
+
+/**
+ * Get total damage you've taken this match.
+ */
+export function useDamageTaken(): number
+{
+	return getWizardContext().damageTaken;
+}
+
+/**
+ * Get the tick number when you last took damage. Returns 0 if never hit.
+ * Compare with useTick() to get ticks since last hit.
+ */
+export function useLastHitTick(): number
+{
+	return getWizardContext().lastHitTick;
+}
+
+// ============================================================
+// ARENA HOOKS
+// ============================================================
+
+/**
+ * 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.
+ */
+export function useArenaSize(): {width: number; height: number}
+{
+	const ctx = getWizardContext();
+	return {width: ctx.arenaWidth, height: ctx.arenaHeight};
+}
+
+/**
+ * Get current game tick (starts at 0, increments each tick).
+ * 100 ticks = 1 second. Match ends at 30,000 ticks (5 minutes).
+ */
+export function useTick(): number
+{
+	return getWizardContext().tick;
+}
+
+// ============================================================
+// THREAT ANALYSIS HOOKS
+// ============================================================
+
+/**
+ * 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
+ */
+export function useThreats(): AnalyzedThreat[]
+{
+	const ctx = getWizardContext();
+	const ticksUntilReady = useTicksUntilReady();
+
+	// Memoize to avoid recalculating every call
+	return useMemo(() =>
+	{
+		return analyzeThreats(
+			ctx.position,
+			ctx.projectiles,
+			ctx.myProjectiles,
+			ticksUntilReady,
+			// Mid-CAST you are one cancel() away from being able to shield, so the analysis
+			// must not charge you the whole remainder of the cast. A GCD cannot be cancelled,
+			// so it keeps the pessimistic reading.
+			{canCancelCurrentCast: ctx.state === 'casting'},
+		);
+	}, [ctx.projectiles, ctx.myProjectiles, ctx.position.x, ctx.position.y, ticksUntilReady, ctx.state]);
+}
+
+/**
+ * Get the most imminent threat, or null if no threats.
+ * Shorthand for useThreats()[0].
+ */
+export function useClosestThreat(): AnalyzedThreat | null
+{
+	const threats = useThreats();
+	return threats[0] ?? null;
+}
+
+/**
+ * Get your missiles analyzed from the enemy's perspective.
+ * Useful to predict when enemy will shield/dodge your attacks.
+ */
+export function useMyThreatsToEnemy(): AnalyzedThreat[]
+{
+	const ctx = getWizardContext();
+	const enemy = ctx.enemies[0];
+
+	if (!enemy)
+	{
+		return [];
+	}
+
+	// Memoize to avoid recalculating every call
+	return useMemo(() =>
+	{
+		// Analyze from enemy's perspective
+		// Pass empty array for "enemy's own projectiles" since we're analyzing our missiles as threats TO them
+		return analyzeThreats(
+			enemy.position,
+			ctx.myProjectiles, // Our projectiles are their threats
+			[], // Enemy has no "own projectiles" in this context
+			0, // We don't know enemy's ticksUntilReady
+		);
+	}, [ctx.myProjectiles, enemy.position.x, enemy.position.y]);
+}