feat(data,engine): persistent Settings + SFX volume hotkeys

- solitaire_data::Settings { sfx_volume, first_run_complete } with
  atomic JSON persistence and clamping sanitizer.
- SettingsPlugin (engine): [ / ] adjust SFX volume by 0.1, clamped;
  persists on change; emits SettingsChangedEvent. No-op at rails.
- AudioPlugin applies sfx_volume to kira's main track at startup
  and on every change so live tweaks take effect without restart.
- Brief "SFX: N%" toast on each change. Help cheat sheet updated.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

solitaire_engine/src/animation_plugin.rs

@@ -13,6 +13,7 @@ use crate::events::{AchievementUnlockedEvent, GameWonEvent};
 use crate::game_plugin::GameMutation;
 use crate::layout::LayoutResource;
 use crate::progress_plugin::LevelUpEvent;
+use crate::settings_plugin::SettingsChangedEvent;
 use crate::time_attack_plugin::TimeAttackEndedEvent;
 use crate::weekly_goals_plugin::WeeklyGoalCompletedEvent;
 
@@ -26,6 +27,7 @@ const DAILY_TOAST_SECS: f32 = 3.0;
 const WEEKLY_TOAST_SECS: f32 = 3.0;
 const TIME_ATTACK_TOAST_SECS: f32 = 5.0;
 const CHALLENGE_TOAST_SECS: f32 = 3.0;
+const VOLUME_TOAST_SECS: f32 = 1.4;
 const CASCADE_STAGGER: f32 = 0.05;
 const CASCADE_DURATION: f32 = 0.5;
 
@@ -65,6 +67,7 @@ impl Plugin for AnimationPlugin {
             .add_event::<WeeklyGoalCompletedEvent>()
             .add_event::<TimeAttackEndedEvent>()
             .add_event::<ChallengeAdvancedEvent>()
+            .add_event::<SettingsChangedEvent>()
             .add_systems(
                 Update,
                 (
@@ -76,6 +79,7 @@ impl Plugin for AnimationPlugin {
                     handle_weekly_toast,
                     handle_time_attack_toast,
                     handle_challenge_toast,
+                    handle_settings_toast,
                     tick_toasts,
                 )
                     .after(GameMutation),
@@ -215,6 +219,20 @@ fn handle_challenge_toast(
     }
 }
 
+fn handle_settings_toast(
+    mut commands: Commands,
+    mut events: EventReader<SettingsChangedEvent>,
+) {
+    for ev in events.read() {
+        let pct = (ev.0.sfx_volume * 100.0).round() as i32;
+        spawn_toast(
+            &mut commands,
+            format!("SFX: {pct}%"),
+            VOLUME_TOAST_SECS,
+        );
+    }
+}
+
 fn tick_toasts(
     mut commands: Commands,
     time: Res<Time>,

solitaire_engine/src/audio_plugin.rs

@@ -22,10 +22,12 @@ use bevy::prelude::*;
 use kira::manager::backend::DefaultBackend;
 use kira::manager::{AudioManager, AudioManagerSettings};
 use kira::sound::static_sound::StaticSoundData;
+use kira::tween::Tween;
 
 use crate::events::{
     DrawRequestEvent, GameWonEvent, MoveRejectedEvent, MoveRequestEvent, NewGameRequestEvent,
 };
+use crate::settings_plugin::{SettingsChangedEvent, SettingsResource};
 
 /// Pre-decoded sound effects. Cheap to clone (frames are an `Arc<[Frame]>`),
 /// so we hand a fresh handle to `manager.play()` on every event.
@@ -66,6 +68,11 @@ impl Plugin for AudioPlugin {
             .add_event::<MoveRejectedEvent>()
             .add_event::<NewGameRequestEvent>()
             .add_event::<GameWonEvent>()
+            .add_event::<SettingsChangedEvent>()
+            .add_systems(
+                Startup,
+                apply_initial_volume,
+            )
             .add_systems(
                 Update,
                 (
@@ -74,6 +81,7 @@ impl Plugin for AudioPlugin {
                     play_on_rejected,
                     play_on_new_game,
                     play_on_win,
+                    apply_volume_on_change,
                 ),
             );
     }
@@ -113,6 +121,32 @@ fn play(audio: &mut AudioState, sound: &StaticSoundData) {
     }
 }
 
+fn set_main_track_volume(audio: &mut AudioState, volume: f32) {
+    let Some(manager) = audio.manager.as_mut() else {
+        return;
+    };
+    manager
+        .main_track()
+        .set_volume(volume.clamp(0.0, 1.0) as f64, Tween::default());
+}
+
+fn apply_initial_volume(
+    mut audio: NonSendMut<AudioState>,
+    settings: Option<Res<SettingsResource>>,
+) {
+    let volume = settings.map_or(1.0, |s| s.0.sfx_volume);
+    set_main_track_volume(&mut audio, volume);
+}
+
+fn apply_volume_on_change(
+    mut events: EventReader<SettingsChangedEvent>,
+    mut audio: NonSendMut<AudioState>,
+) {
+    for ev in events.read() {
+        set_main_track_volume(&mut audio, ev.0.sfx_volume);
+    }
+}
+
 fn play_on_draw(
     mut events: EventReader<DrawRequestEvent>,
     mut audio: NonSendMut<AudioState>,

solitaire_engine/src/help_plugin.rs

@@ -54,6 +54,7 @@ fn spawn_help_screen(commands: &mut Commands) {
         "  S            Toggle stats / progression".to_string(),
         "  H or ?       Toggle this help".to_string(),
         "  Esc          Pause / resume".to_string(),
+        "  [ / ]        SFX volume down / up".to_string(),
         String::new(),
         "Press H or ? to close".to_string(),
     ];

solitaire_engine/src/lib.rs

@@ -12,6 +12,7 @@ pub mod help_plugin;
 pub mod input_plugin;
 pub mod layout;
 pub mod pause_plugin;
+pub mod settings_plugin;
 pub mod progress_plugin;
 pub mod resources;
 pub mod stats_plugin;
@@ -39,6 +40,9 @@ pub use game_plugin::{GameMutation, GamePlugin};
 pub use help_plugin::{HelpPlugin, HelpScreen};
 pub use input_plugin::InputPlugin;
 pub use pause_plugin::{PausePlugin, PauseScreen, PausedResource};
+pub use settings_plugin::{
+    SettingsChangedEvent, SettingsPlugin, SettingsResource, SFX_STEP,
+};
 pub use layout::{compute_layout, Layout, LayoutResource};
 pub use resources::{DragState, GameStateResource, SyncStatus, SyncStatusResource};
 pub use stats_plugin::{StatsPlugin, StatsResource, StatsScreen, StatsUpdate};

solitaire_engine/src/settings_plugin.rs

@@ -0,0 +1,168 @@
+//! Persists `solitaire_data::Settings` and exposes hotkeys for live tuning.
+//!
+//! Hotkeys (always active, no overlay required):
+//! - `[` decrease SFX volume by `SFX_STEP`
+//! - `]` increase SFX volume by `SFX_STEP`
+//!
+//! On change, the plugin persists `settings.json` and fires
+//! `SettingsChangedEvent` so dependents (e.g. `AudioPlugin`) can react.
+
+use std::path::PathBuf;
+
+use bevy::prelude::*;
+use solitaire_data::{load_settings_from, save_settings_to, settings_file_path, Settings};
+
+/// Volume adjustment step.
+pub const SFX_STEP: f32 = 0.1;
+
+/// Bevy resource wrapping the current `Settings`.
+#[derive(Resource, Debug, Clone)]
+pub struct SettingsResource(pub Settings);
+
+/// Persistence path for `SettingsResource`. `None` disables I/O.
+#[derive(Resource, Debug, Clone)]
+pub struct SettingsStoragePath(pub Option<PathBuf>);
+
+/// Fired any time settings change so consumers (audio, UI) can react.
+#[derive(Event, Debug, Clone)]
+pub struct SettingsChangedEvent(pub Settings);
+
+pub struct SettingsPlugin {
+    pub storage_path: Option<PathBuf>,
+}
+
+impl Default for SettingsPlugin {
+    fn default() -> Self {
+        Self {
+            storage_path: settings_file_path(),
+        }
+    }
+}
+
+impl SettingsPlugin {
+    /// Plugin configured with no persistence — for tests and headless apps.
+    pub fn headless() -> Self {
+        Self { storage_path: None }
+    }
+}
+
+impl Plugin for SettingsPlugin {
+    fn build(&self, app: &mut App) {
+        let loaded = match &self.storage_path {
+            Some(path) => load_settings_from(path),
+            None => Settings::default(),
+        };
+        app.insert_resource(SettingsResource(loaded))
+            .insert_resource(SettingsStoragePath(self.storage_path.clone()))
+            .add_event::<SettingsChangedEvent>()
+            .add_systems(Update, handle_volume_keys);
+    }
+}
+
+fn persist(path: &SettingsStoragePath, settings: &Settings) {
+    let Some(target) = &path.0 else {
+        return;
+    };
+    if let Err(e) = save_settings_to(target, settings) {
+        warn!("failed to save settings: {e}");
+    }
+}
+
+fn handle_volume_keys(
+    keys: Res<ButtonInput<KeyCode>>,
+    mut settings: ResMut<SettingsResource>,
+    path: Res<SettingsStoragePath>,
+    mut changed: EventWriter<SettingsChangedEvent>,
+) {
+    let mut delta = 0.0;
+    if keys.just_pressed(KeyCode::BracketLeft) {
+        delta -= SFX_STEP;
+    }
+    if keys.just_pressed(KeyCode::BracketRight) {
+        delta += SFX_STEP;
+    }
+    if delta == 0.0 {
+        return;
+    }
+    let before = settings.0.sfx_volume;
+    let after = settings.0.adjust_sfx_volume(delta);
+    if (before - after).abs() < f32::EPSILON {
+        // Already at the rail — no point persisting or notifying.
+        return;
+    }
+    persist(&path, &settings.0);
+    changed.send(SettingsChangedEvent(settings.0.clone()));
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn headless_app() -> App {
+        let mut app = App::new();
+        app.add_plugins(MinimalPlugins)
+            .add_plugins(SettingsPlugin::headless());
+        app.init_resource::<ButtonInput<KeyCode>>();
+        app.update();
+        app
+    }
+
+    fn press(app: &mut App, key: KeyCode) {
+        let mut input = app.world_mut().resource_mut::<ButtonInput<KeyCode>>();
+        input.release(key);
+        input.clear();
+        input.press(key);
+    }
+
+    #[test]
+    fn defaults_are_loaded() {
+        let app = headless_app();
+        assert_eq!(
+            app.world().resource::<SettingsResource>().0,
+            Settings::default()
+        );
+    }
+
+    #[test]
+    fn pressing_left_bracket_decreases_volume_and_emits_event() {
+        let mut app = headless_app();
+        let before = app.world().resource::<SettingsResource>().0.sfx_volume;
+
+        press(&mut app, KeyCode::BracketLeft);
+        app.update();
+
+        let after = app.world().resource::<SettingsResource>().0.sfx_volume;
+        assert!(after < before);
+
+        let events = app.world().resource::<Events<SettingsChangedEvent>>();
+        let mut cursor = events.get_cursor();
+        assert_eq!(cursor.read(events).count(), 1);
+    }
+
+    #[test]
+    fn pressing_right_bracket_increases_volume() {
+        let mut app = headless_app();
+        // Drop volume first so there's headroom to grow.
+        app.world_mut().resource_mut::<SettingsResource>().0.sfx_volume = 0.5;
+
+        press(&mut app, KeyCode::BracketRight);
+        app.update();
+
+        let after = app.world().resource::<SettingsResource>().0.sfx_volume;
+        assert!((after - 0.6).abs() < 1e-3);
+    }
+
+    #[test]
+    fn clamped_change_does_not_emit_event() {
+        let mut app = headless_app();
+        // Already at max — pressing right bracket should be a no-op.
+        app.world_mut().resource_mut::<SettingsResource>().0.sfx_volume = 1.0;
+
+        press(&mut app, KeyCode::BracketRight);
+        app.update();
+
+        let events = app.world().resource::<Events<SettingsChangedEvent>>();
+        let mut cursor = events.get_cursor();
+        assert_eq!(cursor.read(events).count(), 0);
+    }
+}