feat(engine): per-scenario turn_order with predator-first step swap

Add Scenario.turn_order class attribute ("focal_first" default) and honour it
in MotiveGridGame.step(): predator_first calls advance_threat before the focal
moves; focal_first (default) preserves legacy behaviour so predator_evade and
all existing tests are unaffected.

proteus/game/engine/grid.py

@@ -145,27 +145,32 @@ class MotiveGridGame(ARCBaseGame):
         return self.perform_action(action_input)
 
     def step(self) -> None:
-        """Resolve a single turn (one focal move + threat advance + outcome).
+        """Resolve a single turn, honouring ``scenario.turn_order``.
 
-        Reads the pending engine action, moves the focal sprite, advances the
-        threat, then checks for elimination or survival.  Always completes the
-        action so the engine loop terminates after one step.
+        focal_first (default): move focal, then advance threat (chasing the new
+        focal cell). predator_first: advance threat first (chasing the current
+        focal cell), then move focal. Capture/survival are checked once, after
+        both have moved. Always completes the action so the engine loop ends.
         """
         action = _GAMEACTION_TO_ACTION.get(self._action.id, "stay")
         dx, dy = _DIRECTION_DELTAS[action]
-
         focal = self.focal_sprite
+        predator_first = (
+            getattr(self.scenario, "turn_order", "focal_first") == "predator_first"
+        )
+
+        if predator_first:
+            self.scenario.advance_threat(self)
+
         if (
             focal is not None
             and (dx != 0 or dy != 0)
             and self._footprint_in_bounds(focal, dx, dy)
         ):
-            # arc_grid has no implicit world border: try_move_sprite reverts
-            # only on sprite collision, so the framework guards the grid edge
-            # itself.  Internal walls are still handled by try_move_sprite.
             self.try_move_sprite(focal, dx, dy)
 
-        self.scenario.advance_threat(self)
+        if not predator_first:
+            self.scenario.advance_threat(self)
 
         self.step_count += 1
 

proteus/game/scenarios/base.py

@@ -66,6 +66,12 @@ class Scenario(ABC):
     # Default empty -> callers fall back to rules_text. Scenarios that want a
     # more transparent practice brief override this with their own text.
     memory_brief: str = ""
+    # Turn resolution order. "focal_first" (default): focal moves, then the
+    # threat advances (chasing the focal's NEW cell). "predator_first": the
+    # threat advances first (chasing the focal's CURRENT cell), then the focal
+    # moves. Scenarios override this; predator_evade keeps the default so its
+    # dead-end diagnostic is preserved.
+    turn_order: str = "focal_first"
 
     @abstractmethod
     def build_level(self, rng: random.Random, difficulty: Difficulty) -> Level:

tests/engine/test_turn_order.py

@@ -0,0 +1,36 @@
+# tests/engine/test_turn_order.py
+"""predator-first reorders the turn: advance_threat sees the focal's PRE-move cell."""
+import random
+
+from proteus.game.engine.difficulty import Difficulty
+from proteus.game.engine.grid import MotiveGridGame
+from proteus.game.scenarios.base import get_scenario
+import proteus.game.scenarios  # noqa: F401  (register scenarios)
+
+
+def _focal_cell_seen_by_threat(turn_order: str, action: str = "up"):
+    scen = get_scenario("predator_evade")()
+    scen.turn_order = turn_order  # instance override
+    game = MotiveGridGame(scen, random.Random(0), Difficulty.EASY, max_steps=10)
+    seen = {}
+    real_advance = scen.advance_threat
+
+    def spy(g):
+        f = g.focal_sprite
+        seen["focal"] = (f.x, f.y)
+        real_advance(g)
+
+    scen.advance_threat = spy  # shadow the bound method on this instance
+    before = (game.focal_sprite.x, game.focal_sprite.y)
+    game.apply_motive_action(action)
+    return before, seen["focal"]
+
+
+def test_predator_first_threat_sees_premove_focal():
+    before, seen = _focal_cell_seen_by_threat("predator_first", "up")
+    assert seen == before  # predator advanced BEFORE the focal moved
+
+
+def test_focal_first_threat_sees_postmove_focal():
+    before, seen = _focal_cell_seen_by_threat("focal_first", "up")
+    assert seen != before  # legacy: focal moved first, predator chased the new cell