trianglengin 2.0.1__cp312-cp312-macosx_11_0_arm64.whl

trianglengin/ui/interaction/play_mode_handler.py

@@ -0,0 +1,156 @@
+# src/trianglengin/ui/interaction/play_mode_handler.py
+import logging
+from typing import TYPE_CHECKING, cast
+
+# Guard UI imports
+try:
+    import pygame
+
+    # Use absolute import
+    from trianglengin.ui.visualization import core as vis_core
+except ImportError as e:
+    raise ImportError(
+        "UI components require 'pygame'. Install with 'pip install trianglengin[ui]'."
+    ) from e
+
+# Use absolute imports for core components
+from trianglengin.config import EnvConfig
+
+if TYPE_CHECKING:
+    # Use absolute import for InputHandler as well
+    from trianglengin.game_interface import GameState, Shape
+    from trianglengin.ui.interaction.input_handler import InputHandler
+
+logger = logging.getLogger(__name__)
+
+
+# Add EnvConfig type hint for config
+def _encode_action(shape_idx: int, r: int, c: int, config: EnvConfig) -> int:
+    """Helper to encode action based on config. Matches C++ internal logic."""
+    grid_size = config.ROWS * config.COLS
+    if not (
+        0 <= shape_idx < config.NUM_SHAPE_SLOTS
+        and 0 <= r < config.ROWS
+        and 0 <= c < config.COLS
+    ):
+        return -1
+    # Cast the result to int for mypy
+    return cast("int", shape_idx * grid_size + r * config.COLS + c)
+
+
+def handle_play_click(event: pygame.event.Event, handler: "InputHandler") -> None:
+    """Handles mouse clicks in play mode (select preview, place shape). Modifies handler state."""
+    if not (event.type == pygame.MOUSEBUTTONDOWN and event.button == 1):
+        return
+
+    game_state: GameState = handler.game_state
+    visualizer = handler.visualizer
+    mouse_pos = handler.mouse_pos
+
+    if game_state.is_over():
+        logger.info("Game is over, ignoring click.")
+        return
+
+    layout_rects = visualizer.ensure_layout()
+    grid_rect = layout_rects.get("grid")
+    preview_rects = visualizer.preview_rects
+    current_shapes = game_state.get_shapes()
+
+    preview_idx = vis_core.coord_mapper.get_preview_index_from_screen(
+        mouse_pos, preview_rects
+    )
+    if preview_idx is not None:
+        if handler.selected_shape_idx == preview_idx:
+            handler.selected_shape_idx = -1
+            handler.hover_grid_coord = None
+            handler.hover_shape = None
+            logger.info("Deselected shape.")
+        elif (
+            0 <= preview_idx < len(current_shapes)
+            and current_shapes[preview_idx] is not None
+        ):
+            handler.selected_shape_idx = preview_idx
+            logger.info(f"Selected shape index: {preview_idx}")
+            update_play_hover(handler)
+        else:
+            logger.info(f"Clicked empty/invalid preview slot: {preview_idx}")
+            if handler.selected_shape_idx != -1:
+                handler.selected_shape_idx = -1
+                handler.hover_grid_coord = None
+                handler.hover_shape = None
+        return
+
+    selected_idx = handler.selected_shape_idx
+    if selected_idx != -1 and grid_rect and grid_rect.collidepoint(mouse_pos):
+        grid_coords = vis_core.coord_mapper.get_grid_coords_from_screen(
+            mouse_pos, grid_rect, game_state.env_config
+        )
+        shape_to_place: Shape | None = (
+            current_shapes[selected_idx]
+            if 0 <= selected_idx < len(current_shapes)
+            else None
+        )
+
+        if grid_coords and shape_to_place:
+            r, c = grid_coords
+            potential_action = _encode_action(selected_idx, r, c, game_state.env_config)
+
+            if (
+                potential_action != -1
+                and potential_action in game_state.valid_actions()
+            ):
+                reward, done = game_state.step(potential_action)
+                logger.info(
+                    f"Placed shape {selected_idx} at {grid_coords}. R={reward:.1f}, Done={done}"
+                )
+                handler.selected_shape_idx = -1
+                handler.hover_grid_coord = None
+                handler.hover_shape = None
+            else:
+                logger.info(
+                    f"Clicked grid at {grid_coords}, but placement invalid (action {potential_action} not found in valid set)."
+                )
+        else:
+            logger.info(f"Clicked grid at {grid_coords}, but shape or coords invalid.")
+
+
+def update_play_hover(handler: "InputHandler") -> None:
+    """Updates the hover state within the InputHandler."""
+    handler.hover_grid_coord = None
+    handler.hover_is_valid = False
+    handler.hover_shape = None
+
+    game_state: GameState = handler.game_state
+    visualizer = handler.visualizer
+    mouse_pos = handler.mouse_pos
+
+    if game_state.is_over() or handler.selected_shape_idx == -1:
+        return
+
+    layout_rects = visualizer.ensure_layout()
+    grid_rect = layout_rects.get("grid")
+    selected_idx = handler.selected_shape_idx
+    current_shapes = game_state.get_shapes()
+    if not (0 <= selected_idx < len(current_shapes)):
+        return
+    shape: Shape | None = current_shapes[selected_idx]
+    if not shape:
+        return
+
+    handler.hover_shape = shape
+
+    if not grid_rect or not grid_rect.collidepoint(mouse_pos):
+        return
+
+    grid_coords = vis_core.coord_mapper.get_grid_coords_from_screen(
+        mouse_pos, grid_rect, game_state.env_config
+    )
+
+    if grid_coords:
+        r, c = grid_coords
+        potential_action = _encode_action(selected_idx, r, c, game_state.env_config)
+        is_valid = (
+            potential_action != -1 and potential_action in game_state.valid_actions()
+        )
+        handler.hover_grid_coord = grid_coords
+        handler.hover_is_valid = is_valid

trianglengin/ui/visualization/README.md

@@ -0,0 +1,42 @@
+
+# UI Visualization Module (`trianglengin.ui.visualization`)
+
+**Requires:** `pygame`
+
+## Purpose and Architecture
+
+This module is responsible for rendering the game state visually using the Pygame library, specifically for the **interactive modes** (play/debug) provided by the `trianglengin.ui` package.
+
+-   **Core Components ([`core/README.md`](core/README.md)):**
+    -   `Visualizer`: Orchestrates the rendering process for interactive modes.
+    -   `layout`: Calculates the screen positions and sizes for different UI areas.
+    -   `fonts`: Loads necessary font files.
+    -   `colors`: Defines a centralized palette of RGB color tuples.
+    -   `coord_mapper`: Provides functions to map screen coordinates to grid coordinates and preview indices.
+-   **Drawing Components ([`drawing/README.md`](drawing/README.md)):**
+    -   Contains specific functions for drawing different elements onto Pygame surfaces (grid, shapes, previews, HUD, highlights).
+
+**Note:** This module depends on the core `trianglengin` engine for game state data (`GameState`, `EnvConfig`, `Shape`).
+
+## Exposed Interfaces
+
+-   **Core Classes & Functions:**
+    -   `Visualizer`: Main renderer for interactive modes.
+    -   `load_fonts`: Loads Pygame fonts.
+    -   `colors`: Module containing color constants (e.g., `colors.WHITE`).
+    -   `get_grid_coords_from_screen`: Maps screen to grid coordinates.
+    -   `get_preview_index_from_screen`: Maps screen to preview index.
+-   **Drawing Functions:** (Exposed via `trianglengin.ui.visualization.drawing`)
+-   **Config:** (Configs are *not* re-exported from this module)
+
+## Dependencies
+
+-   **`trianglengin` (core):** `GameState`, `EnvConfig`, `Shape`.
+-   **`trianglengin.ui.config`**: `DisplayConfig`.
+-   **`trianglengin.utils`**: `geometry`.
+-   **`pygame`**: The core library used for all drawing, surface manipulation, and font rendering.
+-   **Standard Libraries:** `typing`, `logging`, `math`.
+
+---
+
+**Note:** Please keep this README updated when changing rendering logic, adding new visual elements, modifying layout calculations, or altering the interfaces exposed.

trianglengin/ui/visualization/__init__.py

@@ -0,0 +1,58 @@
+"""
+Visualization module for rendering the game state using Pygame.
+Provides components for interactive play/debug modes.
+"""
+
+# Imports are now direct. If pygame is missing, errors will occur upon use.
+
+# Import core components needed externally
+# Import core EnvConfig for type hinting if needed
+# from trianglengin.config import EnvConfig # REMOVED Re-export
+# from ..config import DisplayConfig  # REMOVED Re-export
+
+from .core import colors  # Import the colors module
+from .core.coord_mapper import (  # Import specific functions
+    get_grid_coords_from_screen,
+    get_preview_index_from_screen,
+)
+from .core.fonts import load_fonts  # Import specific function
+from .core.visualizer import Visualizer  # Import the class
+
+# Import drawing functions directly
+from .drawing.grid import (
+    draw_debug_grid_overlay,
+    draw_grid_background,
+    draw_grid_state,
+)
+from .drawing.highlight import draw_debug_highlight
+from .drawing.hud import render_hud
+from .drawing.previews import (
+    draw_floating_preview,
+    draw_placement_preview,
+    render_previews,
+)
+from .drawing.shapes import draw_shape
+from .drawing.utils import get_triangle_points
+
+__all__ = [
+    # Core Renderer & Layout related
+    "Visualizer",
+    "load_fonts",
+    "colors",  # Export the colors module
+    "get_grid_coords_from_screen",
+    "get_preview_index_from_screen",
+    # Drawing Functions
+    "draw_grid_background",
+    "draw_grid_state",
+    "draw_debug_grid_overlay",
+    "draw_shape",
+    "render_previews",
+    "draw_placement_preview",
+    "draw_floating_preview",
+    "render_hud",
+    "draw_debug_highlight",
+    "get_triangle_points",
+    # Configs are NOT re-exported here
+    # "DisplayConfig",
+    # "EnvConfig",
+]

trianglengin/ui/visualization/core/README.md

@@ -0,0 +1,51 @@
+
+
+# UI Visualization Core Submodule (`trianglengin.ui.visualization.core`)
+
+**Requires:** `pygame`
+
+## Purpose and Architecture
+
+This submodule contains the central classes and foundational elements for the **interactive** visualization system within the `trianglengin.ui` package. It orchestrates rendering for play/debug modes, manages layout and coordinate systems, and defines core visual properties like colors and fonts.
+
+-   **Render Orchestration:**
+    -   [`Visualizer`](visualizer.py): The main class for rendering in **interactive modes** ("play", "debug"). It maintains the Pygame screen, calculates layout using `layout.py`, manages cached preview area rectangles, and calls appropriate drawing functions from [`trianglengin.ui.visualization.drawing`](../drawing/README.md). **It receives interaction state (hover position, selected index) via its `render` method to display visual feedback.**
+-   **Layout Management:**
+    -   [`layout.py`](layout.py): Contains functions (`calculate_interactive_layout`, `calculate_training_layout`) to determine the size and position of the main UI areas based on the screen dimensions, mode, and `DisplayConfig`.
+-   **Coordinate System:**
+    -   [`coord_mapper.py`](coord_mapper.py): Provides essential mapping functions:
+        -   `_calculate_render_params`: Internal helper to get scaling and offset for grid rendering.
+        -   `get_grid_coords_from_screen`: Converts mouse/screen coordinates into logical grid (row, column) coordinates.
+        -   `get_preview_index_from_screen`: Converts mouse/screen coordinates into the index of the shape preview slot being pointed at.
+-   **Visual Properties:**
+    -   [`colors.py`](colors.py): Defines a centralized palette of named color constants (RGB tuples).
+    -   [`fonts.py`](fonts.py): Contains the `load_fonts` function to load and manage Pygame font objects.
+
+## Exposed Interfaces
+
+-   **Classes:**
+    -   `Visualizer` (Import directly from `visualizer.py`, not exported here)
+-   **Functions:**
+    -   `calculate_interactive_layout(...) -> Dict[str, pygame.Rect]`
+    -   `calculate_training_layout(...) -> Dict[str, pygame.Rect]` (Kept for potential future use)
+    -   `load_fonts() -> Dict[str, Optional[pygame.font.Font]]`
+    -   `get_grid_coords_from_screen(...) -> Optional[Tuple[int, int]]`
+    -   `get_preview_index_from_screen(...) -> Optional[int]`
+-   **Modules:**
+    -   `colors`: Provides color constants (e.g., `colors.RED`).
+    -   `layout`: Provides layout calculation functions.
+    -   `coord_mapper`: Provides coordinate mapping functions.
+    -   `fonts`: Provides font loading functions.
+
+## Dependencies
+
+-   **`trianglengin` (core):** `GameState`, `EnvConfig`, `Shape`.
+-   **`trianglengin.ui.config`**: `DisplayConfig`.
+-   **`trianglengin.utils`**: `geometry`.
+-   **`trianglengin.ui.visualization.drawing`**: Drawing functions are called by `Visualizer`.
+-   **`pygame`**: Used for surfaces, rectangles, fonts, display management.
+-   **Standard Libraries:** `typing`, `logging`, `math`.
+
+---
+
+**Note:** Please keep this README updated when changing the core rendering logic, layout calculations, coordinate mapping, or the interfaces of the renderers.

trianglengin/ui/visualization/core/__init__.py

@@ -0,0 +1,16 @@
+"""Core visualization components: renderers, layout, fonts, colors, coordinate mapping."""
+
+# Direct imports - if pygame is missing, these will fail, which is intended behavior
+# for the optional UI package.
+from . import colors, coord_mapper, fonts, layout  # Import modules needed by others
+
+# Visualizer is NOT exported from here to avoid circular imports.
+# Import it directly: from trianglengin.ui.visualization.core.visualizer import Visualizer
+
+__all__ = [
+    # "Visualizer", # REMOVED
+    "layout",
+    "fonts",
+    "colors",
+    "coord_mapper",
+]

trianglengin/ui/visualization/core/colors.py

@@ -0,0 +1,115 @@
+"""
+Defines color constants and mappings used throughout the application,
+especially for visualization.
+"""
+
+# Define the Color type alias (RGB)
+Color = tuple[int, int, int]
+# Define RGBA type alias for clarity where alpha is used
+ColorRGBA = tuple[int, int, int, int]
+
+# --- Standard Colors ---
+WHITE: Color = (255, 255, 255)
+BLACK: Color = (0, 0, 0)
+GRAY: Color = (128, 128, 128)
+LIGHT_GRAY: Color = (200, 200, 200)
+DARK_GRAY: Color = (50, 50, 50)
+RED: Color = (255, 0, 0)
+GREEN: Color = (0, 255, 0)
+BLUE: Color = (0, 0, 255)
+YELLOW: Color = (255, 255, 0)
+CYAN: Color = (0, 255, 255)
+MAGENTA: Color = (255, 0, 255)
+ORANGE: Color = (255, 165, 0)
+PURPLE: Color = (128, 0, 128)
+TEAL: Color = (0, 128, 128)
+OLIVE: Color = (128, 128, 0)
+
+# --- Game Specific Colors ---
+# Colors used for the placeable shapes
+# These should align with the colors used/generated by the C++ core if specified there,
+# or be used to interpret the color_id returned by the C++ core.
+SHAPE_COLORS: tuple[Color, ...] = (
+    (220, 40, 40),  # 0: Red
+    (60, 60, 220),  # 1: Blue
+    (40, 200, 40),  # 2: Green
+    (230, 230, 40),  # 3: Yellow
+    (240, 150, 20),  # 4: Orange
+    (140, 40, 140),  # 5: Purple
+    (40, 200, 200),  # 6: Cyan
+    (200, 100, 180),  # 7: Pink
+    (100, 180, 200),  # 8: Light Blue
+)
+
+# Mapping from Color ID (returned by C++) to RGB tuple for visualization.
+ID_TO_COLOR_MAP: dict[int, Color] = dict(enumerate(SHAPE_COLORS))
+
+# Special Color IDs (ensure these match C++ constants)
+NO_COLOR_ID: int = -1
+DEBUG_COLOR_ID: int = -2
+
+# Grid background colors
+GRID_BG_LIGHT: Color = (40, 40, 40)
+GRID_BG_DARK: Color = (30, 30, 30)
+GRID_LINE_COLOR: Color = (80, 80, 80)
+DEATH_ZONE_COLOR: Color = (60, 0, 0)
+TRIANGLE_EMPTY_COLOR: Color = GRAY
+GRID_BG_DEFAULT: Color = DARK_GRAY
+GRID_BG_GAME_OVER: Color = (70, 30, 30)
+
+# UI Colors
+HUD_BG_COLOR: Color = (20, 20, 20)
+HUD_TEXT_COLOR: Color = WHITE
+PREVIEW_BG_COLOR: Color = (25, 25, 25)
+PREVIEW_BORDER: Color = GRAY
+PREVIEW_SELECTED_BORDER: Color = WHITE
+
+# Highlight Colors
+HIGHLIGHT_VALID_COLOR: Color = GREEN
+HIGHLIGHT_INVALID_COLOR: Color = RED
+PLACEMENT_VALID_COLOR: Color = GREEN
+PLACEMENT_INVALID_COLOR: Color = RED
+
+# Debug Colors
+DEBUG_TOGGLE_COLOR: Color = MAGENTA
+
+__all__ = [
+    "Color",
+    "ColorRGBA",
+    "WHITE",
+    "BLACK",
+    "GRAY",
+    "LIGHT_GRAY",
+    "DARK_GRAY",
+    "RED",
+    "GREEN",
+    "BLUE",
+    "YELLOW",
+    "CYAN",
+    "MAGENTA",
+    "ORANGE",
+    "PURPLE",
+    "TEAL",
+    "OLIVE",
+    "SHAPE_COLORS",  # Keep if needed elsewhere, but ID_TO_COLOR_MAP is primary
+    "ID_TO_COLOR_MAP",
+    "NO_COLOR_ID",
+    "DEBUG_COLOR_ID",
+    "GRID_BG_LIGHT",
+    "GRID_BG_DARK",
+    "GRID_LINE_COLOR",
+    "DEATH_ZONE_COLOR",
+    "TRIANGLE_EMPTY_COLOR",
+    "GRID_BG_DEFAULT",
+    "GRID_BG_GAME_OVER",
+    "HUD_BG_COLOR",
+    "HUD_TEXT_COLOR",
+    "PREVIEW_BG_COLOR",
+    "PREVIEW_BORDER",
+    "PREVIEW_SELECTED_BORDER",
+    "HIGHLIGHT_VALID_COLOR",
+    "HIGHLIGHT_INVALID_COLOR",
+    "PLACEMENT_VALID_COLOR",
+    "PLACEMENT_INVALID_COLOR",
+    "DEBUG_TOGGLE_COLOR",
+]

trianglengin/ui/visualization/core/coord_mapper.py

@@ -0,0 +1,85 @@
+# Guard UI imports
+try:
+    import pygame
+except ImportError as e:
+    raise ImportError(
+        "UI components require 'pygame'. Install with 'pip install trianglengin[ui]'."
+    ) from e
+
+# Use absolute imports for core components
+from trianglengin.config import EnvConfig
+from trianglengin.utils import geometry
+
+# Correct the import path for the drawing utility (relative within UI)
+from ..drawing.utils import get_triangle_points
+
+
+def _calculate_render_params(
+    width: int, height: int, config: EnvConfig
+) -> tuple[float, float, float, float]:
+    """Calculates scale (cw, ch) and offset (ox, oy) for rendering the grid."""
+    rows, cols = config.ROWS, config.COLS
+    cols_eff = cols * 0.75 + 0.25 if cols > 0 else 1
+    scale_w = width / cols_eff if cols_eff > 0 else 1
+    scale_h = height / rows if rows > 0 else 1
+    scale = max(1.0, min(scale_w, scale_h))
+    cell_size = scale
+    grid_w_px = cols_eff * cell_size
+    grid_h_px = rows * cell_size
+    offset_x = (width - grid_w_px) / 2
+    offset_y = (height - grid_h_px) / 2
+    return cell_size, cell_size, offset_x, offset_y
+
+
+def get_grid_coords_from_screen(
+    screen_pos: tuple[int, int], grid_area_rect: pygame.Rect, config: EnvConfig
+) -> tuple[int, int] | None:
+    """Maps screen coordinates (relative to screen) to grid row/column."""
+    if not grid_area_rect or not grid_area_rect.collidepoint(screen_pos):
+        return None
+
+    local_x = screen_pos[0] - grid_area_rect.left
+    local_y = screen_pos[1] - grid_area_rect.top
+    cw, ch, ox, oy = _calculate_render_params(
+        grid_area_rect.width, grid_area_rect.height, config
+    )
+    if cw <= 0 or ch <= 0:
+        return None
+
+    # Estimate row/col based on overall position
+    row = int((local_y - oy) / ch) if ch > 0 else -1
+    # Approximate column based on horizontal position, accounting for 0.75 width factor
+    approx_col_center_index = (local_x - ox - cw / 4) / (cw * 0.75) if cw > 0 else -1
+    col = int(round(approx_col_center_index))
+
+    # Check the estimated cell and its immediate neighbors using point-in-polygon
+    # This is more accurate near triangle boundaries
+    for r_check in [row, row - 1, row + 1]:
+        if not (0 <= r_check < config.ROWS):
+            continue
+        # Check a slightly wider range of columns due to triangular nature
+        for c_check in [col - 1, col, col + 1, col + 2]:
+            if not (0 <= c_check < config.COLS):
+                continue
+            is_up = (r_check + c_check) % 2 != 0
+            pts = get_triangle_points(r_check, c_check, is_up, ox, oy, cw, ch)
+            # Use the geometry utility function
+            if geometry.is_point_in_polygon((local_x, local_y), pts):
+                return r_check, c_check
+
+    # Fallback if point-in-polygon check fails (should be rare)
+    if 0 <= row < config.ROWS and 0 <= col < config.COLS:
+        return row, col
+    return None
+
+
+def get_preview_index_from_screen(
+    screen_pos: tuple[int, int], preview_rects: dict[int, pygame.Rect]
+) -> int | None:
+    """Maps screen coordinates to a shape preview index."""
+    if not preview_rects:
+        return None
+    for idx, rect in preview_rects.items():
+        if rect and rect.collidepoint(screen_pos):
+            return idx
+    return None

trianglengin/ui/visualization/core/fonts.py

@@ -0,0 +1,65 @@
+import logging
+
+# Guard UI imports
+try:
+    import pygame
+
+    pygame.font.init()  # Initialize font module here
+except ImportError as e:
+    raise ImportError(
+        "UI components require 'pygame'. Install with 'pip install trianglengin[ui]'."
+    ) from e
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_FONT_NAME = None
+FALLBACK_FONT_NAME = "arial,freesans"
+
+
+def load_single_font(name: str | None, size: int) -> pygame.font.Font | None:
+    """Loads a single font, handling potential errors."""
+    try:
+        font = pygame.font.SysFont(name, size)
+        return font
+    except Exception as e:
+        logger.error(f"Error loading font '{name}' size {size}: {e}")
+        if name != FALLBACK_FONT_NAME:
+            logger.warning(f"Attempting fallback font: {FALLBACK_FONT_NAME}")
+            try:
+                font = pygame.font.SysFont(FALLBACK_FONT_NAME, size)
+                logger.info(f"Loaded fallback font: {FALLBACK_FONT_NAME} size {size}")
+                return font
+            except Exception as e_fallback:
+                logger.error(f"Fallback font failed: {e_fallback}")
+                return None
+        return None
+
+
+def load_fonts(
+    font_sizes: dict[str, int] | None = None,
+) -> dict[str, pygame.font.Font | None]:
+    """Loads standard game fonts."""
+    if font_sizes is None:
+        font_sizes = {
+            "ui": 24,
+            "score": 30,
+            "help": 18,
+            "title": 48,
+            # Add debug font size if needed, though DisplayConfig handles the object
+            "debug": 12,
+        }
+
+    fonts: dict[str, pygame.font.Font | None] = {}
+    required_fonts = ["score", "help"]
+
+    logger.info("Loading fonts...")
+    for name, size in font_sizes.items():
+        fonts[name] = load_single_font(DEFAULT_FONT_NAME, size)
+
+    for name in required_fonts:
+        if fonts.get(name) is None:
+            logger.critical(
+                f"Essential font '{name}' failed to load. Text rendering will be affected."
+            )
+
+    return fonts

trianglengin/ui/visualization/core/layout.py

@@ -0,0 +1,77 @@
+"""
+Functions to calculate the layout of UI elements based on screen size and config.
+"""
+
+import logging
+
+import pygame  # Required dependency
+
+# Use absolute imports
+from trianglengin.ui.config import DisplayConfig
+
+logger = logging.getLogger(__name__)
+
+
+def calculate_interactive_layout(
+    screen_width: int, screen_height: int, config: DisplayConfig
+) -> dict[str, pygame.Rect]:
+    """
+    Calculates layout rectangles for interactive modes (play/debug).
+
+    Args:
+        screen_width: Current width of the screen/window.
+        screen_height: Current height of the screen/window.
+        config: The DisplayConfig object.
+
+    Returns:
+        A dictionary mapping area names ('grid', 'preview') to pygame.Rect objects.
+    """
+    pad = config.PADDING
+    hud_h = config.HUD_HEIGHT
+    preview_w = config.PREVIEW_AREA_WIDTH
+
+    # Available height after accounting for top/bottom padding and HUD
+    available_h = screen_height - 2 * pad - hud_h
+    # Available width after accounting for left/right padding and preview area
+    available_w = screen_width - 3 * pad - preview_w
+
+    if available_w <= 0 or available_h <= 0:
+        logger.warning(
+            f"Screen size ({screen_width}x{screen_height}) too small for layout."
+        )
+        # Return minimal valid rects to avoid errors downstream
+        return {
+            "grid": pygame.Rect(pad, pad, 1, 1),
+            "preview": pygame.Rect(screen_width - pad - preview_w, pad, 1, 1),
+        }
+
+    # Grid area takes up the main left space
+    grid_rect = pygame.Rect(pad, pad, available_w, available_h)
+
+    # Preview area is on the right
+    preview_rect = pygame.Rect(grid_rect.right + pad, pad, preview_w, available_h)
+
+    # HUD area (optional, could be drawn directly without a rect)
+    # hud_rect = pygame.Rect(pad, grid_rect.bottom + pad, screen_width - 2 * pad, hud_h)
+
+    return {"grid": grid_rect, "preview": preview_rect}
+
+
+def calculate_training_layout(
+    screen_width: int, screen_height: int, config: DisplayConfig
+) -> dict[str, pygame.Rect]:
+    """
+    Calculates layout rectangles for training/headless visualization (if needed).
+    Currently simple, just uses the whole screen for the grid.
+
+    Args:
+        screen_width: Current width of the screen/window.
+        screen_height: Current height of the screen/window.
+        config: The DisplayConfig object.
+
+    Returns:
+        A dictionary mapping area names ('grid') to pygame.Rect objects.
+    """
+    pad = config.PADDING
+    grid_rect = pygame.Rect(pad, pad, screen_width - 2 * pad, screen_height - 2 * pad)
+    return {"grid": grid_rect}