sunsetr v0.4.0 Release Notes

Major Features and Enhancements

Multi-Compositor Backend Support

sunsetr now supports multiple Wayland compositors!

• Universal Wayland Support: Full implementation of wlr-gamma-control-unstable-v1 protocol for all compatible Wayland compositors
• Automatic Backend Detection: Intelligently detects your compositor and uses the appropriate backend
• Zero Configuration Required: Works out-of-the-box on Hyprland, niri, Sway, river, Wayfire, and other Wayland compositors
• Backward Compatibility: Existing Hyprland configurations work unchanged

Enhanced Configuration System

• New backend Configuration Field:
  • backend = "auto" (default) - Automatically detects your compositor
  • backend = "hyprland" - Explicitly use Hyprland/hyprsunset backend
  • backend = "wayland" - Explicitly use Wayland protocols backend
• Dual Configuration Path Support:
  • New preferred location: ~/.config/sunsetr/sunsetr.toml
  • Legacy location: ~/.config/hypr/sunsetr.toml (still supported)
  • Automatic migration with user choice when both exist
• Smart Configuration Validation: Prevents incompatible backend/hyprsunset combinations

Code Architecture Improvements

• Modular Backend System: Clean separation between Hyprland and Wayland implementations
• Progressive Code Migration: Eliminated code duplication while preserving existing functionality
• Enhanced Error Handling: Better error messages with actionable guidance
• Improved Test Coverage: Comprehensive property-based testing for all backend scenarios

Technical Implementation Details

Backend Architecture

• Trait-Based Abstraction: ColorTemperatureBackend trait provides unified interface
• Zero-Regression Design: Existing Hyprland code moved with identical functionality
• Direct Protocol Communication: Wayland backend communicates directly with compositor protocols
• Multi-Output Support: Full support for multiple monitors on Wayland compositors

Environment Detection Logic

// Detection priority:
1. Explicit configuration (`backend` field)
2. WAYLAND_DISPLAY verification (required)
3. HYPRLAND_INSTANCE_SIGNATURE detection
4. Fallback to appropriate backend

Configuration Enhancements

• Backend-Specific Defaults: Automatically configures appropriate settings per backend
• Validation Logic: Comprehensive validation prevents configuration conflicts
• Migration Support: Seamless transition from legacy configuration locations

Breaking Changes

None! This release maintains 100% backward compatibility:

• Existing configurations work unchanged
• Same command-line interface
• Identical behavior on Hyprland systems
• No performance impact for existing users

New Configuration Options

Backend Selection

# Choose backend explicitly (optional - auto-detection works great!)
backend = "auto"        # Default: auto-detect compositor
backend = "hyprland"    # Force Hyprland backend
backend = "wayland"     # Force Wayland protocols backend

Configuration Path Updates

• New configs will be created at ~/.config/sunsetr/sunsetr.toml
• Existing configs at ~/.config/hypr/sunsetr.toml continue to work
• Interactive migration prompt when both locations have configs

Bug Fixes and Improvements

• Improved Error Messages: Clear, actionable error messages for configuration issues
• Better Environment Validation: Comprehensive checks for Wayland session requirements
• Enhanced Signal Handling: Improved graceful shutdown and cleanup
• Memory Safety: All implementations remain 100% safe Rust with no unsafe blocks

Comprehensive Testing

• Property-Based Testing: Comprehensive testing of all backend combinations
• Multi-Compositor Testing: Verified functionality across different Wayland compositors
• Configuration Validation Testing: All configuration scenarios thoroughly tested
• Zero-Regression Verification: Existing functionality confirmed identical through testing

Documentation Updates

• Updated README: Reflects new multi-compositor support
• Backend Architecture Documentation: Comprehensive technical documentation
• Configuration Guide: Updated with new backend options
• Migration Guide: Guidance for users transitioning configurations

Future Compatibility

This release lays the groundwork for future enhancements:

• Extensible Backend System: Easy to add support for new compositors
• Niri Support Preparation: Architecture ready for niri compositor support
• Additional Protocol Support: Foundation for supporting more Wayland protocols

For Hyprland Users

No changes needed! sunsetr will auto-detect Hyprland and work exactly as before.

For Other Wayland Compositor Users

1. Install sunsetr v0.4.0
2. Run sunsetr - it will auto-detect your compositor
3. Configuration will be created automatically at ~/.config/sunsetr/sunsetr.toml

Manual Backend Selection (Optional)

If you prefer explicit control:

backend = "wayland"     # For Sway, river, Wayfire, etc.
backend = "hyprland"    # For Hyprland only  
backend = "auto"        # Let sunsetr decide (recommended)

Performance and Reliability

• Zero Performance Impact: Same efficient code paths for existing users
• Robust Error Recovery: Enhanced error handling with graceful fallbacks
• Memory Efficient: Minimal memory overhead for backend abstraction
• Fast Startup: Quick backend detection and initialization

🙏 Acknowledgments

This release represents a significant architectural improvement that maintains simplicity and reliability while expanding compatibility. The modular design ensures sunsetr will continue to evolve with the Wayland ecosystem.

Special thanks to the wayland-protocols maintainers, the creator of wlsunset for sharing his color science with an MIT license, and the broader Rust community for making this multi-backend implementation possible.

Installation

From Source

git clone https://github.com/psi4j/sunsetr.git
cd sunsetr
cargo build --release
sudo cp target/release/sunsetr /usr/local/bin/

AUR (Arch Linux)

paru -S sunsetr-bin

Compatibility

• Hyprland >= 0.49.0 (via hyprsunset)
• Sway (via wlr-gamma-control-unstable-v1)
• river (via wlr-gamma-control-unstable-v1)
• Wayfire (via wlr-gamma-control-unstable-v1)
• Other wlr-based compositors with gamma control support

Full Changelog: v0.3.0...v0.4.0

Comprehensive Changes Since v0.2.1: Major Feature Expansion

Overview

This commit represents a massive expansion of sunsetr functionality since the initial separation of concerns in v0.2.1. The application has evolved from a basic day/night switcher to a sophisticated color temperature management system with smooth transitions, intelligent state management, and robust error handling.

Core Architecture Enhancements

🏗️ New Module Structure

• constants.rs - Centralized configuration defaults, validation limits, and operational constants
• startup_transition.rs - Smooth animated startup transitions with progress visualization
• process.rs - Complete hyprsunset process lifecycle management
• utils.rs - Interpolation, version comparison, and helper utilities
• Enhanced existing modules with significantly expanded functionality

🎯 Advanced State Management

• Transition States: Beyond simple day/night - now supports gradual transition states with progress tracking
• Startup Transitions: Configurable smooth animations from day values to current state on startup
• Sleep/Resume Detection: Handles system suspend/resume with automatic state recalculation
• Timing Consistency: Prevents state jumping during transition boundaries

Major Feature Additions

🌅 Sophisticated Transition System

• Dynamic Interpolation: Smooth temperature and gamma transitions between day/night values
• Configurable Durations: User-customizable transition timing (5-120 minutes)
• Multiple Transition Modes: "finish_by" mode ensures transitions complete at exact sunrise/sunset times
• Progress Tracking: Real-time transition progress with percentage completion
• Update Intervals: Configurable granularity for transition smoothness

🚀 Startup Transition System

• Animated Progress Bar: Visual feedback during startup transitions with live temp/gamma display
• Dynamic Target Tracking: Handles transitions that are ongoing when sunsetr starts
• Graceful Fallback: Falls back to immediate state application if startup transition fails
• Configurable Duration: 10-60 second startup transitions with 200ms update intervals

🔧 Process Management

• Automatic hyprsunset Startup: Can start and manage hyprsunset process lifecycle
• Conflict Detection: Prevents multiple hyprsunset instances with clear error messages
• Graceful Shutdown: Proper process termination and cleanup on exit
• Socket Validation: Verifies hyprsunset is responsive, not just that socket file exists

📊 Version Compatibility System

• Semantic Version Checking: Validates hyprsunset version compatibility
• Explicit Compatibility Lists: Maintains tested compatible versions
• Detailed Error Messages: Provides upgrade guidance for incompatible versions
• Graceful Degradation: Continues with functional testing if version parsing fails

🖥️ Enhanced User Interface

• Terminal Management: Hides cursor and suppresses control character echo for clean output
• Structured Logging: Hierarchical log formatting with pipes, blocks, and decoration
• Progress Visualization: Real-time progress bars with temperature/gamma display
• Context-Aware Messages: Different output styles for different types of operations

🔄 Robust Error Handling

• Connection Recovery: Automatic retry mechanisms for hyprsunset communication failures
• Lock File Management: Prevents multiple instances with proper cleanup
• Socket Resilience: Handles socket disappearance and reconnection scenarios
• Timeout Management: Prevents hanging on unresponsive hyprsunset connections

⚡ Performance & Reliability

• Intelligent Sleep Intervals: Dynamic sleep durations based on transition state
• Memory Efficient: Minimal resource usage during stable periods
• Signal Handling: Proper SIGINT/SIGTERM handling with cleanup
• Resource Cleanup: Automatic cleanup of processes, sockets, and lock files

Configuration System Overhaul

📝 Extended Configuration Options

# Basic timing (existing)
sunset = "19:00:00"
sunrise = "06:00:00"

# Color temperature control (enhanced)
night_temp = 3300      # Now defaults to 3300K (warmer)
day_temp = 6500        # New day temperature setting
night_gamma = 90.0     # Enhanced with better defaults
day_gamma = 100.0      # Existing

# Process management (new)
start_hyprsunset = true  # Now defaults to true

# Transition system (new)
transition_duration = 45              # minutes
update_interval = 60                  # seconds
transition_mode = "finish_by"         # timing mode

# Startup behavior (new)
startup_transition = true             # enable smooth startup
startup_transition_duration = 10      # seconds

🔍 Comprehensive Validation

• Range Validation: All numeric values validated against safe operational ranges
• Temperature Limits: 1000-20000K with clear error messages
• Gamma Limits: 0.0-100.0% with validation feedback
• Duration Limits: Prevents both too-fast and too-slow transitions
• Time Format Validation: Strict HH:MM:SS format enforcement

Advanced Functionality

🧮 Mathematical Interpolation System

• Linear Interpolation: Smooth transitions between temperature and gamma values
• Clamped Progress: Automatic bounds checking prevents invalid interpolation
• Type-Safe Operations: Separate u32/f32 interpolation functions with proper rounding
• Comprehensive Testing: Extensive test coverage for edge cases and extreme values

🕐 Intelligent Time Management

• Transition Detection: Automatically detects when transitions should start/stop
• Progress Calculation: Real-time progress tracking during ongoing transitions
• Event Scheduling: Calculates optimal sleep intervals until next state change
• Cross-Midnight Handling: Proper handling of transitions that cross midnight

🔌 Robust IPC Communication

• Socket Path Detection: Intelligent socket path resolution with HIS support
• Connection Management: Creates fresh connections per command with automatic cleanup
• Command Retry Logic: Fixed-delay retry attempts with error classification
• Error Recovery: Automatic reconnection attempts with configurable delays

🧪 Comprehensive Testing Framework

• Unit Tests: 54+ test functions covering critical functionality
• Property Tests: Mathematical validation of interpolation functions (with --features proptest)
• Integration Tests: End-to-end configuration and state management scenarios
• Error Case Testing: Comprehensive validation of error paths and edge cases

Technical Improvements

📚 Code Documentation

• Module Documentation: Comprehensive rustdoc for all modules
• Function Documentation: Detailed examples and parameter explanations
• Inline Comments: Extensive code comments explaining complex logic
• Architecture Docs: High-level documentation of system design

🔒 Type Safety & Memory Management

• Strong Typing: Leverages Rust's type system to prevent bugs
• RAII Patterns: Automatic resource cleanup via Drop implementations
• Atomic Operations: Thread-safe flag management for shutdown coordination
• Error Propagation: Comprehensive Result<> usage with context

🏃‍♂️ Performance Optimizations

• Lazy Evaluation: Only recalculates state when necessary
• Efficient Sleep: Uses appropriate sleep intervals to minimize CPU usage
• Fresh Connections: Creates new socket connections per command with immediate cleanup

Breaking Changes from v0.2.1

⚠️ Configuration Changes

• Default Values Updated: Some defaults changed for better user experience
• New Required Dependencies: Added regex crate for version parsing
• File Structure: Configuration validation is now more strict

🔄 API Changes

• Module Structure: Significant reorganization of internal APIs
• Function Signatures: Many internal functions have updated signatures
• Error Types: More specific error types with better context

Migration Notes

📦 Dependencies Added

regex = "1.0"           # For version string parsing
termios = "0.3"         # For terminal control

📋 Configuration Migration

Existing v0.2.1 configurations remain compatible, but users can benefit from:

• Setting start_hyprsunset = true for automatic hyprsunset management
• Adding day_temp = 6500 for full day/night temperature control
• Enabling startup_transition = true for smoother startup experience
• Configuring transition_duration = 45 for gradual day/night changes

Statistics

📊 Lines of Code Growth

• constants.rs: 97 lines (new) - Centralized configuration
• startup_transition.rs: 460 lines (new) - Startup animation system
• process.rs: 138 lines (new) - Process lifecycle management
• utils.rs: 296 lines (new) - Utility functions and interpolation
• Enhanced modules: Significant expansion of existing modules
• Total: ~5000+ lines of well-documented, tested code

🧪 Test Coverage

• Unit Tests: 54+ test functions covering critical functionality
• Property Tests: Mathematical validation of interpolation functions (with --features proptest)
• Integration Tests: End-to-end configuration and state management scenarios
• Error Case Testing: Comprehensive validation of error paths and edge cases

Future Compatibility

This release establishes a solid foundation for future enhancements:

• Plugin System Ready: Modular architecture supports future extensions
• Configuration Extensible: Easy t...

Updated the Systemd service and did some minor edits to the README.md. Smooth transitions coming later this week!

In this version, I've rewritten the controller to use the new IPC socket and added the new gamma functionality so you can also dim your screen automatically. I'll be creating an AUR package real soon and setting hyprsunset as a dependency once they update their AUR package version to v.0.2.0. In the meantime, you can build hyprsunset v.0.2.0 from source and build sunsetr v.0.2.0 from source to use the new implementation.