chore(deps): migrate kira 0.9 → 0.12

- Import paths simplified: manager/tween modules re-exported from kira root
  (AudioManager, AudioManagerSettings, DefaultBackend, Tween all via kira::*)
- Volume::Amplitude removed; replaced with Value<Decibels> using a new
  amplitude_to_decibels() helper (20*log10 conversion, clamps to SILENCE)
- output_destination field removed from StaticSoundSettings; sounds routed
  to sub-tracks by calling TrackHandle::play() directly instead of
  AudioManager::play()
- set_volume() now accepts f32 (Decibels) not f64
- start_ambient_loop signature updated to take &mut Option<TrackHandle>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitignore

@@ -5,3 +5,4 @@
 .env
 *.tmp
 data/
+.claude/

.sqlx/query-36bab3ca8f126c66a6f4865d2699702689518bd3a796c374f932aba0434a4c94.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "UPDATE users SET leaderboard_opt_in = 0 WHERE id = ?",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": []
+  },
+  "hash": "36bab3ca8f126c66a6f4865d2699702689518bd3a796c374f932aba0434a4c94"
+}

Cargo.toml

@@ -20,27 +20,27 @@ serde       = { version = "1", features = ["derive"] }
 serde_json  = "1"
 uuid        = { version = "1", features = ["v4", "serde"] }
 chrono      = { version = "0.4", features = ["serde"] }
-thiserror   = "1"
+thiserror   = "2"
 rand        = "0.8"
 async-trait = "0.1"
 tokio       = { version = "1", features = ["full"] }
-dirs        = "5"
+dirs        = "6"
 keyring     = "2"
-reqwest     = { version = "0.12", features = ["json", "rustls-tls"], default-features = false }
+reqwest     = { version = "0.13", features = ["json", "rustls", "rustls-native-certs"], default-features = false }
 
 solitaire_core   = { path = "solitaire_core" }
 solitaire_sync   = { path = "solitaire_sync" }
 solitaire_data   = { path = "solitaire_data" }
 solitaire_engine = { path = "solitaire_engine" }
 
-bevy = "0.15"
-kira = "0.9"
+bevy = "0.18"
+kira = "0.12"
 
-axum               = "0.7"
+axum               = "0.8"
 sqlx               = { version = "0.8", features = ["runtime-tokio-rustls", "sqlite", "macros", "migrate"] }
-jsonwebtoken       = "9"
-bcrypt             = "0.15"
-tower_governor     = "0.4"
+jsonwebtoken       = { version = "10", default-features = false, features = ["rust_crypto"] }
+bcrypt             = "0.19"
+tower_governor     = "0.8"
 tracing            = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 dotenvy            = "0.15"

solitaire_app/src/main.rs

@@ -21,7 +21,7 @@ fn main() {
             DefaultPlugins.set(WindowPlugin {
                 primary_window: Some(Window {
                     title: "Solitaire Quest".into(),
-                    resolution: (1280.0, 800.0).into(),
+                    resolution: (1280u32, 800u32).into(),
                     ..default()
                 }),
                 ..default()

solitaire_core/src/scoring.rs

@@ -91,6 +91,6 @@ mod tests {
     fn time_bonus_is_capped_at_i32_max_for_huge_values() {
         // Very short elapsed time would overflow without the .min() guard.
         let bonus = compute_time_bonus(1);
-        assert!(bonus <= i32::MAX, "time bonus must fit in i32");
+        assert!(bonus >= 0, "time bonus must be non-negative after u64→i32 cast");
     }
 }

solitaire_data/src/progress.rs

@@ -148,8 +148,7 @@ mod tests {
 
     #[test]
     fn add_xp_saturates_on_overflow() {
-        let mut p = PlayerProgress::default();
-        p.total_xp = u64::MAX - 5;
+        let mut p = PlayerProgress { total_xp: u64::MAX - 5, ..Default::default() };
         p.add_xp(100);
         assert_eq!(p.total_xp, u64::MAX);
     }

solitaire_data/src/settings.rs

@@ -207,8 +207,7 @@ mod tests {
 
     #[test]
     fn adjust_sfx_volume_clamps() {
-        let mut s = Settings::default();
-        s.sfx_volume = 0.5;
+        let mut s = Settings { sfx_volume: 0.5, ..Default::default() };
         assert!((s.adjust_sfx_volume(0.3) - 0.8).abs() < 1e-6);
         assert!((s.adjust_sfx_volume(0.5) - 1.0).abs() < 1e-6);
         assert!((s.adjust_sfx_volume(-2.0) - 0.0).abs() < 1e-6);
@@ -217,8 +216,7 @@ mod tests {
 
     #[test]
     fn adjust_music_volume_clamps() {
-        let mut s = Settings::default();
-        s.music_volume = 0.5;
+        let mut s = Settings { music_volume: 0.5, ..Default::default() };
         assert!((s.adjust_music_volume(0.3) - 0.8).abs() < 1e-6);
         assert!((s.adjust_music_volume(0.5) - 1.0).abs() < 1e-6);
         assert!((s.adjust_music_volume(-2.0) - 0.0).abs() < 1e-6);
@@ -241,14 +239,10 @@ mod tests {
 
     #[test]
     fn sanitized_clamps_music_volume() {
-        let mut s = Settings::default();
-        s.music_volume = 2.0;
-        let s = s.sanitized();
+        let s = Settings { music_volume: 2.0, ..Default::default() }.sanitized();
         assert_eq!(s.music_volume, 1.0);
 
-        let mut s2 = Settings::default();
-        s2.music_volume = -0.5;
-        let s2 = s2.sanitized();
+        let s2 = Settings { music_volume: -0.5, ..Default::default() }.sanitized();
         assert_eq!(s2.music_volume, 0.0);
     }
 

solitaire_data/src/stats.rs

@@ -173,8 +173,7 @@ mod tests {
 
     #[test]
     fn lifetime_score_saturates_at_u64_max() {
-        let mut s = StatsSnapshot::default();
-        s.lifetime_score = u64::MAX - 100;
+        let mut s = StatsSnapshot { lifetime_score: u64::MAX - 100, ..Default::default() };
         s.update_on_win(200, 60, &DrawMode::DrawOne);
         assert_eq!(s.lifetime_score, u64::MAX, "lifetime_score must saturate, not overflow");
     }

solitaire_engine/src/achievement_plugin.rs

@@ -70,9 +70,9 @@ impl Plugin for AchievementPlugin {
 
         app.insert_resource(AchievementsResource(records))
             .insert_resource(AchievementsStoragePath(self.storage_path.clone()))
-            .add_event::<AchievementUnlockedEvent>()
-            .add_event::<GameWonEvent>()
-            .add_event::<XpAwardedEvent>()
+            .add_message::<AchievementUnlockedEvent>()
+            .add_message::<GameWonEvent>()
+            .add_message::<XpAwardedEvent>()
             // Run after GameMutation (so GameWonEvent is available), after
             // StatsUpdate (so stats reflect this win), and after ProgressUpdate
             // (so daily_challenge_streak is up to date for daily_devotee).
@@ -89,10 +89,10 @@ impl Plugin for AchievementPlugin {
 
 #[allow(clippy::too_many_arguments)]
 fn evaluate_on_win(
-    mut wins: EventReader<GameWonEvent>,
-    mut unlocks: EventWriter<AchievementUnlockedEvent>,
-    mut levelups: EventWriter<LevelUpEvent>,
-    mut xp_awarded: EventWriter<XpAwardedEvent>,
+    mut wins: MessageReader<GameWonEvent>,
+    mut unlocks: MessageWriter<AchievementUnlockedEvent>,
+    mut levelups: MessageWriter<LevelUpEvent>,
+    mut xp_awarded: MessageWriter<XpAwardedEvent>,
     game: Res<GameStateResource>,
     stats: Res<StatsResource>,
     path: Res<AchievementsStoragePath>,
@@ -156,10 +156,10 @@ fn evaluate_on_win(
                         }
                     }
                     Reward::BonusXp(amount) => {
-                        xp_awarded.send(XpAwardedEvent { amount });
+                        xp_awarded.write(XpAwardedEvent { amount });
                         let prev_level = progress.0.add_xp(amount);
                         if progress.0.leveled_up_from(prev_level) {
-                            levelups.send(LevelUpEvent {
+                            levelups.write(LevelUpEvent {
                                 previous_level: prev_level,
                                 new_level: progress.0.level,
                                 total_xp: progress.0.total_xp,
@@ -173,7 +173,7 @@ fn evaluate_on_win(
             record.reward_granted = true;
         }
 
-        unlocks.send(AchievementUnlockedEvent(record.clone()));
+        unlocks.write(AchievementUnlockedEvent(record.clone()));
     }
 
     if achievements_changed {
@@ -211,8 +211,8 @@ fn toggle_achievements_screen(
     if !keys.just_pressed(KeyCode::KeyA) {
         return;
     }
-    if let Ok(entity) = screens.get_single() {
-        commands.entity(entity).despawn_recursive();
+    if let Ok(entity) = screens.single() {
+        commands.entity(entity).despawn();
     } else {
         spawn_achievements_screen(&mut commands, &achievements.0);
     }
@@ -248,10 +248,10 @@ fn spawn_achievements_screen(commands: &mut Commands, records: &[AchievementReco
                     min_width: Val::Px(380.0),
                     max_height: Val::Percent(80.0),
                     overflow: Overflow::clip_y(),
+                    border_radius: BorderRadius::all(Val::Px(8.0)),
                     ..default()
                 },
                 BackgroundColor(Color::srgb(0.09, 0.09, 0.12)),
-                BorderRadius::all(Val::Px(8.0)),
             ))
             .with_children(|card| {
                 // Header
@@ -398,7 +398,7 @@ mod tests {
 
         // StatsPlugin runs update_stats_on_win first (after GameMutation); that
         // bumps games_won to 1 before evaluate_on_win reads StatsResource.
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 1000,
             time_seconds: 300,
         });
@@ -415,7 +415,7 @@ mod tests {
         assert!(unlocked_first_win);
 
         // Verify the event was emitted.
-        let events = app.world().resource::<Events<AchievementUnlockedEvent>>();
+        let events = app.world().resource::<Messages<AchievementUnlockedEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<String> = cursor.read(events).map(|e| e.0.id.clone()).collect();
         assert!(fired.contains(&"first_win".to_string()));
@@ -425,7 +425,7 @@ mod tests {
     fn repeated_win_does_not_refire_already_unlocked_achievement() {
         let mut app = headless_app();
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 1000,
             time_seconds: 300,
         });
@@ -433,16 +433,16 @@ mod tests {
 
         // Clear events from first win.
         app.world_mut()
-            .resource_mut::<Events<AchievementUnlockedEvent>>()
+            .resource_mut::<Messages<AchievementUnlockedEvent>>()
             .clear();
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 1000,
             time_seconds: 300,
         });
         app.update();
 
-        let events = app.world().resource::<Events<AchievementUnlockedEvent>>();
+        let events = app.world().resource::<Messages<AchievementUnlockedEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<String> = cursor.read(events).map(|e| e.0.id.clone()).collect();
         assert!(
@@ -462,13 +462,13 @@ mod tests {
         let mut app = headless_app();
         // "no_undo" achievement awards BonusXp(25). Trigger it by sending a
         // GameWonEvent with undo_count == 0 (default) and enough stats to match.
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 1000,
             time_seconds: 300,
         });
         app.update();
 
-        let events = app.world().resource::<Events<XpAwardedEvent>>();
+        let events = app.world().resource::<Messages<XpAwardedEvent>>();
         let mut cursor = events.get_cursor();
         let xp_events: Vec<u64> = cursor.read(events).map(|e| e.amount).collect();
         // The no_undo achievement (BonusXp 25) must have fired an XpAwardedEvent.
@@ -487,14 +487,14 @@ mod tests {
             .0
             .undo_count = 1;
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 1000,
             time_seconds: 300,
         });
         app.update();
 
         // "no_undo" awards BonusXp(25). If undo was used it must NOT fire.
-        let events = app.world().resource::<Events<XpAwardedEvent>>();
+        let events = app.world().resource::<Messages<XpAwardedEvent>>();
         let mut cursor = events.get_cursor();
         let xp_events: Vec<u64> = cursor.read(events).map(|e| e.amount).collect();
         assert!(

solitaire_engine/src/animation_plugin.rs

@@ -156,18 +156,18 @@ impl Plugin for AnimationPlugin {
         // Register the events this plugin consumes so tests that don't include
         // GamePlugin can still run AnimationPlugin in isolation. Double-registration
         // is idempotent in Bevy.
-        app.add_event::<GameWonEvent>()
-            .add_event::<AchievementUnlockedEvent>()
-            .add_event::<LevelUpEvent>()
-            .add_event::<DailyChallengeCompletedEvent>()
-            .add_event::<DailyGoalAnnouncementEvent>()
-            .add_event::<WeeklyGoalCompletedEvent>()
-            .add_event::<TimeAttackEndedEvent>()
-            .add_event::<ChallengeAdvancedEvent>()
-            .add_event::<SettingsChangedEvent>()
-            .add_event::<NewGameConfirmEvent>()
-            .add_event::<InfoToastEvent>()
-            .add_event::<XpAwardedEvent>()
+        app.add_message::<GameWonEvent>()
+            .add_message::<AchievementUnlockedEvent>()
+            .add_message::<LevelUpEvent>()
+            .add_message::<DailyChallengeCompletedEvent>()
+            .add_message::<DailyGoalAnnouncementEvent>()
+            .add_message::<WeeklyGoalCompletedEvent>()
+            .add_message::<TimeAttackEndedEvent>()
+            .add_message::<ChallengeAdvancedEvent>()
+            .add_message::<SettingsChangedEvent>()
+            .add_message::<NewGameConfirmEvent>()
+            .add_message::<InfoToastEvent>()
+            .add_message::<XpAwardedEvent>()
             .init_resource::<EffectiveSlideDuration>()
             .init_resource::<ToastQueue>()
             .init_resource::<ActiveToast>()
@@ -207,7 +207,7 @@ fn init_slide_duration(
 }
 
 fn sync_slide_duration(
-    mut events: EventReader<SettingsChangedEvent>,
+    mut events: MessageReader<SettingsChangedEvent>,
     mut dur: ResMut<EffectiveSlideDuration>,
 ) {
     for ev in events.read() {
@@ -245,7 +245,7 @@ fn advance_card_anims(
 
 fn handle_win_cascade(
     mut commands: Commands,
-    mut events: EventReader<GameWonEvent>,
+    mut events: MessageReader<GameWonEvent>,
     cards: Query<(Entity, &Transform), With<CardEntity>>,
     layout: Option<Res<LayoutResource>>,
     settings: Option<Res<SettingsResource>>,
@@ -290,7 +290,7 @@ fn handle_win_cascade(
 
 fn handle_achievement_toast(
     mut commands: Commands,
-    mut events: EventReader<AchievementUnlockedEvent>,
+    mut events: MessageReader<AchievementUnlockedEvent>,
 ) {
     for ev in events.read() {
         spawn_toast(
@@ -301,7 +301,7 @@ fn handle_achievement_toast(
     }
 }
 
-fn handle_levelup_toast(mut commands: Commands, mut events: EventReader<LevelUpEvent>) {
+fn handle_levelup_toast(mut commands: Commands, mut events: MessageReader<LevelUpEvent>) {
     for ev in events.read() {
         spawn_toast(
             &mut commands,
@@ -313,7 +313,7 @@ fn handle_levelup_toast(mut commands: Commands, mut events: EventReader<LevelUpE
 
 fn handle_daily_goal_announcement_toast(
     mut commands: Commands,
-    mut events: EventReader<DailyGoalAnnouncementEvent>,
+    mut events: MessageReader<DailyGoalAnnouncementEvent>,
 ) {
     for ev in events.read() {
         spawn_toast(&mut commands, format!("Goal: {}", ev.0), DAILY_TOAST_SECS);
@@ -322,7 +322,7 @@ fn handle_daily_goal_announcement_toast(
 
 fn handle_daily_toast(
     mut commands: Commands,
-    mut events: EventReader<DailyChallengeCompletedEvent>,
+    mut events: MessageReader<DailyChallengeCompletedEvent>,
 ) {
     for ev in events.read() {
         spawn_toast(
@@ -335,7 +335,7 @@ fn handle_daily_toast(
 
 fn handle_weekly_toast(
     mut commands: Commands,
-    mut events: EventReader<WeeklyGoalCompletedEvent>,
+    mut events: MessageReader<WeeklyGoalCompletedEvent>,
 ) {
     for ev in events.read() {
         spawn_toast(
@@ -348,7 +348,7 @@ fn handle_weekly_toast(
 
 fn handle_time_attack_toast(
     mut commands: Commands,
-    mut events: EventReader<TimeAttackEndedEvent>,
+    mut events: MessageReader<TimeAttackEndedEvent>,
 ) {
     for ev in events.read() {
         spawn_toast(
@@ -361,7 +361,7 @@ fn handle_time_attack_toast(
 
 fn handle_challenge_toast(
     mut commands: Commands,
-    mut events: EventReader<ChallengeAdvancedEvent>,
+    mut events: MessageReader<ChallengeAdvancedEvent>,
 ) {
     for ev in events.read() {
         spawn_toast(
@@ -374,7 +374,7 @@ fn handle_challenge_toast(
 
 fn handle_settings_toast(
     mut commands: Commands,
-    mut events: EventReader<SettingsChangedEvent>,
+    mut events: MessageReader<SettingsChangedEvent>,
     mut last_sfx: Local<Option<f32>>,
     mut last_music: Local<Option<f32>>,
 ) {
@@ -417,7 +417,7 @@ fn handle_auto_complete_toast(
 
 fn handle_new_game_confirm_toast(
     mut commands: Commands,
-    mut events: EventReader<NewGameConfirmEvent>,
+    mut events: MessageReader<NewGameConfirmEvent>,
 ) {
     for _ in events.read() {
         spawn_toast(&mut commands, "Press N again to start a new game".to_string(), 3.0);
@@ -430,7 +430,7 @@ fn handle_new_game_confirm_toast(
 /// decouples event production from rendering so multiple simultaneous events do
 /// not cause overlapping toast text on screen.
 fn enqueue_toasts(
-    mut events: EventReader<InfoToastEvent>,
+    mut events: MessageReader<InfoToastEvent>,
     mut queue: ResMut<ToastQueue>,
 ) {
     for ev in events.read() {
@@ -465,7 +465,7 @@ fn drive_toast_display(
         active.timer -= dt;
         if active.timer <= 0.0 {
             // Despawn the toast entity and clear the active slot.
-            commands.entity(entity).despawn_recursive();
+            commands.entity(entity).despawn();
             active.entity = None;
             active.timer = 0.0;
         }
@@ -509,7 +509,7 @@ fn spawn_queued_toast(commands: &mut Commands, message: String) -> Entity {
         .id()
 }
 
-fn handle_xp_awarded_toast(mut commands: Commands, mut events: EventReader<XpAwardedEvent>) {
+fn handle_xp_awarded_toast(mut commands: Commands, mut events: MessageReader<XpAwardedEvent>) {
     for ev in events.read() {
         spawn_toast(&mut commands, format!("+{} XP", ev.amount), 3.0);
     }
@@ -532,7 +532,7 @@ fn tick_toasts(
     for (entity, mut timer) in &mut toasts {
         timer.0 -= dt;
         if timer.0 <= 0.0 {
-            commands.entity(entity).despawn_recursive();
+            commands.entity(entity).despawn();
         }
     }
 }
@@ -709,7 +709,7 @@ mod tests {
         let mut app = App::new();
         app.add_plugins(MinimalPlugins).add_plugins(AnimationPlugin);
 
-        app.world_mut().send_event(InfoToastEvent("hello".to_string()));
+        app.world_mut().write_message(InfoToastEvent("hello".to_string()));
         app.update();
 
         let count = app
@@ -745,7 +745,7 @@ mod tests {
     fn toast_queue_enqueues_on_event() {
         let mut app = queue_app();
         app.world_mut()
-            .send_event(InfoToastEvent("test message".to_string()));
+            .write_message(InfoToastEvent("test message".to_string()));
         app.update();
         // After one update the message should have been consumed (shown) or is
         // still in the queue — either way we verify the system processed it by
@@ -775,9 +775,8 @@ mod tests {
         let mut app = App::new();
         app.add_plugins(MinimalPlugins).add_plugins(AnimationPlugin);
 
-        let mut fast_settings = Settings::default();
-        fast_settings.animation_speed = AnimSpeed::Fast;
-        app.world_mut().send_event(SettingsChangedEvent(fast_settings));
+        let fast_settings = Settings { animation_speed: AnimSpeed::Fast, ..Default::default() };
+        app.world_mut().write_message(SettingsChangedEvent(fast_settings));
         app.update();
 
         let dur = app.world().resource::<EffectiveSlideDuration>().slide_secs;
@@ -796,7 +795,7 @@ mod tests {
         assert_eq!(before, 0, "no animations before win");
 
         app.world_mut()
-            .send_event(GameWonEvent { score: 500, time_seconds: 60 });
+            .write_message(GameWonEvent { score: 500, time_seconds: 60 });
         app.update();
 
         let after = app

solitaire_engine/src/audio_plugin.rs

@@ -23,13 +23,10 @@
 use std::io::Cursor;
 
 use bevy::prelude::*;
-use kira::manager::backend::DefaultBackend;
-use kira::manager::{AudioManager, AudioManagerSettings};
 use kira::sound::static_sound::{StaticSoundData, StaticSoundHandle};
 use kira::sound::Region;
 use kira::track::{TrackBuilder, TrackHandle};
-use kira::tween::Tween;
-use kira::Volume;
+use kira::{AudioManager, AudioManagerSettings, Decibels, DefaultBackend, Tween, Value};
 
 use crate::events::{
     CardFaceRevealedEvent, CardFlippedEvent, DrawRequestEvent, GameWonEvent, MoveRejectedEvent,
@@ -46,6 +43,16 @@ const RECYCLE_VOLUME: f64 = 0.5;
 /// Volume amplitude for the ambient music loop placeholder.
 const AMBIENT_VOLUME: f64 = 0.05;
 
+/// Converts a linear amplitude (0.0–1.0+) to the `Decibels` type used by
+/// kira 0.12. Clamps to `Decibels::SILENCE` for non-positive amplitudes.
+fn amplitude_to_decibels(amplitude: f32) -> Decibels {
+    if amplitude <= 0.0 {
+        Decibels::SILENCE
+    } else {
+        Decibels(20.0 * amplitude.log10())
+    }
+}
+
 /// Returns `true` when a `DrawRequestEvent` will recycle the waste pile back
 /// to stock rather than drawing a new card.
 ///
@@ -56,7 +63,7 @@ fn is_recycle(stock_len: usize) -> bool {
 }
 
 /// Pre-decoded sound effects. Cheap to clone (frames are an `Arc<[Frame]>`),
-/// so we hand a fresh handle to `manager.play()` on every event.
+/// so we hand a fresh handle to `track.play()` on every event.
 #[derive(Resource, Clone)]
 pub struct SoundLibrary {
     pub deal: StaticSoundData,
@@ -104,7 +111,7 @@ impl Plugin for AudioPlugin {
             warn!("failed to decode embedded SFX assets; SFX disabled");
         }
 
-        let (sfx_track, music_track) = match manager.as_mut() {
+        let (sfx_track, mut music_track) = match manager.as_mut() {
             Some(mgr) => {
                 let sfx = mgr.add_sub_track(TrackBuilder::default()).ok();
                 let music = mgr.add_sub_track(TrackBuilder::default()).ok();
@@ -116,7 +123,7 @@ impl Plugin for AudioPlugin {
         // Start the ambient loop placeholder (card_flip.wav looped at very low
         // volume through music_track).
         let ambient_handle =
-            start_ambient_loop(manager.as_mut(), library.as_ref(), &music_track);
+            start_ambient_loop(manager.as_mut(), library.as_ref(), &mut music_track);
 
         app.insert_non_send_resource(AudioState {
             manager,
@@ -130,15 +137,15 @@ impl Plugin for AudioPlugin {
             app.insert_resource(lib);
         }
 
-        app.add_event::<DrawRequestEvent>()
-            .add_event::<MoveRequestEvent>()
-            .add_event::<MoveRejectedEvent>()
-            .add_event::<NewGameRequestEvent>()
-            .add_event::<GameWonEvent>()
-            .add_event::<CardFlippedEvent>()
-            .add_event::<CardFaceRevealedEvent>()
-            .add_event::<UndoRequestEvent>()
-            .add_event::<SettingsChangedEvent>()
+        app.add_message::<DrawRequestEvent>()
+            .add_message::<MoveRequestEvent>()
+            .add_message::<MoveRejectedEvent>()
+            .add_message::<NewGameRequestEvent>()
+            .add_message::<GameWonEvent>()
+            .add_message::<CardFlippedEvent>()
+            .add_message::<CardFaceRevealedEvent>()
+            .add_message::<UndoRequestEvent>()
+            .add_message::<SettingsChangedEvent>()
             .add_systems(Startup, apply_initial_volume)
             .add_systems(
                 Update,
@@ -190,20 +197,22 @@ fn decode(bytes: &'static [u8]) -> Option<StaticSoundData> {
 fn start_ambient_loop(
     manager: Option<&mut AudioManager<DefaultBackend>>,
     library: Option<&SoundLibrary>,
-    music_track: &Option<TrackHandle>,
+    music_track: &mut Option<TrackHandle>,
 ) -> Option<StaticSoundHandle> {
     let manager = manager?;
     let lib = library?;
 
     let mut data = lib.flip.clone();
-    // Loop the entire file from start to end.
     data.settings.loop_region = Some(Region::default());
-    data.settings.volume = Volume::Amplitude(AMBIENT_VOLUME).into();
-    if let Some(track) = music_track {
-        data.settings.output_destination = track.id().into();
-    }
+    data.settings.volume = Value::Fixed(amplitude_to_decibels(AMBIENT_VOLUME as f32));
 
-    match manager.play(data) {
+    let result = if let Some(track) = music_track.as_mut() {
+        track.play(data)
+    } else {
+        manager.play(data)
+    };
+
+    match result {
         Ok(handle) => Some(handle),
         Err(e) => {
             warn!("failed to start ambient loop: {e}");
@@ -213,16 +222,17 @@ fn start_ambient_loop(
 }
 
 fn play(audio: &mut AudioState, sound: &StaticSoundData) {
-    let Some(manager) = audio.manager.as_mut() else {
-        return;
-    };
+    let data = sound.clone();
     // Route SFX through the dedicated sfx_track so its volume is independent
     // of the music_track volume.
-    let mut data = sound.clone();
-    if let Some(track) = &audio.sfx_track {
-        data.settings.output_destination = track.id().into();
-    }
-    if let Err(e) = manager.play(data) {
+    let result = if let Some(track) = audio.sfx_track.as_mut() {
+        track.play(data)
+    } else if let Some(manager) = audio.manager.as_mut() {
+        manager.play(data)
+    } else {
+        return;
+    };
+    if let Err(e) = result {
         warn!("failed to play SFX: {e}");
     }
 }
@@ -234,15 +244,17 @@ impl AudioState {
     /// explicit volume override so callers can play sounds at a fraction of their
     /// normal level. Silently does nothing when audio is unavailable.
     pub fn play_sfx_at_volume(&mut self, sound: &StaticSoundData, volume: f64) {
-        let Some(manager) = self.manager.as_mut() else {
+        let mut data = sound.clone();
+        data.settings.volume = Value::Fixed(amplitude_to_decibels(volume as f32));
+
+        let result = if let Some(track) = self.sfx_track.as_mut() {
+            track.play(data)
+        } else if let Some(manager) = self.manager.as_mut() {
+            manager.play(data)
+        } else {
             return;
         };
-        let mut data = sound.clone();
-        data.settings.volume = Volume::Amplitude(volume).into();
-        if let Some(track) = &self.sfx_track {
-            data.settings.output_destination = track.id().into();
-        }
-        if let Err(e) = manager.play(data) {
+        if let Err(e) = result {
             warn!("failed to play SFX at volume {volume}: {e}");
         }
     }
@@ -250,13 +262,13 @@ impl AudioState {
 
 fn set_sfx_volume(audio: &mut AudioState, volume: f32) {
     if let Some(track) = audio.sfx_track.as_mut() {
-        track.set_volume(volume.clamp(0.0, 1.0) as f64, Tween::default());
+        track.set_volume(amplitude_to_decibels(volume.clamp(0.0, 1.0)), Tween::default());
     }
 }
 
 fn set_music_volume(audio: &mut AudioState, volume: f32) {
     if let Some(track) = audio.music_track.as_mut() {
-        track.set_volume(volume.clamp(0.0, 1.0) as f64, Tween::default());
+        track.set_volume(amplitude_to_decibels(volume.clamp(0.0, 1.0)), Tween::default());
     }
 }
 
@@ -270,7 +282,7 @@ fn apply_initial_volume(
 }
 
 fn play_on_undo(
-    mut events: EventReader<UndoRequestEvent>,
+    mut events: MessageReader<UndoRequestEvent>,
     mut audio: NonSendMut<AudioState>,
     lib: Option<Res<SoundLibrary>>,
 ) {
@@ -281,7 +293,7 @@ fn play_on_undo(
 }
 
 fn apply_volume_on_change(
-    mut events: EventReader<SettingsChangedEvent>,
+    mut events: MessageReader<SettingsChangedEvent>,
     mut audio: NonSendMut<AudioState>,
     mute: Option<Res<MuteState>>,
 ) {
@@ -326,7 +338,7 @@ fn handle_mute_keys(
 }
 
 fn play_on_draw(
-    mut events: EventReader<DrawRequestEvent>,
+    mut events: MessageReader<DrawRequestEvent>,
     mut audio: NonSendMut<AudioState>,
     lib: Option<Res<SoundLibrary>>,
     game: Option<Res<GameStateResource>>,
@@ -345,15 +357,18 @@ fn play_on_draw(
 
         if is_recycle(stock_len) {
             let mut data = lib.flip.clone();
-            data.settings.volume = Volume::Amplitude(RECYCLE_VOLUME).into();
-            if let Some(track) = &audio.sfx_track {
-                data.settings.output_destination = track.id().into();
-            }
-            if let Some(manager) = audio.manager.as_mut() {
-                if let Err(e) = manager.play(data) {
+            data.settings.volume =
+                Value::Fixed(amplitude_to_decibels(RECYCLE_VOLUME as f32));
+            let result = if let Some(track) = audio.sfx_track.as_mut() {
+                track.play(data)
+            } else if let Some(manager) = audio.manager.as_mut() {
+                manager.play(data)
+            } else {
+                continue;
+            };
+            if let Err(e) = result {
                 warn!("failed to play recycle SFX: {e}");
             }
-            }
         } else {
             play(&mut audio, &lib.flip);
         }
@@ -361,7 +376,7 @@ fn play_on_draw(
 }
 
 fn play_on_move(
-    mut events: EventReader<MoveRequestEvent>,
+    mut events: MessageReader<MoveRequestEvent>,
     mut audio: NonSendMut<AudioState>,
     lib: Option<Res<SoundLibrary>>,
 ) {
@@ -374,7 +389,7 @@ fn play_on_move(
 }
 
 fn play_on_rejected(
-    mut events: EventReader<MoveRejectedEvent>,
+    mut events: MessageReader<MoveRejectedEvent>,
     mut audio: NonSendMut<AudioState>,
     lib: Option<Res<SoundLibrary>>,
 ) {
@@ -387,7 +402,7 @@ fn play_on_rejected(
 }
 
 fn play_on_new_game(
-    mut events: EventReader<NewGameRequestEvent>,
+    mut events: MessageReader<NewGameRequestEvent>,
     mut audio: NonSendMut<AudioState>,
     lib: Option<Res<SoundLibrary>>,
 ) {
@@ -400,7 +415,7 @@ fn play_on_new_game(
 }
 
 fn play_on_win(
-    mut events: EventReader<GameWonEvent>,
+    mut events: MessageReader<GameWonEvent>,
     mut audio: NonSendMut<AudioState>,
     lib: Option<Res<SoundLibrary>>,
 ) {
@@ -418,7 +433,7 @@ fn play_on_win(
 /// Driven by `CardFaceRevealedEvent`, which is fired by `tick_flip_anim` at
 /// the phase transition (scale.x crosses 0), not by the move event itself.
 fn play_on_face_revealed(
-    mut events: EventReader<CardFaceRevealedEvent>,
+    mut events: MessageReader<CardFaceRevealedEvent>,
     mut audio: NonSendMut<AudioState>,
     lib: Option<Res<SoundLibrary>>,
 ) {

solitaire_engine/src/auto_complete_plugin.rs

@@ -57,7 +57,7 @@ impl Plugin for AutoCompletePlugin {
 fn detect_auto_complete(
     mut state: ResMut<AutoCompleteState>,
     game: Res<GameStateResource>,
-    mut changed: EventReader<StateChangedEvent>,
+    mut changed: MessageReader<StateChangedEvent>,
 ) {
     // Only re-evaluate on state changes to avoid per-frame allocations.
     if changed.is_empty() && !game.is_changed() {
@@ -106,7 +106,7 @@ fn drive_auto_complete(
     mut state: ResMut<AutoCompleteState>,
     game: Res<GameStateResource>,
     time: Res<Time>,
-    mut moves: EventWriter<MoveRequestEvent>,
+    mut moves: MessageWriter<MoveRequestEvent>,
 ) {
     if !state.active {
         return;
@@ -122,7 +122,7 @@ fn drive_auto_complete(
         return;
     };
 
-    moves.send(MoveRequestEvent { from, to, count: 1 });
+    moves.write(MoveRequestEvent { from, to, count: 1 });
     state.cooldown = STEP_INTERVAL;
 }
 
@@ -176,7 +176,7 @@ mod tests {
         let mut app = headless_app();
         // Install a nearly-won state and fire StateChangedEvent.
         app.world_mut().resource_mut::<GameStateResource>().0 = nearly_won_state();
-        app.world_mut().send_event(StateChangedEvent);
+        app.world_mut().write_message(StateChangedEvent);
         app.update();
 
         assert!(app.world().resource::<AutoCompleteState>().active);
@@ -186,11 +186,11 @@ mod tests {
     fn drive_fires_move_request_when_active() {
         let mut app = headless_app();
         app.world_mut().resource_mut::<GameStateResource>().0 = nearly_won_state();
-        app.world_mut().send_event(StateChangedEvent);
+        app.world_mut().write_message(StateChangedEvent);
         app.update(); // detect runs, sets active
         app.update(); // drive fires the move
 
-        let events = app.world().resource::<Events<MoveRequestEvent>>();
+        let events = app.world().resource::<Messages<MoveRequestEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).collect();
         // At least one MoveRequestEvent should have been fired.
@@ -206,7 +206,7 @@ mod tests {
         let mut gs = nearly_won_state();
         gs.is_won = true;
         app.world_mut().resource_mut::<GameStateResource>().0 = gs;
-        app.world_mut().send_event(StateChangedEvent);
+        app.world_mut().write_message(StateChangedEvent);
         app.update();
 
         assert!(!app.world().resource::<AutoCompleteState>().active);

solitaire_engine/src/card_animation/animation.rs

@@ -0,0 +1,372 @@
+//! `CardAnimation` component and the system that drives it.
+//!
+//! # Design
+//!
+//! `CardAnimation` is a **drop-in upgrade** for the existing linear `CardAnim`.
+//! It targets `Transform` (the current sprite-based architecture). Swapping to
+//! Bevy UI requires only changing the four write lines in `advance_card_animations`
+//! to write `Style.left` / `Style.top` via a `Style` component query instead.
+//!
+//! # Z-lift
+//!
+//! During motion, `translation.z` follows a parabolic arc:
+//!
+//! ```text
+//! z(t) = lerp(start_z, end_z, t) + z_lift × sin(t × π)
+//! ```
+//!
+//! The sine term is 0 at `t = 0` and `t = 1` and peaks at `t = 0.5`, so the
+//! card "floats up" in the middle of its travel and lands at its correct rest z.
+//!
+//! # Retargeting
+//!
+//! When a card is redirected mid-flight, call [`retarget_animation`]. It reads
+//! the current interpolated position so the card never snaps.
+//!
+//! # Coexistence with `CardAnim`
+//!
+//! `CardAnimation` and the legacy `CardAnim` can coexist in the same world but
+//! **must never be on the same entity** — both write to `Transform`. When
+//! migrating, replace `CardAnim` insertions with `CardAnimation` insertions and
+//! register `CardAnimationPlugin` alongside `AnimationPlugin`.
+
+use std::f32::consts::PI;
+
+use bevy::prelude::*;
+
+use super::curves::{sample_curve, MotionCurve};
+use super::timing::compute_duration;
+use crate::pause_plugin::PausedResource;
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+/// Curve-based card animation.
+///
+/// Drives `Transform` XY translation via a [`MotionCurve`], with optional
+/// z-lift and scale interpolation. Removes itself when the animation completes.
+#[derive(Component, Debug, Clone)]
+pub struct CardAnimation {
+    /// 2-D start position (world space).
+    pub start: Vec2,
+    /// 2-D destination (world space).
+    pub end: Vec2,
+    /// Seconds elapsed since the delay expired.
+    pub elapsed: f32,
+    /// Total animation duration in seconds (excluding delay).
+    pub duration: f32,
+    /// Easing curve applied to the interpolation factor.
+    pub curve: MotionCurve,
+    /// Seconds to wait before starting movement.
+    pub delay: f32,
+    /// Z coordinate at animation start (used for parabolic lift calculation).
+    pub start_z: f32,
+    /// Z coordinate at animation end — the card's resting z after completion.
+    pub end_z: f32,
+    /// Extra Z added at the midpoint of motion (`z(0.5) = base_z + z_lift`).
+    /// Set to 0.0 to disable the depth arc.
+    pub z_lift: f32,
+    /// Transform scale at `t = 0`.
+    pub scale_start: f32,
+    /// Transform scale at `t = 1`.
+    pub scale_end: f32,
+}
+
+impl CardAnimation {
+    /// Convenience constructor: slide from `start` to `end` with auto-computed
+    /// duration based on pixel distance. No z-lift or scale change.
+    pub fn slide(start: Vec2, start_z: f32, end: Vec2, end_z: f32, curve: MotionCurve) -> Self {
+        Self {
+            start,
+            end,
+            elapsed: 0.0,
+            duration: compute_duration(start.distance(end)),
+            curve,
+            delay: 0.0,
+            start_z,
+            end_z,
+            z_lift: 0.0,
+            scale_start: 1.0,
+            scale_end: 1.0,
+        }
+    }
+
+    /// Sets the pre-animation delay in seconds.
+    #[must_use]
+    pub fn with_delay(mut self, secs: f32) -> Self {
+        self.delay = secs;
+        self
+    }
+
+    /// Overrides the auto-computed duration.
+    #[must_use]
+    pub fn with_duration(mut self, secs: f32) -> Self {
+        self.duration = secs;
+        self
+    }
+
+    /// Enables the parabolic z-lift arc with the given peak offset.
+    #[must_use]
+    pub fn with_z_lift(mut self, lift: f32) -> Self {
+        self.z_lift = lift;
+        self
+    }
+
+    /// Interpolates `Transform.scale` from `start` to `end` over the animation.
+    #[must_use]
+    pub fn with_scale(mut self, start: f32, end: f32) -> Self {
+        self.scale_start = start;
+        self.scale_end = end;
+        self
+    }
+
+    /// Returns the current interpolated XY position without advancing time.
+    ///
+    /// Used by [`retarget_animation`] to read mid-flight position cleanly.
+    pub fn current_xy(&self) -> Vec2 {
+        if self.duration <= 0.0 {
+            return self.end;
+        }
+        let t = (self.elapsed / self.duration).clamp(0.0, 1.0);
+        let s = sample_curve(self.curve, t);
+        self.start.lerp(self.end, s)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Retarget helper
+// ---------------------------------------------------------------------------
+
+/// Redirects a card to a new destination without snapping or interrupting motion.
+///
+/// Reads the card's current interpolated position (from a live `CardAnimation` if
+/// present, or from `Transform` if the card is stationary) and starts a fresh
+/// `CardAnimation` from that position. Duration is recalculated from the remaining
+/// distance so short remaining paths feel appropriately quick.
+///
+/// # Example
+///
+/// ```ignore
+/// // Inside a system that decides to move a card to a new target:
+/// let (entity, transform, anim) = cards.get(card_entity)?;
+/// retarget_animation(
+///     &mut commands,
+///     entity,
+///     anim,            // Option<&CardAnimation>
+///     transform,
+///     Vec2::new(400.0, 200.0),
+///     resting_z,
+///     MotionCurve::SmoothSnap,
+/// );
+/// ```
+pub fn retarget_animation(
+    commands: &mut Commands,
+    entity: Entity,
+    current_anim: Option<&CardAnimation>,
+    transform: &Transform,
+    new_end: Vec2,
+    new_end_z: f32,
+    curve: MotionCurve,
+) {
+    let (current_xy, current_z) = match current_anim {
+        Some(anim) => (anim.current_xy(), transform.translation.z),
+        None => (transform.translation.truncate(), transform.translation.z),
+    };
+
+    let distance = current_xy.distance(new_end);
+    commands.entity(entity).insert(CardAnimation {
+        start: current_xy,
+        end: new_end,
+        elapsed: 0.0,
+        duration: compute_duration(distance),
+        curve,
+        delay: 0.0,
+        start_z: current_z,
+        end_z: new_end_z,
+        z_lift: 8.0,
+        scale_start: 1.0,
+        scale_end: 1.0,
+    });
+}
+
+// ---------------------------------------------------------------------------
+// System
+// ---------------------------------------------------------------------------
+
+/// Advances all [`CardAnimation`] components each frame.
+///
+/// Skipped while the game is paused. On completion the component is removed
+/// and `Transform` is snapped to the exact destination to prevent floating-point
+/// drift.
+pub(crate) fn advance_card_animations(
+    mut commands: Commands,
+    time: Res<Time>,
+    paused: Option<Res<PausedResource>>,
+    mut q: Query<(Entity, &mut Transform, &mut CardAnimation)>,
+) {
+    if paused.is_some_and(|p| p.0) {
+        return;
+    }
+    let dt = time.delta_secs();
+
+    for (entity, mut transform, mut anim) in &mut q {
+        // Honour pre-animation delay.
+        if anim.delay > 0.0 {
+            anim.delay = (anim.delay - dt).max(0.0);
+            continue;
+        }
+
+        // Zero-duration: instant snap.
+        if anim.duration <= 0.0 {
+            transform.translation = anim.end.extend(anim.end_z);
+            transform.scale = Vec3::splat(anim.scale_end);
+            commands.entity(entity).remove::<CardAnimation>();
+            continue;
+        }
+
+        anim.elapsed += dt;
+        let t = (anim.elapsed / anim.duration).min(1.0);
+        let s = sample_curve(anim.curve, t);
+
+        // --- XY via curve ---
+        let xy = anim.start.lerp(anim.end, s);
+        transform.translation.x = xy.x;
+        transform.translation.y = xy.y;
+
+        // --- Z: linear base interpolation + parabolic lift arc ---
+        //
+        // The sine arch is 0 at t=0 and t=1, peaking at t=0.5.
+        // This keeps the card's resting Z correct at both ends.
+        let base_z = anim.start_z + (anim.end_z - anim.start_z) * t;
+        let lift = anim.z_lift * (t * PI).sin();
+        transform.translation.z = base_z + lift;
+
+        // --- Scale ---
+        let scale = anim.scale_start + (anim.scale_end - anim.scale_start) * s;
+        transform.scale = Vec3::splat(scale);
+
+        // --- Completion ---
+        if t >= 1.0 {
+            transform.translation = anim.end.extend(anim.end_z);
+            transform.scale = Vec3::splat(anim.scale_end);
+            commands.entity(entity).remove::<CardAnimation>();
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Win cascade
+// ---------------------------------------------------------------------------
+
+/// Win-cascade scatter targets — 8 points beyond the window edges.
+///
+/// Scaled by `radius` (pass `layout.card_size.x * 8.0` for a good result).
+pub fn win_scatter_targets(radius: f32) -> [Vec2; 8] {
+    let r = radius;
+    [
+        Vec2::new(r, r),
+        Vec2::new(-r, r),
+        Vec2::new(r, -r),
+        Vec2::new(-r, -r),
+        Vec2::new(0.0, r),
+        Vec2::new(0.0, -r),
+        Vec2::new(r, 0.0),
+        Vec2::new(-r, 0.0),
+    ]
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn make_anim(start: Vec2, end: Vec2, elapsed: f32, duration: f32) -> CardAnimation {
+        CardAnimation {
+            start,
+            end,
+            elapsed,
+            duration,
+            curve: MotionCurve::Responsive, // linear-ish for easy assertion
+            delay: 0.0,
+            start_z: 0.0,
+            end_z: 0.0,
+            z_lift: 0.0,
+            scale_start: 1.0,
+            scale_end: 1.0,
+        }
+    }
+
+    #[test]
+    fn current_xy_at_start() {
+        let anim = make_anim(Vec2::ZERO, Vec2::new(100.0, 0.0), 0.0, 1.0);
+        let pos = anim.current_xy();
+        assert!(pos.x < 5.0, "at t=0 position should be near start, got {pos:?}");
+    }
+
+    #[test]
+    fn current_xy_at_end() {
+        let anim = make_anim(Vec2::ZERO, Vec2::new(100.0, 0.0), 1.0, 1.0);
+        let pos = anim.current_xy();
+        assert!(
+            (pos.x - 100.0).abs() < 1e-3,
+            "at t=1 position should be at end, got {pos:?}"
+        );
+    }
+
+    #[test]
+    fn current_xy_zero_duration_returns_end() {
+        let anim = make_anim(Vec2::ZERO, Vec2::new(50.0, 0.0), 0.0, 0.0);
+        let pos = anim.current_xy();
+        assert!(
+            (pos.x - 50.0).abs() < 1e-3,
+            "zero-duration must return end immediately, got {pos:?}"
+        );
+    }
+
+    #[test]
+    fn slide_constructor_auto_computes_duration() {
+        let start = Vec2::ZERO;
+        let end = Vec2::new(300.0, 0.0);
+        let anim = CardAnimation::slide(start, 0.0, end, 0.0, MotionCurve::SmoothSnap);
+        let distance = 300.0_f32;
+        let expected = compute_duration(distance);
+        assert!(
+            (anim.duration - expected).abs() < 1e-5,
+            "slide() duration mismatch: got {}, expected {}",
+            anim.duration,
+            expected
+        );
+    }
+
+    #[test]
+    fn with_delay_sets_delay() {
+        let anim = CardAnimation::slide(Vec2::ZERO, 0.0, Vec2::ONE, 0.0, MotionCurve::SmoothSnap)
+            .with_delay(0.5);
+        assert!((anim.delay - 0.5).abs() < 1e-6);
+    }
+
+    #[test]
+    fn with_z_lift_sets_z_lift() {
+        let anim = CardAnimation::slide(Vec2::ZERO, 0.0, Vec2::ONE, 0.0, MotionCurve::SmoothSnap)
+            .with_z_lift(12.0);
+        assert!((anim.z_lift - 12.0).abs() < 1e-6);
+    }
+
+    #[test]
+    fn win_scatter_has_eight_targets() {
+        let targets = win_scatter_targets(800.0);
+        assert_eq!(targets.len(), 8);
+    }
+
+    #[test]
+    fn win_scatter_targets_are_off_center() {
+        for t in win_scatter_targets(400.0) {
+            let dist = t.length();
+            assert!(dist > 100.0, "scatter target should be well off-center: {t:?}");
+        }
+    }
+}

solitaire_engine/src/card_animation/curves.rs

@@ -0,0 +1,196 @@
+//! Motion curve definitions for card animations.
+//!
+//! All curves map `t ∈ [0, 1]` to a position ratio. Curves with overshoot
+//! (`SmoothSnap`, `SoftBounce`, `Expressive`) may return values slightly
+//! outside `[0, 1]` near the destination — callers should not clamp the output
+//! before applying it to a lerp, as the overshoot is intentional.
+//!
+//! # Curve selection guide
+//!
+//! | Interaction          | Recommended curve |
+//! |----------------------|-------------------|
+//! | Standard card move   | `SmoothSnap`      |
+//! | Foundation placement | `SoftBounce`      |
+//! | Invalid snap-back    | `Responsive`      |
+//! | Win cascade          | `Expressive`      |
+
+use std::f32::consts::PI;
+
+/// Motion curve variant controlling animation easing behaviour.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum MotionCurve {
+    /// Cubic ease-out with a 1.5 % terminal overshoot.
+    ///
+    /// Overshoot is a sine arch in the final 25 % of the animation that peaks
+    /// ~1.5 % beyond the target, settling cleanly to 1.0 at `t = 1`. Gives a
+    /// lively, slightly "alive" feel without feeling heavy.
+    #[default]
+    SmoothSnap,
+
+    /// Underdamped spring (ζ = 0.65, ω = 20 rad/s).
+    ///
+    /// One visible overshoot of ~8 % followed by fast decay. Good for
+    /// satisfying "thud" feedback when placing cards on foundations or tableau.
+    SoftBounce,
+
+    /// Quintic ease-out — aggressive deceleration, zero overshoot.
+    ///
+    /// Starts extremely fast and decelerates hard. Best for snap-back on
+    /// invalid drops: the card returns instantly without any bounce.
+    Responsive,
+
+    /// Underdamped spring (ζ = 0.45, ω = 18 rad/s).
+    ///
+    /// Two visible bounces before settling. High visual energy — reserved for
+    /// win cascade animations where expressivity matters more than subtlety.
+    Expressive,
+}
+
+/// Samples `curve` at normalised time `t ∈ [0, 1]`.
+///
+/// The return value is the interpolation factor to pass to `Vec2::lerp` /
+/// `Vec3::lerp`. Values may slightly exceed 1.0 for curves with overshoot.
+#[inline]
+pub fn sample_curve(curve: MotionCurve, t: f32) -> f32 {
+    let t = t.clamp(0.0, 1.0);
+    match curve {
+        MotionCurve::SmoothSnap => smooth_snap(t),
+        MotionCurve::SoftBounce => soft_bounce(t),
+        MotionCurve::Responsive => responsive(t),
+        MotionCurve::Expressive => expressive(t),
+    }
+}
+
+/// Cubic ease-out with a sine-arch overshoot in the final 25 % of `t`.
+///
+/// The overshoot term is `sin(tail * π) * 0.015` where `tail` is `t` linearly
+/// rescaled from `[0.75, 1.0]` to `[0, 1]`. At `t = 0.875` the card is ~1.5 %
+/// past its target; at `t = 1` the card is exactly on target.
+#[inline]
+fn smooth_snap(t: f32) -> f32 {
+    let base = 1.0 - (1.0 - t).powi(3);
+    let tail = ((t - 0.75) / 0.25).clamp(0.0, 1.0);
+    let overshoot = (tail * PI).sin() * 0.015;
+    base + overshoot
+}
+
+/// Underdamped spring response (ζ = 0.65, ω₀ = 20 rad/s).
+///
+/// Derived from the exact closed-form solution:
+/// `x(t) = 1 − e^{−ζω₀t}[cos(ωd·t) + (ζω₀/ωd)·sin(ωd·t)]`
+/// where `ωd = ω₀·√(1 − ζ²)`.
+#[inline]
+fn soft_bounce(t: f32) -> f32 {
+    const OMEGA: f32 = 20.0;
+    const ZETA: f32 = 0.65;
+    let omega_d = OMEGA * (1.0 - ZETA * ZETA).sqrt();
+    let decay = (-ZETA * OMEGA * t).exp();
+    1.0 - decay * ((omega_d * t).cos() + (ZETA * OMEGA / omega_d) * (omega_d * t).sin())
+}
+
+/// Quintic ease-out: `f(t) = 1 − (1 − t)^5`.
+///
+/// Reaches ~97 % of the target by `t = 0.5`. No overshoot.
+#[inline]
+fn responsive(t: f32) -> f32 {
+    1.0 - (1.0 - t).powi(5)
+}
+
+/// Underdamped spring response (ζ = 0.45, ω₀ = 18 rad/s) — two visible bounces.
+///
+/// Uses the same closed-form spring formula as `soft_bounce` but with lower
+/// damping, producing higher overshoot (~18 %) and two discernible oscillations
+/// before settling.
+#[inline]
+fn expressive(t: f32) -> f32 {
+    const OMEGA: f32 = 18.0;
+    const ZETA: f32 = 0.45;
+    let omega_d = OMEGA * (1.0 - ZETA * ZETA).sqrt();
+    let decay = (-ZETA * OMEGA * t).exp();
+    1.0 - decay * ((omega_d * t).cos() + (ZETA * OMEGA / omega_d) * (omega_d * t).sin())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn assert_near(a: f32, b: f32, eps: f32, msg: &str) {
+        assert!((a - b).abs() < eps, "{msg}: expected ~{b}, got {a}");
+    }
+
+    #[test]
+    fn all_curves_start_at_zero() {
+        for curve in [
+            MotionCurve::SmoothSnap,
+            MotionCurve::SoftBounce,
+            MotionCurve::Responsive,
+            MotionCurve::Expressive,
+        ] {
+            assert_near(sample_curve(curve, 0.0), 0.0, 1e-5, &format!("{curve:?} at t=0"));
+        }
+    }
+
+    #[test]
+    fn all_curves_end_at_one() {
+        for curve in [
+            MotionCurve::SmoothSnap,
+            MotionCurve::SoftBounce,
+            MotionCurve::Responsive,
+        ] {
+            assert_near(sample_curve(curve, 1.0), 1.0, 1e-4, &format!("{curve:?} at t=1"));
+        }
+        // Spring-based curves have residual oscillation at finite t=1; allow 2 e-3.
+        assert_near(
+            sample_curve(MotionCurve::Expressive, 1.0),
+            1.0,
+            2e-3,
+            "Expressive at t=1",
+        );
+    }
+
+    #[test]
+    fn responsive_reaches_half_before_midpoint() {
+        // Quintic ease-out accelerates fast — >50 % by t=0.5.
+        let v = sample_curve(MotionCurve::Responsive, 0.5);
+        assert!(v > 0.96, "Responsive should be >96 % at t=0.5, got {v}");
+    }
+
+    #[test]
+    fn smooth_snap_overshoots_slightly_near_end() {
+        // Peak overshoot is around t = 0.875.
+        let peak = sample_curve(MotionCurve::SmoothSnap, 0.875);
+        assert!(peak > 1.0, "SmoothSnap should overshoot at t=0.875, got {peak}");
+        assert!(peak < 1.03, "SmoothSnap overshoot should be small (<3 %), got {peak}");
+    }
+
+    #[test]
+    fn soft_bounce_overshoots_and_returns() {
+        let v = sample_curve(MotionCurve::SoftBounce, 1.0);
+        assert_near(v, 1.0, 1e-3, "SoftBounce must settle at 1.0");
+    }
+
+    #[test]
+    fn expressive_has_more_overshoot_than_soft_bounce() {
+        // Compare max value in [0,1] range.
+        let max_soft: f32 = (0..=100)
+            .map(|i| sample_curve(MotionCurve::SoftBounce, i as f32 / 100.0))
+            .fold(f32::NEG_INFINITY, f32::max);
+        let max_expr: f32 = (0..=100)
+            .map(|i| sample_curve(MotionCurve::Expressive, i as f32 / 100.0))
+            .fold(f32::NEG_INFINITY, f32::max);
+        assert!(
+            max_expr > max_soft,
+            "Expressive should overshoot more than SoftBounce: {max_expr} vs {max_soft}"
+        );
+    }
+
+    #[test]
+    fn sample_curve_clamps_t_below_zero() {
+        assert_near(sample_curve(MotionCurve::SmoothSnap, -1.0), 0.0, 1e-5, "t<0 clamped");
+    }
+
+    #[test]
+    fn sample_curve_clamps_t_above_one() {
+        assert_near(sample_curve(MotionCurve::Responsive, 2.0), 1.0, 1e-5, "t>1 clamped");
+    }
+}

solitaire_engine/src/card_animation/interaction.rs

@@ -0,0 +1,321 @@
+//! Card interaction visuals: hover scale, drag lift, and input buffering.
+//!
+//! # Hover
+//!
+//! [`HoverState`] tracks the entity currently under the cursor. A system
+//! smoothly lerps `Transform.scale` toward `HOVER_SCALE` on the hovered card
+//! and back to 1.0 when the cursor leaves. Scale is only written when no
+//! [`CardAnimation`] is active on the entity (the animation takes priority).
+//!
+//! # Drag visual
+//!
+//! While [`DragState`] is non-idle, the dragged card entities receive a subtle
+//! scale boost (`DRAG_LIFT_SCALE`) and their z-order is pushed up. The exact
+//! translation is still controlled by the existing [`crate::input_plugin`] —
+//! this system only applies the _visual_ enhancement without touching XY.
+//!
+//! # Input buffer
+//!
+//! [`InputBuffer`] stores move/draw/undo actions that arrived while cards are
+//! still animating. Call [`InputBuffer::push`] from any system that wants
+//! buffering. The drain system fires the oldest buffered action as soon as all
+//! [`CardAnimation`] components have cleared, giving a responsive feel on
+//! fast repeated clicks.
+//!
+//! # Visual priority
+//!
+//! Dragged cards always have the highest z. The existing [`crate::input_plugin`]
+//! sets drag z; this module applies scale on top. The ordering constraint
+//! `.after(crate::game_plugin::GameMutation)` ensures all game-state changes
+//! settle before visual updates run.
+
+use std::collections::VecDeque;
+
+use bevy::prelude::*;
+use bevy::window::PrimaryWindow;
+
+use super::animation::CardAnimation;
+use crate::card_plugin::CardEntity;
+use crate::events::{DrawRequestEvent, MoveRequestEvent, UndoRequestEvent};
+use crate::layout::LayoutResource;
+use crate::resources::DragState;
+
+/// Type alias to reduce complexity in hover/drag query signatures.
+type CardTransformQuery<'w, 's> =
+    Query<'w, 's, (Entity, &'static mut Transform), (With<CardEntity>, Without<CardAnimation>)>;
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/// Scale applied to the card currently under the cursor (1.0 = no change).
+const HOVER_SCALE: f32 = 1.04;
+
+/// Additional scale applied to dragged cards while in flight.
+const DRAG_LIFT_SCALE: f32 = 1.08;
+
+/// Lerp speed for hover scale interpolation (higher = snappier).
+const HOVER_LERP_SPEED: f32 = 14.0;
+
+/// Lerp speed for drag scale interpolation.
+const DRAG_LERP_SPEED: f32 = 20.0;
+
+/// Maximum number of buffered inputs retained.
+const INPUT_BUFFER_CAPACITY: usize = 4;
+
+// ---------------------------------------------------------------------------
+// Resources
+// ---------------------------------------------------------------------------
+
+/// Tracks the entity currently under the cursor and the interpolated hover scale.
+#[derive(Resource, Debug, Default)]
+pub struct HoverState {
+    /// Entity currently hovered (`None` when cursor is off all cards or dragging).
+    pub entity: Option<Entity>,
+    /// Current interpolated scale applied to the hovered card.
+    pub scale: f32,
+}
+
+/// Describes a user action that arrived while cards were still animating.
+#[derive(Debug, Clone)]
+pub enum BufferedInput {
+    Move { from: crate::events::MoveRequestEvent },
+    Draw,
+    Undo,
+}
+
+/// FIFO queue of inputs deferred until ongoing animations complete.
+///
+/// Populate via [`InputBuffer::push`] and consume via the drain system.
+/// Capped at [`INPUT_BUFFER_CAPACITY`] — further pushes when full are silently
+/// dropped to prevent stale action pileup.
+#[derive(Resource, Debug, Default)]
+pub struct InputBuffer {
+    pub(crate) queue: VecDeque<BufferedInput>,
+}
+
+impl InputBuffer {
+    /// Enqueues an input if the buffer is not full.
+    pub fn push(&mut self, input: BufferedInput) {
+        if self.queue.len() < INPUT_BUFFER_CAPACITY {
+            self.queue.push_back(input);
+        }
+    }
+
+    /// Returns `true` when no inputs are pending.
+    pub fn is_empty(&self) -> bool {
+        self.queue.is_empty()
+    }
+
+    /// Returns how many inputs are queued.
+    pub fn len(&self) -> usize {
+        self.queue.len()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Systems
+// ---------------------------------------------------------------------------
+
+/// Detects which card is under the cursor and updates [`HoverState`].
+///
+/// Clears hover when [`DragState`] is active (dragging takes visual priority).
+/// Picks the topmost card (highest `translation.z`) when multiple cards overlap.
+pub(crate) fn detect_hover(
+    windows: Query<&Window, With<PrimaryWindow>>,
+    cameras: Query<(&Camera, &GlobalTransform)>,
+    drag: Option<Res<DragState>>,
+    layout: Option<Res<LayoutResource>>,
+    cards: Query<(Entity, &Transform), With<CardEntity>>,
+    mut hover: ResMut<HoverState>,
+) {
+    let is_dragging = drag.as_ref().is_some_and(|d| !d.is_idle());
+    if is_dragging {
+        hover.entity = None;
+        return;
+    }
+
+    let Some(layout) = layout else { return };
+    let Some(cursor_world) = cursor_world(&windows, &cameras) else {
+        hover.entity = None;
+        return;
+    };
+
+    let half_w = layout.0.card_size.x * 0.5;
+    let half_h = layout.0.card_size.y * 0.5;
+
+    let mut best: Option<(Entity, f32)> = None;
+    for (entity, transform) in &cards {
+        let pos = transform.translation.truncate();
+        if (cursor_world.x - pos.x).abs() < half_w
+            && (cursor_world.y - pos.y).abs() < half_h
+        {
+            let z = transform.translation.z;
+            if best.is_none_or(|(_, bz)| z > bz) {
+                best = Some((entity, z));
+            }
+        }
+    }
+
+    hover.entity = best.map(|(e, _)| e);
+}
+
+/// Applies the hover scale to the currently hovered card via smooth lerp.
+///
+/// Only runs on cards that have **no active [`CardAnimation`]** — animated
+/// cards control their own scale. When hover changes entities, the previous
+/// entity's scale is snapped back to 1.0 to avoid leaving a permanently
+/// enlarged card.
+pub(crate) fn apply_hover_scale(
+    time: Res<Time>,
+    mut hover_state: ResMut<HoverState>,
+    mut cards: CardTransformQuery,
+) {
+    let dt = time.delta_secs();
+    let target_entity = hover_state.entity;
+
+    for (entity, mut transform) in &mut cards {
+        let target_scale = if Some(entity) == target_entity {
+            HOVER_SCALE
+        } else {
+            1.0
+        };
+
+        let current = transform.scale.x;
+        let new_scale = current + (target_scale - current) * (HOVER_LERP_SPEED * dt).min(1.0);
+        transform.scale = Vec3::splat(new_scale);
+    }
+
+    // Update the tracked scale for external inspection.
+    hover_state.scale = if let Some(entity) = target_entity {
+        cards
+            .get(entity)
+            .map(|(_, t)| t.scale.x)
+            .unwrap_or(HOVER_SCALE)
+    } else {
+        1.0
+    };
+}
+
+/// Applies a scale boost and z-lift to dragged card entities.
+///
+/// Reads [`DragState`] for the list of card IDs being dragged. Does **not**
+/// modify `translation.xy` — the existing `InputPlugin` owns drag translation.
+/// Only writes `scale` and `translation.z` so the two systems are disjoint.
+pub(crate) fn apply_drag_visual(
+    time: Res<Time>,
+    drag: Option<Res<DragState>>,
+    mut cards: Query<(Entity, &CardEntity, &mut Transform), (Without<CardAnimation>,)>,
+) {
+    let dt = time.delta_secs();
+    let empty: Vec<u32> = Vec::new();
+    let dragged_ids: &[u32] = drag.as_ref().map_or(empty.as_slice(), |d| &d.cards);
+
+    for (_, card, mut transform) in &mut cards {
+        let is_dragged = dragged_ids.contains(&card.card_id);
+        let target_scale = if is_dragged { DRAG_LIFT_SCALE } else { 1.0 };
+        let current = transform.scale.x;
+        let new_scale = current + (target_scale - current) * (DRAG_LERP_SPEED * dt).min(1.0);
+        transform.scale = Vec3::splat(new_scale);
+    }
+}
+
+/// Fires the oldest buffered input when no [`CardAnimation`] components remain.
+///
+/// Call this system late in the `Update` schedule so freshly-removed animations
+/// are already gone before the drain runs.
+pub(crate) fn drain_input_buffer(
+    mut buffer: ResMut<InputBuffer>,
+    anims: Query<&CardAnimation>,
+    mut move_events: MessageWriter<MoveRequestEvent>,
+    mut draw_events: MessageWriter<DrawRequestEvent>,
+    mut undo_events: MessageWriter<UndoRequestEvent>,
+) {
+    if !anims.is_empty() {
+        return;
+    }
+    match buffer.queue.pop_front() {
+        Some(BufferedInput::Move { from }) => {
+            move_events.write(from);
+        }
+        Some(BufferedInput::Draw) => {
+            draw_events.write(DrawRequestEvent);
+        }
+        Some(BufferedInput::Undo) => {
+            undo_events.write(UndoRequestEvent);
+        }
+        None => {}
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Cursor helper (mirrors the pattern used by input_plugin)
+// ---------------------------------------------------------------------------
+
+/// Converts the cursor screen position to 2-D world coordinates.
+///
+/// Returns `None` when the cursor is outside the window or no camera is found.
+fn cursor_world(
+    windows: &Query<&Window, With<PrimaryWindow>>,
+    cameras: &Query<(&Camera, &GlobalTransform)>,
+) -> Option<Vec2> {
+    let window = windows.single().ok()?;
+    let cursor = window.cursor_position()?;
+    let (camera, camera_transform) = cameras.single().ok()?;
+    camera.viewport_to_world_2d(camera_transform, cursor).ok()
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn input_buffer_capacity_is_respected() {
+        let mut buf = InputBuffer::default();
+        for _ in 0..INPUT_BUFFER_CAPACITY + 5 {
+            buf.push(BufferedInput::Draw);
+        }
+        assert_eq!(
+            buf.len(),
+            INPUT_BUFFER_CAPACITY,
+            "buffer must not exceed capacity"
+        );
+    }
+
+    #[test]
+    fn input_buffer_is_fifo() {
+        let mut buf = InputBuffer::default();
+        buf.push(BufferedInput::Draw);
+        buf.push(BufferedInput::Undo);
+
+        matches!(buf.queue.pop_front().unwrap(), BufferedInput::Draw);
+        matches!(buf.queue.pop_front().unwrap(), BufferedInput::Undo);
+    }
+
+    #[test]
+    fn input_buffer_empty_initially() {
+        let buf = InputBuffer::default();
+        assert!(buf.is_empty());
+        assert_eq!(buf.len(), 0);
+    }
+
+    #[test]
+    fn input_buffer_len_increments() {
+        let mut buf = InputBuffer::default();
+        buf.push(BufferedInput::Draw);
+        assert_eq!(buf.len(), 1);
+        buf.push(BufferedInput::Undo);
+        assert_eq!(buf.len(), 2);
+    }
+
+    #[test]
+    fn hover_state_default_has_no_entity() {
+        let state = HoverState::default();
+        assert!(state.entity.is_none());
+        assert_eq!(state.scale, 0.0);
+    }
+}

solitaire_engine/src/card_animation/mod.rs

@@ -0,0 +1,390 @@
+//! `CardAnimationPlugin` — curve-based card animation system.
+//!
+//! # Quick start
+//!
+//! Register the plugin alongside the existing animation plugins:
+//!
+//! ```ignore
+//! app.add_plugins((
+//!     AnimationPlugin,       // existing: drives CardAnim (linear)
+//!     FeedbackAnimPlugin,    // existing: shake + settle
+//!     CardAnimationPlugin,   // new: curve-based CardAnimation
+//! ));
+//! ```
+//!
+//! Spawn a card with a `CardAnimation` component:
+//!
+//! ```ignore
+//! use solitaire_engine::card_animation::{CardAnimation, MotionCurve};
+//!
+//! commands.spawn((
+//!     SpriteBundle { /* ... */ },
+//!     CardAnimation::slide(
+//!         Vec2::new(0.0, 0.0),    // start xy
+//!         0.0,                    // start z
+//!         Vec2::new(300.0, 200.0),// end xy
+//!         5.0,                    // end z (resting)
+//!         MotionCurve::SmoothSnap,
+//!     )
+//!     .with_z_lift(12.0)          // floats up during motion
+//!     .with_delay(0.03),          // stagger delay
+//! ));
+//! ```
+//!
+//! Retarget a card mid-flight:
+//!
+//! ```ignore
+//! use solitaire_engine::card_animation::retarget_animation;
+//!
+//! fn handle_drop(
+//!     mut commands: Commands,
+//!     q: Query<(Entity, &Transform, Option<&CardAnimation>), With<CardEntity>>,
+//! ) {
+//!     let (entity, transform, anim) = q.get(card_entity).unwrap();
+//!     retarget_animation(
+//!         &mut commands,
+//!         entity,
+//!         anim,
+//!         transform,
+//!         new_target_xy,
+//!         new_target_z,
+//!         MotionCurve::SmoothSnap,
+//!     );
+//! }
+//! ```
+//!
+//! # Win cascade with `Expressive` curve
+//!
+//! The existing `AnimationPlugin` drives the win cascade with `CardAnim`
+//! (linear). To use the curve-based cascade instead, disable
+//! `handle_win_cascade` in `AnimationPlugin` and register `WinCascadePlugin`
+//! (declared below) which uses `CardAnimation` + `MotionCurve::Expressive`.
+//!
+//! They **must not both be active** — both write to `Transform` on the same
+//! 52 entities and will race.
+//!
+//! # Coexistence rules
+//!
+//! | Condition | Safe? |
+//! |---|---|
+//! | `CardAnim` and `CardAnimation` on **different** entities | ✓ |
+//! | `CardAnim` and `CardAnimation` on the **same** entity | ✗ |
+//! | `HoverState` scale + `CardAnimation` scale on same entity | ✓ (CardAnimation takes priority — hover skipped via `Without<CardAnimation>` filter) |
+//! | `apply_drag_visual` scale + `CardAnimation` scale | ✓ (same filter) |
+
+pub mod animation;
+pub mod curves;
+pub mod interaction;
+pub mod timing;
+
+pub use animation::{retarget_animation, win_scatter_targets, CardAnimation};
+pub use curves::{sample_curve, MotionCurve};
+pub use interaction::{BufferedInput, HoverState, InputBuffer};
+pub use timing::{
+    cascade_delay, compute_duration, micro_vary, DEAL_INTERVAL_SECS, MAX_DURATION_SECS,
+    MIN_DURATION_SECS, WIN_CASCADE_INTERVAL_SECS,
+};
+
+use bevy::prelude::*;
+
+use crate::card_plugin::CardEntity;
+use crate::events::{DrawRequestEvent, GameWonEvent, MoveRequestEvent, UndoRequestEvent};
+use crate::game_plugin::GameMutation;
+use crate::layout::LayoutResource;
+use crate::resources::DragState;
+
+use animation::advance_card_animations;
+use interaction::{apply_drag_visual, apply_hover_scale, detect_hover, drain_input_buffer};
+
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+
+/// Registers all systems, resources, and components for curve-based card
+/// animation, hover visuals, drag lift, and input buffering.
+///
+/// Safe to register alongside `AnimationPlugin` and `FeedbackAnimPlugin` as
+/// long as no single entity carries both `CardAnim` and `CardAnimation`.
+pub struct CardAnimationPlugin;
+
+impl Plugin for CardAnimationPlugin {
+    fn build(&self, app: &mut App) {
+        // Register events and resources that interaction systems depend on,
+        // idempotently — double-registration is safe in Bevy.
+        app.add_message::<MoveRequestEvent>()
+            .add_message::<DrawRequestEvent>()
+            .add_message::<UndoRequestEvent>()
+            .add_message::<GameWonEvent>()
+            .init_resource::<DragState>()
+            .init_resource::<HoverState>()
+            .init_resource::<InputBuffer>()
+            .add_systems(
+                Update,
+                (
+                    // Advance active animations (highest priority — runs first).
+                    advance_card_animations,
+                    // Interaction visuals (run after animation to read final positions).
+                    detect_hover,
+                    apply_hover_scale,
+                    apply_drag_visual,
+                    // Drain buffered inputs only when no animations remain.
+                    drain_input_buffer,
+                )
+                    .chain()
+                    .after(GameMutation),
+            );
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Optional: win cascade with Expressive curve
+// ---------------------------------------------------------------------------
+
+/// Optional plugin that replaces the linear win cascade in `AnimationPlugin`
+/// with an `Expressive`-curve cascade.
+///
+/// **Do not register this alongside `AnimationPlugin`'s win cascade** — they
+/// will race on the same card entities. To use this plugin, prevent
+/// `AnimationPlugin` from handling `GameWonEvent` (or remove it and manage
+/// win toasts manually).
+pub struct WinCascadePlugin;
+
+impl Plugin for WinCascadePlugin {
+    fn build(&self, app: &mut App) {
+        app.add_systems(
+            Update,
+            trigger_expressive_win_cascade.after(GameMutation),
+        );
+    }
+}
+
+/// Inserts `CardAnimation` (Expressive curve) on every card when `GameWonEvent` fires.
+///
+/// Cards scatter to 8 off-screen positions with per-card stagger. The z-lift
+/// creates a "burst" effect as cards fly outward.
+fn trigger_expressive_win_cascade(
+    mut events: MessageReader<GameWonEvent>,
+    cards: Query<(Entity, &Transform), With<CardEntity>>,
+    layout: Option<Res<LayoutResource>>,
+    mut commands: Commands,
+) {
+    if events.read().next().is_none() {
+        return;
+    }
+
+    let radius = layout
+        .as_ref()
+        .map_or(800.0, |l| l.0.card_size.x * 8.0);
+
+    let targets = win_scatter_targets(radius);
+
+    for (index, (entity, transform)) in cards.iter().enumerate() {
+        let start_xy = transform.translation.truncate();
+        let start_z = transform.translation.z;
+        let target = targets[index % targets.len()];
+
+        commands.entity(entity).insert(
+            CardAnimation::slide(start_xy, start_z, target, start_z + 60.0, MotionCurve::Expressive)
+                .with_delay(cascade_delay(index, WIN_CASCADE_INTERVAL_SECS))
+                .with_duration(0.65)
+                .with_z_lift(25.0),
+        );
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::animation_plugin::AnimationPlugin;
+    use crate::card_plugin::CardPlugin;
+    use crate::game_plugin::GamePlugin;
+    use crate::table_plugin::TablePlugin;
+
+    fn base_app() -> App {
+        let mut app = App::new();
+        app.add_plugins(MinimalPlugins)
+            .add_plugins(GamePlugin)
+            .add_plugins(TablePlugin)
+            .add_plugins(CardPlugin)
+            .add_plugins(AnimationPlugin)
+            .add_plugins(CardAnimationPlugin);
+        app.update();
+        app
+    }
+
+    #[test]
+    fn plugin_registers_hover_state() {
+        let app = base_app();
+        assert!(
+            app.world().get_resource::<HoverState>().is_some(),
+            "HoverState resource must be registered"
+        );
+    }
+
+    #[test]
+    fn plugin_registers_input_buffer() {
+        let app = base_app();
+        assert!(
+            app.world().get_resource::<InputBuffer>().is_some(),
+            "InputBuffer resource must be registered"
+        );
+    }
+
+    #[test]
+    fn card_animation_advances_and_removes_itself() {
+        let mut app = App::new();
+        app.add_plugins(MinimalPlugins).add_plugins(CardAnimationPlugin);
+
+        let start = Vec2::new(0.0, 0.0);
+        let end = Vec2::new(100.0, 0.0);
+        let entity = app
+            .world_mut()
+            .spawn((
+                Transform::from_translation(start.extend(0.0)),
+                CardAnimation {
+                    start,
+                    end,
+                    elapsed: 0.99,
+                    duration: 1.0,
+                    curve: MotionCurve::Responsive,
+                    delay: 0.0,
+                    start_z: 0.0,
+                    end_z: 0.0,
+                    z_lift: 0.0,
+                    scale_start: 1.0,
+                    scale_end: 1.0,
+                },
+            ))
+            .id();
+
+        app.update();
+
+        // After one update at elapsed=0.99, component should still be present.
+        // We can't advance time reliably in MinimalPlugins, but we can check
+        // that the advance_card_animations system processed the component
+        // (pos moved closer to end).
+        let transform = app.world().entity(entity).get::<Transform>().unwrap();
+        assert!(
+            transform.translation.x > 50.0,
+            "card should have moved past midpoint by elapsed=0.99, got x={}",
+            transform.translation.x
+        );
+    }
+
+    #[test]
+    fn card_animation_instant_snaps_on_zero_duration() {
+        let mut app = App::new();
+        app.add_plugins(MinimalPlugins).add_plugins(CardAnimationPlugin);
+
+        let end = Vec2::new(200.0, 100.0);
+        let entity = app
+            .world_mut()
+            .spawn((
+                Transform::from_translation(Vec3::ZERO),
+                CardAnimation {
+                    start: Vec2::ZERO,
+                    end,
+                    elapsed: 0.0,
+                    duration: 0.0, // zero duration → instant snap
+                    curve: MotionCurve::SmoothSnap,
+                    delay: 0.0,
+                    start_z: 0.0,
+                    end_z: 5.0,
+                    z_lift: 0.0,
+                    scale_start: 1.0,
+                    scale_end: 1.0,
+                },
+            ))
+            .id();
+
+        app.update();
+
+        assert!(
+            app.world().entity(entity).get::<CardAnimation>().is_none(),
+            "zero-duration animation must be removed after one update"
+        );
+        let transform = app.world().entity(entity).get::<Transform>().unwrap();
+        assert!(
+            (transform.translation.x - 200.0).abs() < 1e-3,
+            "card must snap to end.x"
+        );
+        assert!(
+            (transform.translation.y - 100.0).abs() < 1e-3,
+            "card must snap to end.y"
+        );
+        assert!(
+            (transform.translation.z - 5.0).abs() < 1e-3,
+            "card must snap to end_z"
+        );
+    }
+
+    #[test]
+    fn card_animation_respects_delay() {
+        let mut app = App::new();
+        app.add_plugins(MinimalPlugins).add_plugins(CardAnimationPlugin);
+
+        let entity = app
+            .world_mut()
+            .spawn((
+                Transform::from_translation(Vec3::ZERO),
+                CardAnimation {
+                    start: Vec2::ZERO,
+                    end: Vec2::new(100.0, 0.0),
+                    elapsed: 0.0,
+                    duration: 0.15,
+                    curve: MotionCurve::SmoothSnap,
+                    delay: 100.0, // huge delay — card must not move
+                    start_z: 0.0,
+                    end_z: 0.0,
+                    z_lift: 0.0,
+                    scale_start: 1.0,
+                    scale_end: 1.0,
+                },
+            ))
+            .id();
+
+        app.update();
+
+        let transform = app.world().entity(entity).get::<Transform>().unwrap();
+        assert!(
+            transform.translation.x.abs() < 1e-3,
+            "card must not move during delay, got x={}",
+            transform.translation.x
+        );
+    }
+
+    #[test]
+    fn input_buffer_push_and_drain_ordering() {
+        let mut buf = InputBuffer::default();
+        buf.push(BufferedInput::Draw);
+        buf.push(BufferedInput::Undo);
+        // FIFO: Draw comes out first.
+        assert!(matches!(buf.queue.pop_front().unwrap(), BufferedInput::Draw));
+        assert!(matches!(buf.queue.pop_front().unwrap(), BufferedInput::Undo));
+    }
+
+    #[test]
+    fn hover_state_initialises_without_entity() {
+        let state = HoverState::default();
+        assert!(state.entity.is_none());
+    }
+
+    #[test]
+    fn win_scatter_produces_eight_distinct_points() {
+        let targets = win_scatter_targets(600.0);
+        assert_eq!(targets.len(), 8);
+        // All must be different.
+        for i in 0..8 {
+            for j in (i + 1)..8 {
+                assert_ne!(
+                    targets[i], targets[j],
+                    "scatter targets {i} and {j} must be distinct"
+                );
+            }
+        }
+    }
+}

solitaire_engine/src/card_animation/timing.rs

@@ -0,0 +1,152 @@
+//! Distance-based duration calculation and stagger utilities.
+//!
+//! All functions are pure (no Bevy dependency) and can be tested in isolation.
+
+/// Minimum animation duration — applied to very short or zero-distance moves.
+pub const MIN_DURATION_SECS: f32 = 0.12;
+
+/// Hard cap on animation duration regardless of distance.
+pub const MAX_DURATION_SECS: f32 = 0.35;
+
+/// Sqrt scale factor calibrated so a 600-pixel move hits `MAX_DURATION_SECS`:
+/// `MIN + √600 × SCALE ≈ 0.35 s`.
+const SQRT_SCALE: f32 = 0.0094;
+
+/// Micro-variation amplitude: ±0.4 % of the computed duration.
+///
+/// Small enough to be imperceptible in isolation but enough to break the
+/// "robotic" uniformity when many cards animate simultaneously.
+const MICRO_VARY_AMPLITUDE: f32 = 0.004;
+
+/// Computes animation duration from a pixel distance using square-root scaling.
+///
+/// Square-root growth keeps short moves feeling instant while preventing long
+/// moves from feeling excessively slow.
+///
+/// | Distance | Duration  |
+/// |----------|-----------|
+/// | 25 px    | ~0.17 s   |
+/// | 100 px   | ~0.21 s   |
+/// | 300 px   | ~0.28 s   |
+/// | 600 px   | ~0.35 s   |
+/// | 1200 px  | ~0.35 s ← capped |
+#[inline]
+pub fn compute_duration(distance: f32) -> f32 {
+    (MIN_DURATION_SECS + distance.abs().sqrt() * SQRT_SCALE).min(MAX_DURATION_SECS)
+}
+
+/// Applies a deterministic ±0.4 % micro-variation to `duration`.
+///
+/// `entity_index` should be a stable per-entity value (e.g. `Entity::index()`).
+/// The same index always produces the same variation so animations don't
+/// change between frames.
+#[inline]
+pub fn micro_vary(duration: f32, entity_index: u32) -> f32 {
+    // Multiplicative Fibonacci hash — cheap, decent distribution.
+    let hash = entity_index.wrapping_mul(2_654_435_761);
+    let noise = (hash >> 16) as f32 / 65_536.0; // 0.0 ..= 1.0
+    let variation = (noise - 0.5) * 2.0 * MICRO_VARY_AMPLITUDE;
+    duration * (1.0 + variation)
+}
+
+/// Returns the pre-animation delay for card at `index` in a staggered cascade.
+///
+/// `delay = index × interval_secs`.
+#[inline]
+pub fn cascade_delay(index: usize, interval_secs: f32) -> f32 {
+    index as f32 * interval_secs
+}
+
+/// Recommended per-card interval for the win cascade (Normal speed).
+pub const WIN_CASCADE_INTERVAL_SECS: f32 = 0.018;
+
+/// Recommended per-card interval for deal animations (Normal speed).
+pub const DEAL_INTERVAL_SECS: f32 = 0.022;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn zero_distance_gives_minimum_duration() {
+        assert!(
+            (compute_duration(0.0) - MIN_DURATION_SECS).abs() < 1e-5,
+            "zero distance must yield MIN_DURATION_SECS"
+        );
+    }
+
+    #[test]
+    fn large_distance_is_capped() {
+        assert!(
+            (compute_duration(10_000.0) - MAX_DURATION_SECS).abs() < 1e-5,
+            "very large distance must be capped at MAX_DURATION_SECS"
+        );
+    }
+
+    #[test]
+    fn duration_increases_monotonically() {
+        let mut prev = 0.0f32;
+        for d in [10, 50, 100, 200, 400, 600] {
+            let dur = compute_duration(d as f32);
+            assert!(dur >= prev, "duration must be monotone: d={d} dur={dur} prev={prev}");
+            prev = dur;
+        }
+    }
+
+    #[test]
+    fn duration_is_within_bounds() {
+        for d in [0, 1, 25, 100, 300, 600, 1200] {
+            let dur = compute_duration(d as f32);
+            assert!(
+                (MIN_DURATION_SECS..=MAX_DURATION_SECS).contains(&dur),
+                "duration out of bounds for d={d}: {dur}"
+            );
+        }
+    }
+
+    #[test]
+    fn micro_vary_stays_within_tolerance() {
+        for i in 0..=1000u32 {
+            let base = 0.25;
+            let varied = micro_vary(base, i);
+            let ratio = (varied - base).abs() / base;
+            assert!(
+                ratio <= MICRO_VARY_AMPLITUDE + 1e-6,
+                "variation for index {i} exceeds amplitude: ratio={ratio}"
+            );
+        }
+    }
+
+    #[test]
+    fn micro_vary_is_deterministic() {
+        let a = micro_vary(0.2, 42);
+        let b = micro_vary(0.2, 42);
+        assert!((a - b).abs() < 1e-9, "micro_vary must be deterministic");
+    }
+
+    #[test]
+    fn micro_vary_differs_for_different_indices() {
+        let a = micro_vary(0.2, 1);
+        let b = micro_vary(0.2, 2);
+        // Very unlikely to be equal (would require hash collision mod 65536).
+        assert!((a - b).abs() > 1e-9, "micro_vary should differ for different indices");
+    }
+
+    #[test]
+    fn cascade_delay_zero_index_is_zero() {
+        assert_eq!(cascade_delay(0, 0.018), 0.0);
+    }
+
+    #[test]
+    fn cascade_delay_scales_linearly() {
+        let interval = 0.018;
+        for i in 0..52usize {
+            let expected = i as f32 * interval;
+            let actual = cascade_delay(i, interval);
+            assert!(
+                (actual - expected).abs() < 1e-6,
+                "cascade_delay({i}) = {actual}, expected {expected}"
+            );
+        }
+    }
+}

solitaire_engine/src/card_plugin.rs

@@ -82,11 +82,28 @@ pub struct HintHighlight {
     pub remaining: f32,
 }
 
+/// Countdown (seconds) until the `HintHighlight` on a card entity is removed.
+///
+/// Inserted alongside `HintHighlight` by the hint-visual system. When the timer
+/// reaches zero both `HintHighlight` and `HintHighlightTimer` are removed from
+/// the entity and the sprite colour is restored.
+#[derive(Component, Debug, Clone)]
+pub struct HintHighlightTimer(pub f32);
+
 /// Marker on a `PileMarker` entity that is highlighted because the right-clicked
 /// card can legally be placed there.
 #[derive(Component, Debug)]
 pub struct RightClickHighlight;
 
+/// Countdown (seconds) until this right-click destination highlight despawns.
+///
+/// Inserted alongside `RightClickHighlight` so that highlights auto-clear after
+/// 1.5 s even if the player does not make a move or click again. The existing
+/// clear-on-state-change and clear-on-pause logic still fires early when
+/// appropriate.
+#[derive(Component, Debug, Clone)]
+pub struct RightClickHighlightTimer(pub f32);
+
 /// Marker placed on the child `Text2d` entity that shows "↺" on the stock pile
 /// marker when the stock pile is empty.
 #[derive(Component, Debug)]
@@ -140,9 +157,9 @@ impl Plugin for CardPlugin {
         // `MinimalPlugins` (tests) this resource is absent by default, so we
         // ensure it exists here. Under `DefaultPlugins` the call is a no-op.
         app.init_resource::<ButtonInput<MouseButton>>()
-            .add_event::<SettingsChangedEvent>()
-            .add_event::<CardFlippedEvent>()
-            .add_event::<CardFaceRevealedEvent>()
+            .add_message::<SettingsChangedEvent>()
+            .add_message::<CardFlippedEvent>()
+            .add_message::<CardFaceRevealedEvent>()
             .add_systems(PostStartup, (sync_cards_startup, update_stock_empty_indicator_startup))
             .add_systems(
                 Update,
@@ -154,6 +171,7 @@ impl Plugin for CardPlugin {
                     update_drag_shadow,
                     tick_hint_highlight,
                     handle_right_click,
+                    tick_right_click_highlights,
                     clear_right_click_highlights_on_state_change.after(GameMutation),
                     clear_right_click_highlights_on_pause,
                     update_stock_empty_indicator.after(GameMutation),
@@ -165,11 +183,11 @@ impl Plugin for CardPlugin {
 /// When card-back selection changes in Settings, re-render all cards so the
 /// new back colour is applied immediately (without waiting for a state change).
 fn resync_cards_on_settings_change(
-    mut setting_events: EventReader<SettingsChangedEvent>,
-    mut state_events: EventWriter<StateChangedEvent>,
+    mut setting_events: MessageReader<SettingsChangedEvent>,
+    mut state_events: MessageWriter<StateChangedEvent>,
 ) {
     if setting_events.read().next().is_some() {
-        state_events.send(StateChangedEvent);
+        state_events.write(StateChangedEvent);
     }
 }
 
@@ -195,7 +213,7 @@ fn sync_cards_startup(
 }
 
 fn sync_cards_on_change(
-    mut events: EventReader<StateChangedEvent>,
+    mut events: MessageReader<StateChangedEvent>,
     commands: Commands,
     game: Res<GameStateResource>,
     layout: Option<Res<LayoutResource>>,
@@ -238,7 +256,7 @@ fn sync_cards(
     // Despawn any entity whose card is no longer tracked.
     for (card_id, (entity, _)) in &existing {
         if !live_ids.contains(card_id) {
-            commands.entity(*entity).despawn_recursive();
+            commands.entity(*entity).despawn();
         }
     }
 
@@ -425,7 +443,7 @@ fn update_card_entity(
 
     // Despawn the old label child and respawn a fresh one, so rank/suit/
     // colour/visibility all stay in sync with the card's current state.
-    commands.entity(entity).despawn_descendants();
+    commands.entity(entity).despawn_related::<Children>();
     commands.entity(entity).with_children(|b| {
         b.spawn((
             CardLabel,
@@ -490,7 +508,7 @@ fn label_visibility(card: &Card) -> Visibility {
 ///
 /// Skipped when `EffectiveSlideDuration::slide_secs == 0.0` (Instant speed).
 fn start_flip_anim(
-    mut events: EventReader<CardFlippedEvent>,
+    mut events: MessageReader<CardFlippedEvent>,
     slide_dur: Option<Res<EffectiveSlideDuration>>,
     mut commands: Commands,
     card_entities: Query<(Entity, &CardEntity)>,
@@ -525,7 +543,7 @@ fn tick_flip_anim(
     mut commands: Commands,
     time: Res<Time>,
     mut anims: Query<(Entity, &CardEntity, &mut Transform, &mut CardFlipAnim)>,
-    mut reveal_events: EventWriter<CardFaceRevealedEvent>,
+    mut reveal_events: MessageWriter<CardFaceRevealedEvent>,
 ) {
     let dt = time.delta_secs();
     for (entity, card_entity, mut transform, mut anim) in &mut anims {
@@ -540,7 +558,7 @@ fn tick_flip_anim(
                     transform.scale.x = 0.0;
                     // Fire the reveal event exactly once, at the phase transition,
                     // so the flip sound is synchronised with the visual face reveal.
-                    reveal_events.send(CardFaceRevealedEvent(card_entity.card_id));
+                    reveal_events.write(CardFaceRevealedEvent(card_entity.card_id));
                 }
             }
             FlipPhase::ScalingUp => {
@@ -574,7 +592,7 @@ fn update_drag_shadow(
     if drag.is_idle() {
         // No drag in progress — remove shadow if it exists.
         if let Some(e) = shadow.take() {
-            commands.entity(e).despawn_recursive();
+            commands.entity(e).despawn();
         }
         return;
     }
@@ -627,7 +645,8 @@ fn update_drag_shadow(
 // ---------------------------------------------------------------------------
 
 /// Counts down `HintHighlight::remaining` each frame. When it reaches zero,
-/// removes the component and resets the card sprite to its normal face-up colour.
+/// removes both `HintHighlight` and `HintHighlightTimer` (if present) and
+/// resets the card sprite to its normal face-up colour.
 fn tick_hint_highlight(
     time: Res<Time>,
     mut commands: Commands,
@@ -649,7 +668,10 @@ fn tick_hint_highlight(
             } else {
                 card_back_colour(back_idx)
             };
-            commands.entity(entity).remove::<HintHighlight>();
+            commands
+                .entity(entity)
+                .remove::<HintHighlight>()
+                .remove::<HintHighlightTimer>();
         }
     }
 }
@@ -664,6 +686,37 @@ const RIGHT_CLICK_HIGHLIGHT_COLOUR: Color = Color::srgba(0.2, 0.8, 0.2, 0.6);
 /// Restored color for `PileMarker` sprites when the highlight is cleared.
 const PILE_MARKER_DEFAULT_COLOUR: Color = Color::srgba(1.0, 1.0, 1.0, 0.08);
 
+/// Counts down `RightClickHighlightTimer` each frame and clears the highlight
+/// when the timer expires.
+///
+/// This is a fallback expiry: highlights also clear immediately on
+/// `StateChangedEvent` (move made) or when the game is paused, whichever comes
+/// first. The 1.5 s timer ensures highlights always disappear even if the
+/// player takes no further action.
+fn tick_right_click_highlights(
+    mut commands: Commands,
+    time: Res<Time>,
+    paused: Option<Res<PausedResource>>,
+    mut highlights: Query<(Entity, &mut RightClickHighlightTimer, &mut Sprite), With<RightClickHighlight>>,
+) {
+    if paused.is_some_and(|p| p.0) {
+        return;
+    }
+    let dt = time.delta_secs();
+    for (entity, mut timer, mut sprite) in &mut highlights {
+        timer.0 -= dt;
+        if timer.0 <= 0.0 {
+            // Restore the pile marker to its default colour before removing
+            // the highlight marker component.
+            sprite.color = PILE_MARKER_DEFAULT_COLOUR;
+            commands
+                .entity(entity)
+                .remove::<RightClickHighlight>()
+                .remove::<RightClickHighlightTimer>();
+        }
+    }
+}
+
 /// Removes the `RightClickHighlight` marker from every highlighted pile and
 /// resets its sprite colour to `PILE_MARKER_DEFAULT_COLOUR`.
 ///
@@ -689,7 +742,7 @@ fn clear_right_click_highlights(
 ///
 /// This ensures stale highlights do not linger after a card is moved.
 fn clear_right_click_highlights_on_state_change(
-    mut events: EventReader<StateChangedEvent>,
+    mut events: MessageReader<StateChangedEvent>,
     mut commands: Commands,
     highlighted: Query<Entity, With<RightClickHighlight>>,
     mut pile_markers: Query<(Entity, &PileMarker, &mut Sprite)>,
@@ -781,7 +834,10 @@ fn handle_right_click(
         };
         if legal {
             sprite.color = RIGHT_CLICK_HIGHLIGHT_COLOUR;
-            commands.entity(entity).insert(RightClickHighlight);
+            commands
+                .entity(entity)
+                .insert(RightClickHighlight)
+                .insert(RightClickHighlightTimer(1.5));
         }
     }
 }
@@ -791,9 +847,9 @@ fn cursor_world_pos(
     windows: &Query<&Window, With<bevy::window::PrimaryWindow>>,
     cameras: &Query<(&Camera, &GlobalTransform)>,
 ) -> Option<Vec2> {
-    let window = windows.get_single().ok()?;
+    let window = windows.single().ok()?;
     let cursor = window.cursor_position()?;
-    let (camera, camera_transform) = cameras.get_single().ok()?;
+    let (camera, camera_transform) = cameras.single().ok()?;
     camera.viewport_to_world_2d(camera_transform, cursor).ok()
 }
 
@@ -855,7 +911,7 @@ fn apply_stock_empty_indicator(
     commands: &mut Commands,
     game: &GameState,
     pile_markers: &mut Query<(Entity, &PileMarker, &mut Sprite)>,
-    label_children: &Query<(Entity, &Parent), With<StockEmptyLabel>>,
+    label_children: &Query<(Entity, &ChildOf), With<StockEmptyLabel>>,
     layout: &Layout,
 ) {
     let stock_empty = game
@@ -875,7 +931,7 @@ fn apply_stock_empty_indicator(
             // Spawn the "↺" label only if one does not already exist.
             let already_has_label = label_children
                 .iter()
-                .any(|(_, parent)| parent.get() == entity);
+                .any(|(_, parent)| parent.parent() == entity);
             if !already_has_label {
                 let font_size = layout.card_size.x * 0.4;
                 commands.entity(entity).with_children(|b| {
@@ -894,8 +950,8 @@ fn apply_stock_empty_indicator(
 
             // Despawn any existing "↺" label children.
             for (label_entity, parent) in label_children.iter() {
-                if parent.get() == entity {
-                    commands.entity(label_entity).despawn_recursive();
+                if parent.parent() == entity {
+                    commands.entity(label_entity).despawn();
                 }
             }
         }
@@ -909,7 +965,7 @@ fn update_stock_empty_indicator_startup(
     game: Res<GameStateResource>,
     layout: Option<Res<LayoutResource>>,
     mut pile_markers: Query<(Entity, &PileMarker, &mut Sprite)>,
-    label_children: Query<(Entity, &Parent), With<StockEmptyLabel>>,
+    label_children: Query<(Entity, &ChildOf), With<StockEmptyLabel>>,
 ) {
     let Some(layout) = layout else { return };
     apply_stock_empty_indicator(
@@ -924,12 +980,12 @@ fn update_stock_empty_indicator_startup(
 /// Runs each `Update` tick when a `StateChangedEvent` arrives, keeping the
 /// stock pile marker dim state and "↺" label in sync with the current stock.
 fn update_stock_empty_indicator(
-    mut events: EventReader<StateChangedEvent>,
+    mut events: MessageReader<StateChangedEvent>,
     mut commands: Commands,
     game: Res<GameStateResource>,
     layout: Option<Res<LayoutResource>>,
     mut pile_markers: Query<(Entity, &PileMarker, &mut Sprite)>,
-    label_children: Query<(Entity, &Parent), With<StockEmptyLabel>>,
+    label_children: Query<(Entity, &ChildOf), With<StockEmptyLabel>>,
 ) {
     if events.read().next().is_none() {
         return;
@@ -1050,7 +1106,7 @@ mod tests {
         let mut app = app();
         // Trigger a draw, which moves a card from stock to waste and should
         // flip it face-up. Count visible labels after.
-        app.world_mut().send_event(crate::events::DrawRequestEvent);
+        app.world_mut().write_message(crate::events::DrawRequestEvent);
         app.update();
         // Now 1 card in waste (face-up), 23 in stock (face-down). So 24
         // hidden labels total in stock, plus 21 in tableau = 44.
@@ -1223,6 +1279,49 @@ mod tests {
         assert_ne!(FlipPhase::ScalingDown, FlipPhase::ScalingUp);
     }
 
+    // -----------------------------------------------------------------------
+    // Task #5 — RightClickHighlightTimer pure-function tests
+    // -----------------------------------------------------------------------
+
+    /// Verify that a freshly-created timer with 1.5 s has a positive countdown
+    /// and has not yet expired.
+    #[test]
+    fn right_click_highlight_timer_starts_positive() {
+        let timer = RightClickHighlightTimer(1.5);
+        assert!(
+            timer.0 > 0.0,
+            "timer must start with a positive countdown, got {}",
+            timer.0
+        );
+    }
+
+    /// Simulate ticking the timer by a delta that exceeds its initial value and
+    /// verify the resulting value is ≤ 0 (expiry condition).
+    #[test]
+    fn right_click_highlight_timer_expires_after_sufficient_ticks() {
+        let mut remaining = 1.5_f32;
+        // Tick by more than the initial value to ensure expiry.
+        remaining -= 2.0;
+        assert!(
+            remaining <= 0.0,
+            "timer must be expired (≤ 0) after 2.0 s tick on a 1.5 s timer, got {}",
+            remaining
+        );
+    }
+
+    /// Simulate ticking by less than the initial value and verify the timer is
+    /// still positive (not yet expired).
+    #[test]
+    fn right_click_highlight_timer_not_expired_before_duration() {
+        let mut remaining = 1.5_f32;
+        remaining -= 0.5; // only 0.5 s elapsed
+        assert!(
+            remaining > 0.0,
+            "timer must still be positive after only 0.5 s on a 1.5 s timer, got {}",
+            remaining
+        );
+    }
+
     #[test]
     fn facedown_cards_use_tighter_fan_than_uniform_faceup_fan() {
         let g = GameState::new(42, solitaire_core::game_state::DrawMode::DrawOne);

solitaire_engine/src/challenge_plugin.rs

@@ -18,7 +18,7 @@ pub const CHALLENGE_UNLOCK_LEVEL: u32 = 5;
 
 /// Fired when the player has just completed a Challenge-mode game and the
 /// `challenge_index` cursor advances.
-#[derive(Event, Debug, Clone, Copy)]
+#[derive(Message, Debug, Clone, Copy)]
 pub struct ChallengeAdvancedEvent {
     pub previous_index: u32,
     pub new_index: u32,
@@ -28,10 +28,10 @@ pub struct ChallengePlugin;
 
 impl Plugin for ChallengePlugin {
     fn build(&self, app: &mut App) {
-        app.add_event::<ChallengeAdvancedEvent>()
-            .add_event::<GameWonEvent>()
-            .add_event::<NewGameRequestEvent>()
-            .add_event::<InfoToastEvent>()
+        app.add_message::<ChallengeAdvancedEvent>()
+            .add_message::<GameWonEvent>()
+            .add_message::<NewGameRequestEvent>()
+            .add_message::<InfoToastEvent>()
             // Run after ProgressUpdate so we don't fight ProgressPlugin's add_xp.
             .add_systems(Update, advance_on_challenge_win.after(ProgressUpdate))
             .add_systems(Update, handle_start_challenge_request.before(GameMutation));
@@ -39,12 +39,12 @@ impl Plugin for ChallengePlugin {
 }
 
 fn advance_on_challenge_win(
-    mut wins: EventReader<GameWonEvent>,
+    mut wins: MessageReader<GameWonEvent>,
     game: Res<GameStateResource>,
     mut progress: ResMut<ProgressResource>,
     path: Res<ProgressStoragePath>,
-    mut advanced: EventWriter<ChallengeAdvancedEvent>,
-    mut toast: EventWriter<InfoToastEvent>,
+    mut advanced: MessageWriter<ChallengeAdvancedEvent>,
+    mut toast: MessageWriter<InfoToastEvent>,
 ) {
     for _ in wins.read() {
         if game.0.mode != GameMode::Challenge {
@@ -59,8 +59,8 @@ fn advance_on_challenge_win(
         }
         // Human-readable level is 1-based (index 0 → "Challenge 1").
         let level_number = prev.saturating_add(1);
-        toast.send(InfoToastEvent(format!("Challenge {level_number} complete!")));
-        advanced.send(ChallengeAdvancedEvent {
+        toast.write(InfoToastEvent(format!("Challenge {level_number} complete!")));
+        advanced.write(ChallengeAdvancedEvent {
             previous_index: prev,
             new_index: progress.0.challenge_index,
         });
@@ -70,14 +70,14 @@ fn advance_on_challenge_win(
 fn handle_start_challenge_request(
     keys: Res<ButtonInput<KeyCode>>,
     progress: Res<ProgressResource>,
-    mut new_game: EventWriter<NewGameRequestEvent>,
-    mut info_toast: EventWriter<InfoToastEvent>,
+    mut new_game: MessageWriter<NewGameRequestEvent>,
+    mut info_toast: MessageWriter<InfoToastEvent>,
 ) {
     if !keys.just_pressed(KeyCode::KeyX) {
         return;
     }
     if progress.0.level < CHALLENGE_UNLOCK_LEVEL {
-        info_toast.send(InfoToastEvent(format!(
+        info_toast.write(InfoToastEvent(format!(
             "Challenge mode unlocks at level {CHALLENGE_UNLOCK_LEVEL}"
         )));
         return;
@@ -86,7 +86,7 @@ fn handle_start_challenge_request(
         warn!("challenge seed list is empty");
         return;
     };
-    new_game.send(NewGameRequestEvent {
+    new_game.write(NewGameRequestEvent {
         seed: Some(seed),
         mode: Some(GameMode::Challenge),
     });
@@ -124,7 +124,7 @@ mod tests {
         app.world_mut().resource_mut::<GameStateResource>().0 =
             GameState::new_with_mode(1, DrawMode::DrawOne, GameMode::Challenge);
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 100,
         });
@@ -133,7 +133,7 @@ mod tests {
         let p = &app.world().resource::<ProgressResource>().0;
         assert_eq!(p.challenge_index, 1);
 
-        let events = app.world().resource::<Events<ChallengeAdvancedEvent>>();
+        let events = app.world().resource::<Messages<ChallengeAdvancedEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).copied().collect();
         assert_eq!(fired.len(), 1);
@@ -145,7 +145,7 @@ mod tests {
     fn classic_win_does_not_advance_challenge_index() {
         let mut app = headless_app();
         // Default GameStateResource is Classic mode.
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 100,
         });
@@ -154,7 +154,7 @@ mod tests {
         let p = &app.world().resource::<ProgressResource>().0;
         assert_eq!(p.challenge_index, 0);
 
-        let events = app.world().resource::<Events<ChallengeAdvancedEvent>>();
+        let events = app.world().resource::<Messages<ChallengeAdvancedEvent>>();
         let mut cursor = events.get_cursor();
         assert!(cursor.read(events).next().is_none());
     }
@@ -168,7 +168,7 @@ mod tests {
             .press(KeyCode::KeyX);
         app.update();
 
-        let events = app.world().resource::<Events<NewGameRequestEvent>>();
+        let events = app.world().resource::<Messages<NewGameRequestEvent>>();
         let mut cursor = events.get_cursor();
         assert!(cursor.read(events).next().is_none());
     }
@@ -188,7 +188,7 @@ mod tests {
             .press(KeyCode::KeyX);
         app.update();
 
-        let events = app.world().resource::<Events<NewGameRequestEvent>>();
+        let events = app.world().resource::<Messages<NewGameRequestEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).copied().collect();
         assert_eq!(fired.len(), 1);
@@ -211,13 +211,13 @@ mod tests {
         app.world_mut().resource_mut::<GameStateResource>().0 =
             GameState::new_with_mode(1, DrawMode::DrawOne, GameMode::Challenge);
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 100,
         });
         app.update();
 
-        let events = app.world().resource::<Events<InfoToastEvent>>();
+        let events = app.world().resource::<Messages<InfoToastEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).collect();
         assert_eq!(fired.len(), 1, "exactly one toast must fire on challenge win");
@@ -231,13 +231,13 @@ mod tests {
     fn classic_win_does_not_fire_challenge_complete_toast() {
         let mut app = headless_app();
         // Default mode is Classic.
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 100,
         });
         app.update();
 
-        let events = app.world().resource::<Events<InfoToastEvent>>();
+        let events = app.world().resource::<Messages<InfoToastEvent>>();
         let mut cursor = events.get_cursor();
         assert!(
             cursor.read(events).next().is_none(),
@@ -254,7 +254,7 @@ mod tests {
             .press(KeyCode::KeyX);
         app.update();
 
-        let events = app.world().resource::<Events<InfoToastEvent>>();
+        let events = app.world().resource::<Messages<InfoToastEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).collect();
         assert_eq!(fired.len(), 1, "must show a toast explaining the lock");

solitaire_engine/src/cursor_plugin.rs

@@ -12,8 +12,7 @@
 //!   The tint is cleared to default the frame the drag ends.
 
 use bevy::prelude::*;
-use bevy::window::{PrimaryWindow, SystemCursorIcon};
-use bevy::winit::cursor::CursorIcon;
+use bevy::window::{CursorIcon, PrimaryWindow, SystemCursorIcon};
 use solitaire_core::card::Suit;
 use solitaire_core::game_state::{DrawMode, GameState};
 use solitaire_core::pile::PileType;
@@ -52,7 +51,7 @@ fn update_cursor_icon(
     game: Option<Res<GameStateResource>>,
     mut commands: Commands,
 ) {
-    let Ok((win_entity, window)) = windows.get_single() else { return };
+    let Ok((win_entity, window)) = windows.single() else { return };
 
     if !drag.is_idle() {
         commands
@@ -63,7 +62,7 @@ fn update_cursor_icon(
 
     let hovering = (|| {
         let cursor = window.cursor_position()?;
-        let (camera, cam_xf) = cameras.get_single().ok()?;
+        let (camera, cam_xf) = cameras.single().ok()?;
         let world = camera.viewport_to_world_2d(cam_xf, cursor).ok()?;
         let layout = layout.as_ref()?.0.clone();
         let game = game.as_ref()?;
@@ -214,7 +213,6 @@ fn point_in_rect(point: Vec2, center: Vec2, size: Vec2) -> bool {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use solitaire_core::card::{Card, Rank};
 
     #[test]
     fn point_in_rect_center_is_inside() {

solitaire_engine/src/daily_challenge_plugin.rs

@@ -43,7 +43,7 @@ pub struct DailyChallengeResource {
 
 /// Fired when the player presses C to start the daily challenge.
 /// Carries the current goal description so it can be displayed as a toast.
-#[derive(Event, Debug, Clone)]
+#[derive(Message, Debug, Clone)]
 pub struct DailyGoalAnnouncementEvent(pub String);
 
 impl DailyChallengeResource {
@@ -60,7 +60,7 @@ impl DailyChallengeResource {
 }
 
 /// Fired when the player has just completed today's daily challenge.
-#[derive(Event, Debug, Clone, Copy)]
+#[derive(Message, Debug, Clone, Copy)]
 pub struct DailyChallengeCompletedEvent {
     pub date: NaiveDate,
     pub streak: u32,
@@ -77,11 +77,11 @@ impl Plugin for DailyChallengePlugin {
     fn build(&self, app: &mut App) {
         app.insert_resource(DailyChallengeResource::for_today())
             .init_resource::<DailyChallengeTask>()
-            .add_event::<DailyChallengeCompletedEvent>()
-            .add_event::<DailyGoalAnnouncementEvent>()
-            .add_event::<GameWonEvent>()
-            .add_event::<NewGameRequestEvent>()
-            .add_event::<XpAwardedEvent>()
+            .add_message::<DailyChallengeCompletedEvent>()
+            .add_message::<DailyGoalAnnouncementEvent>()
+            .add_message::<GameWonEvent>()
+            .add_message::<NewGameRequestEvent>()
+            .add_message::<XpAwardedEvent>()
             .add_systems(Startup, fetch_server_challenge)
             .add_systems(Update, poll_server_challenge)
             // record/award after the base ProgressUpdate so we don't fight
@@ -145,14 +145,14 @@ fn poll_server_challenge(
 
 #[allow(clippy::too_many_arguments)]
 fn handle_daily_completion(
-    mut wins: EventReader<GameWonEvent>,
+    mut wins: MessageReader<GameWonEvent>,
     daily: Res<DailyChallengeResource>,
     game: Res<GameStateResource>,
     mut progress: ResMut<ProgressResource>,
     path: Res<ProgressStoragePath>,
-    mut completed: EventWriter<DailyChallengeCompletedEvent>,
-    mut xp_awarded: EventWriter<XpAwardedEvent>,
-    mut toast: EventWriter<InfoToastEvent>,
+    mut completed: MessageWriter<DailyChallengeCompletedEvent>,
+    mut xp_awarded: MessageWriter<XpAwardedEvent>,
+    mut toast: MessageWriter<InfoToastEvent>,
 ) {
     for ev in wins.read() {
         if game.0.seed != daily.seed {
@@ -174,28 +174,28 @@ fn handle_daily_completion(
             continue;
         }
         progress.0.add_xp(DAILY_BONUS_XP);
-        xp_awarded.send(XpAwardedEvent { amount: DAILY_BONUS_XP });
+        xp_awarded.write(XpAwardedEvent { amount: DAILY_BONUS_XP });
         if let Some(target) = &path.0 {
             if let Err(e) = save_progress_to(target, &progress.0) {
                 warn!("failed to save progress after daily completion: {e}");
             }
         }
-        completed.send(DailyChallengeCompletedEvent {
+        completed.write(DailyChallengeCompletedEvent {
             date: daily.date,
             streak: progress.0.daily_challenge_streak,
         });
-        toast.send(InfoToastEvent("Daily challenge complete! +100 XP".to_string()));
+        toast.write(InfoToastEvent("Daily challenge complete! +100 XP".to_string()));
     }
 }
 
 fn handle_start_daily_request(
     keys: Res<ButtonInput<KeyCode>>,
     daily: Res<DailyChallengeResource>,
-    mut new_game: EventWriter<NewGameRequestEvent>,
-    mut announce: EventWriter<DailyGoalAnnouncementEvent>,
+    mut new_game: MessageWriter<NewGameRequestEvent>,
+    mut announce: MessageWriter<DailyGoalAnnouncementEvent>,
 ) {
     if keys.just_pressed(KeyCode::KeyC) {
-        new_game.send(NewGameRequestEvent {
+        new_game.write(NewGameRequestEvent {
             seed: Some(daily.seed),
             mode: None,
         });
@@ -203,7 +203,7 @@ fn handle_start_daily_request(
             .goal_description
             .clone()
             .unwrap_or_else(|| "Daily Challenge".to_string());
-        announce.send(DailyGoalAnnouncementEvent(desc));
+        announce.write(DailyGoalAnnouncementEvent(desc));
     }
 }
 
@@ -244,7 +244,7 @@ mod tests {
         app.world_mut().resource_mut::<GameStateResource>().0 =
             GameState::new(daily_seed, DrawMode::DrawOne);
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 200,
         });
@@ -255,7 +255,7 @@ mod tests {
         // +100 from the daily bonus
         assert!(progress.total_xp >= DAILY_BONUS_XP);
 
-        let events = app.world().resource::<Events<DailyChallengeCompletedEvent>>();
+        let events = app.world().resource::<Messages<DailyChallengeCompletedEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).copied().collect();
         assert_eq!(fired.len(), 1);
@@ -270,7 +270,7 @@ mod tests {
         app.world_mut().resource_mut::<GameStateResource>().0 =
             GameState::new(daily_seed.wrapping_add(7777), DrawMode::DrawOne);
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 200,
         });
@@ -279,7 +279,7 @@ mod tests {
         let progress = &app.world().resource::<ProgressResource>().0;
         assert_eq!(progress.daily_challenge_streak, 0);
 
-        let events = app.world().resource::<Events<DailyChallengeCompletedEvent>>();
+        let events = app.world().resource::<Messages<DailyChallengeCompletedEvent>>();
         let mut cursor = events.get_cursor();
         assert!(cursor.read(events).next().is_none());
     }
@@ -291,13 +291,13 @@ mod tests {
         app.world_mut().resource_mut::<GameStateResource>().0 =
             GameState::new(daily_seed, DrawMode::DrawOne);
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 200,
         });
         app.update();
         // Re-send win.
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 200,
         });
@@ -317,7 +317,7 @@ mod tests {
             .press(KeyCode::KeyC);
         app.update();
 
-        let events = app.world().resource::<Events<NewGameRequestEvent>>();
+        let events = app.world().resource::<Messages<NewGameRequestEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).copied().collect();
         assert_eq!(fired.len(), 1);
@@ -337,7 +337,7 @@ mod tests {
             .press(KeyCode::KeyC);
         app.update();
 
-        let events = app.world().resource::<Events<DailyGoalAnnouncementEvent>>();
+        let events = app.world().resource::<Messages<DailyGoalAnnouncementEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).cloned().collect();
         assert_eq!(fired.len(), 1);
@@ -355,7 +355,7 @@ mod tests {
             .press(KeyCode::KeyC);
         app.update();
 
-        let events = app.world().resource::<Events<DailyGoalAnnouncementEvent>>();
+        let events = app.world().resource::<Messages<DailyGoalAnnouncementEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).cloned().collect();
         assert_eq!(fired.len(), 1);

solitaire_engine/src/events.rs

@@ -1,13 +1,13 @@
 //! Cross-system events used by the engine's plugins.
 
-use bevy::prelude::Event;
+use bevy::prelude::Message;
 use solitaire_core::game_state::GameMode;
 use solitaire_core::pile::PileType;
 use solitaire_data::AchievementRecord;
 
 /// Request to move `count` cards from `from` to `to`. Fired by input systems,
 /// consumed by `GamePlugin`.
-#[derive(Event, Debug, Clone)]
+#[derive(Message, Debug, Clone)]
 pub struct MoveRequestEvent {
     pub from: PileType,
     pub to: PileType,
@@ -15,16 +15,16 @@ pub struct MoveRequestEvent {
 }
 
 /// Request to draw from the stock (or recycle waste when stock is empty).
-#[derive(Event, Debug, Clone, Copy, Default)]
+#[derive(Message, Debug, Clone, Copy, Default)]
 pub struct DrawRequestEvent;
 
 /// Request to undo the most recent state change.
-#[derive(Event, Debug, Clone, Copy, Default)]
+#[derive(Message, Debug, Clone, Copy, Default)]
 pub struct UndoRequestEvent;
 
 /// Request to start a new game. `seed = None` uses a system-time seed.
 /// `mode = None` reuses the current game's `GameMode`.
-#[derive(Event, Debug, Clone, Copy, Default)]
+#[derive(Message, Debug, Clone, Copy, Default)]
 pub struct NewGameRequestEvent {
     pub seed: Option<u64>,
     pub mode: Option<GameMode>,
@@ -32,13 +32,13 @@ pub struct NewGameRequestEvent {
 
 /// Fired by `GamePlugin` after any successful state mutation. Rendering and
 /// score-display systems listen for this to refresh.
-#[derive(Event, Debug, Clone, Copy, Default)]
+#[derive(Message, Debug, Clone, Copy, Default)]
 pub struct StateChangedEvent;
 
 /// Fired by input/UI systems when a player attempts to drop dragged cards
 /// on a real pile but the move violates the rules. Drives the
 /// `card_invalid.wav` SFX. Not fired for drops in empty space.
-#[derive(Event, Debug, Clone)]
+#[derive(Message, Debug, Clone)]
 pub struct MoveRejectedEvent {
     pub from: PileType,
     pub to: PileType,
@@ -46,14 +46,14 @@ pub struct MoveRejectedEvent {
 }
 
 /// Fired once when the active game transitions to won.
-#[derive(Event, Debug, Clone, Copy)]
+#[derive(Message, Debug, Clone, Copy)]
 pub struct GameWonEvent {
     pub score: i32,
     pub time_seconds: u64,
 }
 
 /// Fired when a card's face-up state changes during gameplay.
-#[derive(Event, Debug, Clone, Copy)]
+#[derive(Message, Debug, Clone, Copy)]
 pub struct CardFlippedEvent(pub u32);
 
 /// Fired by the flip animation at its midpoint — the instant the card face
@@ -62,37 +62,37 @@ pub struct CardFlippedEvent(pub u32);
 /// Audio systems should listen to this event rather than `CardFlippedEvent`
 /// so the flip sound is synchronised with the visual reveal, not the move
 /// that triggered the animation.
-#[derive(Event, Debug, Clone, Copy)]
+#[derive(Message, Debug, Clone, Copy)]
 pub struct CardFaceRevealedEvent(pub u32);
 
 /// Achievement unlocked notification carrying the full `AchievementRecord` for
 /// the newly unlocked achievement. Consumed by the toast renderer and any
 /// persistence/UI systems that need unlock metadata.
-#[derive(Event, Debug, Clone)]
+#[derive(Message, Debug, Clone)]
 pub struct AchievementUnlockedEvent(pub AchievementRecord);
 
 /// Request to manually trigger a sync pull from the active backend.
 ///
 /// Fired by the Settings panel "Sync Now" button. `SyncPlugin` responds by
 /// starting a new pull task if one is not already in flight.
-#[derive(Event, Debug, Clone, Copy, Default)]
+#[derive(Message, Debug, Clone, Copy, Default)]
 pub struct ManualSyncRequestEvent;
 
 /// Fired by `InputPlugin` when N is pressed while a game is in progress
 /// but confirmation has not yet been received. The animation plugin shows
 /// a "Press N again to confirm" toast. A second N press within the
 /// confirmation window sends `NewGameRequestEvent`.
-#[derive(Event, Debug, Clone, Copy, Default)]
+#[derive(Message, Debug, Clone, Copy, Default)]
 pub struct NewGameConfirmEvent;
 
 /// Generic informational toast message. Any system can fire this to display
 /// a short string to the player, e.g. "Locked — reach level 5".
-#[derive(Event, Debug, Clone)]
+#[derive(Message, Debug, Clone)]
 pub struct InfoToastEvent(pub String);
 
 /// Fired by `ProgressPlugin` immediately after awarding XP for a win so the
 /// animation layer can display a "+N XP" toast alongside the win cascade.
-#[derive(Event, Debug, Clone, Copy)]
+#[derive(Message, Debug, Clone, Copy)]
 pub struct XpAwardedEvent {
     pub amount: u64,
 }
@@ -100,5 +100,18 @@ pub struct XpAwardedEvent {
 /// Fired by `InputPlugin` when the player presses G to forfeit the current
 /// game. Consumed by `StatsPlugin` which records the abandoned game,
 /// persists stats, and starts a fresh deal.
-#[derive(Event, Debug, Clone, Copy, Default)]
+#[derive(Message, Debug, Clone, Copy, Default)]
 pub struct ForfeitEvent;
+
+/// Fired when the player requests a hint (H key). Carries the source card ID
+/// and destination pile for visual highlighting.
+///
+/// Consumed by `CardPlugin` (to apply `HintHighlight` on the card entity) and
+/// `TablePlugin` (to tint the destination `PileMarker` gold for 2 s).
+#[derive(Message, Debug, Clone)]
+pub struct HintVisualEvent {
+    /// The `Card::id` of the source card to be highlighted.
+    pub source_card_id: u32,
+    /// The destination pile whose `PileMarker` should be tinted gold.
+    pub dest_pile: solitaire_core::pile::PileType,
+}

solitaire_engine/src/feedback_anim_plugin.rs

@@ -184,7 +184,7 @@ impl Plugin for FeedbackAnimPlugin {
 /// Inserts `ShakeAnim` on all card entities belonging to the destination pile
 /// when a `MoveRejectedEvent` fires.
 fn start_shake_anim(
-    mut events: EventReader<MoveRejectedEvent>,
+    mut events: MessageReader<MoveRejectedEvent>,
     game: Res<GameStateResource>,
     card_entities: Query<(Entity, &CardEntity, &Transform)>,
     mut commands: Commands,
@@ -243,7 +243,7 @@ fn tick_shake_anim(
 /// Inserts `SettleAnim` on the top card of every non-empty pile when
 /// `StateChangedEvent` fires.
 fn start_settle_anim(
-    mut events: EventReader<StateChangedEvent>,
+    mut events: MessageReader<StateChangedEvent>,
     game: Res<GameStateResource>,
     card_entities: Query<(Entity, &CardEntity)>,
     mut commands: Commands,
@@ -304,7 +304,7 @@ fn tick_settle_anim(
 /// and fires the deal animation for every card entity currently in the world.
 /// The stagger is looked up from `SettingsResource` via `deal_stagger_secs_for_speed`.
 fn start_deal_anim(
-    mut events: EventReader<NewGameRequestEvent>,
+    mut events: MessageReader<NewGameRequestEvent>,
     layout: Option<Res<LayoutResource>>,
     game: Res<GameStateResource>,
     settings: Option<Res<SettingsResource>>,

solitaire_engine/src/game_plugin.rs

@@ -71,16 +71,16 @@ impl Plugin for GamePlugin {
             .insert_resource(GameStatePath(path))
             .init_resource::<DragState>()
             .init_resource::<SyncStatusResource>()
-            .add_event::<MoveRequestEvent>()
-            .add_event::<DrawRequestEvent>()
-            .add_event::<UndoRequestEvent>()
-            .add_event::<NewGameRequestEvent>()
-            .add_event::<StateChangedEvent>()
-            .add_event::<crate::events::MoveRejectedEvent>()
-            .add_event::<GameWonEvent>()
-            .add_event::<crate::events::CardFlippedEvent>()
-            .add_event::<crate::events::AchievementUnlockedEvent>()
-            .add_event::<InfoToastEvent>()
+            .add_message::<MoveRequestEvent>()
+            .add_message::<DrawRequestEvent>()
+            .add_message::<UndoRequestEvent>()
+            .add_message::<NewGameRequestEvent>()
+            .add_message::<StateChangedEvent>()
+            .add_message::<crate::events::MoveRejectedEvent>()
+            .add_message::<GameWonEvent>()
+            .add_message::<crate::events::CardFlippedEvent>()
+            .add_message::<crate::events::AchievementUnlockedEvent>()
+            .add_message::<InfoToastEvent>()
             .add_systems(
                 Update,
                 (
@@ -152,9 +152,9 @@ fn seed_from_system_time() -> u64 {
 #[allow(clippy::too_many_arguments)]
 fn handle_new_game(
     mut commands: Commands,
-    mut new_game: EventReader<NewGameRequestEvent>,
+    mut new_game: MessageReader<NewGameRequestEvent>,
     mut game: ResMut<GameStateResource>,
-    mut changed: EventWriter<StateChangedEvent>,
+    mut changed: MessageWriter<StateChangedEvent>,
     settings: Option<Res<crate::settings_plugin::SettingsResource>>,
     path: Option<Res<GameStatePath>>,
     confirm_screens: Query<Entity, With<ConfirmNewGameScreen>>,
@@ -169,7 +169,7 @@ fn handle_new_game(
         if needs_confirm && !confirm_already_open {
             // Despawn any stale game-over overlay before showing confirm dialog.
             for entity in &game_over_screens {
-                commands.entity(entity).despawn_recursive();
+                commands.entity(entity).despawn();
             }
             spawn_confirm_dialog(&mut commands, *ev);
             continue;
@@ -177,10 +177,10 @@ fn handle_new_game(
 
         // Despawn confirm and game-over overlays before starting the new game.
         for entity in &confirm_screens {
-            commands.entity(entity).despawn_recursive();
+            commands.entity(entity).despawn();
         }
         for entity in &game_over_screens {
-            commands.entity(entity).despawn_recursive();
+            commands.entity(entity).despawn();
         }
 
         let seed = ev.seed.unwrap_or_else(seed_from_system_time);
@@ -199,7 +199,7 @@ fn handle_new_game(
                 warn!("game_state: failed to delete saved game: {e}");
             }
         }
-        changed.send(StateChangedEvent);
+        changed.write(StateChangedEvent);
     }
 }
 
@@ -238,10 +238,10 @@ fn spawn_confirm_dialog(commands: &mut Commands, original_request: NewGameReques
                     row_gap: Val::Px(20.0),
                     min_width: Val::Px(360.0),
                     align_items: AlignItems::Center,
+                    border_radius: BorderRadius::all(Val::Px(12.0)),
                     ..default()
                 },
                 BackgroundColor(Color::srgb(0.10, 0.12, 0.15)),
-                BorderRadius::all(Val::Px(12.0)),
             ))
             .with_children(|card| {
                 // Heading
@@ -287,9 +287,9 @@ fn handle_confirm_input(
     mut commands: Commands,
     keys: Option<Res<ButtonInput<KeyCode>>>,
     screens: Query<(Entity, &OriginalNewGameRequest), With<ConfirmNewGameScreen>>,
-    mut new_game: EventWriter<NewGameRequestEvent>,
+    mut new_game: MessageWriter<NewGameRequestEvent>,
 ) {
-    let Ok((entity, original)) = screens.get_single() else {
+    let Ok((entity, original)) = screens.single() else {
         return;
     };
     let Some(keys) = keys else {
@@ -300,24 +300,24 @@ fn handle_confirm_input(
     let cancelled = keys.just_pressed(KeyCode::KeyN) || keys.just_pressed(KeyCode::Escape);
 
     if confirmed {
-        commands.entity(entity).despawn_recursive();
+        commands.entity(entity).despawn();
         // Re-send with move_count already 0 would bypass the dialog next time.
         // We fire the event — handle_new_game will skip the dialog because
         // the screen is despawned before the next read.
-        new_game.send(NewGameRequestEvent {
+        new_game.write(NewGameRequestEvent {
             seed: original.0.seed,
             mode: original.0.mode,
         });
     } else if cancelled {
-        commands.entity(entity).despawn_recursive();
+        commands.entity(entity).despawn();
     }
 }
 
 fn handle_draw(
-    mut draws: EventReader<DrawRequestEvent>,
+    mut draws: MessageReader<DrawRequestEvent>,
     mut game: ResMut<GameStateResource>,
-    mut changed: EventWriter<StateChangedEvent>,
-    mut flipped: EventWriter<CardFlippedEvent>,
+    mut changed: MessageWriter<StateChangedEvent>,
+    mut flipped: MessageWriter<CardFlippedEvent>,
 ) {
     use solitaire_core::pile::PileType;
 
@@ -347,9 +347,9 @@ fn handle_draw(
             Ok(()) => {
                 // Fire a flip event for each card that moved from stock to waste.
                 for id in drawn_ids {
-                    flipped.send(CardFlippedEvent(id));
+                    flipped.write(CardFlippedEvent(id));
                 }
-                changed.send(StateChangedEvent);
+                changed.write(StateChangedEvent);
             }
             Err(e) => warn!("draw rejected: {e}"),
         }
@@ -357,11 +357,11 @@ fn handle_draw(
 }
 
 fn handle_move(
-    mut moves: EventReader<MoveRequestEvent>,
+    mut moves: MessageReader<MoveRequestEvent>,
     mut game: ResMut<GameStateResource>,
-    mut changed: EventWriter<StateChangedEvent>,
-    mut won: EventWriter<GameWonEvent>,
-    mut flipped: EventWriter<crate::events::CardFlippedEvent>,
+    mut changed: MessageWriter<StateChangedEvent>,
+    mut won: MessageWriter<GameWonEvent>,
+    mut flipped: MessageWriter<crate::events::CardFlippedEvent>,
     path: Option<Res<GameStatePath>>,
 ) {
     for ev in moves.read() {
@@ -385,12 +385,12 @@ fn handle_move(
                         .and_then(|p| p.cards.last())
                         .is_some_and(|c| c.id == fid && c.face_up)
                     {
-                        flipped.send(crate::events::CardFlippedEvent(fid));
+                        flipped.write(crate::events::CardFlippedEvent(fid));
                     }
                 }
-                changed.send(StateChangedEvent);
+                changed.write(StateChangedEvent);
                 if !was_won && game.0.is_won {
-                    won.send(GameWonEvent {
+                    won.write(GameWonEvent {
                         score: game.0.score,
                         time_seconds: game.0.elapsed_seconds,
                     });
@@ -408,20 +408,20 @@ fn handle_move(
 }
 
 fn handle_undo(
-    mut undos: EventReader<UndoRequestEvent>,
+    mut undos: MessageReader<UndoRequestEvent>,
     mut game: ResMut<GameStateResource>,
-    mut changed: EventWriter<StateChangedEvent>,
-    mut toast: EventWriter<InfoToastEvent>,
+    mut changed: MessageWriter<StateChangedEvent>,
+    mut toast: MessageWriter<InfoToastEvent>,
 ) {
     use solitaire_core::error::MoveError;
 
     for _ in undos.read() {
         match game.0.undo() {
             Ok(()) => {
-                changed.send(StateChangedEvent);
+                changed.write(StateChangedEvent);
             }
             Err(MoveError::UndoStackEmpty) => {
-                toast.send(InfoToastEvent("Nothing to undo".to_string()));
+                toast.write(InfoToastEvent("Nothing to undo".to_string()));
             }
             Err(e) => warn!("undo rejected: {e}"),
         }
@@ -500,9 +500,9 @@ pub fn has_legal_moves(game: &GameState) -> bool {
 /// game is won.
 fn check_no_moves(
     mut commands: Commands,
-    mut events: EventReader<StateChangedEvent>,
+    mut events: MessageReader<StateChangedEvent>,
     game: Res<GameStateResource>,
-    mut toast: EventWriter<InfoToastEvent>,
+    mut toast: MessageWriter<InfoToastEvent>,
     mut already_fired: Local<bool>,
     game_over_screens: Query<Entity, With<GameOverScreen>>,
 ) {
@@ -523,7 +523,7 @@ fn check_no_moves(
     let moves_ok = has_legal_moves(&game.0);
     if moves_ok || game.0.is_won {
         for entity in &game_over_screens {
-            commands.entity(entity).despawn_recursive();
+            commands.entity(entity).despawn();
         }
     }
 
@@ -532,7 +532,7 @@ fn check_no_moves(
     }
 
     if !moves_ok && !*already_fired {
-        toast.send(InfoToastEvent(
+        toast.write(InfoToastEvent(
             "No moves available \u{2014} press D to draw or N for a new game".to_string(),
         ));
         *already_fired = true;
@@ -574,10 +574,10 @@ fn spawn_game_over_screen(commands: &mut Commands, score: i32) {
                     row_gap: Val::Px(16.0),
                     min_width: Val::Px(340.0),
                     align_items: AlignItems::Center,
+                    border_radius: BorderRadius::all(Val::Px(12.0)),
                     ..default()
                 },
                 BackgroundColor(Color::srgb(0.10, 0.08, 0.08)),
-                BorderRadius::all(Val::Px(12.0)),
             ))
             .with_children(|card| {
                 // Header — explains why the overlay appeared.
@@ -628,8 +628,8 @@ fn handle_game_over_input(
     mut commands: Commands,
     keys: Option<Res<ButtonInput<KeyCode>>>,
     screens: Query<Entity, With<GameOverScreen>>,
-    mut new_game: EventWriter<NewGameRequestEvent>,
-    mut undo: EventWriter<UndoRequestEvent>,
+    mut new_game: MessageWriter<NewGameRequestEvent>,
+    mut undo: MessageWriter<UndoRequestEvent>,
 ) {
     if screens.is_empty() {
         return;
@@ -639,12 +639,12 @@ fn handle_game_over_input(
     };
 
     if keys.just_pressed(KeyCode::KeyN) || keys.just_pressed(KeyCode::Escape) {
-        new_game.send(NewGameRequestEvent::default());
+        new_game.write(NewGameRequestEvent::default());
     } else if keys.just_pressed(KeyCode::KeyU) {
         for entity in &screens {
-            commands.entity(entity).despawn_recursive();
+            commands.entity(entity).despawn();
         }
-        undo.send(UndoRequestEvent);
+        undo.write(UndoRequestEvent);
     }
 }
 
@@ -685,7 +685,7 @@ fn auto_save_game_state(
 /// `save_game_state_to` helper skips them). Blocking on exit is acceptable
 /// because the game loop is already shutting down.
 fn save_game_state_on_exit(
-    mut exit_events: EventReader<AppExit>,
+    mut exit_events: MessageReader<AppExit>,
     game: Res<GameStateResource>,
     path: Res<GameStatePath>,
 ) {
@@ -739,7 +739,7 @@ mod tests {
             .cards
             .len();
 
-        app.world_mut().send_event(DrawRequestEvent);
+        app.world_mut().write_message(DrawRequestEvent);
         app.update();
 
         let stock_after = app
@@ -763,9 +763,9 @@ mod tests {
     #[test]
     fn draw_request_fires_state_changed_event() {
         let mut app = test_app(42);
-        app.world_mut().send_event(DrawRequestEvent);
+        app.world_mut().write_message(DrawRequestEvent);
         app.update();
-        let events = app.world().resource::<Events<StateChangedEvent>>();
+        let events = app.world().resource::<Messages<StateChangedEvent>>();
         let mut reader = events.get_cursor();
         assert!(reader.read(events).next().is_some());
     }
@@ -773,9 +773,9 @@ mod tests {
     #[test]
     fn undo_after_draw_restores_state() {
         let mut app = test_app(42);
-        app.world_mut().send_event(DrawRequestEvent);
+        app.world_mut().write_message(DrawRequestEvent);
         app.update();
-        app.world_mut().send_event(UndoRequestEvent);
+        app.world_mut().write_message(UndoRequestEvent);
         app.update();
         let g = &app.world().resource::<GameStateResource>().0;
         assert_eq!(g.piles[&PileType::Stock].cards.len(), 24);
@@ -795,7 +795,7 @@ mod tests {
             .map(|c| c.id)
             .collect();
 
-        app.world_mut().send_event(NewGameRequestEvent { seed: Some(999), mode: None });
+        app.world_mut().write_message(NewGameRequestEvent { seed: Some(999), mode: None });
         app.update();
 
         let after: Vec<u32> = app
@@ -858,13 +858,13 @@ mod tests {
     fn invalid_move_does_not_fire_state_changed() {
         let mut app = test_app(42);
         // Stock -> Waste is InvalidDestination; no state change expected.
-        app.world_mut().send_event(MoveRequestEvent {
+        app.world_mut().write_message(MoveRequestEvent {
             from: PileType::Stock,
             to: PileType::Waste,
             count: 1,
         });
         app.update();
-        let events = app.world().resource::<Events<StateChangedEvent>>();
+        let events = app.world().resource::<Messages<StateChangedEvent>>();
         let mut reader = events.get_cursor();
         assert!(reader.read(events).next().is_none());
     }
@@ -892,7 +892,7 @@ mod tests {
         app.world_mut().resource_mut::<GameStateResource>().0 =
             GameState::new(7654, DrawMode::DrawOne);
 
-        app.world_mut().send_event(AppExit::Success);
+        app.world_mut().write_message(AppExit::Success);
         app.update();
 
         let loaded = load_game_state_from(&path).expect("file should exist after exit");
@@ -913,7 +913,7 @@ mod tests {
 
         let mut app = test_app(1);
         app.insert_resource(GameStatePath(Some(path.clone())));
-        app.world_mut().send_event(NewGameRequestEvent { seed: Some(2), mode: None });
+        app.world_mut().write_message(NewGameRequestEvent { seed: Some(2), mode: None });
         app.update();
 
         assert!(!path.exists(), "saved file should be deleted after new game");
@@ -949,14 +949,14 @@ mod tests {
             t.cards.push(Card { id: 902, suit: Suit::Clubs, rank: Rank::King, face_up: true });
         }
 
-        app.world_mut().send_event(MoveRequestEvent {
+        app.world_mut().write_message(MoveRequestEvent {
             from: PileType::Tableau(0),
             to: PileType::Tableau(1),
             count: 1,
         });
         app.update();
 
-        let events = app.world().resource::<Events<crate::events::CardFlippedEvent>>();
+        let events = app.world().resource::<Messages<crate::events::CardFlippedEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).collect();
         assert_eq!(fired.len(), 1, "CardFlippedEvent must fire when a face-down card is exposed");
@@ -1035,14 +1035,14 @@ mod tests {
                 .push(Card { id: 912, suit: Suit::Spades, rank: Rank::King, face_up: true });
         }
 
-        app.world_mut().send_event(MoveRequestEvent {
+        app.world_mut().write_message(MoveRequestEvent {
             from: PileType::Tableau(0),
             to: PileType::Tableau(1),
             count: 1,
         });
         app.update();
 
-        let events = app.world().resource::<Events<crate::events::CardFlippedEvent>>();
+        let events = app.world().resource::<Messages<crate::events::CardFlippedEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).collect();
         assert!(fired.is_empty(), "no flip event when exposed card was already face-up");
@@ -1125,7 +1125,7 @@ mod tests {
         // Simulate an active game with moves made.
         app.world_mut().resource_mut::<GameStateResource>().0.move_count = 5;
         app.world_mut()
-            .send_event(NewGameRequestEvent { seed: None, mode: None });
+            .write_message(NewGameRequestEvent { seed: None, mode: None });
         app.update();
 
         let count = app
@@ -1146,7 +1146,7 @@ mod tests {
             "test assumes a fresh game with no moves"
         );
         app.world_mut()
-            .send_event(NewGameRequestEvent { seed: None, mode: None });
+            .write_message(NewGameRequestEvent { seed: None, mode: None });
         app.update();
 
         let count = app
@@ -1165,7 +1165,7 @@ mod tests {
     fn game_over_screen_absent_when_moves_available() {
         // A fresh game always has moves (stock is non-empty).
         let mut app = test_app_with_input(42);
-        app.world_mut().send_event(StateChangedEvent);
+        app.world_mut().write_message(StateChangedEvent);
         app.update();
 
         let count = app
@@ -1201,7 +1201,7 @@ mod tests {
             });
         }
 
-        app.world_mut().send_event(StateChangedEvent);
+        app.world_mut().write_message(StateChangedEvent);
         app.update();
 
         let count = app
@@ -1240,7 +1240,7 @@ mod tests {
             });
         }
 
-        app.world_mut().send_event(StateChangedEvent);
+        app.world_mut().write_message(StateChangedEvent);
         app.update();
 
         // Collect all Text values that are children of the GameOverScreen entity tree.
@@ -1295,7 +1295,7 @@ mod tests {
                 face_up: true,
             });
         }
-        app.world_mut().send_event(StateChangedEvent);
+        app.world_mut().write_message(StateChangedEvent);
         app.update();
 
         // Confirm the overlay is present.
@@ -1309,7 +1309,7 @@ mod tests {
         );
 
         // Clear the NewGameRequestEvent queue so we start with a clean slate.
-        app.world_mut().resource_mut::<Events<NewGameRequestEvent>>().clear();
+        app.world_mut().resource_mut::<Messages<NewGameRequestEvent>>().clear();
 
         // Simulate Escape press.
         {
@@ -1320,7 +1320,7 @@ mod tests {
         app.update();
 
         // NewGameRequestEvent must have been fired.
-        let events = app.world().resource::<Events<NewGameRequestEvent>>();
+        let events = app.world().resource::<Messages<NewGameRequestEvent>>();
         let mut reader = events.get_cursor();
         assert!(
             reader.read(events).next().is_some(),
@@ -1338,10 +1338,10 @@ mod tests {
     fn undo_on_empty_stack_fires_info_toast() {
         let mut app = test_app(42);
         // Fresh game — undo stack is empty, so undo() returns UndoStackEmpty.
-        app.world_mut().send_event(UndoRequestEvent);
+        app.world_mut().write_message(UndoRequestEvent);
         app.update();
 
-        let events = app.world().resource::<Events<InfoToastEvent>>();
+        let events = app.world().resource::<Messages<InfoToastEvent>>();
         let mut reader = events.get_cursor();
         let fired: Vec<_> = reader.read(events).collect();
         assert_eq!(fired.len(), 1, "exactly one InfoToastEvent must fire on empty-stack undo");
@@ -1357,15 +1357,15 @@ mod tests {
     fn undo_after_draw_does_not_fire_info_toast() {
         let mut app = test_app(42);
         // Make a move so the undo stack is non-empty.
-        app.world_mut().send_event(DrawRequestEvent);
+        app.world_mut().write_message(DrawRequestEvent);
         app.update();
         // Clear events from the draw so we start with a clean slate.
-        app.world_mut().resource_mut::<Events<InfoToastEvent>>().clear();
+        app.world_mut().resource_mut::<Messages<InfoToastEvent>>().clear();
 
-        app.world_mut().send_event(UndoRequestEvent);
+        app.world_mut().write_message(UndoRequestEvent);
         app.update();
 
-        let events = app.world().resource::<Events<InfoToastEvent>>();
+        let events = app.world().resource::<Messages<InfoToastEvent>>();
         let mut reader = events.get_cursor();
         let fired: Vec<_> = reader.read(events).collect();
         assert!(

solitaire_engine/src/help_plugin.rs

@@ -25,8 +25,8 @@ fn toggle_help_screen(
     if !keys.just_pressed(KeyCode::F1) {
         return;
     }
-    if let Ok(entity) = screens.get_single() {
-        commands.entity(entity).despawn_recursive();
+    if let Ok(entity) = screens.single() {
+        commands.entity(entity).despawn();
     } else {
         spawn_help_screen(&mut commands);
     }

solitaire_engine/src/home_plugin.rs

@@ -31,8 +31,8 @@ fn toggle_home_screen(
     if !keys.just_pressed(KeyCode::KeyM) {
         return;
     }
-    if let Ok(entity) = screens.get_single() {
-        commands.entity(entity).despawn_recursive();
+    if let Ok(entity) = screens.single() {
+        commands.entity(entity).despawn();
     } else {
         spawn_home_screen(&mut commands, &game);
     }
@@ -139,7 +139,7 @@ fn spawn_home_screen(commands: &mut Commands, game: &GameStateResource) {
         });
 }
 
-fn spawn_shortcut_row(parent: &mut ChildBuilder, key: &str, action: &str) {
+fn spawn_shortcut_row(parent: &mut ChildSpawnerCommands, key: &str, action: &str) {
     parent
         .spawn(Node {
             flex_direction: FlexDirection::Row,

solitaire_engine/src/hud_plugin.rs

@@ -325,7 +325,7 @@ fn update_hud(
     if game.is_changed() {
         let g = &game.0;
         let is_zen = g.mode == GameMode::Zen;
-        if let Ok(mut t) = score_q.get_single_mut() {
+        if let Ok(mut t) = score_q.single_mut() {
             // Zen mode suppresses score display per spec ("No score display").
             **t = if is_zen {
                 String::new()
@@ -333,10 +333,10 @@ fn update_hud(
                 format!("Score: {}", g.score)
             };
         }
-        if let Ok(mut t) = moves_q.get_single_mut() {
+        if let Ok(mut t) = moves_q.single_mut() {
             **t = format!("Moves: {}", g.move_count);
         }
-        if let Ok(mut t) = mode_q.get_single_mut() {
+        if let Ok(mut t) = mode_q.single_mut() {
             **t = match g.mode {
                 GameMode::Classic => match g.draw_mode {
                     DrawMode::DrawOne => String::new(),
@@ -349,7 +349,7 @@ fn update_hud(
         }
 
         // --- Daily challenge constraint (with time-low colour warning) ---
-        if let Ok((mut t, mut color)) = challenge_q.get_single_mut() {
+        if let Ok((mut t, mut color)) = challenge_q.single_mut() {
             if g.is_won {
                 **t = String::new();
             } else if let Some(dc) = daily.as_deref() {
@@ -364,7 +364,7 @@ fn update_hud(
         }
 
         // --- Undo count ---
-        if let Ok((mut t, mut color)) = undos_q.get_single_mut() {
+        if let Ok((mut t, mut color)) = undos_q.single_mut() {
             let count = g.undo_count;
             if count == 0 {
                 **t = String::new();
@@ -377,7 +377,7 @@ fn update_hud(
         }
 
         // --- Recycle counter (both modes, hidden until first recycle) ---
-        if let Ok(mut t) = recycles_q.get_single_mut() {
+        if let Ok(mut t) = recycles_q.single_mut() {
             **t = if g.recycle_count > 0 {
                 format!("Recycles: {}", g.recycle_count)
             } else {
@@ -386,7 +386,7 @@ fn update_hud(
         }
 
         // --- Draw-cycle indicator (Draw-Three mode only) ---
-        if let Ok(mut t) = draw_cycle_q.get_single_mut() {
+        if let Ok(mut t) = draw_cycle_q.single_mut() {
             **t = if g.is_won || g.draw_mode != DrawMode::DrawThree {
                 // Hide when not in Draw-Three or after the game is won.
                 String::new()
@@ -405,7 +405,7 @@ fn update_hud(
     let is_zen = game.0.mode == GameMode::Zen;
     let update_time = (ta_active || game.is_changed()) && !is_zen;
     if update_time {
-        if let Ok(mut t) = time_q.get_single_mut() {
+        if let Ok(mut t) = time_q.single_mut() {
             if let Some(ta) = time_attack.as_ref().filter(|ta| ta.active) {
                 let remaining = ta.remaining_secs.max(0.0) as u64;
                 let m = remaining / 60;
@@ -422,7 +422,7 @@ fn update_hud(
         // Clear the time display immediately whenever Zen mode is active —
         // do not guard on game.is_changed() so it clears on the same frame
         // the player presses Z, before any move is made.
-        if let Ok(mut t) = time_q.get_single_mut() {
+        if let Ok(mut t) = time_q.single_mut() {
             **t = String::new();
         }
     }
@@ -432,7 +432,7 @@ fn update_hud(
     let ac_active = auto_complete.as_ref().is_some_and(|ac| ac.active);
     let ac_changed = auto_complete.as_ref().is_some_and(|ac| ac.is_changed());
     if ac_changed || game.is_changed() {
-        if let Ok(mut t) = auto_q.get_single_mut() {
+        if let Ok(mut t) = auto_q.single_mut() {
             **t = if ac_active {
                 "AUTO".to_string()
             } else {
@@ -451,7 +451,7 @@ fn update_selection_hud(
     selection: Option<Res<SelectionState>>,
     mut q: Query<&mut Text, With<HudSelection>>,
 ) {
-    let Ok(mut t) = q.get_single_mut() else { return };
+    let Ok(mut t) = q.single_mut() else { return };
     let label = match selection.as_deref().and_then(|s| s.selected_pile.as_ref()) {
         None => String::new(),
         Some(PileType::Waste) => "▶ Waste".to_string(),
@@ -475,12 +475,12 @@ fn update_selection_hud(
 /// to debounce so the toast only appears on the leading edge.
 fn announce_auto_complete(
     auto_complete: Option<Res<AutoCompleteState>>,
-    mut toast: EventWriter<InfoToastEvent>,
+    mut toast: MessageWriter<InfoToastEvent>,
     mut was_active: Local<bool>,
 ) {
     let now_active = auto_complete.as_ref().is_some_and(|ac| ac.active);
     if now_active && !*was_active {
-        toast.send(InfoToastEvent("Auto-completing...".to_string()));
+        toast.write(InfoToastEvent("Auto-completing...".to_string()));
     }
     *was_active = now_active;
 }

solitaire_engine/src/input_plugin.rs

@@ -28,13 +28,13 @@ use solitaire_core::game_state::GameState;
 use solitaire_core::pile::PileType;
 use solitaire_core::rules::{can_place_on_foundation, can_place_on_tableau};
 
-use crate::card_plugin::{CardEntity, HintHighlight, TABLEAU_FAN_FRAC};
+use crate::card_plugin::{CardEntity, HintHighlight, HintHighlightTimer, TABLEAU_FAN_FRAC};
 use crate::feedback_anim_plugin::ShakeAnim;
 use solitaire_core::game_state::DrawMode;
 use crate::challenge_plugin::CHALLENGE_UNLOCK_LEVEL;
 use crate::events::{
-    DrawRequestEvent, ForfeitEvent, InfoToastEvent, MoveRejectedEvent, MoveRequestEvent,
-    NewGameConfirmEvent, NewGameRequestEvent, StateChangedEvent, UndoRequestEvent,
+    DrawRequestEvent, ForfeitEvent, HintVisualEvent, InfoToastEvent, MoveRejectedEvent,
+    MoveRequestEvent, NewGameConfirmEvent, NewGameRequestEvent, StateChangedEvent, UndoRequestEvent,
 };
 use crate::game_plugin::GameMutation;
 use crate::pause_plugin::PausedResource;
@@ -58,9 +58,10 @@ pub struct InputPlugin;
 impl Plugin for InputPlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<HintCycleIndex>()
-            .add_event::<NewGameConfirmEvent>()
-            .add_event::<InfoToastEvent>()
-            .add_event::<ForfeitEvent>()
+            .add_message::<NewGameConfirmEvent>()
+            .add_message::<InfoToastEvent>()
+            .add_message::<ForfeitEvent>()
+            .add_message::<HintVisualEvent>()
             .add_systems(
                 Update,
                 (
@@ -87,13 +88,14 @@ const FORFEIT_CONFIRM_WINDOW: f32 = 3.0;
 /// Bundles all event writers used by `handle_keyboard` so the system stays
 /// within Bevy's 16-parameter limit.
 #[derive(SystemParam)]
-struct KeyboardEvents<'w> {
-    undo: EventWriter<'w, UndoRequestEvent>,
-    new_game: EventWriter<'w, NewGameRequestEvent>,
-    confirm_event: EventWriter<'w, NewGameConfirmEvent>,
-    info_toast: EventWriter<'w, InfoToastEvent>,
-    draw: EventWriter<'w, DrawRequestEvent>,
-    forfeit: EventWriter<'w, ForfeitEvent>,
+struct KeyboardMessages<'w> {
+    undo: MessageWriter<'w, UndoRequestEvent>,
+    new_game: MessageWriter<'w, NewGameRequestEvent>,
+    confirm_event: MessageWriter<'w, NewGameConfirmEvent>,
+    info_toast: MessageWriter<'w, InfoToastEvent>,
+    draw: MessageWriter<'w, DrawRequestEvent>,
+    forfeit: MessageWriter<'w, ForfeitEvent>,
+    hint_visual: MessageWriter<'w, HintVisualEvent>,
 }
 
 #[allow(clippy::too_many_arguments)]
@@ -106,7 +108,7 @@ fn handle_keyboard(
     mut confirm_countdown: Local<f32>,
     mut confirm_pending: Local<bool>,
     mut forfeit_countdown: Local<f32>,
-    mut ev: KeyboardEvents,
+    mut ev: KeyboardMessages<'_>,
     mut commands: Commands,
     card_entities: Query<(Entity, &CardEntity, &Sprite)>,
     layout: Option<Res<LayoutResource>>,
@@ -124,7 +126,7 @@ fn handle_keyboard(
             // Countdown expired without a second N press — notify the player.
             if *confirm_pending {
                 *confirm_pending = false;
-                ev.info_toast.send(InfoToastEvent("New game cancelled".to_string()));
+                ev.info_toast.write(InfoToastEvent("New game cancelled".to_string()));
             }
         }
     }
@@ -138,7 +140,7 @@ fn handle_keyboard(
 
     if keys.just_pressed(KeyCode::KeyU) {
         if *forfeit_countdown > 0.0 { *forfeit_countdown = 0.0; }
-        ev.undo.send(UndoRequestEvent);
+        ev.undo.write(UndoRequestEvent);
     }
     if keys.just_pressed(KeyCode::KeyN) {
         // If a Time Attack session is running, cancel it and start a Classic game.
@@ -146,8 +148,8 @@ fn handle_keyboard(
             if session.active {
                 session.active = false;
                 session.remaining_secs = 0.0;
-                ev.info_toast.send(InfoToastEvent("Time Attack ended".to_string()));
-                ev.new_game.send(NewGameRequestEvent {
+                ev.info_toast.write(InfoToastEvent("Time Attack ended".to_string()));
+                ev.new_game.write(NewGameRequestEvent {
                     seed: None,
                     mode: Some(solitaire_core::game_state::GameMode::Classic),
                 });
@@ -160,19 +162,19 @@ fn handle_keyboard(
         let shift_held = keys.pressed(KeyCode::ShiftLeft) || keys.pressed(KeyCode::ShiftRight);
         if shift_held || !active_game {
             // Shift+N or no active game — start immediately, no confirmation.
-            ev.new_game.send(NewGameRequestEvent::default());
+            ev.new_game.write(NewGameRequestEvent::default());
             *confirm_countdown = 0.0;
             *confirm_pending = false;
         } else if *confirm_countdown > 0.0 {
             // Second press within the window — confirmed.
-            ev.new_game.send(NewGameRequestEvent::default());
+            ev.new_game.write(NewGameRequestEvent::default());
             *confirm_countdown = 0.0;
             *confirm_pending = false;
         } else {
             // First press on an active game — require confirmation.
             *confirm_countdown = NEW_GAME_CONFIRM_WINDOW;
             *confirm_pending = true;
-            ev.confirm_event.send(NewGameConfirmEvent);
+            ev.confirm_event.write(NewGameConfirmEvent);
         }
     }
     if keys.just_pressed(KeyCode::KeyZ) {
@@ -181,19 +183,19 @@ fn handle_keyboard(
         // X is gated separately by ChallengePlugin.
         let level = progress.as_ref().map_or(0, |p| p.0.level);
         if level >= CHALLENGE_UNLOCK_LEVEL {
-            ev.new_game.send(NewGameRequestEvent {
+            ev.new_game.write(NewGameRequestEvent {
                 seed: None,
                 mode: Some(solitaire_core::game_state::GameMode::Zen),
             });
         } else {
-            ev.info_toast.send(InfoToastEvent(format!(
+            ev.info_toast.write(InfoToastEvent(format!(
                 "Zen mode unlocks at level {CHALLENGE_UNLOCK_LEVEL}"
             )));
         }
     }
     if keys.just_pressed(KeyCode::KeyD) || keys.just_pressed(KeyCode::Space) {
         if *forfeit_countdown > 0.0 { *forfeit_countdown = 0.0; }
-        ev.draw.send(DrawRequestEvent);
+        ev.draw.write(DrawRequestEvent);
     }
     // H — cycle through all available hints on each press, highlighting the
     // source card yellow for 1.5 s. The index wraps around once all hints have
@@ -202,13 +204,13 @@ fn handle_keyboard(
         if *forfeit_countdown > 0.0 { *forfeit_countdown = 0.0; }
         if let Some(ref g) = game {
             if g.0.is_won {
-                ev.info_toast.send(InfoToastEvent(
+                ev.info_toast.write(InfoToastEvent(
                     "Game won! Press N for a new game".to_string(),
                 ));
             } else if let Some(ref layout_res) = layout {
                     let hints = all_hints(&g.0);
                     if hints.is_empty() {
-                        ev.info_toast.send(InfoToastEvent("No hints available".to_string()));
+                        ev.info_toast.write(InfoToastEvent("No hints available".to_string()));
                     } else {
                         // Pick the hint at the current cycle index (wrapping) and advance.
                         let idx = hint_cycle.0 % hints.len();
@@ -227,7 +229,7 @@ fn handle_keyboard(
                             } else {
                                 "Hint: draw from stock (D)".to_string()
                             };
-                            ev.info_toast.send(InfoToastEvent(msg));
+                            ev.info_toast.write(InfoToastEvent(msg));
                         } else {
                             // Find the top face-up card in the source pile and highlight it.
                             let top_card_id = g.0.piles.get(from)
@@ -237,7 +239,8 @@ fn handle_keyboard(
                                 for (entity, card_entity, _sprite) in card_entities.iter() {
                                     if card_entity.card_id == card_id {
                                         commands.entity(entity)
-                                            .insert(HintHighlight { remaining: 1.5 })
+                                            .insert(HintHighlight { remaining: 2.0 })
+                                            .insert(HintHighlightTimer(2.0))
                                             .insert(Sprite {
                                                 color: Color::srgba(1.0, 1.0, 0.4, 1.0),
                                                 custom_size: Some(layout_res.0.card_size),
@@ -246,6 +249,12 @@ fn handle_keyboard(
                                         break;
                                     }
                                 }
+                                // Emit HintVisualEvent so the destination pile
+                                // marker is also tinted gold for 2 s.
+                                ev.hint_visual.write(HintVisualEvent {
+                                    source_card_id: card_id,
+                                    dest_pile: to.clone(),
+                                });
                             }
                             // Fire an informational toast describing where the hinted card
                             // should move so the player always sees the suggestion in text.
@@ -264,7 +273,7 @@ fn handle_keyboard(
                                 }
                                 _ => "Hint: move card".to_string(),
                             };
-                            ev.info_toast.send(InfoToastEvent(msg));
+                            ev.info_toast.write(InfoToastEvent(msg));
                         }
                     }
             }
@@ -278,12 +287,12 @@ fn handle_keyboard(
         if active_game {
             if *forfeit_countdown > 0.0 {
                 // Second press within the confirmation window — confirmed.
-                ev.forfeit.send(ForfeitEvent);
+                ev.forfeit.write(ForfeitEvent);
                 *forfeit_countdown = 0.0;
             } else {
                 // First press — start the countdown and warn the player.
                 *forfeit_countdown = FORFEIT_CONFIRM_WINDOW;
-                ev.info_toast.send(InfoToastEvent("Press G again to forfeit".to_string()));
+                ev.info_toast.write(InfoToastEvent("Press G again to forfeit".to_string()));
             }
         }
     }
@@ -299,8 +308,8 @@ fn handle_keyboard(
 /// game plugin fires after dealing — preventing a stale hint from the previous
 /// game being shown when H is pressed in that gap frame.
 fn reset_hint_cycle_on_state_change(
-    mut state_events: EventReader<StateChangedEvent>,
-    mut new_game_events: EventReader<NewGameRequestEvent>,
+    mut state_events: MessageReader<StateChangedEvent>,
+    mut new_game_events: MessageReader<NewGameRequestEvent>,
     mut hint_cycle: ResMut<HintCycleIndex>,
 ) {
     if state_events.read().next().is_some() || new_game_events.read().next().is_some() {
@@ -313,12 +322,12 @@ fn reset_hint_cycle_on_state_change(
 fn handle_fullscreen(
     keys: Res<ButtonInput<KeyCode>>,
     mut windows: Query<&mut Window, With<PrimaryWindow>>,
-    mut toast: EventWriter<InfoToastEvent>,
+    mut toast: MessageWriter<InfoToastEvent>,
 ) {
     if !keys.just_pressed(KeyCode::F11) {
         return;
     }
-    let Ok(mut window) = windows.get_single_mut() else { return };
+    let Ok(mut window) = windows.single_mut() else { return };
     let new_mode = match window.mode {
         WindowMode::Windowed => WindowMode::BorderlessFullscreen(MonitorSelection::Current),
         _ => WindowMode::Windowed,
@@ -328,7 +337,7 @@ fn handle_fullscreen(
         WindowMode::Windowed => "Fullscreen: off",
         _ => "Fullscreen: on",
     };
-    toast.send(InfoToastEvent(label.to_string()));
+    toast.write(InfoToastEvent(label.to_string()));
 }
 
 fn handle_stock_click(
@@ -338,7 +347,7 @@ fn handle_stock_click(
     windows: Query<&Window, With<PrimaryWindow>>,
     cameras: Query<(&Camera, &GlobalTransform)>,
     layout: Option<Res<LayoutResource>>,
-    mut draw: EventWriter<DrawRequestEvent>,
+    mut draw: MessageWriter<DrawRequestEvent>,
 ) {
     if paused.is_some_and(|p| p.0) {
         return;
@@ -357,7 +366,7 @@ fn handle_stock_click(
         return;
     };
     if point_in_rect(world, stock_pos, layout.0.card_size) {
-        draw.send(DrawRequestEvent);
+        draw.write(DrawRequestEvent);
     }
 }
 
@@ -458,9 +467,9 @@ fn end_drag(
     layout: Option<Res<LayoutResource>>,
     game: Res<GameStateResource>,
     mut drag: ResMut<DragState>,
-    mut moves: EventWriter<MoveRequestEvent>,
-    mut rejected: EventWriter<MoveRejectedEvent>,
-    mut changed: EventWriter<StateChangedEvent>,
+    mut moves: MessageWriter<MoveRequestEvent>,
+    mut rejected: MessageWriter<MoveRejectedEvent>,
+    mut changed: MessageWriter<StateChangedEvent>,
     mut commands: Commands,
     card_entities: Query<(Entity, &CardEntity, &Transform)>,
 ) {
@@ -508,14 +517,14 @@ fn end_drag(
                     _ => false,
                 };
                 if ok {
-                    moves.send(MoveRequestEvent {
+                    moves.write(MoveRequestEvent {
                         from: origin.clone(),
                         to: target.clone(),
                         count,
                     });
                     fired = true;
                 } else {
-                    rejected.send(MoveRejectedEvent {
+                    rejected.write(MoveRejectedEvent {
                         from: origin.clone(),
                         to: target.clone(),
                         count,
@@ -543,7 +552,7 @@ fn end_drag(
     // Either the move succeeded (GamePlugin will also fire StateChangedEvent)
     // or it didn't — in both cases we emit one so cards resync to the current
     // game state. Duplicate events are harmless.
-    changed.send(StateChangedEvent);
+    changed.write(StateChangedEvent);
     let _ = fired;
 }
 
@@ -555,9 +564,9 @@ fn cursor_world(
     windows: &Query<&Window, With<PrimaryWindow>>,
     cameras: &Query<(&Camera, &GlobalTransform)>,
 ) -> Option<Vec2> {
-    let window = windows.get_single().ok()?;
+    let window = windows.single().ok()?;
     let cursor = window.cursor_position()?;
-    let (camera, camera_transform) = cameras.get_single().ok()?;
+    let (camera, camera_transform) = cameras.single().ok()?;
     camera.viewport_to_world_2d(camera_transform, cursor).ok()
 }
 
@@ -800,8 +809,8 @@ fn handle_double_click(
     layout: Option<Res<LayoutResource>>,
     game: Res<GameStateResource>,
     mut last_click: Local<HashMap<u32, f32>>,
-    mut moves: EventWriter<MoveRequestEvent>,
-    mut rejected: EventWriter<MoveRejectedEvent>,
+    mut moves: MessageWriter<MoveRequestEvent>,
+    mut rejected: MessageWriter<MoveRejectedEvent>,
 ) {
     if paused.is_some_and(|p| p.0) {
         return;
@@ -835,7 +844,7 @@ fn handle_double_click(
 
         // Priority 1: move the single top card (foundation preferred, then tableau).
         if let Some(dest) = best_destination(top_card, &game.0) {
-            moves.send(MoveRequestEvent {
+            moves.write(MoveRequestEvent {
                 from: pile,
                 to: dest,
                 count: 1,
@@ -855,7 +864,7 @@ fn handle_double_click(
                 &game.0,
                 card_ids.len(),
             ) {
-                moves.send(MoveRequestEvent {
+                moves.write(MoveRequestEvent {
                     from: pile,
                     to: dest,
                     count,
@@ -865,7 +874,7 @@ fn handle_double_click(
                 // sound and shake the source pile cards as feedback.
                 // `MoveRejectedEvent` with `from == to` routes the shake to
                 // the source pile (which `start_shake_anim` reads from `ev.to`).
-                rejected.send(MoveRejectedEvent {
+                rejected.write(MoveRejectedEvent {
                     from: pile.clone(),
                     to: pile,
                     count: card_ids.len(),
@@ -979,6 +988,11 @@ pub fn find_hint(game: &GameState) -> Option<(PileType, PileType, usize)> {
     all_hints(game).into_iter().next()
 }
 
+// `Vec3` is referenced only via the `DRAG_Z` constant; keep the import silenced
+// when the compiler can't see it used.
+#[allow(dead_code)]
+const _VEC3_REFERENCED: Option<Vec3> = None;
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -1419,7 +1433,7 @@ mod tests {
     /// window actually opens on the first G press.
     #[test]
     fn forfeit_confirm_window_is_positive() {
-        assert!(FORFEIT_CONFIRM_WINDOW > 0.0, "FORFEIT_CONFIRM_WINDOW must be > 0");
+        const { assert!(FORFEIT_CONFIRM_WINDOW > 0.0, "FORFEIT_CONFIRM_WINDOW must be > 0"); }
     }
 
     /// Simulate the first G press: countdown was 0, so it should become
@@ -1607,7 +1621,3 @@ mod tests {
     }
 }
 
-// `Vec3` is referenced only via the `DRAG_Z` constant; keep the import silenced
-// when the compiler can't see it used.
-#[allow(dead_code)]
-const _VEC3_REFERENCED: Option<Vec3> = None;

solitaire_engine/src/leaderboard_plugin.rs

@@ -112,8 +112,8 @@ fn toggle_leaderboard_screen(
     if !keys.just_pressed(KeyCode::KeyL) {
         return;
     }
-    if let Ok(entity) = screens.get_single() {
-        commands.entity(entity).despawn_recursive();
+    if let Ok(entity) = screens.single() {
+        commands.entity(entity).despawn();
         closed_flag.0 = true;
         return;
     }
@@ -174,7 +174,7 @@ fn update_leaderboard_panel(
         return;
     }
     for entity in &screens {
-        commands.entity(entity).despawn_recursive();
+        commands.entity(entity).despawn();
         spawn_leaderboard_screen(&mut commands, data.0.as_deref());
     }
 }
@@ -218,18 +218,18 @@ fn handle_opt_in_button(
 /// Polls the opt-in task; fires an `InfoToastEvent` on completion or failure.
 fn poll_opt_in_task(
     mut task_res: ResMut<OptInTask>,
-    mut toast: EventWriter<InfoToastEvent>,
+    mut toast: MessageWriter<InfoToastEvent>,
 ) {
     let Some(task) = task_res.0.as_mut() else { return };
     let Some(result) = future::block_on(future::poll_once(task)) else { return };
     task_res.0 = None;
     match result {
         Ok(()) => {
-            toast.send(InfoToastEvent("Opted in to leaderboard".to_string()));
+            toast.write(InfoToastEvent("Opted in to leaderboard".to_string()));
         }
         Err(e) => {
             warn!("leaderboard opt-in failed: {e}");
-            toast.send(InfoToastEvent("Leaderboard update failed".to_string()));
+            toast.write(InfoToastEvent("Leaderboard update failed".to_string()));
         }
     }
 }
@@ -258,18 +258,18 @@ fn handle_opt_out_button(
 /// Polls the opt-out task; fires an `InfoToastEvent` on completion or failure.
 fn poll_opt_out_task(
     mut task_res: ResMut<OptOutTask>,
-    mut toast: EventWriter<InfoToastEvent>,
+    mut toast: MessageWriter<InfoToastEvent>,
 ) {
     let Some(task) = task_res.0.as_mut() else { return };
     let Some(result) = future::block_on(future::poll_once(task)) else { return };
     task_res.0 = None;
     match result {
         Ok(()) => {
-            toast.send(InfoToastEvent("Opted out of leaderboard".to_string()));
+            toast.write(InfoToastEvent("Opted out of leaderboard".to_string()));
         }
         Err(e) => {
             warn!("leaderboard opt-out failed: {e}");
-            toast.send(InfoToastEvent("Leaderboard update failed".to_string()));
+            toast.write(InfoToastEvent("Leaderboard update failed".to_string()));
         }
     }
 }
@@ -305,10 +305,10 @@ fn spawn_leaderboard_screen(commands: &mut Commands, entries: Option<&[Leaderboa
                     min_width: Val::Px(420.0),
                     max_height: Val::Percent(80.0),
                     overflow: Overflow::clip_y(),
+                    border_radius: BorderRadius::all(Val::Px(8.0)),
                     ..default()
                 },
                 BackgroundColor(Color::srgb(0.09, 0.09, 0.12)),
-                BorderRadius::all(Val::Px(8.0)),
             ))
             .with_children(|card| {
                 // Header
@@ -347,10 +347,10 @@ fn spawn_leaderboard_screen(commands: &mut Commands, entries: Option<&[Leaderboa
                         Node {
                             padding: UiRect::axes(Val::Px(14.0), Val::Px(6.0)),
                             justify_content: JustifyContent::Center,
+                            border_radius: BorderRadius::all(Val::Px(4.0)),
                             ..default()
                         },
                         BackgroundColor(Color::srgb(0.18, 0.35, 0.50)),
-                        BorderRadius::all(Val::Px(4.0)),
                     ))
                     .with_children(|b| {
                         b.spawn((
@@ -366,10 +366,10 @@ fn spawn_leaderboard_screen(commands: &mut Commands, entries: Option<&[Leaderboa
                         Node {
                             padding: UiRect::axes(Val::Px(14.0), Val::Px(6.0)),
                             justify_content: JustifyContent::Center,
+                            border_radius: BorderRadius::all(Val::Px(4.0)),
                             ..default()
                         },
                         BackgroundColor(Color::srgb(0.42, 0.15, 0.15)),
-                        BorderRadius::all(Val::Px(4.0)),
                     ))
                     .with_children(|b| {
                         b.spawn((
@@ -454,7 +454,7 @@ fn spawn_leaderboard_screen(commands: &mut Commands, entries: Option<&[Leaderboa
         });
 }
 
-fn header_cell(parent: &mut ChildBuilder, text: &str, width: f32) {
+fn header_cell(parent: &mut ChildSpawnerCommands, text: &str, width: f32) {
     parent.spawn((
         Text::new(text.to_string()),
         TextFont { font_size: 13.0, ..default() },
@@ -463,7 +463,7 @@ fn header_cell(parent: &mut ChildBuilder, text: &str, width: f32) {
     ));
 }
 
-fn data_cell(parent: &mut ChildBuilder, text: &str, width: f32, color: Color) {
+fn data_cell(parent: &mut ChildSpawnerCommands, text: &str, width: f32, color: Color) {
     parent.spawn((
         Text::new(text.to_string()),
         TextFont { font_size: 15.0, ..default() },

solitaire_engine/src/lib.rs

@@ -1,5 +1,6 @@
 //! Bevy integration layer for Solitaire Quest.
 
+pub mod card_animation;
 pub mod achievement_plugin;
 pub mod animation_plugin;
 pub mod auto_complete_plugin;
@@ -41,17 +42,27 @@ pub use daily_challenge_plugin::{
 pub use progress_plugin::{LevelUpEvent, ProgressPlugin, ProgressResource, ProgressUpdate};
 pub use weekly_goals_plugin::{WeeklyGoalCompletedEvent, WeeklyGoalsPlugin};
 pub use animation_plugin::{ActiveToast, AnimationPlugin, CardAnim, ToastEntity, ToastQueue};
+pub use card_animation::{
+    CardAnimation, CardAnimationPlugin, MotionCurve, WinCascadePlugin,
+    retarget_animation, sample_curve, compute_duration, cascade_delay, micro_vary,
+    HoverState, InputBuffer, BufferedInput,
+    win_scatter_targets, WIN_CASCADE_INTERVAL_SECS, DEAL_INTERVAL_SECS,
+    MIN_DURATION_SECS, MAX_DURATION_SECS,
+};
 pub use feedback_anim_plugin::{
     deal_stagger_delay, deal_stagger_secs_for_speed, shake_offset, settle_scale,
     FeedbackAnimPlugin, SettleAnim, ShakeAnim,
 };
 pub use auto_complete_plugin::AutoCompletePlugin;
 pub use audio_plugin::{AudioPlugin, AudioState, SoundLibrary};
-pub use card_plugin::{CardEntity, CardLabel, CardPlugin, HintHighlight, RightClickHighlight};
+pub use card_plugin::{
+    CardEntity, CardLabel, CardPlugin, HintHighlight, HintHighlightTimer, RightClickHighlight,
+    RightClickHighlightTimer,
+};
 pub use cursor_plugin::CursorPlugin;
 pub use events::{
     AchievementUnlockedEvent, CardFlippedEvent, DrawRequestEvent, ForfeitEvent, GameWonEvent,
-    InfoToastEvent, ManualSyncRequestEvent, MoveRejectedEvent, MoveRequestEvent,
+    HintVisualEvent, InfoToastEvent, ManualSyncRequestEvent, MoveRejectedEvent, MoveRequestEvent,
     NewGameConfirmEvent, NewGameRequestEvent, StateChangedEvent, UndoRequestEvent, XpAwardedEvent,
 };
 pub use game_plugin::{ConfirmNewGameScreen, GameMutation, GameOverScreen, GamePlugin, GameStatePath};
@@ -71,7 +82,7 @@ pub use resources::{DragState, GameStateResource, HintCycleIndex, SettingsScroll
 pub use selection_plugin::{SelectionHighlight, SelectionPlugin, SelectionState};
 pub use stats_plugin::{StatsPlugin, StatsResource, StatsScreen, StatsUpdate};
 pub use sync_plugin::{SyncPlugin, SyncProviderResource};
-pub use table_plugin::{PileMarker, TableBackground, TablePlugin};
+pub use table_plugin::{HintPileHighlight, PileMarker, TableBackground, TablePlugin};
 pub use time_attack_plugin::{
     TimeAttackEndedEvent, TimeAttackPlugin, TimeAttackResource, TIME_ATTACK_DURATION_SECS,
 };

solitaire_engine/src/onboarding_plugin.rs

@@ -59,7 +59,7 @@ fn dismiss_on_any_input(
     path: Option<Res<SettingsStoragePath>>,
     screens: Query<Entity, With<OnboardingScreen>>,
 ) {
-    let Ok(entity) = screens.get_single() else {
+    let Ok(entity) = screens.single() else {
         return;
     };
     let pressed = keys.get_just_pressed().next().is_some()
@@ -67,7 +67,7 @@ fn dismiss_on_any_input(
     if !pressed {
         return;
     }
-    commands.entity(entity).despawn_recursive();
+    commands.entity(entity).despawn();
     settings.0.first_run_complete = true;
     persist(path.as_deref().map(|p| &p.0), &settings.0);
 }

solitaire_engine/src/pause_plugin.rs

@@ -54,8 +54,8 @@ impl Plugin for PausePlugin {
     fn build(&self, app: &mut App) {
         // Both add_event calls are idempotent — other plugins may register these
         // events first, but calling add_event again is always safe.
-        app.add_event::<SettingsChangedEvent>()
-            .add_event::<StateChangedEvent>()
+        app.add_message::<SettingsChangedEvent>()
+            .add_message::<StateChangedEvent>()
             .init_resource::<PausedResource>()
             .add_systems(Update, (toggle_pause, handle_pause_draw_toggle));
     }
@@ -74,7 +74,7 @@ fn toggle_pause(
     stats: Option<Res<StatsResource>>,
     settings: Option<Res<SettingsResource>>,
     mut drag: Option<ResMut<DragState>>,
-    mut changed: EventWriter<StateChangedEvent>,
+    mut changed: MessageWriter<StateChangedEvent>,
 ) {
     if !keys.just_pressed(KeyCode::Escape) {
         return;
@@ -90,12 +90,12 @@ fn toggle_pause(
     if let Some(ref mut d) = drag {
         if !d.is_idle() {
             d.clear();
-            changed.send(StateChangedEvent);
+            changed.write(StateChangedEvent);
             return;
         }
     }
-    if let Ok(entity) = screens.get_single() {
-        commands.entity(entity).despawn_recursive();
+    if let Ok(entity) = screens.single() {
+        commands.entity(entity).despawn();
         paused.0 = false;
     } else {
         // Snapshot current level and streak at pause time.
@@ -125,7 +125,7 @@ fn handle_pause_draw_toggle(
     paused: Res<PausedResource>,
     settings: Option<ResMut<SettingsResource>>,
     path: Option<Res<SettingsStoragePath>>,
-    mut changed: EventWriter<SettingsChangedEvent>,
+    mut changed: MessageWriter<SettingsChangedEvent>,
 ) {
     if !paused.0 {
         return;
@@ -146,7 +146,7 @@ fn handle_pause_draw_toggle(
                 }
             }
         }
-        changed.send(SettingsChangedEvent(settings.0.clone()));
+        changed.write(SettingsChangedEvent(settings.0.clone()));
     }
 }
 
@@ -224,10 +224,10 @@ fn spawn_pause_screen(
                             padding: UiRect::axes(Val::Px(14.0), Val::Px(6.0)),
                             justify_content: JustifyContent::Center,
                             align_items: AlignItems::Center,
+                            border_radius: BorderRadius::all(Val::Px(4.0)),
                             ..default()
                         },
                         BackgroundColor(Color::srgb(0.20, 0.30, 0.45)),
-                        BorderRadius::all(Val::Px(4.0)),
                     ))
                     .with_children(|btn| {
                         btn.spawn((
@@ -496,7 +496,7 @@ mod tests {
         );
 
         // Verify a SettingsChangedEvent was fired.
-        let events = app.world().resource::<Events<SettingsChangedEvent>>();
+        let events = app.world().resource::<Messages<SettingsChangedEvent>>();
         let mut cursor = events.get_cursor();
         let count = cursor.read(events).count();
         assert!(count >= 1, "SettingsChangedEvent must be fired on toggle");

solitaire_engine/src/profile_plugin.rs

@@ -42,8 +42,8 @@ fn toggle_profile_screen(
     if !keys.just_pressed(KeyCode::KeyP) {
         return;
     }
-    if let Ok(entity) = screens.get_single() {
-        commands.entity(entity).despawn_recursive();
+    if let Ok(entity) = screens.single() {
+        commands.entity(entity).despawn();
     } else {
         spawn_profile_screen(
             &mut commands,
@@ -246,7 +246,7 @@ fn spawn_profile_screen(
 }
 
 /// Spawn a fixed-height vertical spacer node.
-fn spawn_spacer(parent: &mut ChildBuilder, height_px: f32) {
+fn spawn_spacer(parent: &mut ChildSpawnerCommands, height_px: f32) {
     parent.spawn(Node {
         height: Val::Px(height_px),
         ..default()

solitaire_engine/src/progress_plugin.rs

@@ -25,7 +25,7 @@ pub struct ProgressResource(pub PlayerProgress);
 pub struct ProgressStoragePath(pub Option<PathBuf>);
 
 /// Fired when a win pushes the player to a new level.
-#[derive(Event, Debug, Clone, Copy)]
+#[derive(Message, Debug, Clone, Copy)]
 pub struct LevelUpEvent {
     pub previous_level: u32,
     pub new_level: u32,
@@ -64,9 +64,9 @@ impl Plugin for ProgressPlugin {
         };
         app.insert_resource(ProgressResource(loaded))
             .insert_resource(ProgressStoragePath(self.storage_path.clone()))
-            .add_event::<LevelUpEvent>()
-            .add_event::<XpAwardedEvent>()
-            .add_event::<GameWonEvent>()
+            .add_message::<LevelUpEvent>()
+            .add_message::<XpAwardedEvent>()
+            .add_message::<GameWonEvent>()
             .add_systems(
                 Update,
                 award_xp_on_win
@@ -77,9 +77,9 @@ impl Plugin for ProgressPlugin {
 }
 
 fn award_xp_on_win(
-    mut wins: EventReader<GameWonEvent>,
-    mut levelups: EventWriter<LevelUpEvent>,
-    mut xp_awarded: EventWriter<XpAwardedEvent>,
+    mut wins: MessageReader<GameWonEvent>,
+    mut levelups: MessageWriter<LevelUpEvent>,
+    mut xp_awarded: MessageWriter<XpAwardedEvent>,
     game: Res<GameStateResource>,
     path: Res<ProgressStoragePath>,
     mut progress: ResMut<ProgressResource>,
@@ -88,9 +88,9 @@ fn award_xp_on_win(
         let used_undo = game.0.undo_count > 0;
         let amount = xp_for_win(ev.time_seconds, used_undo);
         let prev_level = progress.0.add_xp(amount);
-        xp_awarded.send(XpAwardedEvent { amount });
+        xp_awarded.write(XpAwardedEvent { amount });
         if progress.0.leveled_up_from(prev_level) {
-            levelups.send(LevelUpEvent {
+            levelups.write(LevelUpEvent {
                 previous_level: prev_level,
                 new_level: progress.0.level,
                 total_xp: progress.0.total_xp,
@@ -131,7 +131,7 @@ mod tests {
     fn win_awards_base_xp() {
         let mut app = headless_app();
         // Game starts with undo_count = 0, so the no-undo bonus applies.
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 300, // no speed bonus
         });
@@ -150,7 +150,7 @@ mod tests {
             .0
             .undo_count = 1;
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 300,
         });
@@ -164,7 +164,7 @@ mod tests {
     #[test]
     fn fast_win_includes_speed_bonus() {
         let mut app = headless_app();
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 0,
         });
@@ -181,13 +181,13 @@ mod tests {
         // Pre-load 480 XP so a 75-XP win pushes us over the 500 boundary.
         app.world_mut().resource_mut::<ProgressResource>().0.total_xp = 480;
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 300,
         });
         app.update();
 
-        let events = app.world().resource::<Events<LevelUpEvent>>();
+        let events = app.world().resource::<Messages<LevelUpEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).copied().collect();
         assert_eq!(fired.len(), 1, "exactly one level-up");
@@ -198,13 +198,13 @@ mod tests {
     #[test]
     fn win_without_level_change_does_not_fire_levelup() {
         let mut app = headless_app();
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 300,
         });
         app.update();
 
-        let events = app.world().resource::<Events<LevelUpEvent>>();
+        let events = app.world().resource::<Messages<LevelUpEvent>>();
         let mut cursor = events.get_cursor();
         assert!(cursor.read(events).next().is_none());
     }
@@ -213,13 +213,13 @@ mod tests {
     fn xp_awarded_event_fired_with_correct_amount() {
         let mut app = headless_app();
         // Slow win, no undo → base 50 + no_undo 25 = 75
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 300,
         });
         app.update();
 
-        let events = app.world().resource::<Events<XpAwardedEvent>>();
+        let events = app.world().resource::<Messages<XpAwardedEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).copied().collect();
         assert_eq!(fired.len(), 1);
@@ -231,14 +231,14 @@ mod tests {
         let mut app = headless_app();
         app.world_mut().resource_mut::<ProgressResource>().0.total_xp = 480;
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 300,
         });
         app.update();
 
         let total_xp = app.world().resource::<ProgressResource>().0.total_xp;
-        let events = app.world().resource::<Events<LevelUpEvent>>();
+        let events = app.world().resource::<Messages<LevelUpEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).copied().collect();
         assert_eq!(fired.len(), 1);
@@ -256,7 +256,7 @@ mod tests {
             .0
             .mode = solitaire_core::game_state::GameMode::Zen;
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 0,        // Zen mode keeps score at 0
             time_seconds: 300,
         });

solitaire_engine/src/selection_plugin.rs

@@ -162,8 +162,8 @@ fn handle_selection_keys(
     paused: Option<Res<PausedResource>>,
     game: Res<GameStateResource>,
     mut selection: ResMut<SelectionState>,
-    mut moves: EventWriter<MoveRequestEvent>,
-    mut info_toast: EventWriter<InfoToastEvent>,
+    mut moves: MessageWriter<MoveRequestEvent>,
+    mut info_toast: MessageWriter<InfoToastEvent>,
 ) {
     if paused.is_some_and(|p| p.0) {
         return;
@@ -200,11 +200,11 @@ fn handle_selection_keys(
     if keys.just_pressed(KeyCode::Tab) {
         let next = cycle_next_pile(&available, selection.selected_pile.as_ref());
         if next.is_none() {
-            info_toast.send(InfoToastEvent("No cards to select".to_string()));
+            info_toast.write(InfoToastEvent("No cards to select".to_string()));
         } else if selection.selected_pile.is_some()
             && did_wrap(&available, selection.selected_pile.as_ref(), next.as_ref())
         {
-            info_toast.send(InfoToastEvent("Back to first card".to_string()));
+            info_toast.write(InfoToastEvent("Back to first card".to_string()));
         }
         selection.selected_pile = next;
         return;
@@ -236,7 +236,7 @@ fn handle_selection_keys(
                 // --- Priority 1: foundation move (single card) ---
                 let foundation_dest = try_foundation_dest(card, &game.0);
                 if let Some(dest) = foundation_dest {
-                    moves.send(MoveRequestEvent {
+                    moves.write(MoveRequestEvent {
                         from: pile.clone(),
                         to: dest,
                         count: 1,
@@ -260,7 +260,7 @@ fn handle_selection_keys(
                     if let Some((dest, count)) =
                         best_tableau_destination_for_stack(bottom, pile, &game.0, run_len)
                     {
-                        moves.send(MoveRequestEvent {
+                        moves.write(MoveRequestEvent {
                             from: pile.clone(),
                             to: dest,
                             count,
@@ -274,7 +274,7 @@ fn handle_selection_keys(
                 // Covers non-tableau sources (Waste, Foundation) that have no
                 // stack-move logic.
                 if let Some(dest) = best_destination(card, &game.0) {
-                    moves.send(MoveRequestEvent {
+                    moves.write(MoveRequestEvent {
                         from: pile.clone(),
                         to: dest,
                         count: 1,
@@ -343,7 +343,7 @@ fn update_selection_highlight(
 ) {
     // Always despawn any existing highlight first.
     for entity in &highlights {
-        commands.entity(entity).despawn_recursive();
+        commands.entity(entity).despawn();
     }
 
     let Some(ref pile) = selection.selected_pile else {

solitaire_engine/src/settings_plugin.rs

@@ -36,7 +36,7 @@ pub struct SettingsStoragePath(pub Option<PathBuf>);
 pub struct SettingsScreen(pub bool);
 
 /// Fired whenever settings change so consumers (audio, UI) can react.
-#[derive(Event, Debug, Clone)]
+#[derive(Message, Debug, Clone)]
 pub struct SettingsChangedEvent(pub Settings);
 
 /// Marker on the root Settings panel entity.
@@ -144,9 +144,9 @@ impl Plugin for SettingsPlugin {
             .insert_resource(SettingsStoragePath(self.storage_path.clone()))
             .init_resource::<SettingsScreen>()
             .init_resource::<SettingsScrollPos>()
-            .add_event::<SettingsChangedEvent>()
-            .add_event::<ManualSyncRequestEvent>()
-            .add_event::<bevy::input::mouse::MouseWheel>()
+            .add_message::<SettingsChangedEvent>()
+            .add_message::<ManualSyncRequestEvent>()
+            .add_message::<bevy::input::mouse::MouseWheel>()
             .add_systems(Update, (handle_volume_keys, toggle_settings_screen, scroll_settings_panel));
 
         if self.ui_enabled {
@@ -185,7 +185,7 @@ fn handle_volume_keys(
     keys: Res<ButtonInput<KeyCode>>,
     mut settings: ResMut<SettingsResource>,
     path: Res<SettingsStoragePath>,
-    mut changed: EventWriter<SettingsChangedEvent>,
+    mut changed: MessageWriter<SettingsChangedEvent>,
 ) {
     let mut delta = 0.0_f32;
     if keys.just_pressed(KeyCode::BracketLeft) {
@@ -203,7 +203,7 @@ fn handle_volume_keys(
         return;
     }
     persist(&path, &settings.0);
-    changed.send(SettingsChangedEvent(settings.0.clone()));
+    changed.write(SettingsChangedEvent(settings.0.clone()));
 }
 
 /// Opens or closes the Settings panel when `O` is pressed.
@@ -256,11 +256,11 @@ fn sync_settings_panel_visibility(
         }
     } else {
         // Save the current scroll offset before despawning the panel.
-        if let Ok(sp) = scroll_nodes.get_single() {
-            scroll_pos.0 = sp.offset_y;
+        if let Ok(sp) = scroll_nodes.single() {
+            scroll_pos.0 = sp.0.y;
         }
         for entity in &panels {
-            commands.entity(entity).despawn_recursive();
+            commands.entity(entity).despawn();
         }
     }
 }
@@ -383,8 +383,8 @@ fn handle_settings_buttons(
     mut settings: ResMut<SettingsResource>,
     mut screen: ResMut<SettingsScreen>,
     path: Res<SettingsStoragePath>,
-    mut changed: EventWriter<SettingsChangedEvent>,
-    mut manual_sync: EventWriter<ManualSyncRequestEvent>,
+    mut changed: MessageWriter<SettingsChangedEvent>,
+    mut manual_sync: MessageWriter<ManualSyncRequestEvent>,
     mut sfx_text: Query<&mut Text, (With<SfxVolumeText>, Without<MusicVolumeText>, Without<DrawModeText>, Without<ThemeText>, Without<AnimSpeedText>, Without<ColorBlindText>)>,
     mut music_text: Query<&mut Text, (With<MusicVolumeText>, Without<SfxVolumeText>, Without<DrawModeText>, Without<ThemeText>, Without<AnimSpeedText>, Without<ColorBlindText>)>,
     mut draw_text: Query<&mut Text, (With<DrawModeText>, Without<SfxVolumeText>, Without<MusicVolumeText>, Without<ThemeText>, Without<AnimSpeedText>, Without<ColorBlindText>)>,
@@ -402,8 +402,8 @@ fn handle_settings_buttons(
                 let after = settings.0.adjust_sfx_volume(-SFX_STEP);
                 if (before - after).abs() > f32::EPSILON {
                     persist(&path, &settings.0);
-                    changed.send(SettingsChangedEvent(settings.0.clone()));
-                    if let Ok(mut t) = sfx_text.get_single_mut() {
+                    changed.write(SettingsChangedEvent(settings.0.clone()));
+                    if let Ok(mut t) = sfx_text.single_mut() {
                         **t = format!("{:.2}", after);
                     }
                 }
@@ -413,8 +413,8 @@ fn handle_settings_buttons(
                 let after = settings.0.adjust_sfx_volume(SFX_STEP);
                 if (before - after).abs() > f32::EPSILON {
                     persist(&path, &settings.0);
-                    changed.send(SettingsChangedEvent(settings.0.clone()));
-                    if let Ok(mut t) = sfx_text.get_single_mut() {
+                    changed.write(SettingsChangedEvent(settings.0.clone()));
+                    if let Ok(mut t) = sfx_text.single_mut() {
                         **t = format!("{:.2}", after);
                     }
                 }
@@ -424,8 +424,8 @@ fn handle_settings_buttons(
                 let after = settings.0.adjust_music_volume(-SFX_STEP);
                 if (before - after).abs() > f32::EPSILON {
                     persist(&path, &settings.0);
-                    changed.send(SettingsChangedEvent(settings.0.clone()));
-                    if let Ok(mut t) = music_text.get_single_mut() {
+                    changed.write(SettingsChangedEvent(settings.0.clone()));
+                    if let Ok(mut t) = music_text.single_mut() {
                         **t = format!("{:.2}", after);
                     }
                 }
@@ -435,8 +435,8 @@ fn handle_settings_buttons(
                 let after = settings.0.adjust_music_volume(SFX_STEP);
                 if (before - after).abs() > f32::EPSILON {
                     persist(&path, &settings.0);
-                    changed.send(SettingsChangedEvent(settings.0.clone()));
-                    if let Ok(mut t) = music_text.get_single_mut() {
+                    changed.write(SettingsChangedEvent(settings.0.clone()));
+                    if let Ok(mut t) = music_text.single_mut() {
                         **t = format!("{:.2}", after);
                     }
                 }
@@ -447,8 +447,8 @@ fn handle_settings_buttons(
                     DrawMode::DrawThree => DrawMode::DrawOne,
                 };
                 persist(&path, &settings.0);
-                changed.send(SettingsChangedEvent(settings.0.clone()));
-                if let Ok(mut t) = draw_text.get_single_mut() {
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+                if let Ok(mut t) = draw_text.single_mut() {
                     **t = draw_mode_label(&settings.0.draw_mode);
                 }
             }
@@ -459,8 +459,8 @@ fn handle_settings_buttons(
                     AnimSpeed::Instant => AnimSpeed::Normal,
                 };
                 persist(&path, &settings.0);
-                changed.send(SettingsChangedEvent(settings.0.clone()));
-                if let Ok(mut t) = anim_speed_text.get_single_mut() {
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+                if let Ok(mut t) = anim_speed_text.single_mut() {
                     **t = anim_speed_label(&settings.0.animation_speed);
                 }
             }
@@ -471,31 +471,31 @@ fn handle_settings_buttons(
                     Theme::Dark => Theme::Green,
                 };
                 persist(&path, &settings.0);
-                changed.send(SettingsChangedEvent(settings.0.clone()));
-                if let Ok(mut t) = theme_text.get_single_mut() {
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+                if let Ok(mut t) = theme_text.single_mut() {
                     **t = theme_label(&settings.0.theme);
                 }
             }
             SettingsButton::ToggleColorBlind => {
                 settings.0.color_blind_mode = !settings.0.color_blind_mode;
                 persist(&path, &settings.0);
-                changed.send(SettingsChangedEvent(settings.0.clone()));
-                if let Ok(mut t) = color_blind_text.get_single_mut() {
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+                if let Ok(mut t) = color_blind_text.single_mut() {
                     **t = color_blind_label(settings.0.color_blind_mode);
                 }
             }
             SettingsButton::SelectCardBack(idx) => {
                 settings.0.selected_card_back = *idx;
                 persist(&path, &settings.0);
-                changed.send(SettingsChangedEvent(settings.0.clone()));
+                changed.write(SettingsChangedEvent(settings.0.clone()));
             }
             SettingsButton::SelectBackground(idx) => {
                 settings.0.selected_background = *idx;
                 persist(&path, &settings.0);
-                changed.send(SettingsChangedEvent(settings.0.clone()));
+                changed.write(SettingsChangedEvent(settings.0.clone()));
             }
             SettingsButton::SyncNow => {
-                manual_sync.send(ManualSyncRequestEvent);
+                manual_sync.write(ManualSyncRequestEvent);
             }
             SettingsButton::Done => {
                 screen.0 = false;
@@ -537,7 +537,7 @@ fn color_blind_label(enabled: bool) -> String {
 /// adds to the offset; scrolling up subtracts. Clamped to >= 0 so it never
 /// scrolls past the top.
 fn scroll_settings_panel(
-    mut scroll_evr: EventReader<MouseWheel>,
+    mut scroll_evr: MessageReader<MouseWheel>,
     screen: Res<SettingsScreen>,
     mut scrollables: Query<&mut ScrollPosition, With<SettingsPanelScrollable>>,
 ) {
@@ -556,7 +556,7 @@ fn scroll_settings_panel(
         return;
     }
     for mut sp in scrollables.iter_mut() {
-        sp.offset_y = (sp.offset_y - delta_y).max(0.0);
+        sp.0.y = (sp.0.y - delta_y).max(0.0);
     }
 }
 
@@ -595,7 +595,7 @@ fn spawn_settings_panel(
             root.spawn((
                 SettingsPanelScrollable,
                 SettingsScrollNode,
-                ScrollPosition { offset_y: scroll_offset, ..default() },
+                ScrollPosition(Vec2::new(0.0, scroll_offset)),
                 Node {
                     flex_direction: FlexDirection::Column,
                     padding: UiRect::all(Val::Px(28.0)),
@@ -603,10 +603,10 @@ fn spawn_settings_panel(
                     min_width: Val::Px(340.0),
                     max_height: Val::Percent(88.0),
                     overflow: Overflow::scroll_y(),
+                    border_radius: BorderRadius::all(Val::Px(8.0)),
                     ..default()
                 },
                 BackgroundColor(Color::srgb(0.11, 0.11, 0.14)),
-                BorderRadius::all(Val::Px(8.0)),
             ))
             .with_children(|card| {
                 // Title
@@ -755,10 +755,10 @@ fn spawn_settings_panel(
                                 height: Val::Px(40.0),
                                 justify_content: JustifyContent::Center,
                                 align_items: AlignItems::Center,
+                                border_radius: BorderRadius::all(Val::Px(4.0)),
                                 ..default()
                             },
                             BackgroundColor(bg_color),
-                            BorderRadius::all(Val::Px(4.0)),
                         ))
                         .with_children(|b| {
                             b.spawn((
@@ -801,10 +801,10 @@ fn spawn_settings_panel(
                                 height: Val::Px(40.0),
                                 justify_content: JustifyContent::Center,
                                 align_items: AlignItems::Center,
+                                border_radius: BorderRadius::all(Val::Px(4.0)),
                                 ..default()
                             },
                             BackgroundColor(bg_color),
-                            BorderRadius::all(Val::Px(4.0)),
                         ))
                         .with_children(|b| {
                             b.spawn((
@@ -839,10 +839,10 @@ fn spawn_settings_panel(
                         Node {
                             padding: UiRect::axes(Val::Px(10.0), Val::Px(4.0)),
                             justify_content: JustifyContent::Center,
+                            border_radius: BorderRadius::all(Val::Px(4.0)),
                             ..default()
                         },
                         BackgroundColor(Color::srgb(0.20, 0.30, 0.45)),
-                        BorderRadius::all(Val::Px(4.0)),
                     ))
                     .with_children(|b| {
                         b.spawn((
@@ -861,10 +861,10 @@ fn spawn_settings_panel(
                         padding: UiRect::axes(Val::Px(20.0), Val::Px(8.0)),
                         justify_content: JustifyContent::Center,
                         margin: UiRect::top(Val::Px(6.0)),
+                        border_radius: BorderRadius::all(Val::Px(4.0)),
                         ..default()
                     },
                     BackgroundColor(Color::srgb(0.22, 0.45, 0.22)),
-                    BorderRadius::all(Val::Px(4.0)),
                 ))
                 .with_children(|b| {
                     b.spawn((
@@ -880,7 +880,7 @@ fn spawn_settings_panel(
         });
 }
 
-fn section_label(parent: &mut ChildBuilder, title: &str) {
+fn section_label(parent: &mut ChildSpawnerCommands, title: &str) {
     parent.spawn((
         Text::new(title),
         TextFont {
@@ -893,7 +893,7 @@ fn section_label(parent: &mut ChildBuilder, title: &str) {
 
 /// Generic volume row: `Label  0.80  [−]  [+]`
 fn volume_row<Marker: Component>(
-    parent: &mut ChildBuilder,
+    parent: &mut ChildSpawnerCommands,
     label: &str,
     value: f32,
     marker: Marker,
@@ -924,7 +924,7 @@ fn volume_row<Marker: Component>(
         });
 }
 
-fn icon_button(parent: &mut ChildBuilder, label: &str, action: SettingsButton) {
+fn icon_button(parent: &mut ChildSpawnerCommands, label: &str, action: SettingsButton) {
     parent
         .spawn((
             action,
@@ -934,10 +934,10 @@ fn icon_button(parent: &mut ChildBuilder, label: &str, action: SettingsButton) {
                 height: Val::Px(28.0),
                 justify_content: JustifyContent::Center,
                 align_items: AlignItems::Center,
+                border_radius: BorderRadius::all(Val::Px(4.0)),
                 ..default()
             },
             BackgroundColor(Color::srgb(0.25, 0.25, 0.30)),
-            BorderRadius::all(Val::Px(4.0)),
         ))
         .with_children(|b| {
             b.spawn((
@@ -995,7 +995,7 @@ mod tests {
         let after = app.world().resource::<SettingsResource>().0.sfx_volume;
         assert!(after < before);
 
-        let events = app.world().resource::<Events<SettingsChangedEvent>>();
+        let events = app.world().resource::<Messages<SettingsChangedEvent>>();
         let mut cursor = events.get_cursor();
         assert_eq!(cursor.read(events).count(), 1);
     }
@@ -1020,7 +1020,7 @@ mod tests {
         press(&mut app, KeyCode::BracketRight);
         app.update();
 
-        let events = app.world().resource::<Events<SettingsChangedEvent>>();
+        let events = app.world().resource::<Messages<SettingsChangedEvent>>();
         let mut cursor = events.get_cursor();
         assert_eq!(cursor.read(events).count(), 0);
     }
@@ -1036,7 +1036,7 @@ mod tests {
         let after = app.world().resource::<SettingsResource>().0.sfx_volume;
         assert!(after >= 0.0, "volume must not go below zero");
 
-        let events = app.world().resource::<Events<SettingsChangedEvent>>();
+        let events = app.world().resource::<Messages<SettingsChangedEvent>>();
         let mut cursor = events.get_cursor();
         assert_eq!(cursor.read(events).count(), 0, "no event when clamped at floor");
     }
@@ -1095,7 +1095,7 @@ mod tests {
             .spawn((SettingsPanelScrollable, ScrollPosition::default()))
             .id();
         // Send a downward scroll event while the panel is closed.
-        app.world_mut().send_event(MouseWheel {
+        app.world_mut().write_message(MouseWheel {
             unit: MouseScrollUnit::Line,
             x: 0.0,
             y: -3.0,
@@ -1108,7 +1108,7 @@ mod tests {
             .entity(entity)
             .get::<ScrollPosition>()
             .unwrap()
-            .offset_y;
+            .0.y;
         assert_eq!(offset, 0.0, "scroll must not move when panel is closed");
     }
 
@@ -1123,11 +1123,11 @@ mod tests {
             .world_mut()
             .spawn((
                 SettingsPanelScrollable,
-                ScrollPosition { offset_y: 100.0, ..default() },
+                ScrollPosition(Vec2::new(0.0, 100.0)),
             ))
             .id();
         // Scroll down by 2 lines (50 px/line → +100 px added to offset_y).
-        app.world_mut().send_event(MouseWheel {
+        app.world_mut().write_message(MouseWheel {
             unit: MouseScrollUnit::Line,
             x: 0.0,
             y: -2.0,
@@ -1139,7 +1139,7 @@ mod tests {
             .entity(entity)
             .get::<ScrollPosition>()
             .unwrap()
-            .offset_y;
+            .0.y;
         assert!((offset - 200.0).abs() < 1e-3, "scrolling down should increase offset_y; got {offset}");
     }
 
@@ -1153,11 +1153,11 @@ mod tests {
             .world_mut()
             .spawn((
                 SettingsPanelScrollable,
-                ScrollPosition { offset_y: 10.0, ..default() },
+                ScrollPosition(Vec2::new(0.0, 10.0)),
             ))
             .id();
         // Scroll up by 5 lines → would subtract 250 px, but must clamp to 0.
-        app.world_mut().send_event(MouseWheel {
+        app.world_mut().write_message(MouseWheel {
             unit: MouseScrollUnit::Line,
             x: 0.0,
             y: 5.0,
@@ -1169,7 +1169,7 @@ mod tests {
             .entity(entity)
             .get::<ScrollPosition>()
             .unwrap()
-            .offset_y;
+            .0.y;
         assert_eq!(offset, 0.0, "scrolling past top must clamp to 0, got {offset}");
     }
 }

solitaire_engine/src/stats_plugin.rs

@@ -77,10 +77,10 @@ impl Plugin for StatsPlugin {
         };
         app.insert_resource(StatsResource(loaded))
             .insert_resource(StatsStoragePath(self.storage_path.clone()))
-            .add_event::<GameWonEvent>()
-            .add_event::<NewGameRequestEvent>()
-            .add_event::<ForfeitEvent>()
-            .add_event::<InfoToastEvent>()
+            .add_message::<GameWonEvent>()
+            .add_message::<NewGameRequestEvent>()
+            .add_message::<ForfeitEvent>()
+            .add_message::<InfoToastEvent>()
             // record_abandoned must read `move_count` BEFORE handle_new_game
             // clobbers it with a fresh game.
             .add_systems(
@@ -111,7 +111,7 @@ fn persist(path: &StatsStoragePath, stats: &StatsSnapshot, context: &str) {
 }
 
 fn update_stats_on_win(
-    mut events: EventReader<GameWonEvent>,
+    mut events: MessageReader<GameWonEvent>,
     game: Res<GameStateResource>,
     mut stats: ResMut<StatsResource>,
     path: Res<StatsStoragePath>,
@@ -125,11 +125,11 @@ fn update_stats_on_win(
 }
 
 fn update_stats_on_new_game(
-    mut events: EventReader<NewGameRequestEvent>,
+    mut events: MessageReader<NewGameRequestEvent>,
     game: Res<GameStateResource>,
     mut stats: ResMut<StatsResource>,
     path: Res<StatsStoragePath>,
-    mut toast: EventWriter<InfoToastEvent>,
+    mut toast: MessageWriter<InfoToastEvent>,
 ) {
     for _ in events.read() {
         if game.0.move_count > 0 && !game.0.is_won {
@@ -137,7 +137,7 @@ fn update_stats_on_new_game(
             stats.0.record_abandoned();
             persist(&path, &stats.0, "abandoned game");
             if streak > 1 {
-                toast.send(InfoToastEvent(format!("Streak of {streak} broken!")));
+                toast.write(InfoToastEvent(format!("Streak of {streak} broken!")));
             }
         }
     }
@@ -149,12 +149,12 @@ fn update_stats_on_new_game(
 /// `AutoCompleteState` is reset here so the "AUTO" badge and chime do not bleed
 /// into the new deal (task #41).
 fn handle_forfeit(
-    mut events: EventReader<ForfeitEvent>,
+    mut events: MessageReader<ForfeitEvent>,
     game: Res<GameStateResource>,
     mut stats: ResMut<StatsResource>,
     path: Res<StatsStoragePath>,
-    mut new_game: EventWriter<NewGameRequestEvent>,
-    mut toast: EventWriter<InfoToastEvent>,
+    mut new_game: MessageWriter<NewGameRequestEvent>,
+    mut toast: MessageWriter<InfoToastEvent>,
     mut auto_complete: Option<ResMut<AutoCompleteState>>,
 ) {
     for _ in events.read() {
@@ -163,7 +163,7 @@ fn handle_forfeit(
             stats.0.record_abandoned();
             persist(&path, &stats.0, "forfeit");
             if streak > 1 {
-                toast.send(InfoToastEvent(format!("Streak of {streak} broken!")));
+                toast.write(InfoToastEvent(format!("Streak of {streak} broken!")));
             }
         }
         // Reset auto-complete so the badge and chime don't carry over to the
@@ -171,8 +171,8 @@ fn handle_forfeit(
         if let Some(ref mut ac) = auto_complete {
             **ac = AutoCompleteState::default();
         }
-        toast.send(InfoToastEvent("Game forfeited".to_string()));
-        new_game.send(NewGameRequestEvent::default());
+        toast.write(InfoToastEvent("Game forfeited".to_string()));
+        new_game.write(NewGameRequestEvent::default());
     }
 }
 
@@ -187,8 +187,8 @@ fn toggle_stats_screen(
     if !keys.just_pressed(KeyCode::KeyS) {
         return;
     }
-    if let Ok(entity) = screens.get_single() {
-        commands.entity(entity).despawn_recursive();
+    if let Ok(entity) = screens.single() {
+        commands.entity(entity).despawn();
     } else {
         spawn_stats_screen(
             &mut commands,
@@ -349,7 +349,7 @@ fn spawn_stats_screen(
 
 /// Spawn a single stat cell: a large value label on top and a small grey
 /// descriptor below, inside a fixed-width column node with a [`StatsCell`] marker.
-fn spawn_stat_cell(parent: &mut ChildBuilder, value: &str, label: &str) {
+fn spawn_stat_cell(parent: &mut ChildSpawnerCommands, value: &str, label: &str) {
     parent
         .spawn((
             StatsCell,
@@ -513,7 +513,7 @@ mod tests {
     #[test]
     fn win_event_increments_games_won() {
         let mut app = headless_app();
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 1000,
             time_seconds: 120,
         });
@@ -532,7 +532,7 @@ mod tests {
             .0
             .draw_mode = solitaire_core::game_state::DrawMode::DrawThree;
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 200,
         });
@@ -553,7 +553,7 @@ mod tests {
             .move_count = 3;
 
         app.world_mut()
-            .send_event(NewGameRequestEvent { seed: Some(999), mode: None });
+            .write_message(NewGameRequestEvent { seed: Some(999), mode: None });
         app.update();
 
         let stats = &app.world().resource::<StatsResource>().0;
@@ -566,7 +566,7 @@ mod tests {
     fn new_game_without_moves_does_not_record_abandoned() {
         let mut app = headless_app();
         app.world_mut()
-            .send_event(NewGameRequestEvent { seed: Some(42), mode: None });
+            .write_message(NewGameRequestEvent { seed: Some(42), mode: None });
         app.update();
 
         let stats = &app.world().resource::<StatsResource>().0;
@@ -781,10 +781,10 @@ mod tests {
             .0
             .move_count = 1;
 
-        app.world_mut().send_event(ForfeitEvent);
+        app.world_mut().write_message(ForfeitEvent);
         app.update();
 
-        let events = app.world().resource::<Events<InfoToastEvent>>();
+        let events = app.world().resource::<Messages<InfoToastEvent>>();
         let mut reader = events.get_cursor();
         let messages: Vec<&str> = reader
             .read(events)
@@ -792,7 +792,7 @@ mod tests {
             .collect();
 
         assert!(
-            messages.iter().any(|m| *m == "Streak of 3 broken!"),
+            messages.contains(&"Streak of 3 broken!"),
             "expected 'Streak of 3 broken!' in toasts, got: {messages:?}"
         );
     }
@@ -810,10 +810,10 @@ mod tests {
             .0
             .move_count = 1;
 
-        app.world_mut().send_event(ForfeitEvent);
+        app.world_mut().write_message(ForfeitEvent);
         app.update();
 
-        let events = app.world().resource::<Events<InfoToastEvent>>();
+        let events = app.world().resource::<Messages<InfoToastEvent>>();
         let mut reader = events.get_cursor();
         let messages: Vec<&str> = reader
             .read(events)

solitaire_engine/src/sync_plugin.rs

@@ -93,7 +93,7 @@ impl Plugin for SyncPlugin {
             .init_resource::<SyncStatusResource>()
             .init_resource::<PullTaskResult>()
             .init_resource::<PullTask>()
-            .add_event::<ManualSyncRequestEvent>()
+            .add_message::<ManualSyncRequestEvent>()
             .add_systems(Startup, start_pull)
             .add_systems(Update, (poll_pull_result, handle_manual_sync_request))
             .add_systems(Last, push_on_exit);
@@ -121,7 +121,7 @@ fn start_pull(
 /// Update system: starts a new pull task when `ManualSyncRequestEvent` is
 /// received, but only if no pull is already in flight.
 fn handle_manual_sync_request(
-    mut events: EventReader<ManualSyncRequestEvent>,
+    mut events: MessageReader<ManualSyncRequestEvent>,
     provider: Res<SyncProviderResource>,
     mut task_res: ResMut<PullTask>,
     mut status: ResMut<SyncStatusResource>,
@@ -217,7 +217,7 @@ fn poll_pull_result(
 /// that blocking on exit is permitted because the game loop is already
 /// shutting down.
 fn push_on_exit(
-    mut exit_events: EventReader<AppExit>,
+    mut exit_events: MessageReader<AppExit>,
     provider: Res<SyncProviderResource>,
     stats: Res<StatsResource>,
     achievements: Res<AchievementsResource>,
@@ -403,8 +403,7 @@ mod tests {
 
     #[test]
     fn build_payload_clones_stats() {
-        let mut stats = StatsSnapshot::default();
-        stats.games_played = 42;
+        let stats = StatsSnapshot { games_played: 42, ..Default::default() };
         let payload = build_payload(&stats, &[], &PlayerProgress::default());
         assert_eq!(payload.stats.games_played, 42);
     }

solitaire_engine/src/table_plugin.rs

@@ -10,6 +10,7 @@ use solitaire_core::card::Suit;
 use solitaire_core::pile::PileType;
 use solitaire_data::settings::Theme;
 
+use crate::events::HintVisualEvent;
 use crate::layout::{compute_layout, Layout, LayoutResource, TABLE_COLOUR};
 use crate::settings_plugin::{SettingsChangedEvent, SettingsResource};
 
@@ -27,6 +28,17 @@ pub struct TableBackground;
 #[derive(Component, Debug, Clone)]
 pub struct PileMarker(pub PileType);
 
+/// Attached to a `PileMarker` entity when it has been temporarily tinted gold
+/// as a hint destination. Stores the remaining countdown and the original sprite
+/// colour so it can be restored when the timer expires.
+#[derive(Component, Debug, Clone)]
+pub struct HintPileHighlight {
+    /// Seconds remaining before the pile marker colour is restored.
+    pub timer: f32,
+    /// The sprite colour the marker had before the hint tint was applied.
+    pub original_color: Color,
+}
+
 /// Registers the table background and pile-marker rendering.
 pub struct TablePlugin;
 
@@ -35,10 +47,19 @@ impl Plugin for TablePlugin {
         // Register WindowResized so the plugin works under MinimalPlugins in
         // tests. Under DefaultPlugins, bevy_window has already registered it
         // and this call is a no-op.
-        app.add_event::<WindowResized>()
-            .add_event::<SettingsChangedEvent>()
+        app.add_message::<WindowResized>()
+            .add_message::<SettingsChangedEvent>()
+            .add_message::<HintVisualEvent>()
             .add_systems(Startup, setup_table)
-            .add_systems(Update, (on_window_resized, apply_theme_on_settings_change));
+            .add_systems(
+                Update,
+                (
+                    on_window_resized,
+                    apply_theme_on_settings_change,
+                    apply_hint_pile_highlight,
+                    tick_hint_pile_highlights,
+                ),
+            );
     }
 }
 
@@ -112,7 +133,7 @@ fn spawn_background(commands: &mut Commands, window_size: Vec2, color: Color) {
 }
 
 fn apply_theme_on_settings_change(
-    mut events: EventReader<SettingsChangedEvent>,
+    mut events: MessageReader<SettingsChangedEvent>,
     mut backgrounds: Query<&mut Sprite, With<TableBackground>>,
 ) {
     let Some(ev) = events.read().last() else {
@@ -192,7 +213,7 @@ fn spawn_pile_markers(commands: &mut Commands, layout: &Layout) {
 
 #[allow(clippy::type_complexity)]
 fn on_window_resized(
-    mut events: EventReader<WindowResized>,
+    mut events: MessageReader<WindowResized>,
     mut layout_res: Option<ResMut<LayoutResource>>,
     mut backgrounds: Query<
         (&mut Sprite, &mut Transform),
@@ -225,6 +246,59 @@ fn on_window_resized(
     }
 }
 
+// ---------------------------------------------------------------------------
+// Task #6 — Hint pile-marker highlight
+// ---------------------------------------------------------------------------
+
+/// Gold tint applied to a `PileMarker` sprite when it is the current hint
+/// destination.
+const HINT_PILE_HIGHLIGHT_COLOUR: Color = Color::srgb(1.0, 0.85, 0.1);
+
+/// Listens for `HintVisualEvent` and tints the matching `PileMarker` entity
+/// gold for 2 s, storing the original colour in `HintPileHighlight` so it can
+/// be restored when the timer expires.
+///
+/// If the pile marker already has a `HintPileHighlight` from a previous hint
+/// press, the timer is reset to 2 s without changing `original_color`.
+fn apply_hint_pile_highlight(
+    mut events: MessageReader<HintVisualEvent>,
+    mut commands: Commands,
+    mut pile_markers: Query<(Entity, &PileMarker, &mut Sprite, Option<&HintPileHighlight>)>,
+) {
+    for ev in events.read() {
+        for (entity, pile_marker, mut sprite, existing) in pile_markers.iter_mut() {
+            if pile_marker.0 != ev.dest_pile {
+                continue;
+            }
+            let original_color = existing
+                .map(|h| h.original_color)
+                .unwrap_or(sprite.color);
+            sprite.color = HINT_PILE_HIGHLIGHT_COLOUR;
+            commands.entity(entity).insert(HintPileHighlight {
+                timer: 2.0,
+                original_color,
+            });
+        }
+    }
+}
+
+/// Counts down `HintPileHighlight::timer` each frame and restores the original
+/// pile marker colour when the timer expires.
+fn tick_hint_pile_highlights(
+    mut commands: Commands,
+    time: Res<Time>,
+    mut pile_markers: Query<(Entity, &mut Sprite, &mut HintPileHighlight)>,
+) {
+    let dt = time.delta_secs();
+    for (entity, mut sprite, mut highlight) in pile_markers.iter_mut() {
+        highlight.timer -= dt;
+        if highlight.timer <= 0.0 {
+            sprite.color = highlight.original_color;
+            commands.entity(entity).remove::<HintPileHighlight>();
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -342,6 +416,76 @@ mod tests {
         assert_eq!(suit_symbol(&Suit::Clubs),    "C");
     }
 
+    // -----------------------------------------------------------------------
+    // Task #6 — HintPileHighlight timer and colour pure-function tests
+    // -----------------------------------------------------------------------
+
+    /// The HINT_PILE_HIGHLIGHT_COLOUR constant must be visibly distinct from the
+    /// default pile marker colour so the player can see which pile is highlighted.
+    #[test]
+    fn hint_pile_highlight_colour_is_distinct_from_default() {
+        let default = Color::srgba(1.0, 1.0, 1.0, 0.08); // PILE_MARKER_DEFAULT_COLOUR
+        assert_ne!(
+            HINT_PILE_HIGHLIGHT_COLOUR, default,
+            "HINT_PILE_HIGHLIGHT_COLOUR must differ from the default pile marker colour"
+        );
+    }
+
+    /// A freshly-created HintPileHighlight has a positive timer countdown.
+    #[test]
+    fn hint_pile_highlight_timer_starts_positive() {
+        let h = HintPileHighlight {
+            timer: 2.0,
+            original_color: Color::srgba(1.0, 1.0, 1.0, 0.08),
+        };
+        assert!(
+            h.timer > 0.0,
+            "HintPileHighlight timer must start positive, got {}",
+            h.timer
+        );
+    }
+
+    /// Ticking the timer past its initial value results in a non-positive (expired)
+    /// countdown.
+    #[test]
+    fn hint_pile_highlight_timer_expires_after_full_duration() {
+        let mut remaining = 2.0_f32;
+        remaining -= 2.5; // 2.5 s elapsed on a 2.0 s timer
+        assert!(
+            remaining <= 0.0,
+            "timer must be expired after ticking past its initial value, got {}",
+            remaining
+        );
+    }
+
+    /// `original_color` is preserved through the highlight lifecycle so colour
+    /// can be correctly restored on expiry.
+    #[test]
+    fn hint_pile_highlight_preserves_original_color() {
+        let original = Color::srgb(0.1, 0.3, 0.5);
+        let h = HintPileHighlight {
+            timer: 2.0,
+            original_color: original,
+        };
+        assert_eq!(
+            h.original_color, original,
+            "original_color must be stored without modification"
+        );
+    }
+
+    /// The gold hint colour must have a strong yellow component (r ≥ 0.9, g ≥ 0.8,
+    /// b ≤ 0.3) to be clearly visible as a "destination" indicator.
+    #[test]
+    fn hint_pile_highlight_colour_is_gold() {
+        // Extract linear components.  srgb(1.0, 0.85, 0.1) is the expected gold.
+        // We test the channel values rather than exact equality so future tweaks
+        // to the shade do not break the test, as long as the colour remains golden.
+        let Srgba { red, green, blue, .. } = HINT_PILE_HIGHLIGHT_COLOUR.to_srgba();
+        assert!(red >= 0.9, "gold hint colour must have red ≥ 0.9, got {red}");
+        assert!(green >= 0.7, "gold hint colour must have green ≥ 0.7, got {green}");
+        assert!(blue <= 0.3, "gold hint colour must have blue ≤ 0.3, got {blue}");
+    }
+
     #[test]
     fn suit_symbol_all_four_are_distinct() {
         let symbols: Vec<&str> = [Suit::Spades, Suit::Hearts, Suit::Diamonds, Suit::Clubs]

solitaire_engine/src/time_attack_plugin.rs

@@ -26,7 +26,7 @@ pub struct TimeAttackResource {
 
 /// Fired when the Time Attack timer expires. The summary toast in
 /// `AnimationPlugin` consumes this; UI/stats consumers can also subscribe.
-#[derive(Event, Debug, Clone, Copy)]
+#[derive(Message, Debug, Clone, Copy)]
 pub struct TimeAttackEndedEvent {
     pub wins: u32,
 }
@@ -36,10 +36,10 @@ pub struct TimeAttackPlugin;
 impl Plugin for TimeAttackPlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<TimeAttackResource>()
-            .add_event::<TimeAttackEndedEvent>()
-            .add_event::<GameWonEvent>()
-            .add_event::<NewGameRequestEvent>()
-            .add_event::<InfoToastEvent>()
+            .add_message::<TimeAttackEndedEvent>()
+            .add_message::<GameWonEvent>()
+            .add_message::<NewGameRequestEvent>()
+            .add_message::<InfoToastEvent>()
             .add_systems(
                 Update,
                 handle_start_time_attack_request.before(GameMutation),
@@ -53,14 +53,14 @@ fn handle_start_time_attack_request(
     keys: Res<ButtonInput<KeyCode>>,
     progress: Res<ProgressResource>,
     mut session: ResMut<TimeAttackResource>,
-    mut new_game: EventWriter<NewGameRequestEvent>,
-    mut info_toast: EventWriter<InfoToastEvent>,
+    mut new_game: MessageWriter<NewGameRequestEvent>,
+    mut info_toast: MessageWriter<InfoToastEvent>,
 ) {
     if !keys.just_pressed(KeyCode::KeyT) {
         return;
     }
     if progress.0.level < CHALLENGE_UNLOCK_LEVEL {
-        info_toast.send(InfoToastEvent(format!(
+        info_toast.write(InfoToastEvent(format!(
             "Time Attack unlocks at level {CHALLENGE_UNLOCK_LEVEL}"
         )));
         return;
@@ -70,7 +70,7 @@ fn handle_start_time_attack_request(
         remaining_secs: TIME_ATTACK_DURATION_SECS,
         wins: 0,
     };
-    new_game.send(NewGameRequestEvent {
+    new_game.write(NewGameRequestEvent {
         seed: None,
         mode: Some(GameMode::TimeAttack),
     });
@@ -79,7 +79,7 @@ fn handle_start_time_attack_request(
 fn advance_time_attack(
     time: Res<Time>,
     mut session: ResMut<TimeAttackResource>,
-    mut ended: EventWriter<TimeAttackEndedEvent>,
+    mut ended: MessageWriter<TimeAttackEndedEvent>,
     paused: Option<Res<crate::pause_plugin::PausedResource>>,
 ) {
     if !session.active {
@@ -93,22 +93,22 @@ fn advance_time_attack(
         let wins = session.wins;
         session.active = false;
         session.remaining_secs = 0.0;
-        ended.send(TimeAttackEndedEvent { wins });
+        ended.write(TimeAttackEndedEvent { wins });
     }
 }
 
 fn auto_deal_on_time_attack_win(
-    mut wins: EventReader<GameWonEvent>,
+    mut wins: MessageReader<GameWonEvent>,
     game: Res<GameStateResource>,
     mut session: ResMut<TimeAttackResource>,
-    mut new_game: EventWriter<NewGameRequestEvent>,
+    mut new_game: MessageWriter<NewGameRequestEvent>,
 ) {
     for _ in wins.read() {
         if !session.active || game.0.mode != GameMode::TimeAttack {
             continue;
         }
         session.wins = session.wins.saturating_add(1);
-        new_game.send(NewGameRequestEvent {
+        new_game.write(NewGameRequestEvent {
             seed: None,
             mode: Some(GameMode::TimeAttack),
         });
@@ -151,7 +151,7 @@ mod tests {
         let session = app.world().resource::<TimeAttackResource>();
         assert!(!session.active);
 
-        let events = app.world().resource::<Events<NewGameRequestEvent>>();
+        let events = app.world().resource::<Messages<NewGameRequestEvent>>();
         let mut cursor = events.get_cursor();
         assert!(cursor.read(events).next().is_none());
     }
@@ -169,7 +169,7 @@ mod tests {
         assert_eq!(session.wins, 0);
         assert!((session.remaining_secs - TIME_ATTACK_DURATION_SECS).abs() < 1.0);
 
-        let events = app.world().resource::<Events<NewGameRequestEvent>>();
+        let events = app.world().resource::<Messages<NewGameRequestEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).copied().collect();
         assert_eq!(fired.len(), 1);
@@ -193,7 +193,7 @@ mod tests {
         assert!(!session.active);
         assert_eq!(session.remaining_secs, 0.0);
 
-        let events = app.world().resource::<Events<TimeAttackEndedEvent>>();
+        let events = app.world().resource::<Messages<TimeAttackEndedEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).copied().collect();
         assert_eq!(fired.len(), 1);
@@ -213,7 +213,7 @@ mod tests {
         app.world_mut().resource_mut::<GameStateResource>().0 =
             GameState::new_with_mode(7, DrawMode::DrawOne, GameMode::TimeAttack);
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 60,
         });
@@ -222,7 +222,7 @@ mod tests {
         let session = app.world().resource::<TimeAttackResource>();
         assert_eq!(session.wins, 1);
 
-        let events = app.world().resource::<Events<NewGameRequestEvent>>();
+        let events = app.world().resource::<Messages<NewGameRequestEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).copied().collect();
         assert_eq!(fired.len(), 1);
@@ -237,7 +237,7 @@ mod tests {
         app.world_mut().resource_mut::<GameStateResource>().0 =
             GameState::new_with_mode(7, DrawMode::DrawOne, GameMode::TimeAttack);
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 60,
         });
@@ -256,7 +256,7 @@ mod tests {
             wins: 0,
         };
         // GameStateResource defaults to Classic mode.
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 60,
         });
@@ -286,7 +286,7 @@ mod tests {
         assert!(session.remaining_secs < 0.0, "remaining_secs must not change while paused");
 
         // No ended event must have been emitted.
-        let events = app.world().resource::<Events<TimeAttackEndedEvent>>();
+        let events = app.world().resource::<Messages<TimeAttackEndedEvent>>();
         let mut cursor = events.get_cursor();
         assert!(
             cursor.read(events).next().is_none(),

solitaire_engine/src/weekly_goals_plugin.rs

@@ -15,7 +15,7 @@ use crate::progress_plugin::{LevelUpEvent, ProgressResource, ProgressStoragePath
 use crate::resources::GameStateResource;
 
 /// Fired when the player has just completed a weekly goal.
-#[derive(Event, Debug, Clone)]
+#[derive(Message, Debug, Clone)]
 pub struct WeeklyGoalCompletedEvent {
     pub goal_id: String,
     pub description: String,
@@ -25,9 +25,9 @@ pub struct WeeklyGoalsPlugin;
 
 impl Plugin for WeeklyGoalsPlugin {
     fn build(&self, app: &mut App) {
-        app.add_event::<WeeklyGoalCompletedEvent>()
-            .add_event::<GameWonEvent>()
-            .add_event::<XpAwardedEvent>()
+        app.add_message::<WeeklyGoalCompletedEvent>()
+            .add_message::<GameWonEvent>()
+            .add_message::<XpAwardedEvent>()
             .add_systems(Startup, roll_weekly_goals_on_startup)
             // Run after GameMutation (so GameWonEvent is available) and
             // ProgressUpdate (so we don't fight ProgressPlugin's add_xp).
@@ -57,13 +57,13 @@ fn roll_weekly_goals_on_startup(
 }
 
 fn evaluate_weekly_goals(
-    mut wins: EventReader<GameWonEvent>,
+    mut wins: MessageReader<GameWonEvent>,
     game: Res<GameStateResource>,
     mut progress: ResMut<ProgressResource>,
     path: Res<ProgressStoragePath>,
-    mut completions: EventWriter<WeeklyGoalCompletedEvent>,
-    mut levelups: EventWriter<LevelUpEvent>,
-    mut xp_awarded: EventWriter<XpAwardedEvent>,
+    mut completions: MessageWriter<WeeklyGoalCompletedEvent>,
+    mut levelups: MessageWriter<LevelUpEvent>,
+    mut xp_awarded: MessageWriter<XpAwardedEvent>,
 ) {
     let mut events: Vec<&GameWonEvent> = wins.read().collect();
     if events.is_empty() {
@@ -92,7 +92,7 @@ fn evaluate_weekly_goals(
             any_change = true;
             if just_completed {
                 bonus_xp = bonus_xp.saturating_add(WEEKLY_GOAL_XP);
-                completions.send(WeeklyGoalCompletedEvent {
+                completions.write(WeeklyGoalCompletedEvent {
                     goal_id: def.id.to_string(),
                     description: def.description.to_string(),
                 });
@@ -101,10 +101,10 @@ fn evaluate_weekly_goals(
     }
 
     if bonus_xp > 0 {
-        xp_awarded.send(XpAwardedEvent { amount: bonus_xp });
+        xp_awarded.write(XpAwardedEvent { amount: bonus_xp });
         let prev_level = progress.0.add_xp(bonus_xp);
         if progress.0.leveled_up_from(prev_level) {
-            levelups.send(LevelUpEvent {
+            levelups.write(LevelUpEvent {
                 previous_level: prev_level,
                 new_level: progress.0.level,
                 total_xp: progress.0.total_xp,
@@ -149,7 +149,7 @@ mod tests {
     #[test]
     fn first_win_increments_win_game_goal() {
         let mut app = headless_app();
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 200,
         });
@@ -158,13 +158,13 @@ mod tests {
         assert_eq!(p.weekly_goal_progress.get("weekly_5_wins"), Some(&1));
         // No-undo + slow win → no_undo goal also ticked, fast goal NOT ticked.
         assert_eq!(p.weekly_goal_progress.get("weekly_3_no_undo"), Some(&1));
-        assert!(p.weekly_goal_progress.get("weekly_3_fast").is_none());
+        assert!(!p.weekly_goal_progress.contains_key("weekly_3_fast"));
     }
 
     #[test]
     fn fast_win_ticks_fast_goal_too() {
         let mut app = headless_app();
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 60,
         });
@@ -181,14 +181,14 @@ mod tests {
             .0
             .undo_count = 1;
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 200,
         });
         app.update();
         let p = &app.world().resource::<ProgressResource>().0;
         assert_eq!(p.weekly_goal_progress.get("weekly_5_wins"), Some(&1));
-        assert!(p.weekly_goal_progress.get("weekly_3_no_undo").is_none());
+        assert!(!p.weekly_goal_progress.contains_key("weekly_3_no_undo"));
     }
 
     #[test]
@@ -214,7 +214,7 @@ mod tests {
 
         let xp_before = app.world().resource::<ProgressResource>().0.total_xp;
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 60,
         });
@@ -228,7 +228,7 @@ mod tests {
         let base_win_xp = solitaire_data::xp_for_win(60, false);
         assert_eq!(p.total_xp - xp_before, base_win_xp + WEEKLY_GOAL_XP);
 
-        let events = app.world().resource::<Events<WeeklyGoalCompletedEvent>>();
+        let events = app.world().resource::<Messages<WeeklyGoalCompletedEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).cloned().collect();
         assert!(fired.iter().any(|e| e.goal_id == "weekly_3_fast"));
@@ -280,13 +280,13 @@ mod tests {
             .0
             .weekly_goal_week_iso = Some(key);
 
-        app.world_mut().send_event(GameWonEvent {
+        app.world_mut().write_message(GameWonEvent {
             score: 500,
             time_seconds: 60,
         });
         app.update();
 
-        let events = app.world().resource::<Events<LevelUpEvent>>();
+        let events = app.world().resource::<Messages<LevelUpEvent>>();
         let mut cursor = events.get_cursor();
         let fired: Vec<_> = cursor.read(events).copied().collect();
         assert!(!fired.is_empty(), "LevelUpEvent must fire when weekly bonus pushes past a level threshold");

solitaire_engine/src/win_summary_plugin.rs

@@ -159,11 +159,11 @@ impl Plugin for WinSummaryPlugin {
         app.init_resource::<WinSummaryPending>()
             .init_resource::<ScreenShakeResource>()
             .init_resource::<SessionAchievements>()
-            .add_event::<GameWonEvent>()
-            .add_event::<XpAwardedEvent>()
-            .add_event::<NewGameRequestEvent>()
-            .add_event::<InfoToastEvent>()
-            .add_event::<AchievementUnlockedEvent>()
+            .add_message::<GameWonEvent>()
+            .add_message::<XpAwardedEvent>()
+            .add_message::<NewGameRequestEvent>()
+            .add_message::<InfoToastEvent>()
+            .add_message::<AchievementUnlockedEvent>()
             // `cache_win_data` must run BEFORE `StatsUpdate` so it can compare
             // the player's old personal-best values before `StatsPlugin` overwrites them.
             .add_systems(
@@ -221,13 +221,13 @@ pub fn format_win_time(seconds: u64) -> String {
 /// This system is scheduled `.before(StatsUpdate)` so the comparison always
 /// sees the old best values.
 fn cache_win_data(
-    mut won: EventReader<GameWonEvent>,
-    mut xp: EventReader<XpAwardedEvent>,
+    mut won: MessageReader<GameWonEvent>,
+    mut xp: MessageReader<XpAwardedEvent>,
     mut pending: ResMut<WinSummaryPending>,
     stats: Res<StatsResource>,
     game: Res<GameStateResource>,
     progress: Res<ProgressResource>,
-    mut toast: EventWriter<InfoToastEvent>,
+    mut toast: MessageWriter<InfoToastEvent>,
 ) {
     for ev in won.read() {
         // Compare against old personal bests BEFORE StatsPlugin updates them.
@@ -255,7 +255,7 @@ fn cache_win_data(
         pending.challenge_level = challenge_level;
 
         if is_new_record {
-            toast.send(InfoToastEvent("New Record!".to_string()));
+            toast.write(InfoToastEvent("New Record!".to_string()));
         }
     }
     for ev in xp.read() {
@@ -274,8 +274,8 @@ fn cache_win_data(
 /// reader covers every implicit game-context reset in addition to the
 /// explicit N / "Play Again" new-game requests.
 fn collect_session_achievements(
-    mut unlocks: EventReader<AchievementUnlockedEvent>,
-    mut new_games: EventReader<NewGameRequestEvent>,
+    mut unlocks: MessageReader<AchievementUnlockedEvent>,
+    mut new_games: MessageReader<NewGameRequestEvent>,
     mut session: ResMut<SessionAchievements>,
 ) {
     // Reset on any new-game request (including mode switches via Z/X/C/T) so
@@ -303,8 +303,8 @@ fn collect_session_achievements(
 #[allow(clippy::too_many_arguments)]
 fn spawn_win_summary_after_delay(
     mut commands: Commands,
-    mut won: EventReader<GameWonEvent>,
-    mut xp_events: EventReader<XpAwardedEvent>,
+    mut won: MessageReader<GameWonEvent>,
+    mut xp_events: MessageReader<XpAwardedEvent>,
     mut shake: ResMut<ScreenShakeResource>,
     mut pending: ResMut<WinSummaryPending>,
     session: Res<SessionAchievements>,
@@ -321,7 +321,7 @@ fn spawn_win_summary_after_delay(
         *delay = Some(WIN_SUMMARY_DELAY_SECS);
         // Clear any stale overlay from a previous win.
         for entity in &overlays {
-            commands.entity(entity).despawn_recursive();
+            commands.entity(entity).despawn();
         }
     }
 
@@ -352,7 +352,7 @@ fn handle_win_summary_buttons(
     interaction_query: Query<(&Interaction, &WinSummaryButton), Changed<Interaction>>,
     overlays: Query<Entity, With<WinSummaryOverlay>>,
     mut commands: Commands,
-    mut new_game: EventWriter<NewGameRequestEvent>,
+    mut new_game: MessageWriter<NewGameRequestEvent>,
 ) {
     for (interaction, button) in &interaction_query {
         if *interaction != Interaction::Pressed {
@@ -362,9 +362,9 @@ fn handle_win_summary_buttons(
             WinSummaryButton::PlayAgain => {
                 // Despawn the modal.
                 for entity in &overlays {
-                    commands.entity(entity).despawn_recursive();
+                    commands.entity(entity).despawn();
                 }
-                new_game.send(NewGameRequestEvent::default());
+                new_game.write(NewGameRequestEvent::default());
             }
         }
     }
@@ -442,10 +442,10 @@ fn spawn_overlay(
                     row_gap: Val::Px(18.0),
                     min_width: Val::Px(320.0),
                     align_items: AlignItems::Center,
+                    border_radius: BorderRadius::all(Val::Px(12.0)),
                     ..default()
                 },
                 BackgroundColor(Color::srgb(0.10, 0.12, 0.10)),
-                BorderRadius::all(Val::Px(12.0)),
             ))
             .with_children(|card| {
                 // Heading
@@ -518,10 +518,10 @@ fn spawn_overlay(
                         padding: UiRect::axes(Val::Px(28.0), Val::Px(12.0)),
                         justify_content: JustifyContent::Center,
                         margin: UiRect::top(Val::Px(8.0)),
+                        border_radius: BorderRadius::all(Val::Px(6.0)),
                         ..default()
                     },
                     BackgroundColor(Color::srgb(0.22, 0.45, 0.22)),
-                    BorderRadius::all(Val::Px(6.0)),
                 ))
                 .with_children(|b| {
                     b.spawn((
@@ -543,7 +543,7 @@ const MAX_ACHIEVEMENTS_SHOWN: usize = 3;
 /// Shows at most [`MAX_ACHIEVEMENTS_SHOWN`] names. When more achievements were
 /// unlocked than the cap, appends a "...and N more" line so the player knows
 /// there are additional unlocks visible on the achievements screen.
-fn spawn_achievements_section(card: &mut ChildBuilder, names: &[String]) {
+fn spawn_achievements_section(card: &mut ChildSpawnerCommands, names: &[String]) {
     card.spawn((
         Text::new("Achievements Unlocked"),
         TextFont { font_size: 18.0, ..default() },
@@ -677,7 +677,7 @@ mod tests {
         use solitaire_data::AchievementRecord;
         let record = AchievementRecord::locked("first_win");
         app.world_mut()
-            .send_event(AchievementUnlockedEvent(record));
+            .write_message(AchievementUnlockedEvent(record));
         app.update();
 
         let session = app.world().resource::<SessionAchievements>();
@@ -693,7 +693,7 @@ mod tests {
         use solitaire_data::AchievementRecord;
         let record = AchievementRecord::locked("first_win");
         app.world_mut()
-            .send_event(AchievementUnlockedEvent(record));
+            .write_message(AchievementUnlockedEvent(record));
         app.update();
 
         // Confirm it was recorded.
@@ -703,7 +703,7 @@ mod tests {
         );
 
         // Fire NewGameRequestEvent — should clear the list.
-        app.world_mut().send_event(NewGameRequestEvent::default());
+        app.world_mut().write_message(NewGameRequestEvent::default());
         app.update();
 
         assert!(
@@ -727,7 +727,7 @@ mod tests {
         // Simulate an achievement unlock during the current session.
         let record = AchievementRecord::locked("first_win");
         app.world_mut()
-            .send_event(AchievementUnlockedEvent(record));
+            .write_message(AchievementUnlockedEvent(record));
         app.update();
 
         assert_eq!(
@@ -739,7 +739,7 @@ mod tests {
         // Simulate pressing Z (Zen mode switch) — fires NewGameRequestEvent
         // with mode = Some(Zen). Same event shape used by X (Challenge),
         // C (Daily Challenge), and T (Time Attack).
-        app.world_mut().send_event(NewGameRequestEvent {
+        app.world_mut().write_message(NewGameRequestEvent {
             seed: None,
             mode: Some(GameMode::Zen),
         });
@@ -756,7 +756,7 @@ mod tests {
         let mut app = make_app();
 
         app.world_mut()
-            .send_event(GameWonEvent { score: 1234, time_seconds: 90 });
+            .write_message(GameWonEvent { score: 1234, time_seconds: 90 });
         app.update();
 
         let pending = app.world().resource::<WinSummaryPending>();
@@ -771,8 +771,8 @@ mod tests {
     fn cache_win_data_sets_xp_from_xp_awarded_event() {
         let mut app = make_app();
 
-        app.world_mut().send_event(GameWonEvent { score: 0, time_seconds: 0 });
-        app.world_mut().send_event(XpAwardedEvent { amount: 75 });
+        app.world_mut().write_message(GameWonEvent { score: 0, time_seconds: 0 });
+        app.world_mut().write_message(XpAwardedEvent { amount: 75 });
         app.update();
 
         let pending = app.world().resource::<WinSummaryPending>();
@@ -784,7 +784,7 @@ mod tests {
         let mut app = make_app();
 
         app.world_mut()
-            .send_event(GameWonEvent { score: 0, time_seconds: 0 });
+            .write_message(GameWonEvent { score: 0, time_seconds: 0 });
         app.update();
 
         let shake = app.world().resource::<ScreenShakeResource>();
@@ -802,7 +802,7 @@ mod tests {
         let mut app = make_app();
 
         app.world_mut()
-            .send_event(GameWonEvent { score: 500, time_seconds: 120 });
+            .write_message(GameWonEvent { score: 500, time_seconds: 120 });
         app.update();
 
         let pending = app.world().resource::<WinSummaryPending>();
@@ -820,7 +820,7 @@ mod tests {
 
         // Score 500 beats previous best of 400.
         app.world_mut()
-            .send_event(GameWonEvent { score: 500, time_seconds: 300 });
+            .write_message(GameWonEvent { score: 500, time_seconds: 300 });
         app.update();
 
         let pending = app.world().resource::<WinSummaryPending>();
@@ -838,7 +838,7 @@ mod tests {
 
         // Score 500 does not beat 800, but time 100 < 200.
         app.world_mut()
-            .send_event(GameWonEvent { score: 500, time_seconds: 100 });
+            .write_message(GameWonEvent { score: 500, time_seconds: 100 });
         app.update();
 
         let pending = app.world().resource::<WinSummaryPending>();
@@ -856,7 +856,7 @@ mod tests {
 
         // Score 500 < 800 and time 120 > 60 — neither record broken.
         app.world_mut()
-            .send_event(GameWonEvent { score: 500, time_seconds: 120 });
+            .write_message(GameWonEvent { score: 500, time_seconds: 120 });
         app.update();
 
         let pending = app.world().resource::<WinSummaryPending>();
@@ -887,7 +887,7 @@ mod tests {
         }
 
         app.world_mut()
-            .send_event(GameWonEvent { score: 0, time_seconds: 0 });
+            .write_message(GameWonEvent { score: 0, time_seconds: 0 });
         app.update();
 
         let pending = app.world().resource::<WinSummaryPending>();
@@ -903,7 +903,7 @@ mod tests {
         let mut app = make_app();
         // Default game mode is Classic — challenge_level should stay None.
         app.world_mut()
-            .send_event(GameWonEvent { score: 0, time_seconds: 0 });
+            .write_message(GameWonEvent { score: 0, time_seconds: 0 });
         app.update();
 
         let pending = app.world().resource::<WinSummaryPending>();

solitaire_server/src/lib.rs

@@ -64,9 +64,7 @@ fn build_router_inner(pool: SqlitePool, rate_limit: bool) -> Router {
                 .finish()
                 .expect("invalid governor config"),
         );
-        auth_routes.layer(GovernorLayer {
-            config: governor_conf,
-        })
+        auth_routes.layer(GovernorLayer::new(governor_conf))
     } else {
         auth_routes
     };

solitaire_server/src/middleware.rs

@@ -100,6 +100,21 @@ pub fn validate_refresh_token(token: &str, secret: &str) -> Result<Claims, AppEr
 // Axum extractor — allows handlers to receive AuthenticatedUser directly
 // ---------------------------------------------------------------------------
 
+impl<S> FromRequestParts<S> for AuthenticatedUser
+where
+    S: Send + Sync,
+{
+    type Rejection = AppError;
+
+    async fn from_request_parts(parts: &mut Parts, _state: &S) -> Result<Self, Self::Rejection> {
+        parts
+            .extensions
+            .get::<AuthenticatedUser>()
+            .cloned()
+            .ok_or(AppError::Unauthorized)
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
@@ -221,19 +236,3 @@ mod tests {
         assert!(result.is_err(), "expired refresh token must be rejected");
     }
 }
-
-#[axum::async_trait]
-impl<S> FromRequestParts<S> for AuthenticatedUser
-where
-    S: Send + Sync,
-{
-    type Rejection = AppError;
-
-    async fn from_request_parts(parts: &mut Parts, _state: &S) -> Result<Self, Self::Rejection> {
-        parts
-            .extensions
-            .get::<AuthenticatedUser>()
-            .cloned()
-            .ok_or(AppError::Unauthorized)
-    }
-}

solitaire_sync/src/progress.rs

@@ -201,8 +201,7 @@ mod tests {
 
     #[test]
     fn add_xp_saturates_on_overflow() {
-        let mut p = PlayerProgress::default();
-        p.total_xp = u64::MAX;
+        let mut p = PlayerProgress { total_xp: u64::MAX, ..Default::default() };
         p.add_xp(1);
         assert_eq!(p.total_xp, u64::MAX);
     }
@@ -230,8 +229,7 @@ mod tests {
 
     #[test]
     fn roll_weekly_goals_clears_progress_for_new_week() {
-        let mut p = PlayerProgress::default();
-        p.weekly_goal_week_iso = Some("2026-W16".to_string());
+        let mut p = PlayerProgress { weekly_goal_week_iso: Some("2026-W16".to_string()), ..Default::default() };
         p.weekly_goal_progress.insert("weekly_5_wins".to_string(), 3);
 
         let rolled = p.roll_weekly_goals_if_new_week("2026-W17");
@@ -242,8 +240,7 @@ mod tests {
 
     #[test]
     fn roll_weekly_goals_is_noop_for_same_week() {
-        let mut p = PlayerProgress::default();
-        p.weekly_goal_week_iso = Some("2026-W17".to_string());
+        let mut p = PlayerProgress { weekly_goal_week_iso: Some("2026-W17".to_string()), ..Default::default() };
         p.weekly_goal_progress.insert("weekly_5_wins".to_string(), 2);
 
         let rolled = p.roll_weekly_goals_if_new_week("2026-W17");

solitaire_sync/src/stats.rs

@@ -135,17 +135,14 @@ mod tests {
 
     #[test]
     fn record_abandoned_resets_win_streak() {
-        let mut s = StatsSnapshot::default();
-        s.win_streak_current = 5;
+        let mut s = StatsSnapshot { win_streak_current: 5, ..Default::default() };
         s.record_abandoned();
         assert_eq!(s.win_streak_current, 0, "abandoned game must break the win streak");
     }
 
     #[test]
     fn record_abandoned_preserves_best_streak() {
-        let mut s = StatsSnapshot::default();
-        s.win_streak_best = 7;
-        s.win_streak_current = 7;
+        let mut s = StatsSnapshot { win_streak_best: 7, win_streak_current: 7, ..Default::default() };
         s.record_abandoned();
         assert_eq!(s.win_streak_best, 7, "best streak must not be reduced on abandon");
         assert_eq!(s.win_streak_current, 0);