chore: Bump version to 1.3.9

Author: Ian-bug

core/configuration.py

@@ -1,29 +1,43 @@
 from dataclasses import dataclass, field
 from typing import Dict, List, Optional
 from PySide6.QtGui import QColor
+from PySide6.QtWidgets import QApplication
 from .logging_config import get_logger
 
 logger = get_logger(__name__)
 
+
+@dataclass
+class DisplayConstants:
+    """Display and layout constants for the overlay."""
+    LANE_START_X: int = 50
+    EXTRA_PADDING: int = 50
+    KEYVIEWER_OFFSET_Y_TOP: int = 50
+    KEYVIEWER_OFFSET_Y_BOTTOM: int = 50
+    FALLBACK_SCREEN_HEIGHT: int = 1080
+    FADE_START_Y: int = 800
+    FADE_RANGE: int = 200
+
 @dataclass
 class VisualSettings:
+    """Visual settings for bar appearance and behavior."""
     scroll_speed: int = 800
     lane_width: int = 70
     bar_width: int = 70
     bar_height: int = 20
     bar_color_str: str = "0,255,255,200"
     fall_direction: str = "up"
 
-    # Display constants
-    LANE_START_X: int = 50
-    EXTRA_PADDING: int = 50
-    KEYVIEWER_OFFSET_Y_TOP: int = 50
-    KEYVIEWER_OFFSET_Y_BOTTOM: int = 50
-    FALLBACK_SCREEN_HEIGHT: int = 1080
-
     @property
     def bar_color(self) -> QColor:
-        """Parse and validate color string, returning QColor."""
+        """Parse and validate color string, returning QColor.
+
+        Returns:
+            QColor object parsed from bar_color_str.
+
+        Raises:
+            ValueError: If color string format is invalid.
+        """
         try:
             parts = self.bar_color_str.split(',')
             if len(parts) != 4:
@@ -36,38 +50,62 @@ def bar_color(self) -> QColor:
 
             return QColor(r, g, b, a)
         except (ValueError, AttributeError) as e:
-            logger.warning(f"Invalid color string '{self.bar_color_str}': {e}. Using default.")
+            logger.error(f"Invalid color string '{self.bar_color_str}': {e}. Using default.")
             return QColor(0, 255, 255, 200)
 
 @dataclass
 class PositionSettings:
+    """Overlay window position settings."""
     x: int = 0
     y: int = 0
 
     def validate(self) -> bool:
-        """Validate position values are within reasonable bounds.
+        """Validate position values are within screen bounds.
+
+        Uses actual screen size when available, falls back to reasonable defaults.
 
         Returns:
             True if all values were valid, False if any were clamped.
         """
-        MIN_POS = -10000
-        MAX_POS = 10000
+        # Get screen bounds for validation
+        try:
+            screen = QApplication.primaryScreen()
+            if screen:
+                size = screen.size()
+                MIN_X = -size.width() // 2
+                MIN_Y = -size.height() // 2
+                MAX_X = size.width() * 2
+                MAX_Y = size.height() * 2
+            else:
+                # Fallback bounds for headless or error cases
+                MIN_X = -10000
+                MIN_Y = -10000
+                MAX_X = 10000
+                MAX_Y = 10000
+        except Exception:
+            # If screen detection fails, use safe defaults
+            MIN_X = -10000
+            MIN_Y = -10000
+            MAX_X = 10000
+            MAX_Y = 10000
+
         valid = True
 
-        if not (MIN_POS <= self.x <= MAX_POS):
-            logger.warning(f"X position {self.x} out of range, clamping to [{MIN_POS}, {MAX_POS}]")
-            self.x = max(MIN_POS, min(MAX_POS, self.x))
+        if not (MIN_X <= self.x <= MAX_X):
+            logger.warning(f"X position {self.x} out of range [{MIN_X}, {MAX_X}], clamping")
+            self.x = max(MIN_X, min(MAX_X, self.x))
             valid = False
 
-        if not (MIN_POS <= self.y <= MAX_POS):
-            logger.warning(f"Y position {self.y} out of range, clamping to [{MIN_POS}, {MAX_POS}]")
-            self.y = max(MIN_POS, min(MAX_POS, self.y))
+        if not (MIN_Y <= self.y <= MAX_Y):
+            logger.warning(f"Y position {self.y} out of range [{MIN_Y}, {MAX_Y}], clamping")
+            self.y = max(MIN_Y, min(MAX_Y, self.y))
             valid = False
 
         return valid
 
 @dataclass
 class KeyViewerSettings:
+    """KeyViewer panel display settings."""
     enabled: bool = True
     layout: str = "horizontal"
     panel_position: str = "below"
@@ -107,30 +145,69 @@ def validate(self) -> bool:
 
 @dataclass
 class AppConfig:
+    """Main application configuration container.
+
+    Attributes:
+        visual: Visual display settings
+        position: Window position settings
+        key_viewer: KeyViewer panel settings
+        lane_map: Mapping from key strings to lane indices
+        MAX_BARS: Maximum number of concurrent bars to render
+        INPUT_LATENCY_OFFSET: Timing offset for input latency compensation
+        DEBUG_MODE: Enable debug rendering and logging
+        VERSION: Application version string
+        CONFIG_VERSION: Config schema version for migrations
+        display: Display and layout constants
+    """
     visual: VisualSettings = field(default_factory=VisualSettings)
     position: PositionSettings = field(default_factory=PositionSettings)
     key_viewer: KeyViewerSettings = field(default_factory=KeyViewerSettings)
-    lane_map: Dict[str, int] = field(default_factory=dict)
-    
+    lane_map: Dict[str, int] = field(default_factory=lambda: {'d': 0, 'f': 1, 'j': 2, 'k': 3})
+
     # Constants
     MAX_BARS: int = 300
     INPUT_LATENCY_OFFSET: float = 0.0
-    FADE_START_Y: int = 800
-    FADE_RANGE: int = 200
     DEBUG_MODE: bool = False
-    VERSION: str = "1.3.7"
-    
-    def __post_init__(self):
-        if not self.lane_map:
-            self.lane_map = {'d': 0, 'f': 1, 'j': 2, 'k': 3}
+    VERSION: str = "1.3.9"
+    CONFIG_VERSION: int = 1  # Config schema version for migrations
+    display: DisplayConstants = field(default_factory=DisplayConstants)
 
     def set_lane_keys(self, keys: List[str]) -> None:
         """Set lane key mapping.
 
         Args:
             keys: List of key strings to map to lanes (by index).
+
+        Example:
+            set_lane_keys(['d', 'f', 'j', 'k']) maps 'd' to lane 0, 'f' to lane 1, etc.
         """
         new_map = {}
         for idx, key in enumerate(keys):
             new_map[key] = idx
         self.lane_map = new_map
+
+    def migrate_config(self, from_version: int) -> None:
+        """Migrate configuration from an older version.
+
+        Args:
+            from_version: The config version to migrate from.
+
+        Example:
+            migrate_config(0)  # Migrate from version 0 to current version
+        """
+        if from_version >= self.CONFIG_VERSION:
+            return  # Already at or past current version
+
+        # Migration from version 0 to 1
+        if from_version == 0:
+            # Add any new settings introduced in version 1
+            logger.info(f"Migrating config from version {from_version} to {self.CONFIG_VERSION}")
+            # No changes needed for v0->v1 migration
+
+        # Future migrations would go here
+        # Example:
+        # if from_version == 1:
+        #     # Migrate v1 to v2
+        #     pass
+
+        logger.info(f"Config migration complete, now at version {self.CONFIG_VERSION}")