From fa84152429d137a393c8bee98525389458d43f75 Mon Sep 17 00:00:00 2001
From: funman300 <funman300@gmail.com>
Date: Sun, 17 May 2026 21:08:11 -0700
Subject: [PATCH] =?UTF-8?q?fix(engine):=20correct=20Android=20help=20hint?=
 =?UTF-8?q?=20label=20from=20=E2=86=92=20to=20!=20(M-17)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The HUD buttons section in the Android controls reference showed "→"
(right-arrow) for the Hint action, but the actual on-screen button is
labelled "!" (ASCII exclamation). Extract ANDROID_HINT_LABEL from
hud_plugin so both the spawn path and the help text share a single
source of truth. Add a cfg(android) regression test that asserts the
hint row's key string matches the const.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 solitaire_engine/src/help_plugin.rs | 27 ++++++++++++++++++++++++++-
 solitaire_engine/src/hud_plugin.rs  |  7 ++++++-
 2 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/solitaire_engine/src/help_plugin.rs b/solitaire_engine/src/help_plugin.rs
index cbf47fa..04d77e2 100644
--- a/solitaire_engine/src/help_plugin.rs
+++ b/solitaire_engine/src/help_plugin.rs
@@ -9,6 +9,8 @@ use bevy::prelude::*;
 
 use crate::events::HelpRequestEvent;
 use crate::font_plugin::FontResource;
+#[cfg(target_os = "android")]
+use crate::hud_plugin::ANDROID_HINT_LABEL;
 use crate::ui_modal::{
     spawn_modal, spawn_modal_actions, spawn_modal_button, spawn_modal_header, ButtonVariant,
     ScrimDismissible,
@@ -158,7 +160,7 @@ const CONTROL_SECTIONS: &[ControlSection] = &[
             ControlRow { keys: "←", description: "Undo last move" },
             ControlRow { keys: "||", description: "Pause / resume" },
             ControlRow { keys: "?", description: "This help screen" },
-            ControlRow { keys: "→", description: "Show a hint" },
+            ControlRow { keys: ANDROID_HINT_LABEL, description: "Show a hint" },
             ControlRow { keys: "≡", description: "Open menu (Stats, Settings, Profile...)" },
         ],
     },
@@ -346,6 +348,29 @@ fn spawn_help_screen(commands: &mut Commands, font_res: Option<&FontResource>) {
 mod tests {
     use super::*;
 
+    /// Regression test for M-17: Android help screen showed "→" (right-arrow)
+    /// for the Hint button when the actual HUD button label is "!".
+    /// Verifies that the HUD Buttons section contains exactly one row whose
+    /// `keys` matches `ANDROID_HINT_LABEL`.
+    #[cfg(target_os = "android")]
+    #[test]
+    fn android_hint_row_matches_hud_label() {
+        use crate::hud_plugin::ANDROID_HINT_LABEL;
+        let hud_section = CONTROL_SECTIONS
+            .iter()
+            .find(|s| s.title == "HUD buttons")
+            .expect("HUD buttons section must exist");
+        let hint_row = hud_section
+            .rows
+            .iter()
+            .find(|r| r.description == "Show a hint")
+            .expect("hint row must exist");
+        assert_eq!(
+            hint_row.keys, ANDROID_HINT_LABEL,
+            "help hint row must match the HUD button label"
+        );
+    }
+
     fn headless_app() -> App {
         let mut app = App::new();
         app.add_plugins(MinimalPlugins).add_plugins(HelpPlugin);
diff --git a/solitaire_engine/src/hud_plugin.rs b/solitaire_engine/src/hud_plugin.rs
index e255c23..6629033 100644
--- a/solitaire_engine/src/hud_plugin.rs
+++ b/solitaire_engine/src/hud_plugin.rs
@@ -298,6 +298,11 @@ pub struct HelpButton;
 #[derive(Component, Debug)]
 pub struct HintButton;
 
+/// Android HUD label for the Hint button — shared with the help screen's
+/// controls reference so both always agree.
+#[cfg(target_os = "android")]
+pub(crate) const ANDROID_HINT_LABEL: &str = "!";
+
 /// Marker on the "Modes" action button. Click toggles the [`ModesPopover`]
 /// (a small dropdown panel) below the action bar. Each popover row starts
 /// the corresponding game mode.
@@ -856,7 +861,7 @@ fn spawn_action_buttons(
         /* undo */  "\u{2190}",  // ←  leftwards arrow (Arrows block, confirmed FiraMono)
         /* pause */ "||",        // || ASCII double-pipe — ‖ (U+2016) absent from FiraMono
         /* help */  "?",
-        /* hint */  "!",         // !  attention/alert — semantically: "look here"
+        /* hint */  ANDROID_HINT_LABEL,
         /* modes */ "M",          // plain ASCII — U+21BB and U+21C4 both render as tofu on FiraMono
         /* new */   "+",
     );