trianglengin 1.0.6__py3-none-any.whl

trianglengin/core/structs/triangle.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+
+class Triangle:
+    """Represents a single triangular cell on the grid."""
+
+    def __init__(self, row: int, col: int, is_up: bool, is_death: bool = False):
+        self.row = row
+        self.col = col
+        self.is_up = is_up
+        self.is_death = is_death
+        self.is_occupied = is_death
+        self.color: tuple[int, int, int] | None = None
+
+        self.neighbor_left: Triangle | None = None
+        self.neighbor_right: Triangle | None = None
+        self.neighbor_vert: Triangle | None = None
+
+    def get_points(
+        self, ox: float, oy: float, cw: float, ch: float
+    ) -> list[tuple[float, float]]:
+        """Calculates vertex points for drawing, relative to origin (ox, oy)."""
+        x = ox + self.col * (cw * 0.75)
+        y = oy + self.row * ch
+        if self.is_up:
+            return [(x, y + ch), (x + cw, y + ch), (x + cw / 2, y)]
+        else:
+            return [(x, y), (x + cw, y), (x + cw / 2, y + ch)]
+
+    def copy(self) -> Triangle:
+        """Creates a copy of the Triangle object's state (neighbors are not copied)."""
+        new_tri = Triangle(self.row, self.col, self.is_up, self.is_death)
+        new_tri.is_occupied = self.is_occupied
+        new_tri.color = self.color
+        return new_tri
+
+    def __repr__(self) -> str:
+        state = "D" if self.is_death else ("O" if self.is_occupied else ".")
+        orient = "^" if self.is_up else "v"
+        return f"T({self.row},{self.col} {orient}{state})"
+
+    def __hash__(self):
+        return hash((self.row, self.col))
+
+    def __eq__(self, other):
+        if not isinstance(other, Triangle):
+            return NotImplemented
+        return self.row == other.row and self.col == other.col

trianglengin/interaction/README.md

@@ -0,0 +1,45 @@
+
+# Interaction Module (`trianglengin.interaction`)
+
+## Purpose and Architecture
+
+This module handles user input (keyboard and mouse) for the interactive modes ("play", "debug") of the `trianglengin` library. It bridges the gap between raw Pygame events and actions within the game simulation (`GameState`).
+
+-   **Event Processing:** [`event_processor.py`](event_processor.py) handles common Pygame events like quitting (QUIT, ESC) and window resizing. It acts as a generator, yielding other events for mode-specific processing.
+-   **Input Handler:** The [`InputHandler`](input_handler.py) class is the main entry point.
+    -   It receives Pygame events (via the `event_processor`).
+    -   It **manages interaction-specific state** internally (e.g., `selected_shape_idx`, `hover_grid_coord`, `debug_highlight_coord`).
+    -   It determines the current interaction mode ("play" or "debug") and delegates event handling and hover updates to specific handler functions ([`play_mode_handler`](play_mode_handler.py), [`debug_mode_handler`](debug_mode_handler.py)).
+    -   It provides the necessary interaction state to the [`Visualizer`](../visualization/core/visualizer.py) for rendering feedback (hover previews, selection highlights).
+-   **Mode-Specific Handlers:** `play_mode_handler.py` and `debug_mode_handler.py` contain the logic specific to each mode, operating on the `InputHandler`'s state and the `GameState`.
+    -   `play`: Handles selecting shapes, checking placement validity, and triggering `GameState.step` on valid clicks. Updates hover state in the `InputHandler`.
+    -   `debug`: Handles toggling the state of individual triangles directly on the `GameState.grid_data`. Updates hover state in the `InputHandler`.
+-   **Decoupling:** It separates input handling logic from the core game simulation ([`core.environment`](../core/environment/README.md)) and rendering ([`visualization`](../visualization/README.md)), although it needs references to both to function.
+
+## Exposed Interfaces
+
+-   **Classes:**
+    -   `InputHandler`:
+        -   `__init__(game_state: GameState, visualizer: Visualizer, mode: str, env_config: EnvConfig)`
+        -   `handle_input() -> bool`: Processes events for one frame, returns `False` if quitting.
+        -   `get_render_interaction_state() -> dict`: Returns interaction state needed by `Visualizer.render`.
+-   **Functions:**
+    -   `process_pygame_events(visualizer: Visualizer) -> Generator[pygame.event.Event, Any, bool]`: Processes common events, yields others.
+    -   `handle_play_click(event: pygame.event.Event, handler: InputHandler)`: Handles clicks in play mode.
+    -   `update_play_hover(handler: InputHandler)`: Updates hover state in play mode.
+    -   `handle_debug_click(event: pygame.event.Event, handler: InputHandler)`: Handles clicks in debug mode.
+    -   `update_debug_hover(handler: InputHandler)`: Updates hover state in debug mode.
+
+## Dependencies
+
+-   **[`trianglengin.core`](../core/README.md)**:
+    -   `GameState`, `EnvConfig`, `GridLogic`, `ActionCodec`, `Shape`, `Triangle`, `DEBUG_COLOR_ID`, `NO_COLOR_ID`.
+-   **[`trianglengin.visualization`](../visualization/README.md)**:
+    -   `Visualizer`, `VisConfig`, `coord_mapper`.
+-   **`pygame`**:
+    -   Relies heavily on Pygame for event handling (`pygame.event`, `pygame.mouse`) and constants (`MOUSEBUTTONDOWN`, `KEYDOWN`, etc.).
+-   **Standard Libraries:** `typing`, `logging`.
+
+---
+
+**Note:** Please keep this README updated when adding new interaction modes, changing input handling logic, or modifying the interfaces between interaction, environment, and visualization. Accurate documentation is crucial for maintainability.

trianglengin/interaction/__init__.py

@@ -0,0 +1,17 @@
+"""
+Interaction handling module for interactive modes (play/debug).
+"""
+
+from .debug_mode_handler import handle_debug_click, update_debug_hover
+from .event_processor import process_pygame_events
+from .input_handler import InputHandler
+from .play_mode_handler import handle_play_click, update_play_hover
+
+__all__ = [
+    "InputHandler",
+    "process_pygame_events",
+    "handle_play_click",
+    "update_play_hover",
+    "handle_debug_click",
+    "update_debug_hover",
+]

trianglengin/interaction/debug_mode_handler.py

@@ -0,0 +1,96 @@
+import logging
+from typing import TYPE_CHECKING
+
+import pygame
+
+# Use internal imports
+from ..core import environment as tg_env
+from ..core import structs as tg_structs
+from ..visualization import core as vis_core
+
+if TYPE_CHECKING:
+    from .input_handler import InputHandler
+
+logger = logging.getLogger(__name__)
+
+
+def handle_debug_click(event: pygame.event.Event, handler: "InputHandler") -> None:
+    """Handles mouse clicks in debug mode (toggle triangle state using NumPy arrays)."""
+    if not (event.type == pygame.MOUSEBUTTONDOWN and event.button == 1):
+        return
+
+    game_state = handler.game_state
+    visualizer = handler.visualizer
+    mouse_pos = handler.mouse_pos
+
+    layout_rects = visualizer.ensure_layout()
+    grid_rect = layout_rects.get("grid")
+    if not grid_rect:
+        logger.error("Grid layout rectangle not available for debug click.")
+        return
+
+    grid_coords = vis_core.coord_mapper.get_grid_coords_from_screen(
+        mouse_pos, grid_rect, game_state.env_config
+    )
+    if not grid_coords:
+        return
+
+    r, c = grid_coords
+    if game_state.grid_data.valid(r, c):
+        # Check death zone first
+        if not game_state.grid_data._death_np[r, c]:
+            # Toggle occupancy state in NumPy array
+            current_occupied_state = game_state.grid_data._occupied_np[r, c]
+            new_occupied_state = not current_occupied_state
+            game_state.grid_data._occupied_np[r, c] = new_occupied_state
+
+            # Update color ID based on new state
+            new_color_id = (
+                tg_structs.DEBUG_COLOR_ID
+                if new_occupied_state
+                else tg_structs.NO_COLOR_ID
+            )
+            game_state.grid_data._color_id_np[r, c] = new_color_id
+
+            logger.debug(
+                f": Toggled triangle ({r},{c}) -> {'Occupied' if new_occupied_state else 'Empty'}"
+            )
+
+            # Check for line clears if the cell became occupied
+            if new_occupied_state:
+                # Pass the coordinate tuple in a set
+                lines_cleared, unique_tris_coords, _ = (
+                    tg_env.GridLogic.check_and_clear_lines(
+                        game_state.grid_data, newly_occupied_coords={(r, c)}
+                    )
+                )
+                if lines_cleared > 0:
+                    logger.debug(
+                        f"Cleared {lines_cleared} lines ({len(unique_tris_coords)} coords) after toggle."
+                    )
+        else:
+            logger.info(f"Clicked on death cell ({r},{c}). No action.")
+
+
+def update_debug_hover(handler: "InputHandler") -> None:
+    """Updates the debug highlight position within the InputHandler."""
+    handler.debug_highlight_coord = None  # Reset hover state
+
+    game_state = handler.game_state
+    visualizer = handler.visualizer
+    mouse_pos = handler.mouse_pos
+
+    layout_rects = visualizer.ensure_layout()
+    grid_rect = layout_rects.get("grid")
+    if not grid_rect or not grid_rect.collidepoint(mouse_pos):
+        return  # Not hovering over grid
+
+    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
+        # Highlight only valid, non-death cells
+        if game_state.grid_data.valid(r, c) and not game_state.grid_data.is_death(r, c):
+            handler.debug_highlight_coord = grid_coords

trianglengin/interaction/event_processor.py

@@ -0,0 +1,43 @@
+import logging
+from collections.abc import Generator
+from typing import TYPE_CHECKING, Any
+
+import pygame
+
+if TYPE_CHECKING:
+    # Use internal import
+    from ..visualization.core.visualizer import Visualizer
+
+logger = logging.getLogger(__name__)
+
+
+def process_pygame_events(
+    visualizer: "Visualizer",
+) -> Generator[pygame.event.Event, Any, bool]:
+    """
+    Processes basic Pygame events like QUIT, ESCAPE, VIDEORESIZE.
+    Yields other events for mode-specific handlers.
+    Returns False via StopIteration value if the application should quit, True otherwise.
+    """
+    should_quit = False
+    for event in pygame.event.get():
+        if event.type == pygame.QUIT:
+            logger.info("Received QUIT event.")
+            should_quit = True
+            break
+        if event.type == pygame.KEYDOWN and event.key == pygame.K_ESCAPE:
+            logger.info("Received ESCAPE key press.")
+            should_quit = True
+            break
+        if event.type == pygame.VIDEORESIZE:
+            try:
+                w, h = max(320, event.w), max(240, event.h)
+                visualizer.screen = pygame.display.set_mode((w, h), pygame.RESIZABLE)
+                visualizer.layout_rects = None
+                logger.info(f"Window resized to {w}x{h}")
+            except pygame.error as e:
+                logger.error(f"Error resizing window: {e}")
+            yield event
+        else:
+            yield event
+    return not should_quit

trianglengin/interaction/input_handler.py

@@ -0,0 +1,82 @@
+import logging
+
+import pygame
+
+# Use internal imports
+from ..config import EnvConfig
+from ..core import environment as tg_env
+from ..core import structs as tg_structs
+from ..visualization import Visualizer
+from . import debug_mode_handler, event_processor, play_mode_handler
+
+logger = logging.getLogger(__name__)
+
+
+class InputHandler:
+    """
+    Handles user input, manages interaction state (selection, hover),
+    and delegates actions to mode-specific handlers.
+    """
+
+    def __init__(
+        self,
+        game_state: tg_env.GameState,
+        visualizer: Visualizer,
+        mode: str,
+        env_config: EnvConfig,
+    ):
+        self.game_state = game_state
+        self.visualizer = visualizer
+        self.mode = mode
+        self.env_config = env_config
+
+        # Interaction state managed here
+        self.selected_shape_idx: int = -1
+        self.hover_grid_coord: tuple[int, int] | None = None
+        self.hover_is_valid: bool = False
+        self.hover_shape: tg_structs.Shape | None = None
+        self.debug_highlight_coord: tuple[int, int] | None = None
+        self.mouse_pos: tuple[int, int] = (0, 0)
+
+    def handle_input(self) -> bool:
+        """Processes Pygame events and updates state based on mode. Returns False to quit."""
+        self.mouse_pos = pygame.mouse.get_pos()
+
+        # Reset hover/highlight state each frame before processing events/updates
+        self.hover_grid_coord = None
+        self.hover_is_valid = False
+        self.hover_shape = None
+        self.debug_highlight_coord = None
+
+        running = True
+        event_generator = event_processor.process_pygame_events(self.visualizer)
+        try:
+            while True:
+                event = next(event_generator)
+                # Pass self to handlers so they can modify interaction state
+                if self.mode == "play":
+                    play_mode_handler.handle_play_click(event, self)
+                elif self.mode == "debug":
+                    debug_mode_handler.handle_debug_click(event, self)
+        except StopIteration as e:
+            running = e.value  # False if quit requested
+
+        # Update hover state after processing events
+        if running:
+            if self.mode == "play":
+                play_mode_handler.update_play_hover(self)
+            elif self.mode == "debug":
+                debug_mode_handler.update_debug_hover(self)
+
+        return running
+
+    def get_render_interaction_state(self) -> dict:
+        """Returns interaction state needed by Visualizer.render"""
+        return {
+            "selected_shape_idx": self.selected_shape_idx,
+            "hover_shape": self.hover_shape,
+            "hover_grid_coord": self.hover_grid_coord,
+            "hover_is_valid": self.hover_is_valid,
+            "hover_screen_pos": self.mouse_pos,  # Pass current mouse pos
+            "debug_highlight_coord": self.debug_highlight_coord,
+        }

trianglengin/interaction/play_mode_handler.py

@@ -0,0 +1,141 @@
+import logging
+from typing import TYPE_CHECKING
+
+import pygame
+
+# Use internal imports
+from ..core import environment as tg_env
+from ..core import structs as tg_structs
+from ..visualization import core as vis_core
+
+if TYPE_CHECKING:
+    from .input_handler import InputHandler
+
+logger = logging.getLogger(__name__)
+
+
+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 = 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")
+    # Get preview rects from visualizer cache
+    preview_rects = visualizer.preview_rects
+
+    # 1. Check for clicks on shape previews
+    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:
+            # Clicked selected shape again: deselect
+            handler.selected_shape_idx = -1
+            handler.hover_grid_coord = None  # Clear hover state on deselect
+            handler.hover_shape = None
+            logger.info("Deselected shape.")
+        elif (
+            0 <= preview_idx < len(game_state.shapes) and game_state.shapes[preview_idx]
+        ):
+            # Clicked a valid, available shape: select it
+            handler.selected_shape_idx = preview_idx
+            logger.info(f"Selected shape index: {preview_idx}")
+            # Immediately update hover based on current mouse pos after selection
+            update_play_hover(handler)  # Update hover state within handler
+        else:
+            # Clicked an empty or invalid slot
+            logger.info(f"Clicked empty/invalid preview slot: {preview_idx}")
+            # Deselect if clicking an empty slot while another is selected
+            if handler.selected_shape_idx != -1:
+                handler.selected_shape_idx = -1
+                handler.hover_grid_coord = None
+                handler.hover_shape = None
+        return  # Handled preview click
+
+    # 2. Check for clicks on the grid (if a shape is selected)
+    selected_idx = handler.selected_shape_idx
+    if selected_idx != -1 and grid_rect and grid_rect.collidepoint(mouse_pos):
+        # A shape is selected, and the click is within the grid area.
+        grid_coords = vis_core.coord_mapper.get_grid_coords_from_screen(
+            mouse_pos, grid_rect, game_state.env_config
+        )
+        # Use Shape from trianglengin
+        shape_to_place: tg_structs.Shape | None = game_state.shapes[selected_idx]
+
+        # Check if the placement is valid *at the clicked location*
+        if (
+            grid_coords
+            and shape_to_place
+            and tg_env.GridLogic.can_place(
+                game_state.grid_data, shape_to_place, grid_coords[0], grid_coords[1]
+            )
+        ):
+            # Valid placement click!
+            r, c = grid_coords
+            action = tg_env.encode_action(selected_idx, r, c, game_state.env_config)
+            # Execute the step using the game state's method
+            reward, done = game_state.step(action)  # Now returns (reward, done)
+            logger.info(
+                f"Placed shape {selected_idx} at {grid_coords}. R={reward:.1f}, Done={done}"
+            )
+            # Deselect shape after successful placement
+            handler.selected_shape_idx = -1
+            handler.hover_grid_coord = None  # Clear hover state
+            handler.hover_shape = None
+        else:
+            # Clicked grid, shape selected, but not a valid placement spot for the click
+            logger.info(f"Clicked grid at {grid_coords}, but placement invalid.")
+
+
+def update_play_hover(handler: "InputHandler") -> None:
+    """Updates the hover state within the InputHandler."""
+    # Reset hover state first
+    handler.hover_grid_coord = None
+    handler.hover_is_valid = False
+    handler.hover_shape = None
+
+    game_state = handler.game_state
+    visualizer = handler.visualizer
+    mouse_pos = handler.mouse_pos
+
+    if game_state.is_over() or handler.selected_shape_idx == -1:
+        return  # No hover if game over or no shape selected
+
+    layout_rects = visualizer.ensure_layout()
+    grid_rect = layout_rects.get("grid")
+    if not grid_rect or not grid_rect.collidepoint(mouse_pos):
+        return  # Not hovering over grid
+
+    shape_idx = handler.selected_shape_idx
+    if not (0 <= shape_idx < len(game_state.shapes)):
+        return
+    # Use Shape from trianglengin
+    shape: tg_structs.Shape | None = game_state.shapes[shape_idx]
+    if not shape:
+        return
+
+    # Get grid coordinates under mouse
+    grid_coords = vis_core.coord_mapper.get_grid_coords_from_screen(
+        mouse_pos, grid_rect, game_state.env_config
+    )
+
+    if grid_coords:
+        # Check if placement is valid at these coordinates
+        is_valid = tg_env.GridLogic.can_place(
+            game_state.grid_data, shape, grid_coords[0], grid_coords[1]
+        )
+        # Update handler's hover state
+        handler.hover_grid_coord = grid_coords
+        handler.hover_is_valid = is_valid
+        handler.hover_shape = shape  # Store the shape being hovered
+    else:
+        handler.hover_shape = shape  # Store shape for floating preview

trianglengin/utils/__init__.py

@@ -0,0 +1,9 @@
+"""
+General utilities for the Triangle Engine.
+"""
+
+# --- ADDED: Export geometry ---
+from . import geometry
+from .types import ActionType
+
+__all__ = ["ActionType", "geometry"]

trianglengin/utils/geometry.py

@@ -0,0 +1,73 @@
+def is_point_in_polygon(
+    point: tuple[float, float], polygon: list[tuple[float, float]]
+) -> bool:
+    """
+    Checks if a point is inside a polygon using the Winding Number algorithm.
+    Handles points on the boundary correctly.
+
+    Args:
+        point: Tuple (x, y) representing the point coordinates.
+        polygon: List of tuples [(x1, y1), (x2, y2), ...] representing polygon vertices in order.
+
+    Returns:
+        True if the point is inside or on the boundary of the polygon, False otherwise.
+    """
+    x, y = point
+    n = len(polygon)
+    if n < 3:  # Need at least 3 vertices for a polygon
+        return False
+
+    wn = 0  # the winding number counter
+    epsilon = 1e-9  # Tolerance for floating point comparisons
+
+    # loop through all edges of the polygon
+    for i in range(n):
+        p1 = polygon[i]
+        p2 = polygon[(i + 1) % n]  # Wrap around to the first vertex
+
+        # Check if point is on the vertex P1
+        if abs(p1[0] - x) < epsilon and abs(p1[1] - y) < epsilon:
+            return True
+
+        # Check if point is on the horizontal edge P1P2
+        if (
+            abs(p1[1] - p2[1]) < epsilon
+            and abs(p1[1] - y) < epsilon
+            and min(p1[0], p2[0]) - epsilon <= x <= max(p1[0], p2[0]) + epsilon
+        ):
+            return True
+
+        # Check if point is on the vertical edge P1P2
+        if (
+            abs(p1[0] - p2[0]) < epsilon
+            and abs(p1[0] - x) < epsilon
+            and min(p1[1], p2[1]) - epsilon <= y <= max(p1[1], p2[1]) + epsilon
+        ):
+            return True
+
+        # Check for intersection using winding number logic
+        # Check y range (inclusive min, exclusive max for upward crossing)
+        y_in_upward_range = p1[1] <= y + epsilon < p2[1] + epsilon
+        y_in_downward_range = p2[1] <= y + epsilon < p1[1] + epsilon
+
+        if y_in_upward_range or y_in_downward_range:
+            # Calculate orientation: > 0 for left turn (counter-clockwise), < 0 for right turn
+            orientation = (p2[0] - p1[0]) * (y - p1[1]) - (x - p1[0]) * (p2[1] - p1[1])
+
+            if (
+                y_in_upward_range and orientation > epsilon
+            ):  # Upward crossing, P left of edge
+                wn += 1
+            elif (
+                y_in_downward_range and orientation < -epsilon
+            ):  # Downward crossing, P right of edge
+                wn -= 1
+            elif (
+                abs(orientation) < epsilon
+                and min(p1[0], p2[0]) - epsilon <= x <= max(p1[0], p2[0]) + epsilon
+                and min(p1[1], p2[1]) - epsilon <= y <= max(p1[1], p2[1]) + epsilon
+            ):
+                return True  # Point is on the edge segment
+
+    # wn == 0 only when P is outside
+    return wn != 0

trianglengin/utils/types.py

@@ -0,0 +1,10 @@
+# File: trianglengin/trianglengin/utils/types.py
+# Placeholder for Phase 1
+"""
+Shared type definitions for the Triangle Engine.
+"""
+
+from typing import TypeAlias
+
+# Action representation (integer index)
+ActionType: TypeAlias = int

trianglengin/visualization/README.md

@@ -0,0 +1,44 @@
+# File: trianglengin/visualization/README.md
+
+# Visualization Module (`trianglengin.visualization`)
+
+## 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 directly by the `trianglengin` library.
+
+-   **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:** More advanced visualization components related to training (e.g., dashboards, plots, progress bars) would typically reside in a separate project that uses this engine.
+
+## Exposed Interfaces
+
+-   **Core Classes & Functions:**
+    -   `Visualizer`: Main renderer for interactive modes.
+    -   `calculate_interactive_layout`, `calculate_training_layout`: Calculates UI layout rectangles.
+    -   `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.visualization.drawing`)
+-   **Config:**
+    -   `DisplayConfig`: Configuration class (re-exported from `trianglengin.config`).
+    -   `EnvConfig`: Configuration class (re-exported from `trianglengin.config`).
+
+## Dependencies
+
+-   **`trianglengin.core`**: `GameState`, `EnvConfig`, `GridData`, `Shape`, `Triangle`.
+-   **`trianglengin.config`**: `DisplayConfig`.
+-   **`trianglengin.utils`**: `geometry` (Planned).
+-   **`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/visualization/__init__.py

@@ -0,0 +1,61 @@
+# trianglengin/visualization/__init__.py
+"""
+Visualization module for rendering the game state using Pygame.
+Provides components for interactive play/debug modes.
+"""
+
+# Import core components needed externally
+# Import DisplayConfig from the new location
+from ..config import DisplayConfig, EnvConfig
+from .core import colors
+from .core.coord_mapper import (
+    get_grid_coords_from_screen,
+    get_preview_index_from_screen,
+)
+from .core.fonts import load_fonts
+from .core.layout import (
+    calculate_interactive_layout,
+    calculate_training_layout,
+)
+from .core.visualizer import Visualizer
+
+# Import drawing functions that might be useful externally (optional)
+from .drawing.grid import (
+    draw_debug_grid_overlay,
+    draw_grid_background,
+    # draw_grid_indices, # Removed
+    draw_grid_state,  # Renamed
+)
+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
+
+__all__ = [
+    # Core Renderer & Layout
+    "Visualizer",
+    "calculate_interactive_layout",
+    "calculate_training_layout",
+    "load_fonts",
+    "colors",
+    "get_grid_coords_from_screen",
+    "get_preview_index_from_screen",
+    # Drawing Functions
+    "draw_grid_background",
+    "draw_grid_state",  # Export renamed
+    "draw_debug_grid_overlay",
+    # "draw_grid_indices", # Removed
+    "draw_shape",
+    "render_previews",
+    "draw_placement_preview",
+    "draw_floating_preview",
+    "render_hud",
+    "draw_debug_highlight",
+    # Config
+    "DisplayConfig",  # Export DisplayConfig
+    "EnvConfig",
+]