feat(movement): dodge timing, wall avoidance, distance control, ram finisher

PhantomMeteor:
- Ram finisher: charge at enemy when <200px and their energy <10
- Ram opportunity: charge when <60px and we have >20 energy advantage
- Integrated gunheat tracker for 1-2 tick earlier wave detection
- Distance control: smooth linear ramp toward preferred engagement distance
- Phantom range expanded 150→250px to catch closer threats

WaveSurfer:
- Wall-aware dodge bin selection: penalize bins leading off-arena
- Dodge timing: predict future position 15 ticks ahead for safety
- Distance control: radial blend when outside deadband (350±50px)
- Wall escape: invert strafe if pushing further into wall, blend toward center

ModularBot:
- Wired KNN gun (purple/magenta)
- Shadows tracked for movement (safer GF prediction)
- Bullet lifecycle management (onBulletFired/onBulletHitBot/onBulletHitWall)
- Unified phantom_meteor movement (wave_surfer unplugged)
- Config logging on round start + gun switch

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

common_libs/movements/wave_surfer.nim

@@ -7,7 +7,12 @@ import std/[math]
 import gun_harness/gun_interface
 import movement_harness/movement_interface
 
-const WS_BINS = 31
+const WS_BINS       = 31
+const WallMargin    = 40.0
+const DodgeTicks    = 15.0   # approximate ticks to reach dodge position
+const WS_PrefDist   = 400.0  # optimal engagement distance
+const WS_DistBand   = 50.0   # deadband: pure strafe within ±50px of preferred
+const WS_RadialFrac = 0.35   # radial blend fraction (0=pure strafe, 1=pure radial)
 
 type
   WSWave = object
@@ -109,10 +114,25 @@ proc computeMove*(m: var WaveSurferModule, ws: WorldState): MoveCommand =
     let avg = total / float64(WS_BINS)
 
     if m.bins[curBin] > avg:
-      # Find lowest-danger bin
+      # Find lowest-danger bin, penalizing positions near walls
+      let dodgeDist = ws.selfSpeed * DodgeTicks
       var bestBin = 0
       for j in 1..<WS_BINS:
-        if m.bins[j] < m.bins[bestBin]: bestBin = j
+        let gfJ      = binToGF(j)
+        let angleJ   = w.bearing + gfJ * maxA
+        let futureX  = botX + cos(angleJ) * dodgeDist
+        let futureY  = botY + sin(angleJ) * dodgeDist
+        let wallHit  = futureX < WallMargin or futureX > ws.arenaWidth  - WallMargin or
+                       futureY < WallMargin or futureY > ws.arenaHeight - WallMargin
+        let dangerJ  = if wallHit: m.bins[j] * 5.0 else: m.bins[j]
+        let gfBest   = binToGF(bestBin)
+        let angleB   = w.bearing + gfBest * maxA
+        let futureXB = botX + cos(angleB) * dodgeDist
+        let futureYB = botY + sin(angleB) * dodgeDist
+        let wallHitB = futureXB < WallMargin or futureXB > ws.arenaWidth  - WallMargin or
+                       futureYB < WallMargin or futureYB > ws.arenaHeight - WallMargin
+        let dangerB  = if wallHitB: m.bins[bestBin] * 5.0 else: m.bins[bestBin]
+        if dangerJ < dangerB: bestBin = j
       let bestGF = binToGF(bestBin)
       # Move in direction of best GF: positive = CCW (orbit left), negative = CW
       m.strafeDir = if bestGF >= curGF: 1.0 else: -1.0
@@ -120,9 +140,48 @@ proc computeMove*(m: var WaveSurferModule, ws: WorldState): MoveCommand =
   # Perpendicular strafe (same body trick as phantom_meteor)
   let enemyBearingRad = arctan2(enemyY - botY, enemyX - botX)
   # Perpendicular in chosen strafe direction
-  let perpAngle =
+  var perpAngle =
     if m.strafeDir >= 0.0: enemyBearingRad + PI * 0.5
     else:                   enemyBearingRad - PI * 0.5
+
+  # Hard wall escape: if near any wall, blend toward arena center
+  # ponytail: linear blend, upgrade to override if blending proves too weak
+  let nearLeft   = botX < WallMargin
+  let nearRight  = botX > ws.arenaWidth  - WallMargin
+  let nearBottom = botY < WallMargin
+  let nearTop    = botY > ws.arenaHeight - WallMargin
+  if nearLeft or nearRight or nearBottom or nearTop:
+    # Flip strafe if it pushes further into the wall
+    let px = cos(perpAngle)
+    let py = sin(perpAngle)
+    if (nearLeft   and px < 0.0) or (nearRight  and px > 0.0) or
+       (nearBottom and py < 0.0) or (nearTop    and py > 0.0):
+      m.strafeDir = -m.strafeDir
+      perpAngle   = if m.strafeDir >= 0.0: enemyBearingRad + PI * 0.5
+                    else:                   enemyBearingRad - PI * 0.5
+    # Blend 50% toward arena center
+    let escapeAngle = arctan2(ws.arenaHeight * 0.5 - botY, ws.arenaWidth * 0.5 - botX)
+    let ex = cos(escapeAngle) + cos(perpAngle)
+    let ey = sin(escapeAngle) + sin(perpAngle)
+    perpAngle = arctan2(ey, ex)
+
+  # Distance control: blend a radial component when outside the deadband.
+  # Secondary to bullet dodge — capped at WS_RadialFrac of travel direction.
+  # ponytail: linear blend, tune WS_RadialFrac if approach/retreat feels sluggish
+  let enemyDist  = sqrt((enemyX - botX)^2 + (enemyY - botY)^2)
+  let distErr    = enemyDist - WS_PrefDist
+  let radialFrac =
+    if   distErr >  WS_DistBand: WS_RadialFrac                     # too far  → approach
+    elif distErr < -WS_DistBand: -WS_RadialFrac                    # too close → retreat
+    else: 0.0                                                       # deadband  → pure strafe
+  if abs(radialFrac) > 1e-9:
+    # Radial direction: toward enemy (positive) or away (negative)
+    let radialAngle = arctan2(enemyY - botY, enemyX - botX) +
+                      (if radialFrac < 0.0: PI else: 0.0)
+    let rx = cos(perpAngle) * (1.0 - abs(radialFrac)) + cos(radialAngle) * abs(radialFrac)
+    let ry = sin(perpAngle) * (1.0 - abs(radialFrac)) + sin(radialAngle) * abs(radialFrac)
+    perpAngle = arctan2(ry, rx)
+
   let desiredDeg = radToDeg(perpAngle)
 
   var delta = desiredDeg - ws.selfHeading