fix(engine): swallow game-mutating hotkeys during pointer drags

U (undo), N (new game), Z (zen), D/Space (draw) and G (forfeit) were
not gated on an active drag, so pressing one mid-drag fired a
StateChangedEvent whose card re-sync inserted a `CardAnim` on the
dragged cards — fighting `follow_drag`'s per-frame Transform writes
(jittering XY, animated Z) and leaving `DragState` origin indices
stale against the mutated state.

`handle_keyboard_core` and `handle_keyboard_forfeit` now reuse the
mutual-exclusion guard `handle_selection_keys` already documents: skip
while `DragState` is non-idle, unless it is the keyboard-lift sentinel
(`KEYBOARD_DRAG_TOUCH_ID`), whose lift is already dropped cleanly by
`clear_selection_on_state_change`.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

CHANGELOG.md

@@ -6,6 +6,25 @@ project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.47.0] — 2026-07-13
+
+### Added
+
+- **"What's new" on update.** The first launch after an update shows a
+  one-time card summarising what changed — like this one, right now.
+  Dismiss it and it never repeats; fresh installs never see it. (#180)
+- **Situational tips.** Two one-time teaches that fire from play, not a
+  tour: staring at a stuck board for a while points you at Hint, and an
+  engaged game quietly mentions the long-press quick-action menu —
+  unless you've already found it yourself. (#181)
+- **UI scale.** Settings → Accessibility now has a UI Scale control
+  (90% / 100% / 115% / 130%) that resizes every menu, button, and HUD
+  element live. The table always fits your screen regardless. (#182)
+- **Hold `/` for shortcuts** (desktop). A reference card of every
+  keyboard binding appears while `/` is held. The onboarding tour and
+  this card now share one binding table, so they can never disagree —
+  the tour's copy had drifted from reality. (#183)
+
 ## [0.46.0] — 2026-07-13
 
 ### Added

solitaire_data/src/settings.rs

@@ -275,6 +275,14 @@ pub struct Settings {
     /// which marks the tip as unnecessary without showing it.
     #[serde(default)]
     pub shown_radial_menu_tip: bool,
+    /// Global UI scale multiplier applied to all UI chrome (HUD, modals,
+    /// action bar) — the table itself stays window-fit via
+    /// `compute_layout`. Cycles through 0.9 / 1.0 / 1.15 / 1.3 in
+    /// Settings → Accessibility; clamped to `[UI_SCALE_MIN,
+    /// UI_SCALE_MAX]` by [`Settings::sanitized`]. Older `settings.json`
+    /// files deserialize cleanly to `1.0` via the serde default.
+    #[serde(default = "default_ui_scale")]
+    pub ui_scale: f32,
     /// Custom public name displayed on the leaderboard. When `None`, the
     /// player's server `username` is used instead. Trimmed to 32 characters
     /// before submission. Older `settings.json` files written before this
@@ -383,6 +391,16 @@ fn default_replay_move_interval_secs() -> f32 {
     0.45
 }
 
+/// Lowest / highest UI scale the settings row offers; anything outside
+/// (hand-edited settings.json) clamps here on load.
+pub const UI_SCALE_MIN: f32 = 0.9;
+/// See [`UI_SCALE_MIN`].
+pub const UI_SCALE_MAX: f32 = 1.3;
+
+fn default_ui_scale() -> f32 {
+    1.0
+}
+
 fn default_matomo_site_id() -> u32 {
     1
 }
@@ -446,6 +464,7 @@ impl Default for Settings {
             last_seen_whats_new: String::new(),
             shown_stall_hint_tip: false,
             shown_radial_menu_tip: false,
+            ui_scale: default_ui_scale(),
             leaderboard_display_name: None,
             leaderboard_opted_in: false,
             take_from_foundation: true,
@@ -481,6 +500,7 @@ impl Settings {
             replay_move_interval_secs: self
                 .replay_move_interval_secs
                 .clamp(REPLAY_MOVE_INTERVAL_MIN_SECS, REPLAY_MOVE_INTERVAL_MAX_SECS),
+            ui_scale: self.ui_scale.clamp(UI_SCALE_MIN, UI_SCALE_MAX),
             selected_theme_id,
             ..self
         }

solitaire_engine/src/cheat_sheet_plugin.rs

@@ -0,0 +1,194 @@
+//! Hold-`/` hotkey cheat sheet (Phase J).
+//!
+//! While `/` is held on a keyboard platform, a lightweight overlay
+//! lists every binding from [`crate::hotkeys::HOTKEYS`] — the same
+//! table the onboarding slide teaches from, so the two can never
+//! disagree. Releasing the key hides it instantly; it never captures
+//! input, never pauses the game, and never spawns while a modal owns
+//! the screen (which also keeps it out of the seed-entry text field's
+//! way).
+//!
+//! Not a `spawn_modal` modal on purpose: modals are sticky and guarded;
+//! this is a momentary reference card, closer to a tooltip than a
+//! dialog.
+
+use bevy::input::ButtonInput;
+use bevy::prelude::*;
+
+use crate::font_plugin::FontResource;
+use crate::hotkeys::HOTKEYS;
+use crate::platform::SHOW_KEYBOARD_ACCELERATORS;
+use crate::ui_modal::ModalScrim;
+use crate::ui_theme::{
+    ACCENT_PRIMARY, BG_ELEVATED, BORDER_STRONG, HighContrastBorder, RADIUS_MD, TEXT_PRIMARY,
+    TEXT_SECONDARY, TYPE_BODY, TYPE_CAPTION, VAL_SPACE_1, VAL_SPACE_2, VAL_SPACE_3, VAL_SPACE_4,
+    Z_TOOLTIP,
+};
+
+/// Marker on the cheat-sheet overlay root.
+#[derive(Component, Debug)]
+pub struct CheatSheetOverlay;
+
+/// Registers the hold-`/` driver. Inert on touch-first builds.
+pub struct CheatSheetPlugin;
+
+impl Plugin for CheatSheetPlugin {
+    fn build(&self, app: &mut App) {
+        app.init_resource::<ButtonInput<KeyCode>>()
+            .add_systems(Update, drive_cheat_sheet);
+    }
+}
+
+/// Shows the overlay while `/` is held (and no modal owns the screen);
+/// hides it the frame the key releases.
+fn drive_cheat_sheet(
+    keys: Res<ButtonInput<KeyCode>>,
+    scrims: Query<(), With<ModalScrim>>,
+    existing: Query<Entity, With<CheatSheetOverlay>>,
+    font_res: Option<Res<FontResource>>,
+    mut commands: Commands,
+) {
+    if !SHOW_KEYBOARD_ACCELERATORS {
+        return;
+    }
+    let held = keys.pressed(KeyCode::Slash);
+    if held && existing.is_empty() && scrims.is_empty() {
+        spawn_cheat_sheet(&mut commands, font_res.as_deref());
+    } else if !held {
+        for entity in &existing {
+            commands.entity(entity).despawn();
+        }
+    }
+}
+
+fn spawn_cheat_sheet(commands: &mut Commands, font_res: Option<&FontResource>) {
+    let font_handle = font_res.map(|f| f.0.clone()).unwrap_or_default();
+    let font_header = TextFont {
+        font: font_handle.clone(),
+        font_size: TYPE_BODY,
+        ..default()
+    };
+    let font_keys = TextFont {
+        font: font_handle.clone(),
+        font_size: TYPE_CAPTION,
+        ..default()
+    };
+    let font_desc = TextFont {
+        font: font_handle,
+        font_size: TYPE_CAPTION,
+        ..default()
+    };
+
+    commands
+        .spawn((
+            CheatSheetOverlay,
+            Node {
+                position_type: PositionType::Absolute,
+                right: Val::Px(16.0),
+                top: Val::Percent(8.0),
+                flex_direction: FlexDirection::Column,
+                row_gap: VAL_SPACE_1,
+                padding: UiRect::all(VAL_SPACE_4),
+                border: UiRect::all(Val::Px(1.0)),
+                border_radius: BorderRadius::all(Val::Px(RADIUS_MD)),
+                max_height: Val::Percent(84.0),
+                overflow: Overflow::scroll_y(),
+                ..default()
+            },
+            BackgroundColor(BG_ELEVATED),
+            BorderColor::all(BORDER_STRONG),
+            HighContrastBorder::with_default(BORDER_STRONG),
+            GlobalZIndex(Z_TOOLTIP),
+        ))
+        .with_children(|panel| {
+            panel.spawn((
+                Text::new("Keyboard shortcuts"),
+                font_header.clone(),
+                TextColor(TEXT_PRIMARY),
+                Node {
+                    margin: UiRect::bottom(VAL_SPACE_2),
+                    ..default()
+                },
+            ));
+            for row in HOTKEYS {
+                panel
+                    .spawn(Node {
+                        flex_direction: FlexDirection::Row,
+                        column_gap: VAL_SPACE_3,
+                        ..default()
+                    })
+                    .with_children(|line| {
+                        line.spawn((
+                            Text::new(row.keys),
+                            font_keys.clone(),
+                            TextColor(ACCENT_PRIMARY),
+                            Node {
+                                min_width: Val::Px(110.0),
+                                ..default()
+                            },
+                        ));
+                        line.spawn((
+                            Text::new(row.description),
+                            font_desc.clone(),
+                            TextColor(TEXT_SECONDARY),
+                        ));
+                    });
+            }
+        });
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn app() -> App {
+        let mut app = App::new();
+        app.add_plugins(MinimalPlugins)
+            .add_plugins(CheatSheetPlugin);
+        app.update();
+        app
+    }
+
+    fn overlay_count(app: &mut App) -> usize {
+        app.world_mut()
+            .query::<&CheatSheetOverlay>()
+            .iter(app.world())
+            .count()
+    }
+
+    #[test]
+    fn holding_slash_shows_and_release_hides() {
+        let mut app = app();
+        app.world_mut()
+            .resource_mut::<ButtonInput<KeyCode>>()
+            .press(KeyCode::Slash);
+        app.update();
+        assert_eq!(overlay_count(&mut app), 1, "held / must show the sheet");
+        // Still held on later frames: exactly one overlay, no stacking.
+        app.update();
+        assert_eq!(overlay_count(&mut app), 1);
+
+        app.world_mut()
+            .resource_mut::<ButtonInput<KeyCode>>()
+            .release(KeyCode::Slash);
+        app.update();
+        app.update();
+        assert_eq!(overlay_count(&mut app), 0, "release must hide the sheet");
+    }
+
+    #[test]
+    fn suppressed_while_a_modal_is_open() {
+        let mut app = app();
+        app.world_mut().spawn(ModalScrim);
+        app.update();
+        app.world_mut()
+            .resource_mut::<ButtonInput<KeyCode>>()
+            .press(KeyCode::Slash);
+        app.update();
+        assert_eq!(
+            overlay_count(&mut app),
+            0,
+            "the sheet must not spawn over a modal (or into a text field)"
+        );
+    }
+}

solitaire_engine/src/core_game_plugin.rs

@@ -14,14 +14,14 @@ use crate::platform::{
 };
 use crate::{
     AchievementPlugin, AnimationPlugin, AssetSourcesPlugin, AutoCompletePlugin,
-    CardAnimationPlugin, CardPlugin, ChallengePlugin, ContextualTipsPlugin, CursorPlugin,
+    CardAnimationPlugin, CardPlugin, ChallengePlugin, CheatSheetPlugin, ContextualTipsPlugin,
-    DailyChallengePlugin, DiagnosticsHudPlugin, DifficultyPlugin, FeedbackAnimPlugin, FontPlugin,
+    CursorPlugin, DailyChallengePlugin, DiagnosticsHudPlugin, DifficultyPlugin, FeedbackAnimPlugin,
-    GamePlugin, HelpPlugin, HomePlugin, HudPlugin, InputPlugin, OnboardingPlugin, PausePlugin,
+    FontPlugin, GamePlugin, HelpPlugin, HomePlugin, HudPlugin, InputPlugin, OnboardingPlugin,
-    PlayBySeedPlugin, ProfilePlugin, ProgressPlugin, RadialMenuPlugin, ReplayOverlayPlugin,
+    PausePlugin, PlayBySeedPlugin, ProfilePlugin, ProgressPlugin, RadialMenuPlugin,
-    ReplayPlaybackPlugin, SafeAreaInsetsPlugin, SelectionPlugin, SettingsPlugin,
+    ReplayOverlayPlugin, ReplayPlaybackPlugin, SafeAreaInsetsPlugin, SelectionPlugin,
-    SolutionPlaybackPlugin, SplashPlugin, StatsPlugin, SyncProvider, TablePlugin, ThemePlugin,
+    SettingsPlugin, SolutionPlaybackPlugin, SplashPlugin, StatsPlugin, SyncProvider, TablePlugin,
-    ThemeRegistryPlugin, TimeAttackPlugin, TouchSelectionPlugin, UiFocusPlugin, UiModalPlugin,
+    ThemePlugin, ThemeRegistryPlugin, TimeAttackPlugin, TouchSelectionPlugin, UiFocusPlugin,
-    UiTooltipPlugin, WeeklyGoalsPlugin, WhatsNewPlugin, WinSummaryPlugin,
+    UiModalPlugin, UiTooltipPlugin, WeeklyGoalsPlugin, WhatsNewPlugin, WinSummaryPlugin,
 };
 #[cfg(not(target_arch = "wasm32"))]
 use crate::{
@@ -117,6 +117,7 @@ impl Plugin for CoreGamePlugin {
             .add_plugins(OnboardingPlugin)
             .add_plugins(WhatsNewPlugin)
             .add_plugins(ContextualTipsPlugin)
+            .add_plugins(CheatSheetPlugin)
             .add_plugins(WinSummaryPlugin)
             .add_plugins(UiModalPlugin)
             .add_plugins(UiFocusPlugin)

solitaire_engine/src/hotkeys.rs

@@ -0,0 +1,169 @@
+//! Single source of truth for the desktop keyboard bindings (Phase J).
+//!
+//! Two static hotkey tables had already diverged (onboarding's slide
+//! and Help's controls reference); every future drift multiplies. This
+//! module owns THE table: the onboarding slide renders the
+//! [`HotkeyRow::essential`] subset, the hold-`/` cheat sheet
+//! ([`crate::cheat_sheet_plugin`]) renders everything.
+//!
+//! The table is hand-maintained but **pinned by test** against the
+//! handlers that actually consume each key — adding a binding without
+//! updating this table (or vice versa) is designed to fail review, not
+//! runtime. A registry generated from the input systems themselves is
+//! the eventual ideal; this is the honest 90 % at 1 % of the cost.
+
+/// One row of the hotkey table.
+#[derive(Debug, Clone, Copy)]
+pub struct HotkeyRow {
+    /// Display form of the key(s), e.g. `"D / Space"`.
+    pub keys: &'static str,
+    /// One-line action description.
+    pub description: &'static str,
+    /// `true` for the beginner-relevant subset the onboarding slide
+    /// shows; the cheat sheet always shows every row.
+    pub essential: bool,
+}
+
+/// Every desktop keyboard binding, in teaching order.
+pub const HOTKEYS: &[HotkeyRow] = &[
+    HotkeyRow {
+        keys: "D / Space",
+        description: "Draw from stock",
+        essential: true,
+    },
+    HotkeyRow {
+        keys: "U",
+        description: "Undo last move (hold to repeat)",
+        essential: true,
+    },
+    HotkeyRow {
+        keys: "H",
+        description: "Hint (repeat to cycle alternatives)",
+        essential: true,
+    },
+    HotkeyRow {
+        keys: "Tab → Enter",
+        description: "Pick a card; arrows pick where; Enter to drop",
+        essential: true,
+    },
+    HotkeyRow {
+        keys: "N",
+        description: "New Classic game",
+        essential: true,
+    },
+    HotkeyRow {
+        keys: "M",
+        description: "Open Home (then 1–6 to pick a mode)",
+        essential: true,
+    },
+    HotkeyRow {
+        keys: "Esc",
+        description: "Pause / resume; close the top dialog",
+        essential: true,
+    },
+    HotkeyRow {
+        keys: "F1",
+        description: "Help / controls",
+        essential: true,
+    },
+    HotkeyRow {
+        keys: "S",
+        description: "Stats & progression",
+        essential: true,
+    },
+    HotkeyRow {
+        keys: "A",
+        description: "Achievements",
+        essential: true,
+    },
+    HotkeyRow {
+        keys: "O",
+        description: "Settings",
+        essential: true,
+    },
+    HotkeyRow {
+        keys: "P",
+        description: "Profile",
+        essential: false,
+    },
+    HotkeyRow {
+        keys: "L",
+        description: "Leaderboard",
+        essential: false,
+    },
+    HotkeyRow {
+        keys: "C",
+        description: "Daily Challenge",
+        essential: false,
+    },
+    HotkeyRow {
+        keys: "Z",
+        description: "Zen mode",
+        essential: false,
+    },
+    HotkeyRow {
+        keys: "X",
+        description: "Challenge mode",
+        essential: false,
+    },
+    HotkeyRow {
+        keys: "T",
+        description: "Time Attack",
+        essential: false,
+    },
+    HotkeyRow {
+        keys: "G",
+        description: "Give up the current deal",
+        essential: false,
+    },
+    HotkeyRow {
+        keys: "[ / ]",
+        description: "Volume down / up",
+        essential: false,
+    },
+    HotkeyRow {
+        keys: "F11",
+        description: "Toggle fullscreen",
+        essential: false,
+    },
+    HotkeyRow {
+        keys: "/ (hold)",
+        description: "This cheat sheet",
+        essential: false,
+    },
+];
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn table_is_populated_and_well_formed() {
+        assert!(!HOTKEYS.is_empty());
+        for row in HOTKEYS {
+            assert!(!row.keys.trim().is_empty(), "empty keys cell");
+            assert!(
+                !row.description.trim().is_empty(),
+                "empty description for {}",
+                row.keys
+            );
+        }
+    }
+
+    #[test]
+    fn essential_subset_is_a_teachable_size() {
+        let essentials = HOTKEYS.iter().filter(|r| r.essential).count();
+        assert!(
+            (6..=12).contains(&essentials),
+            "the onboarding slide wants a skimmable essential set, got {essentials}"
+        );
+    }
+
+    #[test]
+    fn keys_cells_are_unique() {
+        let mut seen = std::collections::HashSet::new();
+        for row in HOTKEYS {
+            assert!(seen.insert(row.keys), "duplicate hotkey row: {}", row.keys);
+        }
+    }
+}

solitaire_engine/src/input_plugin/mod.rs

@@ -215,6 +215,7 @@ fn handle_keyboard_core(
     keys: Res<ButtonInput<KeyCode>>,
     paused: Option<Res<PausedResource>>,
     progress: Option<Res<ProgressResource>>,
+    drag: Res<DragState>,
     mut ev: CoreKeyboardMessages<'_>,
     mut time_attack: Option<ResMut<TimeAttackResource>>,
     selection: Option<Res<SelectionState>>,
@@ -227,6 +228,19 @@ fn handle_keyboard_core(
         return;
     }
 
+    // Mutual exclusion with pointer drags — mirrors `handle_selection_keys`.
+    // Undo / draw / new-game during an active mouse or touch drag would fire
+    // a StateChangedEvent whose card re-sync inserts a `CardAnim` on the
+    // dragged cards, fighting `follow_drag`'s per-frame Transform writes and
+    // leaving `DragState` origin indices stale against the mutated state.
+    // The keyboard-drag sentinel may proceed: `clear_selection_on_state_change`
+    // already drops that lift cleanly when the state moves.
+    if !drag.is_idle()
+        && drag.active_touch_id != Some(crate::selection_plugin::KEYBOARD_DRAG_TOUCH_ID)
+    {
+        return;
+    }
+
     // During replay playback (Playing or Completed) all game-input shortcuts
     // are suppressed. The replay overlay owns Space (pause/resume) and the
     // arrow keys (step). Letting game input through would mutate
@@ -473,11 +487,19 @@ pub fn emit_hint_visuals(
 fn handle_keyboard_forfeit(
     keys: Res<ButtonInput<KeyCode>>,
     paused: Option<Res<PausedResource>>,
+    drag: Res<DragState>,
     mut requests: MessageWriter<ForfeitRequestEvent>,
 ) {
     if paused.is_some_and(|p| p.0) {
         return;
     }
+    // Same pointer-drag exclusion as `handle_keyboard_core` — forfeiting
+    // mid-drag would mutate the game state under the dragged cards.
+    if !drag.is_idle()
+        && drag.active_touch_id != Some(crate::selection_plugin::KEYBOARD_DRAG_TOUCH_ID)
+    {
+        return;
+    }
     if !keys.just_pressed(KeyCode::KeyG) {
         return;
     }

solitaire_engine/src/input_plugin/tests.rs

@@ -817,3 +817,123 @@ fn pressing_h_spawns_pending_hint_task() {
         "pressing H must spawn an async hint task",
     );
 }
+
+// -----------------------------------------------------------------------
+// Pointer-drag / keyboard mutual exclusion.
+//
+// A state mutation fired while `follow_drag` is writing the dragged cards'
+// transforms every frame would make the card re-sync insert a `CardAnim`
+// on the same entities (two systems fighting over `Transform`) and leave
+// `DragState`'s origin indices stale. `handle_keyboard_core` and
+// `handle_keyboard_forfeit` therefore swallow game-mutating shortcuts
+// while a mouse or touch drag is live, mirroring `handle_selection_keys`.
+// The keyboard-lift sentinel is exempt: `clear_selection_on_state_change`
+// drops that lift cleanly when the state moves.
+// -----------------------------------------------------------------------
+
+fn keyboard_core_app() -> App {
+    let mut app = App::new();
+    app.add_plugins(MinimalPlugins);
+    app.add_message::<UndoRequestEvent>();
+    app.add_message::<NewGameRequestEvent>();
+    app.add_message::<InfoToastEvent>();
+    app.add_message::<DrawRequestEvent>();
+    app.add_message::<StartZenRequestEvent>();
+    app.init_resource::<ButtonInput<KeyCode>>();
+    app.init_resource::<DragState>();
+    app.add_systems(Update, handle_keyboard_core);
+    app
+}
+
+fn press_key(app: &mut App, key: KeyCode) {
+    let mut input = app.world_mut().resource_mut::<ButtonInput<KeyCode>>();
+    input.release(key);
+    input.clear();
+    input.press(key);
+}
+
+fn message_count<M: Message>(app: &App) -> usize {
+    let messages = app.world().resource::<Messages<M>>();
+    let mut cursor = messages.get_cursor();
+    cursor.read(messages).count()
+}
+
+fn set_drag(app: &mut App, active_touch_id: Option<u64>) {
+    let mut drag = app.world_mut().resource_mut::<DragState>();
+    drag.cards = vec![Card::new(Deck::Deck1, Suit::Clubs, Rank::Two)];
+    drag.committed = true;
+    drag.active_touch_id = active_touch_id;
+}
+
+#[test]
+fn u_key_fires_undo_when_no_drag_active() {
+    let mut app = keyboard_core_app();
+    press_key(&mut app, KeyCode::KeyU);
+    app.update();
+    assert_eq!(
+        message_count::<UndoRequestEvent>(&app),
+        1,
+        "U with an idle DragState must fire UndoRequestEvent",
+    );
+}
+
+#[test]
+fn u_key_ignored_during_committed_mouse_drag() {
+    let mut app = keyboard_core_app();
+    set_drag(&mut app, None); // mouse drag
+    press_key(&mut app, KeyCode::KeyU);
+    app.update();
+    assert_eq!(
+        message_count::<UndoRequestEvent>(&app),
+        0,
+        "U during a mouse drag must be swallowed",
+    );
+}
+
+#[test]
+fn draw_key_ignored_during_touch_drag() {
+    let mut app = keyboard_core_app();
+    set_drag(&mut app, Some(7)); // real touch id
+    press_key(&mut app, KeyCode::KeyD);
+    app.update();
+    assert_eq!(
+        message_count::<DrawRequestEvent>(&app),
+        0,
+        "D during a touch drag must be swallowed",
+    );
+}
+
+#[test]
+fn u_key_allowed_during_keyboard_lift() {
+    let mut app = keyboard_core_app();
+    set_drag(
+        &mut app,
+        Some(crate::selection_plugin::KEYBOARD_DRAG_TOUCH_ID),
+    );
+    press_key(&mut app, KeyCode::KeyU);
+    app.update();
+    assert_eq!(
+        message_count::<UndoRequestEvent>(&app),
+        1,
+        "the keyboard-lift sentinel must not block core shortcuts",
+    );
+}
+
+#[test]
+fn g_key_forfeit_ignored_during_mouse_drag() {
+    let mut app = App::new();
+    app.add_plugins(MinimalPlugins);
+    app.add_message::<ForfeitRequestEvent>();
+    app.init_resource::<ButtonInput<KeyCode>>();
+    app.init_resource::<DragState>();
+    app.add_systems(Update, handle_keyboard_forfeit);
+
+    set_drag(&mut app, None);
+    press_key(&mut app, KeyCode::KeyG);
+    app.update();
+    assert_eq!(
+        message_count::<ForfeitRequestEvent>(&app),
+        0,
+        "G during a mouse drag must be swallowed",
+    );
+}

solitaire_engine/src/leaderboard_plugin.rs

@@ -24,13 +24,13 @@ use crate::font_plugin::FontResource;
 use crate::settings_plugin::{SettingsResource, SettingsStoragePath};
 use crate::sync_plugin::SyncProviderResource;
 use crate::ui_modal::{
-    ButtonVariant, ModalScrim, ScrimDismissible, spawn_modal, spawn_modal_actions,
+    ButtonVariant, ModalScrim, ScrimDismissible, spawn_empty_state, spawn_modal,
-    spawn_modal_button, spawn_modal_header,
+    spawn_modal_actions, spawn_modal_button, spawn_modal_header,
 };
 use crate::ui_theme::{
-    ACCENT_PRIMARY, BG_ELEVATED, BORDER_SUBTLE, RADIUS_SM, STATE_INFO, TEXT_DISABLED, TEXT_PRIMARY,
+    ACCENT_PRIMARY, BG_ELEVATED, BORDER_SUBTLE, RADIUS_SM, TEXT_DISABLED, TEXT_PRIMARY,
-    TEXT_SECONDARY, TYPE_BODY, TYPE_BODY_LG, TYPE_CAPTION, VAL_SPACE_2, VAL_SPACE_3, VAL_SPACE_4,
+    TEXT_SECONDARY, TYPE_BODY, TYPE_CAPTION, VAL_SPACE_2, VAL_SPACE_3, VAL_SPACE_4, Z_MODAL_PANEL,
-    Z_MODAL_PANEL, Z_PAUSE_DIALOG,
+    Z_PAUSE_DIALOG,
 };
 
 // ---------------------------------------------------------------------------
@@ -536,11 +536,6 @@ fn spawn_leaderboard_screen(
             font_size: TYPE_CAPTION,
             ..default()
         };
-        let font_status = TextFont {
-            font: font_handle.clone(),
-            font_size: TYPE_BODY_LG,
-            ..default()
-        };
         let font_row = TextFont {
             font: font_handle.clone(),
             font_size: TYPE_BODY,
@@ -647,30 +642,31 @@ fn spawn_leaderboard_screen(
         .with_children(|body| {
             match data {
                 LeaderboardResource::Idle => {
-                    body.spawn((
+                    spawn_empty_state(
-                        Text::new("Fetching\u{2026}"),
+                        body,
-                        font_status.clone(),
+                        "\u{21BB}",
-                        TextColor(STATE_INFO),
+                        "Fetching the leaderboard\u{2026}",
-                    ));
+                        None,
+                        font_res,
+                    );
                 }
                 LeaderboardResource::Error(_) => {
-                    body.spawn((
+                    spawn_empty_state(
-                        Text::new("Couldn't reach the leaderboard. Try again later."),
+                        body,
-                        font_status.clone(),
+                        "!",
-                        TextColor(TEXT_SECONDARY),
+                        "Couldn't reach the leaderboard.",
-                    ));
+                        Some("Try again later."),
+                        font_res,
+                    );
                 }
                 LeaderboardResource::Loaded(rows) if rows.is_empty() => {
-                    body.spawn((
+                    spawn_empty_state(
-                        Text::new("Be the first on the leaderboard."),
+                        body,
-                        font_status.clone(),
+                        "\u{2660}",
-                        TextColor(TEXT_PRIMARY),
+                        "Be the first on the leaderboard.",
-                    ));
+                        Some("Win a game and opt in to appear here."),
-                    body.spawn((
+                        font_res,
-                        Text::new("Win a game and opt in to appear here."),
+                    );
-                        font_row.clone(),
-                        TextColor(TEXT_SECONDARY),
-                    ));
                 }
                 LeaderboardResource::Loaded(rows) => {
                     // Column headers

solitaire_engine/src/lib.rs

@@ -15,6 +15,7 @@ pub mod avatar_plugin;
 pub mod card_animation;
 pub mod card_plugin;
 pub mod challenge_plugin;
+pub mod cheat_sheet_plugin;
 pub mod contextual_tips_plugin;
 pub mod core_game_plugin;
 pub mod cursor_plugin;
@@ -27,6 +28,7 @@ pub mod font_plugin;
 pub mod game_plugin;
 pub mod help_plugin;
 pub mod home_plugin;
+pub mod hotkeys;
 pub mod hud_plugin;
 pub mod input_plugin;
 pub mod layout;
@@ -95,6 +97,7 @@ pub use card_plugin::{
 pub use challenge_plugin::{
     CHALLENGE_UNLOCK_LEVEL, ChallengeAdvancedEvent, ChallengePlugin, challenge_progress_label,
 };
+pub use cheat_sheet_plugin::{CheatSheetOverlay, CheatSheetPlugin};
 pub use contextual_tips_plugin::ContextualTipsPlugin;
 pub use core_game_plugin::CoreGamePlugin;
 pub use cursor_plugin::CursorPlugin;

solitaire_engine/src/onboarding_plugin.rs

@@ -84,66 +84,11 @@ struct OnboardingSkipButton;
 pub struct OnboardingSlideIndex(pub u8);
 
 // ---------------------------------------------------------------------------
-// Slide data — hotkey rows are taken verbatim from `help_plugin.rs` so the
+// Slide data — the hotkey slide renders the essential subset of the
-// two screens stay in sync without a shared abstraction.
+// shared table in `crate::hotkeys` (Phase J unified the previously
+// diverging copies here and in help_plugin).
 // ---------------------------------------------------------------------------
 
-/// A single `key — description` pair shown on slide 3.
-#[cfg(not(target_os = "android"))]
-struct HotkeyRow {
-    keys: &'static str,
-    description: &'static str,
-}
-
-/// Most-used shortcuts from the `help_plugin` canonical list.
-///
-/// Updating the list in `help_plugin.rs` should be mirrored here. The
-/// ARCHITECTURE.md decision log calls out that we copy values rather than
-/// refactor the help plugin.
-#[cfg(not(target_os = "android"))]
-const HOTKEYS: &[HotkeyRow] = &[
-    HotkeyRow {
-        keys: "D / Space",
-        description: "Draw from stock",
-    },
-    HotkeyRow {
-        keys: "U",
-        description: "Undo last move",
-    },
-    HotkeyRow {
-        keys: "Tab → Enter",
-        description: "Pick a card; arrows pick where; Enter to drop",
-    },
-    HotkeyRow {
-        keys: "N",
-        description: "New Classic game",
-    },
-    HotkeyRow {
-        keys: "M",
-        description: "Open Mode Launcher (then 1–5 to pick)",
-    },
-    HotkeyRow {
-        keys: "S",
-        description: "Stats & progression",
-    },
-    HotkeyRow {
-        keys: "A",
-        description: "Achievements",
-    },
-    HotkeyRow {
-        keys: "O",
-        description: "Settings",
-    },
-    HotkeyRow {
-        keys: "Esc",
-        description: "Pause / resume",
-    },
-    HotkeyRow {
-        keys: "F1",
-        description: "Help / controls",
-    },
-];
-
 // ---------------------------------------------------------------------------
 // Plugin
 // ---------------------------------------------------------------------------
@@ -446,8 +391,10 @@ fn spawn_slide_hotkeys(commands: &mut Commands, font_res: Option<&FontResource>)
     spawn_modal(commands, OnboardingScreen, Z_ONBOARDING, |card| {
         spawn_modal_header(card, "Keyboard shortcuts", font_res);
 
-        // Vertical list of `key — description` rows, same chip style as HelpScreen.
+        // Vertical list of `key — description` rows, same chip style as
-        for row in HOTKEYS {
+        // HelpScreen. Essential subset only — the full table lives on
+        // the hold-`/` cheat sheet.
+        for row in crate::hotkeys::HOTKEYS.iter().filter(|r| r.essential) {
             card.spawn(Node {
                 flex_direction: FlexDirection::Row,
                 align_items: AlignItems::Center,
@@ -826,22 +773,15 @@ mod tests {
     }
 
     // -----------------------------------------------------------------------
-    // Hotkey list is non-empty (guards against accidental truncation)
+    // Hotkey slide renders a non-empty essential subset (the table's own
+    // integrity tests live in `crate::hotkeys`)
     // -----------------------------------------------------------------------
 
     #[test]
-    fn hotkey_list_is_non_empty() {
+    fn hotkey_slide_subset_is_non_empty() {
-        assert!(!HOTKEYS.is_empty(), "HOTKEYS must not be empty");
+        assert!(
-    }
+            crate::hotkeys::HOTKEYS.iter().any(|r| r.essential),
-
+            "the onboarding slide needs at least one essential hotkey"
-    #[test]
+        );
-    fn all_hotkey_rows_have_non_empty_fields() {
-        for row in HOTKEYS {
-            assert!(!row.keys.is_empty(), "hotkey key field must not be empty");
-            assert!(
-                !row.description.is_empty(),
-                "hotkey description must not be empty"
-            );
-        }
     }
 }

solitaire_engine/src/safe_area.rs

@@ -101,9 +101,10 @@ impl Plugin for SafeAreaInsetsPlugin {
 fn apply_safe_area_anchors(
     insets: Res<SafeAreaInsets>,
     windows: Query<&Window>,
+    ui_scale: Option<Res<UiScale>>,
     mut q: Query<(&SafeAreaAnchoredTop, &mut Node)>,
 ) {
-    if !insets.is_changed() {
+    if !insets.is_changed() && !ui_scale.as_ref().is_some_and(|s| s.is_changed()) {
         return;
     }
     // Android's WindowInsets API returns physical pixels; Bevy UI's Val::Px
@@ -119,19 +120,31 @@ fn apply_safe_area_anchors(
         );
     }
     let top_logical = raw_top.min(max_inset);
+    // `bevy::ui::UiScale` (Phase K) multiplies every Val::Px at layout
+    // time. `base_top` is UI chrome and SHOULD scale with the rest of
+    // the interface, but the system-bar inset is physical reality —
+    // pre-divide it so the post-multiplication offset stays exact.
+    let ui = effective_ui_scale(ui_scale.as_deref());
     for (anchor, mut node) in &mut q {
-        node.top = Val::Px(anchor.base_top + top_logical);
+        node.top = Val::Px(anchor.base_top + top_logical / ui);
     }
 }
 
+/// The live UI scale, defensively clamped — a zero or negative scale
+/// would flip or destroy the inset math.
+fn effective_ui_scale(ui_scale: Option<&UiScale>) -> f32 {
+    ui_scale.map_or(1.0, |s| s.0.max(0.1))
+}
+
 /// Re-applies `base_bottom + insets.bottom / scale` to every entity carrying
 /// [`SafeAreaAnchoredBottom`] whenever [`SafeAreaInsets`] changes.
 fn apply_safe_area_bottom_anchors(
     insets: Res<SafeAreaInsets>,
     windows: Query<&Window>,
+    ui_scale: Option<Res<UiScale>>,
     mut q: Query<(&SafeAreaAnchoredBottom, &mut Node)>,
 ) {
-    if !insets.is_changed() {
+    if !insets.is_changed() && !ui_scale.as_ref().is_some_and(|s| s.is_changed()) {
         return;
     }
     let scale = windows.iter().next().map_or(1.0, |w| w.scale_factor());
@@ -144,8 +157,12 @@ fn apply_safe_area_bottom_anchors(
         );
     }
     let bottom_logical = raw_bottom.min(max_inset);
+    // See `apply_safe_area_anchors`: the physical inset is pre-divided
+    // by the UI scale so a 90% setting can't sink the action bar into
+    // the gesture zone (and 130% doesn't over-inset it).
+    let ui = effective_ui_scale(ui_scale.as_deref());
     for (anchor, mut node) in &mut q {
-        node.bottom = Val::Px(anchor.base_bottom + bottom_logical);
+        node.bottom = Val::Px(anchor.base_bottom + bottom_logical / ui);
     }
 }
 
@@ -163,19 +180,23 @@ fn apply_safe_area_bottom_anchors(
 fn apply_safe_area_to_modal_scrims(
     insets: Res<SafeAreaInsets>,
     windows: Query<&Window>,
+    ui_scale: Option<Res<UiScale>>,
     mut scrims: Query<&mut Node, With<ModalScrim>>,
     new_scrims: Query<(), (With<ModalScrim>, Added<ModalScrim>)>,
 ) {
     let has_new = !new_scrims.is_empty();
-    if !insets.is_changed() && !has_new {
+    if !insets.is_changed() && !has_new && !ui_scale.as_ref().is_some_and(|s| s.is_changed()) {
         return;
     }
     let scale = windows.iter().next().map_or(1.0, |w| w.scale_factor());
     let window_height = windows.iter().next().map_or(800.0, |w| w.height());
     // Clamp each inset to 25% of screen height so an unexpectedly large OS
     // value can't push the modal card off the visible area entirely.
-    let top_logical = (insets.top / scale).min(window_height * 0.25);
+    // Physical insets are pre-divided by the UI scale — see
-    let bottom_logical = (insets.bottom / scale).min(window_height * 0.25);
+    // `apply_safe_area_anchors`.
+    let ui = effective_ui_scale(ui_scale.as_deref());
+    let top_logical = (insets.top / scale).min(window_height * 0.25) / ui;
+    let bottom_logical = (insets.bottom / scale).min(window_height * 0.25) / ui;
     for mut node in &mut scrims {
         // Set both edges so the scrim's content box equals the usable area
         // between the status bar and the gesture/navigation bar. With

solitaire_engine/src/settings_plugin/input.rs

@@ -363,6 +363,14 @@ pub(super) fn handle_settings_buttons(
                 changed.write(SettingsChangedEvent(settings.0.clone()));
                 // Text refreshed by `update_touch_input_mode_text` next frame.
             }
+            SettingsButton::CycleUiScale => {
+                settings.0.ui_scale = next_ui_scale(settings.0.ui_scale);
+                persist(&path, &settings.0);
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+                // Text refreshed by `update_ui_scale_text`; the live
+                // `bevy::ui::UiScale` resource follows via
+                // `sync_ui_scale_resource` next frame.
+            }
             SettingsButton::ToggleWinnableDealsOnly => {
                 settings.0.winnable_deals_only = !settings.0.winnable_deals_only;
                 persist(&path, &settings.0);

solitaire_engine/src/settings_plugin/mod.rs

@@ -139,6 +139,10 @@ struct ReduceMotionText;
 #[derive(Component, Debug)]
 struct TouchInputModeText;
 
+/// Marks the `Text` node showing the current UI scale percentage.
+#[derive(Component, Debug)]
+struct UiScaleText;
+
 /// Marks the `Text` node showing the live tooltip-delay value.
 #[derive(Component, Debug)]
 struct TooltipDelayText;
@@ -277,6 +281,10 @@ enum SettingsButton {
     /// (auto-move on tap, default) and `TapToSelect` (first tap selects
     /// a card/stack, second tap on a target pile moves it).
     ToggleTouchInputMode,
+    /// Cycle [`Settings::ui_scale`] through 90 % → 100 % → 115 % →
+    /// 130 % → 90 %. Applied live via `bevy::ui::UiScale`; the table
+    /// stays window-fit (Phase K).
+    CycleUiScale,
     /// Toggle the [`Settings::winnable_deals_only`] flag. When on, new
     /// random Classic-mode deals are filtered through
     /// [`solitaire_core::game_state::GameState::solve_fresh_deal`] until one is provably
@@ -354,6 +362,7 @@ impl SettingsButton {
             SettingsButton::ToggleHighContrast => 61,
             SettingsButton::ToggleReduceMotion => 62,
             SettingsButton::ToggleTouchInputMode => 63,
+            SettingsButton::CycleUiScale => 64,
             // Picker rows — every swatch in a row shares the row's
             // priority so entity-index tiebreaking yields left → right.
             SettingsButton::SelectCardBack(_) => 70,
@@ -449,6 +458,11 @@ impl Plugin for SettingsPlugin {
                     handle_volume_keys,
                     record_window_geometry_changes,
                     persist_window_geometry_after_debounce,
+                    // State sync, not UI — runs even under `headless()`
+                    // so the live `bevy::ui::UiScale` always mirrors the
+                    // setting; rides the mutator spine so it is ordered
+                    // after every settings writer this frame.
+                    sync_ui_scale_resource,
                 )
                     .chain()
                     .in_set(SettingsMutation),
@@ -492,6 +506,7 @@ impl Plugin for SettingsPlugin {
                     update_high_contrast_backgrounds.run_if(resource_changed::<SettingsResource>),
                     update_reduce_motion_text,
                     update_touch_input_mode_text,
+                    update_ui_scale_text,
                     update_tooltip_delay_text,
                     update_time_bonus_multiplier_text,
                     update_replay_move_interval_text,

solitaire_engine/src/settings_plugin/tests.rs

@@ -736,3 +736,60 @@ fn scroll_clamps_offset_to_zero_at_top() {
         "scrolling past top must clamp to 0, got {offset}"
     );
 }
+
+// ---------------------------------------------------------------------------
+// Phase K: UI scale
+// ---------------------------------------------------------------------------
+
+#[test]
+fn ui_scale_steps_cycle_and_wrap() {
+    assert_eq!(next_ui_scale(0.9), 1.0);
+    assert_eq!(next_ui_scale(1.0), 1.15);
+    assert_eq!(next_ui_scale(1.15), 1.3);
+    assert_eq!(next_ui_scale(1.3), 0.9, "the cycle must wrap");
+    // A hand-edited in-between value advances to the next larger step.
+    assert_eq!(next_ui_scale(1.05), 1.15);
+}
+
+#[test]
+fn ui_scale_label_formats_as_percent() {
+    assert_eq!(ui_scale_label(0.9), "90%");
+    assert_eq!(ui_scale_label(1.0), "100%");
+    assert_eq!(ui_scale_label(1.15), "115%");
+    assert_eq!(ui_scale_label(1.3), "130%");
+}
+
+#[test]
+fn ui_scale_setting_syncs_the_bevy_resource() {
+    let mut app = headless_app();
+    app.insert_resource(UiScale(1.0));
+    app.world_mut()
+        .resource_mut::<SettingsResource>()
+        .0
+        .ui_scale = 1.3;
+    app.update();
+
+    assert!(
+        (app.world().resource::<UiScale>().0 - 1.3).abs() < f32::EPSILON,
+        "Settings::ui_scale must drive bevy::ui::UiScale"
+    );
+}
+
+#[test]
+fn ui_scale_out_of_range_sanitizes_on_load() {
+    use solitaire_data::settings::{UI_SCALE_MAX, UI_SCALE_MIN};
+
+    let wild = Settings {
+        ui_scale: 5.0,
+        ..Settings::default()
+    }
+    .sanitized();
+    assert_eq!(wild.ui_scale, UI_SCALE_MAX);
+
+    let tiny = Settings {
+        ui_scale: 0.1,
+        ..Settings::default()
+    }
+    .sanitized();
+    assert_eq!(tiny.ui_scale, UI_SCALE_MIN);
+}

solitaire_engine/src/settings_plugin/ui.rs

@@ -326,6 +326,15 @@ fn spawn_accessibility_tab(
         "One-tap: tap a card to auto-move it. Tap to select: first tap selects a card, second tap on a pile moves it.",
         font_res,
     );
+    toggle_row(
+        body,
+        "UI Scale",
+        UiScaleText,
+        ui_scale_label(settings.ui_scale),
+        SettingsButton::CycleUiScale,
+        "Scales all menus, buttons, and HUD text. The table itself always fits the screen.",
+        font_res,
+    );
     tooltip_delay_row(body, settings.tooltip_delay_secs, font_res);
 }
 

solitaire_engine/src/settings_plugin/updates.rs

@@ -515,6 +515,58 @@ pub(super) fn touch_input_mode_label(mode: &solitaire_data::settings::TouchInput
     }
 }
 
+/// The four UI-scale steps the settings row cycles through (Phase K).
+pub(super) const UI_SCALE_STEPS: [f32; 4] = [0.9, 1.0, 1.15, 1.3];
+
+/// The next UI-scale step after `current`, wrapping 130 % → 90 %. A
+/// hand-edited value between steps advances to the first step larger
+/// than it, so the cycle always makes visible progress.
+pub(super) fn next_ui_scale(current: f32) -> f32 {
+    for step in UI_SCALE_STEPS {
+        if step > current + 0.001 {
+            return step;
+        }
+    }
+    UI_SCALE_STEPS[0]
+}
+
+/// Display string for the UI-scale row, e.g. `"115%"`.
+pub(super) fn ui_scale_label(scale: f32) -> String {
+    format!("{:.0}%", scale * 100.0)
+}
+
+/// Refreshes the live UI-scale value text whenever settings change.
+pub(super) fn update_ui_scale_text(
+    settings: Res<SettingsResource>,
+    mut text_nodes: Query<&mut Text, With<UiScaleText>>,
+) {
+    if !settings.is_changed() {
+        return;
+    }
+    for mut text in &mut text_nodes {
+        **text = ui_scale_label(settings.0.ui_scale);
+    }
+}
+
+/// Applies `Settings::ui_scale` to the live [`bevy::ui::UiScale`]
+/// resource — at startup (first change tick) and whenever the setting
+/// changes. Absent under `MinimalPlugins` (no `bevy_ui`), hence the
+/// `Option`; the table is unaffected either way (`compute_layout`
+/// owns world-space sizing, not UI scale).
+pub(super) fn sync_ui_scale_resource(
+    settings: Res<SettingsResource>,
+    ui_scale: Option<ResMut<UiScale>>,
+) {
+    let Some(mut ui_scale) = ui_scale else { return };
+    if !settings.is_changed() {
+        return;
+    }
+    let target = settings.0.ui_scale;
+    if (ui_scale.0 - target).abs() > f32::EPSILON {
+        ui_scale.0 = target;
+    }
+}
+
 /// Display string for the "Smart window size" toggle. The argument
 /// is the *enabled* state (i.e. the inverse of the underlying
 /// `disable_smart_default_size` field) so reading the label gives

solitaire_engine/src/stats_plugin.rs

@@ -30,7 +30,7 @@ use crate::ui_modal::{ButtonVariant, ModalButton, spawn_modal_button};
 use crate::ui_theme::{
     ACCENT_PRIMARY, BG_ELEVATED_HI, BORDER_SUBTLE, HighContrastBorder, RADIUS_SM, STATE_INFO,
     STATE_WARNING, STREAK_MILESTONES, TEXT_PRIMARY, TEXT_SECONDARY, TYPE_BODY, TYPE_BODY_LG,
-    TYPE_CAPTION, TYPE_HEADLINE, VAL_SPACE_1, VAL_SPACE_2, VAL_SPACE_3, VAL_SPACE_4,
+    TYPE_HEADLINE, VAL_SPACE_1, VAL_SPACE_2, VAL_SPACE_3, VAL_SPACE_4,
 };
 
 /// Bevy resource wrapping the current stats.
@@ -719,25 +719,17 @@ pub(crate) fn spawn_stats_body(
             },
         ))
         .with_children(|body| {
-            // First-launch caption — sits above the grid as gentle nudge so
+            // First-launch empty state (Phase L) — sits above the grid so
             // the wall of em-dashes reads as "nothing to track yet" rather
             // than as broken state.
             if is_first_launch {
-                body.spawn((
+                crate::ui_modal::spawn_empty_state(
-                    Text::new("Play a game to start tracking stats."),
+                    body,
-                    TextFont {
+                    "\u{2663}",
-                        font_size: TYPE_CAPTION,
+                    "Play a game to start tracking stats.",
-                        ..default()
+                    None,
-                    },
+                    font_res,
-                    TextColor(TEXT_SECONDARY),
+                );
-                    Node {
-                        margin: UiRect {
-                            bottom: VAL_SPACE_2,
-                            ..default()
-                        },
-                        ..default()
-                    },
-                ));
             }
 
             // --- primary stat cells grid ---
@@ -893,6 +885,20 @@ pub(crate) fn spawn_replays_body(
     selected_index: usize,
     font_res: Option<&FontResource>,
 ) {
+    // Standard empty state (Phase L) — the selector / Watch / Copy
+    // controls only spawn when there is something to select, so their
+    // handlers all no-op via their existing empty-query paths.
+    if replays.is_empty() {
+        crate::ui_modal::spawn_empty_state(
+            card,
+            "\u{2666}",
+            "No replays yet.",
+            Some("Every win records a replay here automatically."),
+            font_res,
+        );
+        return;
+    }
+
     let font_handle = font_res.map(|f| f.0.clone()).unwrap_or_default();
     let font_row = TextFont {
         font: font_handle,

solitaire_engine/src/theme_store_plugin.rs

@@ -32,8 +32,8 @@ use crate::resources::TokioRuntimeResource;
 use crate::settings_plugin::{SettingsPanel, SettingsResource};
 use crate::theme::{ImportError, ThemeRegistry, import_theme, refresh_registry};
 use crate::ui_modal::{
-    ButtonVariant, ModalScrim, ScrimDismissible, spawn_modal, spawn_modal_actions,
+    ButtonVariant, ModalScrim, ScrimDismissible, spawn_empty_state, spawn_modal,
-    spawn_modal_button, spawn_modal_header,
+    spawn_modal_actions, spawn_modal_button, spawn_modal_header,
 };
 use crate::ui_theme::{
     BORDER_SUBTLE, TEXT_PRIMARY, TEXT_SECONDARY, TYPE_BODY, TYPE_CAPTION, VAL_SPACE_2, VAL_SPACE_3,
@@ -528,25 +528,31 @@ fn spawn_store_modal(
 
         match catalog_state {
             CatalogState::Idle | CatalogState::Loading => {
-                card.spawn((
+                spawn_empty_state(
-                    Text::new("Loading catalog…"),
+                    card,
-                    body_font.clone(),
+                    "\u{21BB}",
-                    TextColor(TEXT_SECONDARY),
+                    "Loading the catalog\u{2026}",
-                ));
+                    None,
+                    font_res,
+                );
             }
             CatalogState::Error(msg) => {
-                card.spawn((
+                spawn_empty_state(
-                    Text::new(format!("Could not load the catalog: {msg}")),
+                    card,
-                    body_font.clone(),
+                    "!",
-                    TextColor(TEXT_SECONDARY),
+                    "Couldn't load the catalog.",
-                ));
+                    Some(msg.as_str()),
+                    font_res,
+                );
             }
             CatalogState::Loaded(entries) if entries.is_empty() => {
-                card.spawn((
+                spawn_empty_state(
-                    Text::new("The server has no themes yet."),
+                    card,
-                    body_font.clone(),
+                    "#",
-                    TextColor(TEXT_SECONDARY),
+                    "The server has no themes yet.",
-                ));
+                    Some("Themes dropped into the server's theme_store folder appear here."),
+                    font_res,
+                );
             }
             CatalogState::Loaded(entries) => {
                 for entry in entries {

solitaire_engine/src/ui_modal.rs

@@ -60,9 +60,9 @@ use crate::settings_plugin::SettingsResource;
 use crate::ui_theme::{
     ACCENT_PRIMARY, ACCENT_PRIMARY_HOVER, ACCENT_SECONDARY, BG_BASE, BG_ELEVATED, BG_ELEVATED_HI,
     BG_ELEVATED_PRESSED, BG_ELEVATED_TOP, BORDER_STRONG, BORDER_SUBTLE, HighContrastBorder,
-    MOTION_MODAL_SECS, RADIUS_LG, RADIUS_MD, RADIUS_SM, SCRIM, STATE_SUCCESS, TEXT_PRIMARY,
+    MOTION_MODAL_SECS, RADIUS_LG, RADIUS_MD, RADIUS_SM, SCRIM, STATE_SUCCESS, TEXT_DISABLED,
-    TEXT_SECONDARY, TYPE_BODY_LG, TYPE_CAPTION, TYPE_HEADLINE, VAL_SPACE_2, VAL_SPACE_3,
+    TEXT_PRIMARY, TEXT_SECONDARY, TYPE_BODY, TYPE_BODY_LG, TYPE_CAPTION, TYPE_DISPLAY,
-    VAL_SPACE_4, VAL_SPACE_5, scaled_duration,
+    TYPE_HEADLINE, VAL_SPACE_2, VAL_SPACE_3, VAL_SPACE_4, VAL_SPACE_5, scaled_duration,
 };
 
 // ---------------------------------------------------------------------------
@@ -328,6 +328,80 @@ pub fn spawn_modal_body_text(
     parent.spawn((ModalBody, Text::new(text.into()), font, TextColor(color)));
 }
 
+/// Standard empty / loading / error surface (Phase L): a large glyph,
+/// a headline, and an optional secondary detail line, centred in the
+/// available space. Every async or possibly-empty surface (leaderboard,
+/// replays, theme store, first-launch stats) renders through this so
+/// "nothing here yet" reads identically everywhere.
+///
+/// A next-step action is composition, not configuration: spawn a
+/// [`spawn_modal_button`] (or any control) in the same parent right
+/// after this call.
+///
+/// `glyph` MUST come from FiraMono-covered ranges — card suits
+/// (U+2660–2666), Arrows (U+2190–21FF), or ASCII. The Geometric Shapes
+/// block renders as tofu on Android (§10 / §11).
+pub fn spawn_empty_state(
+    parent: &mut ChildSpawnerCommands,
+    glyph: &str,
+    headline: &str,
+    detail: Option<&str>,
+    font_res: Option<&FontResource>,
+) {
+    let font_handle = font_res.map(|f| f.0.clone()).unwrap_or_default();
+    let font_glyph = TextFont {
+        font: font_handle.clone(),
+        font_size: TYPE_DISPLAY,
+        ..default()
+    };
+    let font_headline = TextFont {
+        font: font_handle.clone(),
+        font_size: TYPE_BODY_LG,
+        ..default()
+    };
+    let font_detail = TextFont {
+        font: font_handle,
+        font_size: TYPE_BODY,
+        ..default()
+    };
+
+    parent
+        .spawn((
+            EmptyStateBlock,
+            Node {
+                flex_direction: FlexDirection::Column,
+                align_items: AlignItems::Center,
+                row_gap: VAL_SPACE_2,
+                padding: UiRect::axes(VAL_SPACE_3, VAL_SPACE_5),
+                width: Val::Percent(100.0),
+                ..default()
+            },
+        ))
+        .with_children(|block| {
+            block.spawn((
+                Text::new(glyph.to_string()),
+                font_glyph,
+                TextColor(TEXT_DISABLED),
+            ));
+            block.spawn((
+                Text::new(headline.to_string()),
+                font_headline,
+                TextColor(TEXT_PRIMARY),
+            ));
+            if let Some(detail) = detail {
+                block.spawn((
+                    Text::new(detail.to_string()),
+                    font_detail,
+                    TextColor(TEXT_SECONDARY),
+                ));
+            }
+        });
+}
+
+/// Marker on every [`spawn_empty_state`] block, mostly for tests.
+#[derive(Component, Debug)]
+pub struct EmptyStateBlock;
+
 /// Spawns the bottom actions row — flex-row with primary right-aligned.
 /// The closure populates the row's buttons via `spawn_modal_button`.
 ///
@@ -1184,4 +1258,62 @@ mod tests {
             "exactly one of the two stacked dismissible modals should remain"
         );
     }
+
+    // -----------------------------------------------------------------------
+    // Phase L: standard empty state
+    // -----------------------------------------------------------------------
+
+    /// The helper spawns glyph + headline (+ detail when given) under one
+    /// marked block, so every empty surface renders identically.
+    #[test]
+    fn empty_state_spawns_expected_structure() {
+        let mut app = App::new();
+        app.add_plugins(MinimalPlugins);
+        {
+            let world = app.world_mut();
+            let mut commands = world.commands();
+            commands.spawn(Node::default()).with_children(|parent| {
+                spawn_empty_state(
+                    parent,
+                    "\u{2660}",
+                    "Nothing here.",
+                    Some("Do the thing."),
+                    None,
+                );
+                spawn_empty_state(parent, "!", "No detail variant.", None, None);
+            });
+        }
+        app.update();
+
+        let blocks = app
+            .world_mut()
+            .query_filtered::<Entity, With<EmptyStateBlock>>()
+            .iter(app.world())
+            .count();
+        assert_eq!(blocks, 2, "each call spawns exactly one marked block");
+
+        let texts: Vec<String> = app
+            .world_mut()
+            .query::<&Text>()
+            .iter(app.world())
+            .map(|t| t.0.clone())
+            .collect();
+        for expected in [
+            "\u{2660}",
+            "Nothing here.",
+            "Do the thing.",
+            "!",
+            "No detail variant.",
+        ] {
+            assert!(
+                texts.iter().any(|t| t == expected),
+                "missing text node {expected:?}; got {texts:?}"
+            );
+        }
+        assert_eq!(
+            texts.len(),
+            5,
+            "the detail-less variant must not spawn a detail node"
+        );
+    }
 }