trianglengin 1.0.6__py3-none-any.whl

trianglengin/visualization/core/README.md

@@ -0,0 +1,52 @@
+
+# Visualization Core Submodule (`trianglengin.visualization.core`)
+
+## Purpose and Architecture
+
+This submodule contains the central classes and foundational elements for the **interactive** visualization system within the `trianglengin` library. It orchestrates rendering for play/debug modes, manages layout and coordinate systems, and defines core visual properties like colors and fonts.
+
+**Note:** Training-specific visualization components (like dashboards, plots) would typically reside in a separate project using this engine.
+
+-   **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.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`: Renderer for interactive modes.
+        -   `__init__(...)`
+        -   `render(game_state: GameState, mode: str, **interaction_state)`: Renders based on game state and interaction hints.
+        -   `ensure_layout() -> Dict[str, pygame.Rect]`
+        -   `screen`: Public attribute (Pygame Surface).
+        -   `preview_rects`: Public attribute (cached preview area rects).
+-   **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`).
+
+## Dependencies
+
+-   **`trianglengin.core`**: `GameState`, `EnvConfig`, `GridData`, `Shape`, `Triangle`.
+-   **`trianglengin.config`**: `DisplayConfig`.
+-   **`trianglengin.utils`**: `geometry` (Planned).
+-   **[`trianglengin.visualization.drawing`](../drawing/README.md)**: 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. Accurate documentation is crucial for maintainability.

trianglengin/visualization/core/__init__.py

@@ -0,0 +1,12 @@
+"""Core visualization components: renderers, layout, fonts, colors, coordinate mapping."""
+
+from . import colors, coord_mapper, fonts, layout
+from .visualizer import Visualizer
+
+__all__ = [
+    "Visualizer",
+    "layout",
+    "fonts",
+    "colors",
+    "coord_mapper",
+]

trianglengin/visualization/core/colors.py

@@ -0,0 +1,117 @@
+# trianglengin/visualization/core/colors.py
+"""
+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 (ensure these match constants.py if needed)
+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 shape colors to integer IDs (0 to N-1)
+COLOR_TO_ID_MAP: dict[Color, int] = {color: i for i, color in enumerate(SHAPE_COLORS)}
+# Reverse mapping for convenience (e.g., visualization)
+ID_TO_COLOR_MAP: dict[int, Color] = dict(enumerate(SHAPE_COLORS))
+
+# Special Color IDs (ensure these match constants.py)
+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  # Color for empty grid cells
+GRID_BG_DEFAULT: Color = DARK_GRAY  # Default grid background
+GRID_BG_GAME_OVER: Color = (70, 30, 30)  # BG when game is over
+
+# UI Colors
+HUD_BG_COLOR: Color = (20, 20, 20)
+HUD_TEXT_COLOR: Color = WHITE
+PREVIEW_BG_COLOR: Color = (25, 25, 25)  # Added missing constant
+PREVIEW_BORDER: Color = GRAY
+PREVIEW_SELECTED_BORDER: Color = WHITE
+
+# Highlight Colors (RGB only, alpha handled separately in drawing)
+HIGHLIGHT_VALID_COLOR: Color = GREEN
+HIGHLIGHT_INVALID_COLOR: Color = RED
+PLACEMENT_VALID_COLOR: Color = GREEN  # Alias
+PLACEMENT_INVALID_COLOR: Color = RED  # Alias
+
+# 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",
+    "COLOR_TO_ID_MAP",
+    "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/visualization/core/coord_mapper.py

@@ -0,0 +1,73 @@
+import pygame
+
+# Use internal imports
+from ...config import EnvConfig
+from ...core.structs import Triangle
+from ...utils import geometry
+
+
+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
+
+    row = int((local_y - oy) / ch) if ch > 0 else -1
+    approx_col_center_index = (local_x - ox - cw / 4) / (cw * 0.75) if cw > 0 else -1
+    col = int(round(approx_col_center_index))
+
+    for r_check in [row, row - 1, row + 1]:
+        if not (0 <= r_check < config.ROWS):
+            continue
+        for c_check in [col, col - 1, col + 1]:
+            if not (0 <= c_check < config.COLS):
+                continue
+            # Use corrected orientation check
+            is_up = (r_check + c_check) % 2 != 0
+            temp_tri = Triangle(r_check, c_check, is_up)
+            pts = temp_tri.get_points(ox, oy, cw, ch)
+            # Use geometry from utils
+            if geometry.is_point_in_polygon((local_x, local_y), pts):
+                return r_check, c_check
+
+    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/visualization/core/fonts.py

@@ -0,0 +1,55 @@
+import logging
+
+import pygame
+
+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,
+        }
+
+    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/visualization/core/layout.py

@@ -0,0 +1,101 @@
+import logging
+
+import pygame
+
+# Import DisplayConfig from trianglengin
+from trianglengin.config import DisplayConfig
+
+logger = logging.getLogger(__name__)
+
+
+def calculate_interactive_layout(
+    screen_width: int, screen_height: int, display_config: DisplayConfig
+) -> dict[str, pygame.Rect]:
+    """
+    Calculates layout rectangles for interactive modes (play/debug).
+    Places grid on the left and preview on the right.
+    Uses DisplayConfig for padding and dimensions.
+    """
+    sw, sh = screen_width, screen_height
+    pad = display_config.PADDING
+    hud_h = display_config.HUD_HEIGHT
+    preview_w = display_config.PREVIEW_AREA_WIDTH
+
+    available_h = max(0, sh - hud_h - 2 * pad)
+    available_w = max(0, sw - 3 * pad)
+
+    grid_w = max(0, available_w - preview_w)
+    grid_h = available_h
+
+    grid_rect = pygame.Rect(pad, pad, grid_w, grid_h)
+    preview_rect = pygame.Rect(grid_rect.right + pad, pad, preview_w, grid_h)
+
+    screen_rect = pygame.Rect(0, 0, sw, sh)
+    grid_rect = grid_rect.clip(screen_rect)
+    preview_rect = preview_rect.clip(screen_rect)
+
+    logger.debug(
+        f"Interactive Layout calculated: Grid={grid_rect}, Preview={preview_rect}"
+    )
+
+    return {
+        "grid": grid_rect,
+        "preview": preview_rect,
+    }
+
+
+def calculate_training_layout(
+    screen_width: int,
+    screen_height: int,
+    display_config: DisplayConfig,
+    progress_bars_total_height: int,  # Height needed for progress bars
+) -> dict[str, pygame.Rect]:
+    """
+    Calculates layout rectangles for a potential training visualization mode.
+    MINIMAL SPACING. Worker grid top, progress bars bottom (above HUD), plots fill middle.
+    Uses DisplayConfig for padding and dimensions.
+    """
+    sw, sh = screen_width, screen_height
+    pad = 2  # Minimal padding
+    hud_h = display_config.HUD_HEIGHT
+
+    # --- Worker Grid Area (Top) ---
+    total_available_h_for_grid_plots_bars = max(0, sh - hud_h - 2 * pad)
+    top_area_h = min(
+        int(total_available_h_for_grid_plots_bars * 0.10), 80
+    )  # 10% or 80px max
+    top_area_w = sw - 2 * pad
+    worker_grid_rect = pygame.Rect(pad, pad, top_area_w, top_area_h)
+
+    # --- Progress Bar Area (Bottom, above HUD) ---
+    pb_area_y = sh - hud_h - pad - progress_bars_total_height
+    pb_area_w = sw - 2 * pad
+    progress_bar_area_rect = pygame.Rect(
+        pad, pb_area_y, pb_area_w, progress_bars_total_height
+    )
+
+    # --- Plot Area (Middle) ---
+    plot_area_y = worker_grid_rect.bottom + pad
+    plot_area_w = sw - 2 * pad
+    plot_area_h = max(0, progress_bar_area_rect.top - plot_area_y - pad)  # Fill space
+    plot_rect = pygame.Rect(pad, plot_area_y, plot_area_w, plot_area_h)
+
+    # Clip all rects to screen bounds
+    screen_rect = pygame.Rect(0, 0, sw, sh)
+    worker_grid_rect = worker_grid_rect.clip(screen_rect)
+    plot_rect = plot_rect.clip(screen_rect)
+    progress_bar_area_rect = progress_bar_area_rect.clip(screen_rect)
+
+    logger.debug(
+        f"Training Layout calculated: WorkerGrid={worker_grid_rect}, PlotRect={plot_rect}, ProgressBarArea={progress_bar_area_rect}"
+    )
+
+    return {
+        "worker_grid": worker_grid_rect,
+        "plots": plot_rect,
+        "progress_bar_area": progress_bar_area_rect,
+    }
+
+
+# Default export can remain if desired, or be removed if only specific layouts are used.
+calculate_layout = calculate_interactive_layout

trianglengin/visualization/core/visualizer.py

@@ -0,0 +1,232 @@
+# File: trianglengin/visualization/core/visualizer.py
+import logging
+
+import pygame
+
+# Use internal imports
+from trianglengin.config import DisplayConfig, EnvConfig
+from trianglengin.core.environment import GameState
+from trianglengin.core.structs import Shape
+
+# Import coord_mapper module itself
+from trianglengin.visualization.core import colors, coord_mapper, layout
+from trianglengin.visualization.drawing import grid as grid_drawing
+from trianglengin.visualization.drawing import highlight as highlight_drawing
+from trianglengin.visualization.drawing import hud as hud_drawing
+from trianglengin.visualization.drawing import previews as preview_drawing
+from trianglengin.visualization.drawing.previews import (
+    draw_floating_preview,
+    draw_placement_preview,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class Visualizer:
+    """
+    Orchestrates rendering of a single game state for interactive modes.
+    Receives interaction state (hover, selection) via render parameters.
+    """
+
+    def __init__(
+        self,
+        screen: pygame.Surface,
+        display_config: DisplayConfig,
+        env_config: EnvConfig,
+        fonts: dict[str, pygame.font.Font | None],
+    ):
+        self.screen = screen
+        self.display_config = display_config
+        self.env_config = env_config
+        self.fonts = fonts
+        self.layout_rects: dict[str, pygame.Rect] | None = None
+        self.preview_rects: dict[int, pygame.Rect] = {}
+        self._layout_calculated_for_size: tuple[int, int] = (0, 0)
+        self.ensure_layout()
+
+    def ensure_layout(self) -> dict[str, pygame.Rect]:
+        """Returns cached layout or calculates it if needed."""
+        current_w, current_h = self.screen.get_size()
+        current_size = (current_w, current_h)
+
+        if (
+            self.layout_rects is None
+            or self._layout_calculated_for_size != current_size
+        ):
+            # TODO: Align VisConfig/DisplayConfig usage in layout functions
+            # Assuming layout function can work with DisplayConfig directly or adapt
+            self.layout_rects = layout.calculate_interactive_layout(
+                current_w,
+                current_h,
+                self.display_config,  # type: ignore
+            )
+            self._layout_calculated_for_size = current_size
+            logger.info(
+                f"Recalculated interactive layout for size {current_size}: {self.layout_rects}"
+            )
+            self.preview_rects = {}
+
+        return self.layout_rects if self.layout_rects is not None else {}
+
+    def render(
+        self,
+        game_state: GameState,
+        mode: str,
+        selected_shape_idx: int = -1,
+        hover_shape: Shape | None = None,
+        hover_grid_coord: tuple[int, int] | None = None,
+        hover_is_valid: bool = False,
+        hover_screen_pos: tuple[int, int] | None = None,
+        debug_highlight_coord: tuple[int, int] | None = None,
+    ):
+        """Renders the entire game visualization for interactive modes."""
+        self.screen.fill(colors.GRID_BG_DEFAULT)
+        layout_rects = self.ensure_layout()
+        grid_rect = layout_rects.get("grid")
+        preview_rect = layout_rects.get("preview")
+
+        if grid_rect and grid_rect.width > 0 and grid_rect.height > 0:
+            try:
+                grid_surf = self.screen.subsurface(grid_rect)
+                # Calculate render params for the grid area
+                cw, ch, ox, oy = coord_mapper._calculate_render_params(
+                    grid_rect.width, grid_rect.height, self.env_config
+                )
+                self._render_grid_area(
+                    grid_surf,
+                    game_state,
+                    mode,
+                    grid_rect,
+                    hover_shape,
+                    hover_grid_coord,
+                    hover_is_valid,
+                    hover_screen_pos,
+                    debug_highlight_coord,
+                    cw,
+                    ch,
+                    ox,
+                    oy,  # Pass calculated params
+                )
+            except ValueError as e:
+                logger.error(f"Error creating grid subsurface ({grid_rect}): {e}")
+                pygame.draw.rect(self.screen, colors.RED, grid_rect, 1)
+
+        if preview_rect and preview_rect.width > 0 and preview_rect.height > 0:
+            try:
+                preview_surf = self.screen.subsurface(preview_rect)
+                self._render_preview_area(
+                    preview_surf, game_state, mode, preview_rect, selected_shape_idx
+                )
+            except ValueError as e:
+                logger.error(f"Error creating preview subsurface ({preview_rect}): {e}")
+                pygame.draw.rect(self.screen, colors.RED, preview_rect, 1)
+
+        hud_drawing.render_hud(
+            surface=self.screen,
+            mode=mode,
+            fonts=self.fonts,
+        )
+
+    def _render_grid_area(
+        self,
+        grid_surf: pygame.Surface,
+        game_state: GameState,
+        mode: str,
+        grid_rect: pygame.Rect,
+        hover_shape: Shape | None,
+        hover_grid_coord: tuple[int, int] | None,
+        hover_is_valid: bool,
+        hover_screen_pos: tuple[int, int] | None,
+        debug_highlight_coord: tuple[int, int] | None,
+        cw: float,
+        ch: float,
+        ox: float,
+        oy: float,  # Receive calculated params
+    ):
+        """Renders the main game grid and overlays onto the provided grid_surf."""
+        grid_drawing.draw_grid_background(
+            grid_surf,
+            self.env_config,
+            self.display_config,
+            cw,
+            ch,
+            ox,
+            oy,  # Pass params
+            game_state.is_over(),
+            mode == "debug",
+        )
+
+        grid_drawing.draw_grid_state(
+            grid_surf,
+            game_state.grid_data,
+            cw,
+            ch,
+            ox,
+            oy,  # Pass params
+        )
+
+        if mode == "play" and hover_shape:
+            if hover_grid_coord:
+                draw_placement_preview(
+                    grid_surf,
+                    hover_shape,
+                    hover_grid_coord[0],
+                    hover_grid_coord[1],
+                    is_valid=hover_is_valid,
+                    cw=cw,
+                    ch=ch,
+                    ox=ox,
+                    oy=oy,  # Pass params
+                )
+            elif hover_screen_pos:
+                local_hover_pos = (
+                    hover_screen_pos[0] - grid_rect.left,
+                    hover_screen_pos[1] - grid_rect.top,
+                )
+                if grid_surf.get_rect().collidepoint(local_hover_pos):
+                    draw_floating_preview(
+                        grid_surf,
+                        hover_shape,
+                        local_hover_pos,
+                        # config and mapper removed
+                    )
+
+        if mode == "debug" and debug_highlight_coord:
+            r, c = debug_highlight_coord
+            highlight_drawing.draw_debug_highlight(
+                grid_surf,
+                r,
+                c,
+                cw=cw,
+                ch=ch,
+                ox=ox,
+                oy=oy,  # Pass params
+            )
+
+        score_font = self.fonts.get("score")
+        if score_font:
+            score_text = f"Score: {game_state.game_score():.0f}"
+            score_surf = score_font.render(score_text, True, colors.YELLOW)
+            score_rect = score_surf.get_rect(topleft=(5, 5))
+            grid_surf.blit(score_surf, score_rect)
+
+    def _render_preview_area(
+        self,
+        preview_surf: pygame.Surface,
+        game_state: GameState,
+        mode: str,
+        preview_rect: pygame.Rect,
+        selected_shape_idx: int,
+    ):
+        """Renders the shape preview slots onto preview_surf and caches rects."""
+        current_preview_rects = preview_drawing.render_previews(
+            preview_surf,
+            game_state,
+            preview_rect.topleft,
+            mode,
+            self.env_config,
+            self.display_config,
+            selected_shape_idx=selected_shape_idx,
+        )
+        if not self.preview_rects or self.preview_rects != current_preview_rects:
+            self.preview_rects = current_preview_rects

trianglengin/visualization/drawing/README.md

@@ -0,0 +1,45 @@
+
+
+# Visualization Drawing Submodule (`trianglengin.visualization.drawing`)
+
+## Purpose and Architecture
+
+This submodule contains specialized functions responsible for drawing specific visual elements of the game onto Pygame surfaces for the **interactive modes** within the `trianglengin` library. These functions are typically called by the core renderer (`Visualizer`) in [`trianglengin.visualization.core`](../core/README.md).
+
+-   **[`grid.py`](grid.py):** Functions for drawing the grid background (`draw_grid_background`), the individual triangles within it colored based on occupancy/emptiness (`draw_grid_state`), and optional debug overlays (`draw_debug_grid_overlay`).
+-   **[`shapes.py`](shapes.py):** Contains `draw_shape`, a function to render a given `Shape` object at a specific location on a surface (used primarily for previews).
+-   **[`previews.py`](previews.py):** Handles rendering related to shape previews:
+    -   `render_previews`: Draws the dedicated preview area, including borders and the shapes within their slots, handling selection highlights.
+    -   `draw_placement_preview`: Draws a semi-transparent version of a shape snapped to the grid, indicating a potential placement location (used in play mode hover).
+    -   `draw_floating_preview`: Draws a semi-transparent shape directly under the mouse cursor when hovering over the grid but not snapped (used in play mode hover).
+-   **[`hud.py`](hud.py):** `render_hud` draws Heads-Up Display elements like help text onto the main screen surface (simplified for interactive modes).
+-   **[`highlight.py`](highlight.py):** `draw_debug_highlight` draws a distinct border around a specific triangle, used for visual feedback in debug mode.
+
+## Exposed Interfaces
+
+-   **Grid Drawing:**
+    -   `draw_grid_background(...)`
+    -   `draw_grid_state(...)`
+    -   `draw_debug_grid_overlay(...)`
+-   **Shape Drawing:**
+    -   `draw_shape(...)`
+-   **Preview Drawing:**
+    -   `render_previews(...) -> Dict[int, pygame.Rect]`
+    -   `draw_placement_preview(...)`
+    -   `draw_floating_preview(...)`
+-   **HUD Drawing:**
+    -   `render_hud(...)`
+-   **Highlight Drawing:**
+    -   `draw_debug_highlight(...)`
+
+## Dependencies
+
+-   **[`trianglengin.visualization.core`](../core/README.md)**: `colors`, `coord_mapper`.
+-   **`trianglengin.core`**: `EnvConfig`, `GameState`, `GridData`, `Shape`, `Triangle`.
+-   **`trianglengin.config`**: `DisplayConfig`.
+-   **`pygame`**: The core library used for all drawing operations.
+-   **Standard Libraries:** `typing`, `logging`, `math`.
+
+---
+
+**Note:** Please keep this README updated when adding new drawing functions, modifying existing ones, or changing their dependencies.