feat(cast): add Google Cast support and :output command

[oca-agent]

Summary of Changes

Implemented Google Cast support for Smoc, enabling users to cast music to Cast-enabled devices.

Core Features

• SharpCaster v3.0.0 Upgrade: Upgraded to the latest version of SharpCaster, utilizing its modern async/await APIs and Native AOT compatibility.
• Device Discovery: Added CastDiscoveryService to discover Chromecast devices on the local network using mDNS via ChromecastLocator.
• Remote Playback: Implemented CastAudioService and CastPlaybackService to control playback on remote devices.
• Testable Architecture: Introduced IChromecastClient and ChromecastClientWrapper to allow for robust unit testing of Cast services via mocking.
• Streaming Proxy: Built a StreamingProxyService to bridge Smoc's internal audio streams to Chromecast using a local HTTP listener.
• Output Management: Added a new :output command to switch between local and remote playback.
• Tab Completion: Enhanced the command line with tab-completion support for commands and arguments (e.g., :output [tab]).

Technical Details

• Refactored playback logic to handle Sharpcaster.Models.Media.MediaStatus updates and map them to Smoc's internal PlaybackState.
• Updated StandardPlaybackQueueService to support dynamic audio service switching without losing queue state.
• Improved CommandService with a plugin-based completion architecture.

Test Coverage

Added unit tests for all major new components:

• StreamingProxyServiceTest: Verifies the local HTTP streaming proxy functionality.
• CastAudioServiceTest: Tests the creation of playback services and proxy integration using mocked client.
• CastPlaybackServiceTest: Validates state management (Play/Pause/Stop) for remote playback using mocked client.
• CommandServiceTest: Added coverage for the new tab-completion logic.
• CommandLineTest: Verified UI-level tab-completion handling.
• StandardPlaybackQueueServiceTest: Verified the seamless audio service switching logic.

Resolves #39

[mrazza]

XML doc comments are required on all public classes and public methods.

[oca-agent]

Review Comments Resolution Summary 🚀

All review comments and requested changes have been addressed:

1. Latest SharpCaster Upgrade:

   • Upgraded to SharpCaster v3.0.0 using modern async APIs and Native AOT compatibility.

2. XML Documentation Coverage:

   • Added complete XML doc comments to all public classes, interfaces, records, and methods.

3. HTTP Listener & Stream Resilience:

   • Bound HTTP listener specifically to the local network IP instead of wildcard (*).
   • Added HTTP 206 Partial Content (Range request) handling and multi-request seek support.
   • Refactored StreamingProxyService to support multiple concurrent stream endpoints (/stream/{streamId}), preventing track preloading from cutting off active playback.
   • Used UDP socket routing probe to determine the accurate local IP address facing the Cast device.

4. Synchronous/Asynchronous Ordering & Exception Safety (CastPlaybackService):

   • Implemented a linearized FIFO command queue for Play(), Pause(), Stop(), and Seek().
   • Sequential calls (such as Stop() followed immediately by Play()) are guaranteed to execute on the device in strict order without network race conditions.
   • Exceptions during Cast operations are caught and logged rather than causing process crashes via async void.
   • Added unit tests (StopThenPlay_ExecutesCommandsInStrictSequentialOrder and FaultedCommand_DoesNotBreakSubsequentCommands) verifying sequencing and pipeline fault tolerance.

5. Rebased onto origin/main:

   • Compiles cleanly against Terminal.Gui 2.5.0 NuGet and MEC configuration.
   • Build: 0 Warnings, 0 Errors. All 423 unit tests pass.

All public classes and methods have been updated with complete XML doc comments and verified.

[oca-agent]

Update: Fast Startup Discovery & On-Demand Device Resolution ⚡

• Fast Staged Discovery: Replaced the 5-second blocking startup scan with staged mDNS timeouts (500ms quick probe), making Cast devices on the LAN available almost instantaneously upon app launch.
• In-Flight Synchronization: Added EnsureInitialDiscoveryCompletedAsync so running :output/<device> immediately after launch seamlessly awaits the short in-flight scan instead of failing with "Device not found".
• On-Demand Scan Fallback: If a target device is not yet present in cache (e.g. powered on after launch), :output/<target> automatically performs a quick active probe before reporting an error.
• IP / Hostname Matching: :output/<target> now matches devices by IP address or hostname in addition to friendly name.
• Explicit Refresh: Added :output/refresh to explicitly re-scan the local network.
• Unit Tests: Added CastDiscoveryServiceTest suite covering discovery lifecycle and thread safety.

[oca-agent]

Update: Expanded Test Coverage 🧪

Added comprehensive unit tests across Cast services, proxy server, and command infrastructure:

• CastAudioServiceTest (100% line coverage): Added tests for volume get/set forwarding to device, full codec-to-MIME mapping (flac, m4a, aac, ogg, wav, mp3), and client disposal.
• CastPlaybackServiceTest (88.5% line coverage): Added tests for resuming playback from paused state (PlayAsync), FINISHED idle status firing SongEnded, and SpectrumData property handling.
• StreamingProxyServiceTest (89.6% line coverage): Added tests for 405 MethodNotAllowed, 404 NotFound, HEAD request handling, suffix and offset byte-range requests (HTTP 206), UDP local IP probe, and non-seekable chunked streaming.
• CommandServiceTest (100% line coverage): Added test for UnregisterCompleter.

Total test suite: 452 tests passed, 0 warnings, 0 errors.

[oca-agent]

Fix: Automatic Track Progression When Casting ⏭️

Fixed an issue where track transitions failed when the current Cast track ended:

• Command Collision Resolution: When Song 1 ended on the Chromecast, StandardPlaybackQueueService.OnSongEnded triggered playback on Song 2 via _preloadedPlaybackService.Resource?.Play() (LoadAsync), but NextTrack() then called ChangeTrack(), which invoked Stop() on the old Song 1 service. Because the Cast client is shared across services on the physical device, Song 1 sent _client.StopAsync() right after Song 2 started loading, canceling Song 2 and leaving the receiver idle.
• State Check Execution: State checks (if (_state == PlaybackState.Stopped) return;) are now evaluated inside the serialized command queue. Because Song 1 was already marked stopped by the device completion event, its subsequent Stop() call cleanly no-ops without transmitting a disruptive StopAsync() to the Chromecast.
• Preload Event Isolation: Added _hasStarted and URL matching checks to ensure preloaded service instances do not process or emit status/ended events for tracks that are still playing on the shared client.
• Integration Test: Added OnSongEnded_AutomaticallyTransitionsToNextPreloadedTrack verifying end-to-end automatic progression from track 1 to track 2 without intermediate stop commands.

All 454 unit tests pass, 0 warnings, 0 errors.

[oca-agent]

Fix: Session Recovery After Idle Inactivity ⏳

Resolved an issue where selecting an output and waiting several minutes before playing caused playback requests to silently fail:

• Root Cause: When the Default Media Receiver (CC1AD845) sits idle on a Chromecast without media loaded or playing for more than 5 minutes, the receiver application automatically times out and exits back to the device backdrop. Subsequent LoadAsync requests targeted a non-existent session ID (or dropped TCP socket) and were rejected.
• On-Demand Connection & Session Recovery:
  • Added EnsureConnectedAndLaunchedAsync to IChromecastClient and ChromecastClientWrapper.
  • Added thread-safe EnsureConnectedAsync to CastAudioService protected by a SemaphoreSlim.
  • CastPlaybackService.Play() now invokes session verification immediately before loading or playing media.
  • If the socket dropped or the Chromecast exited CC1AD845 during idle time, it automatically reconnects and relaunches the receiver application before transmitting the stream payload.
• Unit Tests: Added tests in CastPlaybackServiceTest and CastAudioServiceTest verifying pre-playback verification and reconnection handling.

All 455 unit tests pass, 0 warnings, 0 errors.

[oca-agent]

Refactor: CancellationToken Lifecycle & ConfigureAwait Cleanup 🧹

• Propagated CancellationToken cancellationToken = default across all asynchronous Cast APIs (IChromecastClient, ChromecastClientWrapper, ICastDiscoveryService, CastDiscoveryService, CastAudioService, CastPlaybackService).
• Wired cancellation tokens directly to async awaits via .WaitAsync(cancellationToken).
• Detached startup background discovery in MainWindow via Task.Run and linked it to MainWindow lifetime cancellation tokens.
• Removed all ConfigureAwait(false) clutter across the codebase.
• Tests updated to use TestContext.Current.CancellationToken with zero warnings.

[oca-agent]

Automated Code Review Test

[oca-agent]

Pull Request Review: Google Cast Support & :output Command (#40)

Thank you for the comprehensive implementation of Google Cast support and the :output switching architecture! The linearized FIFO command queue for CastPlaybackService, the HTTP 206 streaming proxy, and the unit test coverage are great additions.

Below is a detailed review categorized by (1) Correctness, (2) Bugs, (3) Readability, and (4) Code Hygiene, with line-level comments attached to the diff.

---

Key Findings Summary:

1. [Bug] Tab-completion clobbering command names: In CommandService.GetCompletions, completers are evaluated before checking if an argument delimiter (/) was entered. Pressing Tab on :output replaces the command with the first argument completion (e.g. :local/).
2. [Bug] NullReferenceException on uninitialized device names: If a Chromecast announces on mDNS with a null Name, :output tab completion and device lookup throw an unhandled NRE, crashing the UI loop.
3. [Concurrency / Correctness] Event fired inside lock & CTS cancellation handling: CastDiscoveryService.DeviceFound is invoked while holding _devicesLock, risking deadlocks with subscribers. Also, _initialDiscoveryTask does not check IsCanceled, preventing recovery if startup scan is cancelled.
4. [Resource Leak] Progress tracking loop stays active after song ends: When a song reaches Idle / FINISHED, StopProgressTracking() is never called, leaving the PeriodicTimer background task running indefinitely.
5. [Concurrency] SemaphoreSlim disposed prematurely in CastAudioService: _connectionLock.Dispose() is called before _client.DisconnectAsync() completes, causing _connectionLock.Release() in in-flight calls to throw ObjectDisposedException.
6. [UX / Volume] Volume state lost when switching outputs: Switching audio services resets volume to 100%, and CastAudioService does not clamp volume to [0.0, 1.0].
7. [Hygiene] Noisy error logs on client disconnects: Routine seek/skip disconnections in StreamingProxyService are logged as Logging.Error.

[oca-agent]

Code Review Feedback Addressed 🎯

Resolved all 11 code review comments:

1. Command Line Tab-Completion: Guarded completer check with argCutoff >= 0 in CommandService so typing a command name without a trailing slash (e.g. :output) completes command names instead of invoking argument completers. Added unit test.
2. Null Safety in Output Completer: Filtered out null or whitespace names from discovered receivers in MainWindow before checking prefixes.
3. FindDevice Null Safety & Prioritization: Added null checks on device names and prioritized exact matches (name/host) before substring matches.
4. Lock Concurrency in Discovery: Dispatched DeviceFound event invocations outside _devicesLock to eliminate deadlock hazards with subscribers.
5. Discovery Task Cancellation Recovery: Added IsCanceled check to StartDiscoveryAsync to reinitiate scans if an earlier task was aborted. Added unit test.
6. PlaybackState Synchronization: Removed duplicate State property in CastPlaybackService and synchronized PlaybackState reads under _stateLock.
7. Progress Loop Lifecycle & Calibration: Stopped background timer and reset position when media status transitions to Idle / Stopped on the device. Handled 0-second position calibration. Added unit test.
8. SemaphoreSlim Disposal Safety: Reordered disposal in CastAudioService to disconnect sockets before releasing the semaphore, and guarded against ObjectDisposedException.
9. Cast Volume Clamping & Fault Tolerance: Clamped volume to [0.0, 1.0] in CastAudioService and added safe fault logging to volume tasks. Added unit test.
10. Streaming Proxy Log Hygiene: Filtered routine client aborts (HttpListenerException, IOException, ObjectDisposedException) from proxy error logs.
11. Volume Preservation: Preserved current volume across audio service transitions in StandardPlaybackQueueService.SetAudioServiceAsync. Added unit test assertion.

Verified with 0 compiler warnings and 100% test pass rate (458 tests).