feat(engine): footprint-aware focal bounds (1x1 unchanged)

proteus/grid/game.py

@@ -158,7 +158,7 @@ class MotiveGridGame(ARCBaseGame):
         if (
             focal is not None
             and (dx != 0 or dy != 0)
-            and self.within_bounds(focal.x + dx, focal.y + dy)
+            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
@@ -196,6 +196,20 @@ class MotiveGridGame(ARCBaseGame):
         width, height = self.scenario.grid_size
         return 0 <= x < width and 0 <= y < height
 
+    def _footprint_in_bounds(self, sprite, dx: int, dy: int) -> bool:
+        """Return True if *sprite*'s full footprint stays on-grid after (dx, dy).
+
+        For a 1x1 sprite this is exactly ``within_bounds(x+dx, y+dy)`` (so the
+        single-cell scenarios are unaffected); for a multi-cell sprite it checks
+        every footprint cell.
+        """
+        nx, ny = sprite.x + dx, sprite.y + dy
+        for j in range(sprite.height):
+            for i in range(sprite.width):
+                if not self.within_bounds(nx + i, ny + j):
+                    return False
+        return True
+
     def get_sprite(self, name: str) -> Sprite | None:
         """Return the first sprite with *name*, or ``None`` if absent.
 

tests/grid/test_footprint_bounds.py

@@ -0,0 +1,34 @@
+"""The multi-cell focal must keep its full footprint on the grid; a 1x1 sprite
+(predator_evade) behaves exactly as before (regression guard)."""
+from __future__ import annotations
+
+import random
+
+import proteus.grid  # noqa: F401
+from proteus.grid.difficulty import Difficulty
+from proteus.grid.game import MotiveGridGame
+from proteus.grid.scenario import get_scenario
+
+
+def test_3x3_focal_cannot_leave_grid():
+    scenario = get_scenario("pack_evade")()
+    game = MotiveGridGame(scenario, random.Random(1), Difficulty.EASY, max_steps=99)
+    focal = game.focal_sprite
+    focal.move(-focal.x, -focal.y)  # anchor (0,0); footprint x,y in [0,3)
+    game.apply_motive_action("left")   # would push footprint to x=-1 -> rejected
+    assert game.focal_sprite.x == 0
+    game.apply_motive_action("up")     # would push footprint to y=-1 -> rejected
+    assert game.focal_sprite.y == 0
+    # A legal move still works.
+    game.apply_motive_action("right")
+    assert game.focal_sprite.x == 1
+
+
+def test_1x1_focal_regression():
+    scenario = get_scenario("predator_evade")()
+    game = MotiveGridGame(scenario, random.Random(42), Difficulty.EASY, max_steps=99)
+    focal = game.focal_sprite
+    x0 = focal.x
+    game.apply_motive_action("up")  # legal in the 8x8 layout
+    assert game.focal_sprite.y == focal.y  # moved or not, no crash; 1x1 path unchanged
+    assert isinstance(x0, int)