azeroth-shell 0.0.0-stage → 0.1.0

package/src/engine/combat/slowUpdate.ts

@@ -0,0 +1,178 @@
+// Recoil SlowUpdate cursor (docs/perf/recoil-scale.md C2). Idle/ooc/leashed think every IDLE_RATE ticks;
+// engaged every ENGAGED_RATE. GCD/swing landing this tick, or a live cast, always thinks.
+
+import type { Fighter } from './types.ts';
+import type { SpellDef } from '../../data/schema.ts';
+import { isEnemySide } from '../core/events.ts';
+import { fighterIsInCombat } from './combatFlag.ts';
+
+/** 2 Hz at 10 Hz sim. Kept at 4× so the slice does not get denser with speed. */
+export const SLOW_IDLE_RATE = 5;
+/** 5 Hz at 10 Hz sim. */
+export const SLOW_ENGAGED_RATE = 2;
+// The pickAction backstop only, never the EventAI poll or the area-aura slice. It was 63% of every
+// think in a 40-man fight; 8 is faster still and refused — it blinds a melee for 800 ms, visibly.
+export const SLOW_DECIDE_RATE = 2;
+
+export type SlowDiag = {
+  pickThink: number;
+  pickSkip: number;
+  eventAiThink: number;
+  eventAiSkip: number;
+  areaAuraRadius: number;
+  areaAuraSkip: number;
+};
+
+export function emptySlowDiag(): SlowDiag {
+  return {
+    pickThink: 0,
+    pickSkip: 0,
+    eventAiThink: 0,
+    eventAiSkip: 0,
+    areaAuraRadius: 0,
+    areaAuraSkip: 0,
+  };
+}
+
+// Stable bucket so the slice test is deterministic, memoized because the body allocates and a side's
+// bucket never changes. Asked per engaged enemy, per area-aura holder and per steering unit, per tick.
+const sideBucketCache = new Map<string, number>();
+export function sideBucket(side: string): number {
+  const hit = sideBucketCache.get(side);
+  if (hit !== undefined) return hit;
+  const v = computeSideBucket(side);
+  if (sideBucketCache.size > 4096) sideBucketCache.clear();
+  sideBucketCache.set(side, v);
+  return v;
+}
+function computeSideBucket(side: string): number {
+  if (side === 'player') return 0;
+  if (side === 'pet') return 1;
+  if (side === 'enemy') return 2;
+  if (side.startsWith('ally_')) return 16 + ((Number(side.slice(5)) || 0) | 0);
+  if (side.startsWith('enemy_')) return 64 + ((Number(side.slice(6)) || 0) | 0);
+  let h = 0;
+  for (let i = 0; i < side.length; i++) h = (Math.imul(h, 31) + side.charCodeAt(i)) | 0;
+  return h >>> 0;
+}
+
+export function timerLands(readyAt: number, t: number, tickMs: number): boolean {
+  return t >= readyAt && t - tickMs < readyAt;
+}
+
+export type SlowThinkOpts = {
+  side: string;
+  t: number;
+  tickMs: number;
+  engaged: boolean;
+  gcdUntil: number;
+  swingReadyAt: number;
+  ohSwingReadyAt: number;
+  casting: boolean;
+};
+
+export function slowSliceDue(side: string, t: number, tickMs: number, rate: number): boolean {
+  const step = Math.max(1, tickMs | 0);
+  const tickIndex = Math.floor(t / step);
+  const r = Math.max(1, rate | 0);
+  return tickIndex % r === sideBucket(side) % r;
+}
+
+function lands(opts: SlowThinkOpts): boolean {
+  if (opts.casting) return true;
+  const { t, tickMs } = opts;
+  return timerLands(opts.gcdUntil, t, tickMs)
+    || timerLands(opts.swingReadyAt, t, tickMs)
+    || timerLands(opts.ohSwingReadyAt, t, tickMs);
+}
+
+/** EventAI poll: land or this unit's slice. Timers are `t`-keyed, so a skip does not stall them. */
+export function slowThinkDue(opts: SlowThinkOpts): boolean {
+  if (lands(opts)) return true;
+  return slowSliceDue(
+    opts.side,
+    opts.t,
+    opts.tickMs,
+    opts.engaged ? SLOW_ENGAGED_RATE : SLOW_IDLE_RATE,
+  );
+}
+
+// Longest a decision may sleep past the backstop, in ticks: the precise bound covers timers a unit
+// OWNS, this is insurance. 4, because at 8 the mage fixture kills 2 s faster on 9.8% less damage.
+const DECIDE_SLEEP_CAP_TICKS = 4;
+
+// Earliest instant a timer this unit OWNS can change what it may do: swings, cooldowns, next power
+// quantum. Everything else has a dirty mark. Rage has no term — a hit landing or taken is covered.
+function ownTimerWakeAt(f: Fighter, t: number, tickMs: number): number {
+  let b = Number.POSITIVE_INFINITY;
+  if (f.swingReadyAt > t && f.swingReadyAt < b) b = f.swingReadyAt;
+  if (f.ohSwingReadyAt > t && f.ohSwingReadyAt < b) b = f.ohSwingReadyAt;
+  for (const at of f.cooldowns.values()) if (at > t && at < b) b = at;
+  for (const at of f.categoryCooldowns.values()) if (at > t && at < b) b = at;
+  const pt = f.spec.powerType;
+  if (f.power < f.spec.maxPower) {
+    if (pt === 'energy') { const nx = t + 100; if (nx < b) b = nx; }
+    else if (pt !== 'rage') { const nx = t + 1000; if (nx < b) b = nx; }
+  }
+  // Druid parallel mana pool: shifting out to heal is a decision this pool gates.
+  if (f.maxMana > 0 && f.mana < f.maxMana) { const nx = t + 1000; if (nx < b) b = nx; }
+  if (!Number.isFinite(b)) return b;
+  const capAt = t + DECIDE_SLEEP_CAP_TICKS * Math.max(1, tickMs | 0);
+  return b < capAt ? b : capAt;
+}
+export function nextDecideWakeAt(
+  f: Fighter,
+  t: number,
+  tickMs: number,
+  engaged: boolean,
+): number {
+  let w = f.gcdUntil;
+  if (f.castingSpell && f.castFinishAt > 0 && f.castFinishAt < w) w = f.castFinishAt;
+  if (f.channeling && f.channeling.endsAt < w) w = f.channeling.endsAt;
+  if (w > t) return w;
+  // A RELOCATING unit thinks again next tick: a move pick spends no GCD and starts no cast, so
+  // nothing else wakes it. A fixture caster with a live run-out row was asked once in 120 ticks.
+  if (f.pendingMechanicMove) return t + Math.max(1, tickMs | 0);
+  if (!engaged) return Number.POSITIVE_INFINITY;
+  const pollAt = t + SLOW_DECIDE_RATE * Math.max(1, tickMs | 0);
+  // A live halt ends on an OUTSIDE fact, and `ownTimerWakeAt` knows only this unit's own cooldowns:
+  // a raider with no kit returned Infinity and the halt had no clock at all. Poll while one is armed.
+  if (f.haltDpsSchool !== undefined) return pollAt;
+  // 63% of every think in a sustained 40-man fight was this poll firing on a unit whose own timers
+  // said nothing could change yet: 42,156 polls, 63.6% of them able to sleep past 2 ticks.
+  const own = ownTimerWakeAt(f, t, tickMs);
+  return own > pollAt ? own : pollAt;
+}
+
+/** S2: think on the next tick. AttackStart / party combat-enter / CallAssistance. */
+export function wakeForDecision(f: Fighter): void {
+  f.decideDirty = true;
+  f.nextWakeAt = 0;
+}
+
+// Hard CC does not force pick. CMaNGOS CanExecuteCombatAction is false (UnitAI.cpp:784; CanReactInCombat).
+// Exception: auto-rescue items / a ready breaker.
+export function hardCcMustDecide(
+  f: Fighter,
+  rescueItems: boolean,
+  isBreaker: (s: SpellDef, u: Fighter) => boolean,
+  onCooldown: (u: Fighter, s: SpellDef) => boolean,
+  canAfford: (u: Fighter, s: SpellDef) => boolean,
+): boolean {
+  if (rescueItems) return true;
+  for (const s of f.spec.spells) {
+    if (isBreaker(s, f) && !onCooldown(f, s) && canAfford(f, s)) return true;
+  }
+  return false;
+}
+
+export function slowEngaged(
+  f: Fighter,
+  t: number,
+  threatOf: (owner: Fighter) => { isEmpty(): boolean } | undefined,
+): boolean {
+  if (fighterIsInCombat(f, t)) return true;
+  if (!isEnemySide(f.side)) return false;
+  const tm = threatOf(f);
+  return !!tm && !tm.isEmpty();
+}

package/src/engine/combat/snapToFloor.ts

@@ -0,0 +1,42 @@
+// Snap a combat-yard point onto the navmesh. Extracted from `sessionGeometry.ts` so the SESSION and the
+// main-thread mirror the S6 facade needs are one implementation rather than two: a cheap path that puts
+// the floor somewhere else than the expensive one is the defect CLAUDE.md 0c.4 names.
+
+import { navMeshForMap, snapOntoNavMesh } from '../../domain/nav/navmesh.ts';
+import { detHypot } from '../core/detMath.ts';
+import type { CombatPosYd, PullGeometryAnchor } from './combatGeometry.ts';
+
+// Nearest walkable floor to `pos`, or null when a loaded mesh refuses inside `radiusYd`. No mesh
+// loaded returns the point untouched, so a session without geometry stays planar.
+export function snapPosToMesh(
+  anchor: PullGeometryAnchor | undefined,
+  pos: CombatPosYd,
+  radiusYd: number,
+  refZ?: number | null,
+): CombatPosYd | null {
+  const anchorMapId = anchor?.mapId;
+  const anchorMesh = anchorMapId != null ? navMeshForMap(anchorMapId) : null;
+  if (!anchorMesh) return pos;
+  const o = (anchor?.frame === 'world-translated' ? anchor.origin : null) ?? { x: 0, y: 0 };
+  const w = { x: o.x + pos.x, y: o.y + pos.y };
+  // With a reference floor, walkability alone is not enough, since the mask is stacked. Ask for floor
+  // AND height together and return the resolved z, so the caller can chain the next snap off it.
+  if (refZ != null && Number.isFinite(refZ)) {
+    // Real polys carry z, so the floor at the clicked point on the standing storey is a direct
+    // question. Off-poly, land ON the poly and never keep the void XY.
+    const on = snapOntoNavMesh(anchorMesh, w.x, w.y, refZ, radiusYd, 4);
+    if (on) {
+      const d = detHypot(on.x - w.x, on.y - w.y);
+      if (d <= 0.75) return { ...pos, z: on.z };
+      if (d <= radiusYd) return { x: on.x - o.x, y: on.y - o.y, z: on.z };
+    }
+    // The mesh is loaded and it refused inside the radius: that refusal IS the answer. The raster
+    // second opinion that sat here read a plan bit with no z and recovered a pit onto the floor below.
+    return null;
+  }
+  // Z-less: no reference storey to ask about, so `snapOntoNavMesh` takes the nearest poly at any
+  // height and the caller keeps its own position when there is none within `radiusYd`.
+  const s = snapOntoNavMesh(anchorMesh, w.x, w.y, undefined, radiusYd);
+  if (!s) return pos;
+  return { x: s.x - o.x, y: s.y - o.y, z: s.z };
+}

package/src/engine/combat/speedAura.ts

@@ -0,0 +1,29 @@
+// Hostile vs self/beneficial speed-aura polarity. The decrease-speed family carries self-slows
+// (Stealth, Prowl) with hostile:false, and apply and view must trust that flag over a negative pct.
+
+/** Minimal shape shared by SpellEffect and live session speed rows. */
+export type SpeedPolarity = {
+  kind?: string;
+  hostile?: boolean;
+  pct?: number;
+};
+
+// True when a speed effect is a hostile snare or daze. An explicit hostile:false wins over a negative
+// pct; with the flag omitted a negative pct is hostile, which is what a bake-thin row leaves.
+export function isHostileSpeedEffect(e: SpeedPolarity): boolean {
+  if (e.kind != null && e.kind !== 'speed') return false;
+  if (e.hostile === true) return true;
+  if (e.hostile === false) return false;
+  return (e.pct ?? 0) < 0;
+}
+
+/** UnitSpeedChanged: recompute run speed only on apply/remove, not a per-tick scan. */
+export function markSpeedDirty(f: { speedDirty: boolean }): void {
+  f.speedDirty = true;
+}
+
+/** Beneficial / self speed (Sprint, Cheetah, Stealth cost) — buff bar, not snare. */
+function isBeneficialSpeedEffect(e: SpeedPolarity): boolean {
+  if (e.kind != null && e.kind !== 'speed') return false;
+  return !isHostileSpeedEffect(e);
+}

package/src/engine/combat/spellReagents.ts

@@ -0,0 +1,71 @@
+// Spell reagent CheckItems / TakeReagents for combat casts. Cite: Spell.cpp CheckItems ~6560-6593;
+// TakeReagents ~4332-4350. The OOC path is game.ts castOutOfCombat and must gate the same way.
+
+import type { SpellDef } from '../../data/schema.ts';
+import { isAllySide, type Side } from '../core/events.ts';
+import type { Fighter } from './types.ts';
+
+/** Seed live bag counts for every reagent listed on a kit (entry → count). */
+export function seedReagentBagCounts(
+  spells: readonly SpellDef[] | undefined,
+  countOf: (item: number) => number,
+): Record<number, number> | undefined {
+  if (!spells?.length) return undefined;
+  const bag: Record<number, number> = {};
+  let any = false;
+  for (const sp of spells) {
+    for (const r of sp.reagents ?? []) {
+      const item = r.item | 0;
+      if (!item || bag[item] !== undefined) continue;
+      bag[item] = countOf(item) | 0;
+      any = true;
+    }
+  }
+  return any ? bag : undefined;
+}
+
+// CheckItems: every reagent row needs count >= need in the live bag snapshot. Creatures and fixtures
+// with no bag counts pass, since they never carry reagents; a seeded player without enough fails.
+export function canPaySpellReagents(f: Fighter, spell: SpellDef): boolean {
+  const reagents = spell.reagents;
+  if (!reagents?.length) return true;
+  const bag = f.spec.bagItemCounts;
+  // No snapshot: NPCs and bare createSession fixtures allow. Real pulls seed bagItemCounts
+  // from inventory for any kit that lists reagents (combatSession / companion build).
+  if (!bag) return true;
+  for (const r of reagents) {
+    const need = r.count | 0;
+    if (need <= 0) continue;
+    if ((bag[r.item] ?? 0) < need) return false;
+  }
+  return true;
+}
+
+// Spell.cpp TakeReagents — decrement live bag + record itemsSpent for resolveFight. Returns false if
+// CheckItems would fail (caller should fizzle, no mana spend if pre-check).
+export function takeSpellReagents(
+  f: Fighter,
+  spell: SpellDef,
+  itemsSpent: Map<number, number>,
+  opts?: {
+    unitItemsSpent?: ReadonlyMap<Side, Map<number, number>>;
+  },
+): boolean {
+  const reagents = spell.reagents;
+  if (!reagents?.length) return true;
+  if (!canPaySpellReagents(f, spell)) return false;
+  const bag = f.spec.bagItemCounts;
+  if (!bag) return true;
+  for (const r of reagents) {
+    const n = r.count | 0;
+    if (n <= 0) continue;
+    bag[r.item] = Math.max(0, (bag[r.item] ?? 0) - n);
+    if (f.side === 'player') {
+      itemsSpent.set(r.item, (itemsSpent.get(r.item) ?? 0) + n);
+    } else if (opts?.unitItemsSpent && isAllySide(f.side as Side)) {
+      const m = opts.unitItemsSpent.get(f.side);
+      if (m) m.set(r.item, (m.get(r.item) ?? 0) + n);
+    }
+  }
+  return true;
+}

package/src/engine/combat/stealthDetect.ts

@@ -0,0 +1,93 @@
+// Periodic stealth detect sweep, the C++ predicate on the C++ cadence against fresh positions.
+// Detection ran once at session build, so a unit that WALKED into a pack stayed unseen forever.
+
+import { isEnemySide, isPlayerCharacterSide, isTotemSide } from '../core/events.ts';
+import {
+  PLAYER_COMBAT_REACH_YD,
+  detectsStealth,
+  stealthDetectIntervalMs,
+  totalStealthStrength,
+} from '../../domain/spells/stealth.ts';
+import type { CombatContext } from './context.ts';
+import { navSightClear } from './navSight.ts';
+import { combatPerf } from './perfSink.ts';
+import type { Fighter } from './types.ts';
+
+export function installStealthDetect(
+  ctx: CombatContext,
+  deps: { dead: (f: Fighter) => boolean },
+): void {
+  const { dead } = deps;
+  const cfg = ctx.cfg;
+  const bg = !!cfg.battlegroundMap;
+  const interval = stealthDetectIntervalMs(bg);
+  // The core arms this a second after login and only then falls into its cadence, so the first sweep
+  // is never on the frame the unit appeared. One interval of grace keeps the opener window.
+  let nextAt = interval;
+
+  /** UNIT_FLAG_PLAYER_CONTROLLED. In a battleground every enemy seat is a player too. */
+  const playerControlled = (f: Fighter): boolean =>
+    isPlayerCharacterSide(f.side) || f.side === 'pet' || (bg && isEnemySide(f.side));
+
+  /** TYPEID_PLAYER — caps the detect range at 45 and floors it at the player's own reach. */
+  const isPlayerUnit = (f: Fighter): boolean =>
+    isPlayerCharacterSide(f.side) || (bg && isEnemySide(f.side));
+
+  // `getAttackers()` — someone is already swinging at this unit, so stealth is moot. Threat list membership
+  // is the engine's attacker set (ThreatManager owner -> victim ids).
+  const hasAttackers = (f: Fighter): boolean => {
+    for (const other of ctx.fightersOrder()) {
+      if (other === f || dead(other)) continue;
+      if (isEnemySide(other.side) === isEnemySide(f.side)) continue;
+      const tm = ctx.threatOf?.(other);
+      if (tm && tm.hasThreat(f.side)) return true;
+    }
+    return false;
+  };
+
+  const core = (): void => {
+    if (ctx.t < nextAt) return;
+    nextAt = ctx.t + interval;
+    const all = ctx.fightersOrder();
+    // Cheap early-out: the sweep only exists for stealthed bodies.
+    let anyStealthed = false;
+    for (const f of all) if (f.stealthed && !dead(f)) { anyStealthed = true; break; }
+    if (!anyStealthed) return;
+    const positions = ctx.unitPositionsMutable;
+    for (const sneak of all) {
+      if (!sneak.stealthed || dead(sneak)) continue;
+      const strength = totalStealthStrength(sneak.stealthAuraStrength, sneak.stealthLevelBonus);
+      const attacked = hasAttackers(sneak);
+      const sneakControlled = playerControlled(sneak);
+      for (const det of all) {
+        if (det === sneak || dead(det)) continue;
+        // Same team never blows the cover (IsFogOfWarVisibleStealth: group always sees).
+        if (isEnemySide(det.side) === isEnemySide(sneak.side)) continue;
+        // A totem has no detect sweep of its own (TotemAI never calls it).
+        if (isTotemSide(det.side)) continue;
+        const isPlayer = isPlayerUnit(det);
+        const seen = detectsStealth({
+          distanceYd: ctx.distanceBetween(det, sneak),
+          detectorLevel: det.spec.level,
+          detectorAlive: true,
+          detectorStunned: det.stunnedUntil > ctx.t,
+          detectorIsPlayer: isPlayer,
+          detectorCombatReachYd: isPlayer ? PLAYER_COMBAT_REACH_YD : 0,
+          stealthStrength: strength,
+          detectStrength: det.stealthDetectStrength,
+          stealtherPlayerControlled: sneakControlled,
+          stealtherAttacked: attacked,
+          inFrontArc: ctx.isInFrontArc(det, sneak),
+          // navSightClear fails open with no mask, so an un-baked floor keeps the old answer.
+          lineOfSight: navSightClear(cfg, positions?.[det.side], positions?.[sneak.side]),
+        });
+        if (seen) {
+          ctx.breakStealth?.(sneak, 'detected');
+          break;
+        }
+      }
+    }
+  };
+
+  ctx.stealthDetectPhase = (): void => combatPerf('sim.stealthDetect', core);
+}

package/src/engine/combat/stepBackMotion.ts

@@ -0,0 +1,171 @@
+// After-cast retreat: lock a walkable heading AWAY from the enemy, then hop along it.
+// Live radial-from-center walks THROUGH the mob when you overlap.
+
+import { detHypot } from '../core/detMath.ts';
+import type { CombatPosYd } from './combatGeometry.ts';
+
+/** Inside this, unit centers overlap — the live radial is the approach heading, not "back". */
+const OVERLAP_YD = 2.5;
+
+/** 80% of asked yards is CMaNGOS's "good enough" collision dest. Object.cpp:1600. */
+const GOOD_FRAC = 0.8;
+/** Below this the heading is a wall lip, not a retreat. */
+const MIN_WALK_YD = 2;
+
+function lockStepBackDir(
+  from: CombatPosYd,
+  enemy: CombatPosYd,
+  lastMoveFrom: CombatPosYd | null,
+): { x: number; y: number } {
+  const dist = detHypot(from.x - enemy.x, from.y - enemy.y);
+  if (lastMoveFrom) {
+    const lastD = detHypot(lastMoveFrom.x - enemy.x, lastMoveFrom.y - enemy.y);
+    const mx = from.x - lastMoveFrom.x;
+    const my = from.y - lastMoveFrom.y;
+    const mlen = detHypot(mx, my);
+    // We were closing: reverse that heading (back out the way we walked in).
+    if (mlen > 0.05 && lastD > dist + 0.05) {
+      return { x: -mx / mlen, y: -my / mlen };
+    }
+    // Overlapped with no clear close: the last place we stood is the safe side.
+    if (dist < OVERLAP_YD && lastD > dist + 0.05) {
+      const lx = lastMoveFrom.x - enemy.x;
+      const ly = lastMoveFrom.y - enemy.y;
+      const llen = detHypot(lx, ly);
+      if (llen > 0.05) return { x: lx / llen, y: ly / llen };
+    }
+  }
+  if (dist > 0.05) {
+    return { x: (from.x - enemy.x) / dist, y: (from.y - enemy.y) / dist };
+  }
+  return { x: 1, y: 0 };
+}
+
+/** Dest is on the retreat half-plane (same side of the enemy as `dir`). */
+export function onRetreatSide(
+  enemy: CombatPosYd,
+  dest: CombatPosYd,
+  dir: { x: number; y: number },
+): boolean {
+  return (dest.x - enemy.x) * dir.x + (dest.y - enemy.y) * dir.y > 0;
+}
+
+export function alongDir(
+  from: CombatPosYd,
+  to: CombatPosYd,
+  dir: { x: number; y: number },
+): number {
+  return (to.x - from.x) * dir.x + (to.y - from.y) * dir.y;
+}
+
+function rotate(ux: number, uy: number, c: number, s: number): { x: number; y: number } {
+  return { x: ux * c - uy * s, y: ux * s + uy * c };
+}
+
+// Lock-time fan: back, then 30/60/90/105 each way. ±90 is the wall-strafe a 75° hop fan
+// cannot take (`alongDir` on a back-locked heading is 0). Cite: Object.cpp:1594–1603.
+const PICK_FAN: ReadonlyArray<readonly [number, number]> = [
+  [1, 0],
+  [0.8660254, 0.5], [0.8660254, -0.5],
+  [0.5, 0.8660254], [0.5, -0.8660254],
+  [0, 1], [0, -1],
+  [-0.2588190, 0.9659258], [-0.2588190, -0.9659258],
+];
+
+/** Last walkable point along `aim` — GetFirstCollisionPosition, not A*. */
+type ClampAlong = (aim: CombatPosYd) => CombatPosYd;
+
+// Probe each heading with a straight-line floor clamp (PathFinder.cpp:802 m_straightLine).
+// Pick the one that actually walks, preferring away-from-enemy. Null = cornered.
+export function pickStepBackDir(
+  from: CombatPosYd,
+  enemy: CombatPosYd,
+  lastMoveFrom: CombatPosYd | null,
+  needYd: number,
+  clampAlong: ClampAlong,
+): { x: number; y: number } | null {
+  if (!(needYd > 0)) return null;
+  const base = lockStepBackDir(from, enemy, lastMoveFrom);
+  const blen = detHypot(base.x, base.y);
+  if (!(blen > 0)) return null;
+  const ux = base.x / blen;
+  const uy = base.y / blen;
+  const z = from.z != null ? { z: from.z } : {};
+  const startD = detHypot(from.x - enemy.x, from.y - enemy.y);
+  const goodAt = needYd * GOOD_FRAC;
+  const minWalk = Math.max(0.5, Math.min(MIN_WALK_YD, needYd * 0.2));
+  let best: { x: number; y: number; walk: number; away: number; align: number } | null = null;
+  for (const [c, s] of PICK_FAN) {
+    const h = rotate(ux, uy, c, s);
+    const hlen = detHypot(h.x, h.y);
+    if (!(hlen > 0)) continue;
+    const dx = h.x / hlen;
+    const dy = h.y / hlen;
+    const aim: CombatPosYd = { x: from.x + dx * needYd, y: from.y + dy * needYd, ...z };
+    const hit = clampAlong(aim);
+    const walk = detHypot(hit.x - from.x, hit.y - from.y);
+    if (walk < minWalk) continue;
+    const away = detHypot(hit.x - enemy.x, hit.y - enemy.y) - startD;
+    if (away < -0.25) continue;
+    const align = dx * ux + dy * uy;
+    const cand = { x: dx, y: dy, walk, away, align };
+    if (!best) { best = cand; continue; }
+    const aGood = cand.walk >= goodAt;
+    const bGood = best.walk >= goodAt;
+    if (aGood !== bGood) {
+      if (aGood) best = cand;
+      continue;
+    }
+    if (aGood) {
+      if (Math.abs(cand.away - best.away) > 0.05) {
+        if (cand.away > best.away) best = cand;
+      } else if (cand.align > best.align) {
+        best = cand;
+      }
+    } else if (cand.walk > best.walk) {
+      best = cand;
+    }
+  }
+  return best ? { x: best.x, y: best.y } : null;
+}
+
+// Headings tried as literal (cos, sin) pairs off the locked heading — back, then 30, 60 and 75 degrees
+// each way. Three headings could not round a corner, and a blocked retreat gates every hostile spell.
+const RETREAT_FAN: ReadonlyArray<readonly [number, number]> = [
+  [1, 0],
+  [0.8660254, 0.5], [0.8660254, -0.5],
+  [0.5, 0.8660254], [0.5, -0.8660254],
+  [0.2588190, 0.9659258], [0.2588190, -0.9659258],
+];
+
+// One hop along the locked heading, fanning outward. Never toward / through the enemy. `tryStep` is a
+// clamp-only walk (no A*). Returns the accepted next pos or null.
+export function planStepBackHop(
+  from: CombatPosYd,
+  enemy: CombatPosYd,
+  dir: { x: number; y: number },
+  hop: number,
+  tryStep: (aim: CombatPosYd) => CombatPosYd,
+): CombatPosYd | null {
+  if (!(hop > 0)) return null;
+  const z = from.z != null ? { z: from.z } : {};
+  const dlen = detHypot(dir.x, dir.y);
+  if (!(dlen > 0)) return null;
+  const ux = dir.x / dlen;
+  const uy = dir.y / dlen;
+  // Scale-free: one tick's hop shrinks with the tick rate, so a fixed 0.05 yd floor
+  // rejected legal wide-fan steps outright on a short tick.
+  const minGain = Math.max(1e-3, hop * 0.05);
+  for (const [c, s] of RETREAT_FAN) {
+    const aim: CombatPosYd = {
+      x: from.x + (ux * c - uy * s) * hop,
+      y: from.y + (ux * s + uy * c) * hop,
+      ...z,
+    };
+    const next = tryStep(aim);
+    if (alongDir(from, next, dir) < minGain) continue;
+    if (!onRetreatSide(enemy, next, dir)) continue;
+    return next;
+  }
+  return null;
+}