Card Timing & State Management Implementation

[Devsol-01]

Add Card Timing and State Management to RoundPlayer

🎯 Overview

This PR implements the required card timing and state management functionality for the RoundPlayer model, enabling proper card progression, timeout detection, and state tracking in the lyrics guessing game.

📋 Changes Made

Enhanced RoundPlayer Model

• Added 4 new timing functions to RoundPlayerTrait in src/models/round/round_player.cairo
• Enhanced validation system with new RoundPlayerValidation enum
• Maintained backward compatibility with existing functionality

New Functions Implemented

1. start_next_card() - Validates player state and starts next card with proper state transitions
2. is_answering_card() - Simple boolean check for active card state
3. current_card_timed_out() - Robust timeout detection with edge case handling
4. get_time_remaining() - Accurate time calculation for UI countdown functionality

Validation & Error Handling

• New RoundPlayerValidation enum with specific error types:
  • PlayerNotReady - Player must be in ready state to start cards
  • RoundCompleted - Cannot start cards in completed rounds
  • CardAlreadyActive - Only one card can be active at a time
  • NoActiveCard - For operations requiring an active card
• Preserved existing RoundPlayerValidationResult struct for backward compatibility

🧪 Testing

Comprehensive Test Coverage

• 19 new test cases added for the timing functions
• All 234 tests passing with 100% success rate
• Edge cases covered: Zero timeout, time before start, exact boundaries
• Gas usage optimized - Efficient test execution

Key Test Scenarios

• ✅ Card starting validation (ready state, round completion, active card checks)
• ✅ Timeout detection accuracy including zero timeout handling
• ✅ Time remaining calculations with boundary conditions
• ✅ State transitions and card index incrementation
• ✅ All validation error cases properly handled

🔧 Business Logic

Card Start Rules

• Player must be in ready_state = true
• Round must not be completed (round_completed = false)
• No card can be currently active (current_card_start_time = 0)
• Card index increments with each new card (next_card_index += 1)

Timing Logic

• Card timing starts when start_next_card() is called
• Timeout detection: elapsed_time >= card_timeout
• Time remaining: max(0, card_timeout - elapsed_time)
• Active card indicated by current_card_start_time > 0

State Management

• Card progression tracked via next_card_index
• Start time of 0 indicates no active card
• Time-based timeout detection (not automatic)
• Read-only state queries for efficient UI updates

🎮 Integration

The implementation integrates seamlessly with the existing modular architecture:

• Extends existing RoundPlayerTrait without breaking changes
• Compatible with current game systems and UI requirements
• Ready for immediate use in card progression logic
• Supports real-time UI updates with countdown timers

📊 Performance

• Efficient gas usage - Optimized Cairo code with minimal overhead
• Fast state queries - Simple boolean and arithmetic operations
• Minimal state changes - Only updates necessary fields during transitions

🔍 Code Quality

• Comprehensive documentation - All functions have detailed comments
• Robust edge case handling - Graceful handling of time anomalies
• Strong typing - Uses Result types for proper error handling
• Follows Cairo best practices - Consistent with existing codebase patterns

✅ Acceptance Criteria Met

• All 4 card timing methods implemented correctly
• Card starting validation working properly
• Timeout detection accurate and reliable
• Time remaining calculations correct
• State queries perform efficiently
• Comprehensive error handling
• Complete test coverage (19 new tests)
• All timing edge cases handled
• Documentation comments added

---

closes #135

[manlikeHB]

Thank you! LGTM!