Function bodies 59 total

class RendererConfig:
    """Configuration for the Pygame renderer.

    Attributes:
        width: Window width in pixels. Must be > 0.
        height: Window height in pixels. Must be > 0.
        fps: Target frames per second. Must be > 0.
        title: Window title string.
    """

    width: int = 800
    height: int = 600
    fps: int = 60
    title: str = "Cross-Roads Traffic Simulation"

    def __post_init__(self) -> None:
        """Validate that dimensions and FPS are positive."""
        if self.width <= 0:
            raise ValueError(f"width must be > 0, got {self.width}")
        if self.height <= 0:
            raise ValueError(f"height must be > 0, got {self.height}")
        if self.fps <= 0:
            raise ValueError(f"fps must be > 0, got {self.fps}")

    def __post_init__(self) -> None:
        """Validate that dimensions and FPS are positive."""
        if self.width <= 0:
            raise ValueError(f"width must be > 0, got {self.width}")
        if self.height <= 0:
            raise ValueError(f"height must be > 0, got {self.height}")
        if self.fps <= 0:
            raise ValueError(f"fps must be > 0, got {self.fps}")

class Renderer:
    """Pygame visualization renderer for the traffic simulation.

    Displays the simulation state in a Pygame window. The renderer
    is a thin adapter that reads simulation state (read-only) and
    draws it each frame. It NEVER modifies simulation entity state.

    The only mutation performed is calling ``engine.update(elapsed)``
    to advance simulation time — this is the intended integration
    point per architecture data flow.

    Args:
        engine: The SimulationEngine to visualize. Stored as a
            read-only reference for querying state.
        config: Renderer configuration. Defaults to
            ``RendererConfig()`` if ``None``.
    """

    def __init__(
        self, engine: SimulationEngine, config: RendererConfig | None = None
    ) -> None:
        self._engine = engine
        self._config = config if config is not None else RendererConfig()
        pygame.init()
        self._surface = pygame.display.set_mode(
            (self._confi

    def __init__(
        self, engine: SimulationEngine, config: RendererConfig | None = None
    ) -> None:
        self._engine = engine
        self._config = config if config is not None else RendererConfig()
        pygame.init()
        self._surface = pygame.display.set_mode(
            (self._config.width, self._config.height)
        )
        pygame.display.set_caption(self._config.title)
        self._clock = pygame.time.Clock()
        logger.info(
            "Pygame window created (%dx%d at %d FPS)",
            self._config.width,
            self._config.height,
            self._config.fps,
        )

    def run(self) -> None:
        """Run the main rendering loop.

        Blocks until the user closes the window or presses ESC.
        Each iteration: handle events, update simulation, render
        frame, tick clock at target FPS.
        """
        try:
            running = True
            while running:
                elapsed = self._clock.tick(self._config.fps) / 1000.0
                running = self._handle_events()
                self._engine.update(elapsed)
                self._render()
        finally:
            self._cleanup()

    def _handle_events(self) -> bool:
        """Process Pygame events.

        Returns:
            False if the user requested quit (window close or ESC),
            True otherwise.
        """
        for event in pygame.event.get():
            if event.type == pygame.QUIT:
                return False
            if event.type == pygame.KEYDOWN:
                if event.key == pygame.K_ESCAPE:
                    return False
        return True

    def _render(self) -> None:
        """Render the current simulation frame.

        Fills the background, draws the road intersection,
        traffic lights, and flips the display buffer.
        """
        self._surface.fill(BACKGROUND_COLOR)
        # Draw road intersection cross shape at center
        cx = self._config.width // 2
        cy = self._config.height // 2
        road_w = 60
        pygame.draw.rect(
            self._surface, ROAD_COLOR,
            (cx - road_w // 2, 0, road_w, self._config.height),
        )
        pygame.draw.rect(
            self._surface, ROAD_COLOR,
            (0, cy - road_w // 2, self._config.width, road_w),
        )
        self._draw_traffic_lights()
        pygame.display.flip()

    def _draw_traffic_lights(self) -> None:
        """Draw traffic light indicators for all 4 directions.

        Reads traffic light phase from ``engine.intersection.lights``
        and draws a colored circle for each direction. Does nothing
        if the engine has no intersection assigned.
        """
        intersection = self._engine.intersection
        if intersection is None:
            return

        cx = self._config.width // 2
        cy = self._config.height // 2
        road_w = 60
        offset = road_w // 2 + 25

        positions: dict[str, tuple[int, int]] = {
            "North": (cx, cy - offset),
            "South": (cx, cy + offset),
            "East": (cx + offset, cy),
            "West": (cx - offset, cy),
        }

        for direction, light in intersection.lights.items():
            color = LIGHT_COLORS[light.phase.value]
            pos = positions.get(direction)
            if pos is not None:
                pygame.draw.circle(self._surface, c

    def _cleanup(self) -> None:
        """Clean up Pygame resources."""
        pygame.quit()
        logger.info("Renderer cleanup complete")