fix(engine): correct Android waste fan overlap and resume layout desync

Bug 1 (card_plugin): waste Draw-Three fan step was a fixed 0.28×card_width,
chosen for the desktop gap ratio (H_GAP_DIVISOR=4). On Android
(H_GAP_DIVISOR=32) the column spacing is only 1.031×card_width, so the same
fraction pushed the top fanned card's centre past the waste column's right
edge. Fix: derive fan_step from column spacing × 0.224 — preserves 0.28×cw
on desktop while reducing to ≈0.231×cw on Android, keeping fanned cards
within their column footprint. Adds regression test on 900×2000 portrait window.

Bug 2 (safe_area): refresh_insets stored its retry counter as Local<u32>,
making it impossible to re-arm after a background/foreground cycle. On resume
the counter was already saturated so JNI was never re-queried; layouts
computed with stale (zero) insets pushed the top card row up under the HUD.
Fix: convert tries to SafeAreaPollTries Resource; add android::rearm_on_resumed
which resets both counter and SafeAreaInsets on AppLifecycle::WillResume so
the poller re-fires; add on_app_resumed (all platforms) which emits a synthetic
WindowResized on WillResume to immediately trigger layout recomputation. Adds
pure-function regression test in layout.rs pinning the suspend→resume invariant.

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

solitaire_engine/src/card_plugin.rs

@@ -462,6 +462,49 @@ impl Plugin for CardPlugin {
     }
 }
 
+/// Returns the relative asset path for a card face PNG.
+///
+/// The path format is `cards/faces/classic/{RANK}{SUIT}.png`, e.g. `QS.png`
+/// for the Queen of Spades. Both `load_card_images` and the unit tests use
+/// this function so the filename formula is tested in isolation from the
+/// asset-loading machinery.
+///
+/// Note: this function verifies only the **code-side mapping**. If the PNG
+/// file at the returned path contains wrong artwork (e.g. `QS.png` has a
+/// diamond watermark baked in), that is an **asset content bug** and must be
+/// fixed by replacing the file — no code change can correct it.
+fn card_face_asset_path(rank: Rank, suit: Suit) -> String {
+    const SUIT_CHARS: [&str; 4] = ["C", "D", "H", "S"];
+    const RANK_STRS: [&str; 13] = [
+        "A", "2", "3", "4", "5", "6", "7", "8", "9", "10", "J", "Q", "K",
+    ];
+    let suit_idx = match suit {
+        Suit::Clubs    => 0,
+        Suit::Diamonds => 1,
+        Suit::Hearts   => 2,
+        Suit::Spades   => 3,
+    };
+    let rank_idx = match rank {
+        Rank::Ace   => 0,
+        Rank::Two   => 1,
+        Rank::Three => 2,
+        Rank::Four  => 3,
+        Rank::Five  => 4,
+        Rank::Six   => 5,
+        Rank::Seven => 6,
+        Rank::Eight => 7,
+        Rank::Nine  => 8,
+        Rank::Ten   => 9,
+        Rank::Jack  => 10,
+        Rank::Queen => 11,
+        Rank::King  => 12,
+    };
+    format!(
+        "cards/faces/classic/{}{}.png",
+        RANK_STRS[rank_idx], SUIT_CHARS[suit_idx]
+    )
+}
+
 /// Loads card face and back PNGs at startup via [`AssetServer`] and inserts
 /// [`CardImageSet`].
 ///
@@ -476,17 +519,15 @@ fn load_card_images(asset_server: Option<Res<AssetServer>>, mut commands: Comman
         return;
     };
 
-    // Suit index: Clubs=0, Diamonds=1, Hearts=2, Spades=3
+    const SUITS: [Suit; 4] = [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades];
-    const SUIT_CHARS: [&str; 4] = ["C", "D", "H", "S"];
+    const RANKS: [Rank; 13] = [
-    // Rank index: Ace=0 … King=12
+        Rank::Ace, Rank::Two, Rank::Three, Rank::Four, Rank::Five, Rank::Six, Rank::Seven,
-    const RANK_STRS: [&str; 13] = ["A", "2", "3", "4", "5", "6", "7", "8", "9", "10", "J", "Q", "K"];
+        Rank::Eight, Rank::Nine, Rank::Ten, Rank::Jack, Rank::Queen, Rank::King,
+    ];
 
-    let faces: [[Handle<Image>; 13]; 4] = std::array::from_fn(|suit| {
+    let faces: [[Handle<Image>; 13]; 4] = std::array::from_fn(|si| {
-        std::array::from_fn(|rank| {
+        std::array::from_fn(|ri| {
-            asset_server.load(format!(
+            asset_server.load(card_face_asset_path(RANKS[ri], SUITS[si]))
-                "cards/faces/classic/{}{}.png",
-                RANK_STRS[rank], SUIT_CHARS[suit]
-            ))
         })
     });
     let backs = std::array::from_fn(|i| {
@@ -584,6 +625,7 @@ fn resync_cards_on_settings_change(
 /// Render the initial deal. Runs in `PostStartup`, so all `Startup` systems
 /// (including `TablePlugin::setup_table` which inserts `LayoutResource`)
 /// have already completed.
+#[allow(clippy::too_many_arguments)]
 fn sync_cards_startup(
     commands: Commands,
     game: Res<GameStateResource>,
@@ -592,6 +634,7 @@ fn sync_cards_startup(
     settings: Option<Res<SettingsResource>>,
     entities: Query<(Entity, &CardEntity, &Transform, Option<&CardAnimation>)>,
     card_images: Option<Res<CardImageSet>>,
+    font_res: Option<Res<FontResource>>,
 ) {
     if let Some(layout) = layout {
         let slide_secs = slide_dur.map_or(0.15, |d| d.slide_secs);
@@ -599,7 +642,8 @@ fn sync_cards_startup(
         let back_colour = card_back_colour(selected_back);
         let color_blind = settings.as_ref().is_some_and(|s| s.0.color_blind_mode);
         let high_contrast = settings.as_ref().is_some_and(|s| s.0.high_contrast_mode);
-        sync_cards(commands, &game.0, &layout.0, slide_secs, back_colour, color_blind, high_contrast, &entities, card_images.as_deref(), selected_back);
+        let font_handle = font_res.as_ref().map(|r| &r.0);
+        sync_cards(commands, &game.0, &layout.0, slide_secs, back_colour, color_blind, high_contrast, &entities, card_images.as_deref(), selected_back, font_handle);
     }
 }
 
@@ -613,6 +657,7 @@ fn sync_cards_on_change(
     settings: Option<Res<SettingsResource>>,
     entities: Query<(Entity, &CardEntity, &Transform, Option<&CardAnimation>)>,
     card_images: Option<Res<CardImageSet>>,
+    font_res: Option<Res<FontResource>>,
 ) {
     if events.read().next().is_none() {
         return;
@@ -623,7 +668,8 @@ fn sync_cards_on_change(
         let back_colour = card_back_colour(selected_back);
         let color_blind = settings.as_ref().is_some_and(|s| s.0.color_blind_mode);
         let high_contrast = settings.as_ref().is_some_and(|s| s.0.high_contrast_mode);
-        sync_cards(commands, &game.0, &layout.0, slide_secs, back_colour, color_blind, high_contrast, &entities, card_images.as_deref(), selected_back);
+        let font_handle = font_res.as_ref().map(|r| &r.0);
+        sync_cards(commands, &game.0, &layout.0, slide_secs, back_colour, color_blind, high_contrast, &entities, card_images.as_deref(), selected_back, font_handle);
     }
 }
 
@@ -639,6 +685,7 @@ fn sync_cards(
     entities: &Query<(Entity, &CardEntity, &Transform, Option<&CardAnimation>)>,
     card_images: Option<&CardImageSet>,
     selected_back: usize,
+    font_handle: Option<&Handle<Font>>,
 ) {
     let positions = card_positions(game, layout);
 
@@ -668,10 +715,10 @@ fn sync_cards(
             Some(&(entity, cur, has_anim)) => {
                 update_card_entity(
                     &mut commands, entity, card, position, z, layout,
-                    slide_secs, back_colour, color_blind, high_contrast, cur, has_anim, card_images, selected_back,
+                    slide_secs, back_colour, color_blind, high_contrast, cur, has_anim, card_images, selected_back, font_handle,
                 )
             }
-            None => spawn_card_entity(&mut commands, card, position, z, layout, back_colour, color_blind, high_contrast, card_images, selected_back),
+            None => spawn_card_entity(&mut commands, card, position, z, layout, back_colour, color_blind, high_contrast, card_images, selected_back, font_handle),
         }
     }
 }
@@ -695,6 +742,19 @@ fn card_positions<'a>(game: &'a GameState, layout: &Layout) -> Vec<(&'a Card, Ve
         PileType::Tableau(6),
     ];
 
+    // Compute the Draw-Three waste fan step proportional to the column spacing
+    // (waste_x − stock_x = card_width + h_gap) rather than a fixed fraction of
+    // card_width.  On desktop (H_GAP_DIVISOR=4) col_step = 1.25×cw and
+    // 0.224 × 1.25 = 0.28 — identical to the previous constant.  On Android
+    // (H_GAP_DIVISOR=32) col_step ≈ 1.031×cw so fan_step ≈ 0.231×cw, keeping
+    // the top fanned card's centre within the waste column's own horizontal
+    // footprint instead of spilling into the adjacent gap.
+    let waste_fan_step = {
+        let s = layout.pile_positions.get(&PileType::Stock).copied().unwrap_or_default();
+        let w = layout.pile_positions.get(&PileType::Waste).copied().unwrap_or_default();
+        (w.x - s.x).abs() * 0.224
+    };
+
     for pile_type in piles {
         let Some(base) = layout.pile_positions.get(&pile_type) else {
             continue;
@@ -736,7 +796,7 @@ fn card_positions<'a>(game: &'a GameState, layout: &Layout) -> Vec<(&'a Card, Ve
                 // normally — no card is hidden, so the shift is 0.
                 let visible = 3_usize;
                 let hidden = rendered_len.saturating_sub(visible);
-                slot.saturating_sub(hidden) as f32 * layout.card_size.x * 0.28
+                slot.saturating_sub(hidden) as f32 * waste_fan_step
             } else {
                 0.0
             };
@@ -768,6 +828,7 @@ fn spawn_card_entity(
     high_contrast: bool,
     card_images: Option<&CardImageSet>,
     selected_back: usize,
+    font_handle: Option<&Handle<Font>>,
 ) {
     let sprite = card_sprite(card, layout.card_size, back_colour, card_images, selected_back);
 
@@ -811,9 +872,12 @@ fn spawn_card_entity(
     #[cfg(target_os = "android")]
     if card_images.is_some() {
         entity.with_children(|b| {
-            add_android_corner_label(b, card, layout.card_size, color_blind, high_contrast);
+            add_android_corner_label(b, card, layout.card_size, color_blind, high_contrast, font_handle);
         });
     }
+    // Suppress unused-variable warning when not building for Android.
+    #[cfg(not(target_os = "android"))]
+    let _ = font_handle;
 }
 
 #[allow(clippy::too_many_arguments)]
@@ -832,6 +896,7 @@ fn update_card_entity(
     has_card_animation: bool,
     card_images: Option<&CardImageSet>,
     selected_back: usize,
+    font_handle: Option<&Handle<Font>>,
 ) {
     let target = Vec3::new(pos.x, pos.y, z);
 
@@ -894,9 +959,12 @@ fn update_card_entity(
     #[cfg(target_os = "android")]
     if card_images.is_some() {
         commands.entity(entity).with_children(|b| {
-            add_android_corner_label(b, card, layout.card_size, color_blind, high_contrast);
+            add_android_corner_label(b, card, layout.card_size, color_blind, high_contrast, font_handle);
         });
     }
+    // Suppress unused-variable warning when not building for Android.
+    #[cfg(not(target_os = "android"))]
+    let _ = font_handle;
 }
 
 fn label_for(card: &Card) -> String {
@@ -1000,6 +1068,13 @@ fn mobile_label_for(card: &Card) -> String {
 /// Spawns the [`AndroidCornerLabel`] + [`AndroidCornerBg`] children on
 /// face-up cards. The background sprite covers the card art's own small
 /// corner text so only the large overlay is visible.
+/// Spawns the [`AndroidCornerLabel`] + [`AndroidCornerBg`] children on
+/// face-up cards using FiraMono (passed via `font_handle`) so that the
+/// suit Unicode glyphs U+2660–U+2666 render correctly. Without an explicit
+/// font handle Bevy falls back to its built-in face which does not include
+/// those glyphs, causing a coloured missing-glyph rectangle to appear in
+/// the text colour — the root cause of the "red square on face-down cards"
+/// visual bug (the box bleeds through near the card edge at z=0.02).
 #[cfg(target_os = "android")]
 fn add_android_corner_label(
     parent: &mut ChildSpawnerCommands,
@@ -1007,6 +1082,7 @@ fn add_android_corner_label(
     card_size: Vec2,
     color_blind: bool,
     high_contrast: bool,
+    font_handle: Option<&Handle<Font>>,
 ) {
     if !card.face_up {
         return;
@@ -1034,12 +1110,18 @@ fn add_android_corner_label(
         ),
     ));
 
-    // Large rank+suit text drawn on top of the background.
+    // Large rank+suit text drawn on top of the background. FiraMono must be
+    // wired here explicitly — the suit glyphs (U+2660–U+2666) are not in
+    // Bevy's built-in font and render as a coloured rectangle without it.
     parent.spawn((
         AndroidCornerLabel,
         CardLabel,
         Text2d::new(mobile_label_for(card)),
-        TextFont { font_size, ..default() },
+        TextFont {
+            font: font_handle.cloned().unwrap_or_default(),
+            font_size,
+            ..default()
+        },
         TextColor(text_colour(card, color_blind, high_contrast)),
         Anchor::TOP_LEFT,
         Transform::from_xyz(
@@ -3167,4 +3249,230 @@ mod tests {
         assert!((highlight.blue - success.blue).abs() < 1e-6);
         assert!((highlight.alpha - 0.6).abs() < 1e-6);
     }
+
+    // -----------------------------------------------------------------------
+    // Bug #1 — CardImageSet key lookup (code-side mapping)
+    //
+    // These tests verify that every (Rank, Suit) pair produces the expected
+    // filename via `card_face_asset_path`. They can only detect *code-side*
+    // mapping bugs (e.g. a suit index mismatch). They do NOT inspect pixel
+    // data — if `QS.png` contains a diamond watermark that is an *asset
+    // content* bug that requires replacing the PNG file.
+    // -----------------------------------------------------------------------
+
+    #[test]
+    fn card_face_asset_path_queen_of_spades_is_qs_png() {
+        assert_eq!(
+            card_face_asset_path(Rank::Queen, Suit::Spades),
+            "cards/faces/classic/QS.png",
+            "Queen of Spades must resolve to QS.png, not QD.png"
+        );
+    }
+
+    #[test]
+    fn card_face_asset_path_queen_of_diamonds_is_qd_png() {
+        assert_eq!(
+            card_face_asset_path(Rank::Queen, Suit::Diamonds),
+            "cards/faces/classic/QD.png"
+        );
+    }
+
+    #[test]
+    fn card_face_asset_path_ace_of_clubs_is_ac_png() {
+        assert_eq!(card_face_asset_path(Rank::Ace, Suit::Clubs), "cards/faces/classic/AC.png");
+    }
+
+    #[test]
+    fn card_face_asset_path_ten_of_hearts_is_10h_png() {
+        assert_eq!(card_face_asset_path(Rank::Ten, Suit::Hearts), "cards/faces/classic/10H.png");
+    }
+
+    #[test]
+    fn card_face_asset_path_king_of_spades_is_ks_png() {
+        assert_eq!(card_face_asset_path(Rank::King, Suit::Spades), "cards/faces/classic/KS.png");
+    }
+
+    #[test]
+    fn card_face_asset_path_all_52_keys_are_unique() {
+        use std::collections::HashSet;
+        let suits = [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades];
+        let ranks = [
+            Rank::Ace, Rank::Two, Rank::Three, Rank::Four, Rank::Five, Rank::Six,
+            Rank::Seven, Rank::Eight, Rank::Nine, Rank::Ten, Rank::Jack, Rank::Queen, Rank::King,
+        ];
+        let paths: HashSet<String> = suits
+            .iter()
+            .flat_map(|&s| ranks.iter().map(move |&r| card_face_asset_path(r, s)))
+            .collect();
+        assert_eq!(paths.len(), 52, "all 52 card face paths must be distinct");
+    }
+
+    #[test]
+    fn card_face_asset_path_suits_produce_correct_suffix() {
+        // Each suit must map to its own letter, not a neighbour's.
+        assert!(card_face_asset_path(Rank::Ace, Suit::Clubs).ends_with("AC.png"));
+        assert!(card_face_asset_path(Rank::Ace, Suit::Diamonds).ends_with("AD.png"));
+        assert!(card_face_asset_path(Rank::Ace, Suit::Hearts).ends_with("AH.png"));
+        assert!(card_face_asset_path(Rank::Ace, Suit::Spades).ends_with("AS.png"));
+    }
+
+    // -----------------------------------------------------------------------
+    // Bug #3 — Suit → color mapping for the Android corner overlay
+    //
+    // Black suits (♠♣) must use BLACK_SUIT_COLOUR (near-white) so they
+    // contrast against the dark card face. They must NOT share the red or
+    // lime colours assigned to red suits.
+    // -----------------------------------------------------------------------
+
+    #[test]
+    fn text_colour_black_suits_are_near_white_not_red() {
+        for suit in [Suit::Clubs, Suit::Spades] {
+            let card = Card { id: 0, suit, rank: Rank::Ace, face_up: true };
+            let colour = text_colour(&card, false, false);
+            assert_eq!(
+                colour, BLACK_SUIT_COLOUR,
+                "{suit:?} must map to BLACK_SUIT_COLOUR (near-white)"
+            );
+            assert_ne!(
+                colour, RED_SUIT_COLOUR,
+                "{suit:?} must not use the red suit colour"
+            );
+            // Confirm it's visually light (all channels > 0.85).
+            let srgba = colour.to_srgba();
+            assert!(
+                srgba.red > 0.85 && srgba.green > 0.85 && srgba.blue > 0.85,
+                "{suit:?} colour must be near-white for dark card background contrast, got {srgba:?}"
+            );
+        }
+    }
+
+    // -----------------------------------------------------------------------
+    // Bug #4 — Waste pile z-ordering
+    //
+    // Every rendered waste card must have a strictly greater z than the one
+    // below it so Bevy's CPU-side sprite sort renders them back-to-front.
+    // -----------------------------------------------------------------------
+
+    #[test]
+    fn waste_pile_cards_have_strictly_increasing_z() {
+        use solitaire_core::game_state::DrawMode;
+        let mut g = GameState::new(42, DrawMode::DrawThree);
+        for _ in 0..5 {
+            let _ = g.draw();
+        }
+        let layout = crate::layout::compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+        let positions = card_positions(&g, &layout);
+
+        let waste_ids: std::collections::HashSet<u32> = g.piles[&PileType::Waste]
+            .cards
+            .iter()
+            .map(|c| c.id)
+            .collect();
+
+        let mut waste_zs: Vec<f32> = positions
+            .iter()
+            .filter(|(c, _, _)| waste_ids.contains(&c.id))
+            .map(|(_, _, z)| *z)
+            .collect();
+        waste_zs.sort_by(|a, b| a.partial_cmp(b).unwrap());
+        waste_zs.dedup();
+
+        assert!(
+            waste_zs.len() >= 2,
+            "expected multiple rendered waste cards, got {}",
+            waste_zs.len()
+        );
+        // All z values must be strictly ordered (no duplicates).
+        for w in waste_zs.windows(2) {
+            assert!(
+                w[1] > w[0],
+                "waste z values must be strictly increasing, got {} ≤ {}",
+                w[1],
+                w[0]
+            );
+        }
+    }
+
+    /// Regression: on tight layouts (e.g. Android H_GAP_DIVISOR=32) the
+    /// Draw-Three waste fan must be proportional to column spacing so that no
+    /// fanned card ever bleeds left into the stock column.
+    ///
+    /// The invariant holds structurally (x_offset ≥ 0), but this test pins
+    /// the formula so a future change that accidentally introduces negative
+    /// offsets or flips the fan direction is caught immediately.
+    #[test]
+    fn waste_cards_do_not_overlap_stock_column_on_portrait() {
+        use solitaire_core::game_state::DrawMode;
+        let mut g = GameState::new(42, DrawMode::DrawThree);
+        for _ in 0..5 {
+            let _ = g.draw();
+        }
+
+        // Android-portrait window.  In host tests H_GAP_DIVISOR uses the
+        // desktop value (4), but the no-overlap invariant must hold on any
+        // screen size and gap ratio.
+        let window = Vec2::new(900.0, 2000.0);
+        let layout = crate::layout::compute_layout(window, 32.0, 110.0, true);
+
+        let stock_x = layout.pile_positions[&PileType::Stock].x;
+        let stock_right_edge = stock_x + layout.card_size.x / 2.0;
+
+        let waste_ids: std::collections::HashSet<u32> = g.piles[&PileType::Waste]
+            .cards
+            .iter()
+            .map(|c| c.id)
+            .collect();
+
+        let positions = card_positions(&g, &layout);
+        for (card, pos, _) in positions.iter().filter(|(c, _, _)| waste_ids.contains(&c.id)) {
+            let left_edge = pos.x - layout.card_size.x / 2.0;
+            assert!(
+                left_edge >= stock_right_edge - 1e-3,
+                "waste card {} left edge {:.2} overlaps stock right edge {:.2} on portrait window",
+                card.id,
+                left_edge,
+                stock_right_edge,
+            );
+        }
+    }
+
+    #[test]
+    fn waste_pile_draw_one_cards_have_distinct_z() {
+        use solitaire_core::game_state::DrawMode;
+        let mut g = GameState::new(42, DrawMode::DrawOne);
+        for _ in 0..3 {
+            let _ = g.draw();
+        }
+        let layout = crate::layout::compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+        let positions = card_positions(&g, &layout);
+
+        let waste_ids: std::collections::HashSet<u32> = g.piles[&PileType::Waste]
+            .cards
+            .iter()
+            .map(|c| c.id)
+            .collect();
+
+        let mut waste_zs: Vec<f32> = positions
+            .iter()
+            .filter(|(c, _, _)| waste_ids.contains(&c.id))
+            .map(|(_, _, z)| *z)
+            .collect();
+        waste_zs.sort_by(|a, b| a.partial_cmp(b).unwrap());
+        waste_zs.dedup();
+
+        assert!(
+            waste_zs.len() >= 2,
+            "Draw-One must render at least 2 waste cards (visible + buffer)"
+        );
+        // Deduplicated length must equal pre-dedup length → all z distinct.
+        let raw_count = positions
+            .iter()
+            .filter(|(c, _, _)| waste_ids.contains(&c.id))
+            .count();
+        assert_eq!(
+            waste_zs.len(),
+            raw_count,
+            "all rendered waste card z values must be distinct"
+        );
+    }
 }

solitaire_engine/src/layout.rs

@@ -605,6 +605,74 @@ mod tests {
         );
     }
 
+    /// Suspend → resume layout-consistency invariant.
+    ///
+    /// If the resume handler resets `SafeAreaInsets` to zero and then the JNI
+    /// poller re-resolves the same values, `compute_layout` must produce an
+    /// identical result to the fresh-launch layout.  This test also verifies
+    /// that a layout computed with `safe_area_top = 0` (the brief window while
+    /// insets haven't re-resolved after resume) differs visibly from the
+    /// correct layout, confirming that the bug would manifest without the fix.
+    #[test]
+    fn suspend_resume_layout_matches_fresh_launch() {
+        let window = Vec2::new(900.0, 2000.0);
+        let safe_top = 27.0_f32;
+        let safe_bottom = 110.0_f32;
+
+        // Fresh-launch layout — insets known from startup.
+        let fresh = compute_layout(window, safe_top, safe_bottom, true);
+
+        // Layout computed during the brief post-resume window before insets
+        // re-resolve (safe_area_top temporarily 0).
+        let wrong = compute_layout(window, 0.0, safe_bottom, true);
+
+        // Verify the "wrong" layout actually differs — the bug would push the
+        // top card row upward by exactly safe_top pixels.
+        let fresh_stock_y = fresh.pile_positions[&PileType::Stock].y;
+        let wrong_stock_y = wrong.pile_positions[&PileType::Stock].y;
+        // In Bevy's +y-is-up system, adding safe_area_top pushes the stock
+        // downward (−y direction).  So wrong_stock_y > fresh_stock_y by safe_top.
+        assert!(
+            (wrong_stock_y - fresh_stock_y - safe_top).abs() < 1e-3,
+            "wrong layout must displace stock upward by safe_top ({safe_top}): \
+             fresh={fresh_stock_y:.2} wrong={wrong_stock_y:.2} delta={:.2}",
+            wrong_stock_y - fresh_stock_y,
+        );
+
+        // After the poller re-resolves correct insets the layout must be
+        // identical to the fresh-launch layout.
+        let corrected = compute_layout(window, safe_top, safe_bottom, true);
+        assert_eq!(
+            corrected.card_size, fresh.card_size,
+            "card size must be preserved after resume",
+        );
+        assert!(
+            (corrected.pile_positions[&PileType::Stock].y - fresh_stock_y).abs() < 1e-3,
+            "stock y must match fresh launch after resume: \
+             corrected={:.2} fresh={fresh_stock_y:.2}",
+            corrected.pile_positions[&PileType::Stock].y,
+        );
+        assert!(
+            (corrected.pile_positions[&PileType::Stock].x
+                - fresh.pile_positions[&PileType::Stock].x)
+                .abs()
+                < 1e-3,
+            "stock x must be unchanged after resume",
+        );
+        // The HUD band top clearance (distance from window top to card top)
+        // must match as well — this is the quantity directly visible in Bug 2.
+        let card_top = |layout: &super::Layout| {
+            layout.pile_positions[&PileType::Stock].y + layout.card_size.y / 2.0
+        };
+        assert!(
+            (card_top(&corrected) - card_top(&fresh)).abs() < 1e-3,
+            "top-of-card must match fresh launch after resume: \
+             corrected={:.2} fresh={:.2}",
+            card_top(&corrected),
+            card_top(&fresh),
+        );
+    }
+
     /// safe_area_bottom must not affect horizontal positions.
     #[test]
     fn safe_area_bottom_does_not_affect_horizontal_layout() {

solitaire_engine/src/safe_area.rs

@@ -18,6 +18,7 @@
 //! changes flow through automatically.
 
 use bevy::prelude::*;
+use bevy::window::{AppLifecycle, WindowResized};
 
 use crate::ui_modal::ModalScrim;
 
@@ -65,14 +66,25 @@ pub struct SafeAreaInsetsPlugin;
 
 impl Plugin for SafeAreaInsetsPlugin {
     fn build(&self, app: &mut App) {
-        app.init_resource::<SafeAreaInsets>()
+        // Both message types may already be registered by GamePlugin / TablePlugin;
+        // add_message is idempotent.
+        app.add_message::<AppLifecycle>()
+            .add_message::<WindowResized>()
+            .init_resource::<SafeAreaInsets>()
             .add_systems(
                 Update,
-                (apply_safe_area_anchors, apply_safe_area_bottom_anchors, apply_safe_area_to_modal_scrims),
+                (
+                    apply_safe_area_anchors,
+                    apply_safe_area_bottom_anchors,
+                    apply_safe_area_to_modal_scrims,
+                    on_app_resumed,
+                ),
             );
 
         #[cfg(target_os = "android")]
-        app.add_systems(Update, android::refresh_insets);
+        app.init_resource::<android::SafeAreaPollTries>()
+            .add_systems(Update, android::refresh_insets)
+            .add_systems(Update, android::rearm_on_resumed);
     }
 }
 
@@ -142,33 +154,73 @@ fn apply_safe_area_to_modal_scrims(
     }
 }
 
+/// Emits a synthetic `WindowResized` on `AppLifecycle::WillResume` so that
+/// `on_window_resized` (in `table_plugin`) recomputes the board layout with
+/// whatever `SafeAreaInsets` are current at that moment.
+///
+/// On Android the `android::rearm_on_resumed` system runs in the same frame
+/// and resets both `SafeAreaPollTries` and `SafeAreaInsets` to zero, causing
+/// `refresh_insets` to re-poll JNI over the next few frames.  When it resolves
+/// the correct values, `on_safe_area_changed` in `table_plugin` emits a second
+/// synthetic `WindowResized` and the layout converges to the right position.
+///
+/// On non-Android targets this handler still fires — it ensures that a resume
+/// event always refreshes the layout (e.g., after a minimise/restore on
+/// desktop) even though insets are always zero.
+fn on_app_resumed(
+    mut lifecycle: MessageReader<AppLifecycle>,
+    windows: Query<(Entity, &Window)>,
+    mut resize_events: MessageWriter<WindowResized>,
+) {
+    for event in lifecycle.read() {
+        if !matches!(event, AppLifecycle::WillResume) {
+            continue;
+        }
+        let Some((entity, window)) = windows.iter().next() else {
+            return;
+        };
+        resize_events.write(WindowResized {
+            window: entity,
+            width: window.resolution.width(),
+            height: window.resolution.height(),
+        });
+    }
+}
+
 #[cfg(target_os = "android")]
 mod android {
-    use super::SafeAreaInsets;
+    use super::{AppLifecycle, SafeAreaInsets};
     use bevy::prelude::*;
 
+    /// Tracks how many frames `refresh_insets` has polled.  Stored as a
+    /// `Resource` (not `Local`) so that `rearm_on_resumed` can reset it to 0
+    /// when `AppLifecycle::WillResume` fires, causing the poller to re-query JNI
+    /// after a background/foreground cycle.
+    #[derive(Resource, Default)]
+    pub(super) struct SafeAreaPollTries(pub u32);
+
     /// Polls Android for safe-area insets until we get a non-zero
     /// reading, then stops. `getRootWindowInsets()` returns `null` (or
     /// all-zero `Insets`) until the decor view has been laid out, which
     /// is typically frame 1–3 of a fresh launch.
     pub(super) fn refresh_insets(
         mut insets: ResMut<SafeAreaInsets>,
-        mut tries: Local<u32>,
+        mut poll: ResMut<SafeAreaPollTries>,
     ) {
         // Cap retries so we don't burn CPU forever on edge-to-edge
         // devices that genuinely report zero insets.
         const MAX_TRIES: u32 = 120; // ~2 seconds @ 60 fps
 
-        if *tries >= MAX_TRIES || insets.is_populated() {
+        if poll.0 >= MAX_TRIES || insets.is_populated() {
             return;
         }
-        *tries += 1;
+        poll.0 += 1;
 
         match query_insets() {
             Ok(v) if v.is_populated() => {
                 info!(
                     "safe_area: insets resolved top={} bottom={} left={} right={} (after {} frames)",
-                    v.top, v.bottom, v.left, v.right, *tries
+                    v.top, v.bottom, v.left, v.right, poll.0
                 );
                 *insets = v;
             }
@@ -177,13 +229,35 @@ mod android {
             }
             Err(e) => {
                 // Don't spam — log once and let polling continue silently.
-                if *tries == 1 {
+                if poll.0 == 1 {
                     warn!("safe_area: JNI query failed (will retry): {e}");
                 }
             }
         }
     }
 
+    /// Resets the inset poller and clears cached insets on
+    /// `AppLifecycle::WillResume` so that `refresh_insets` re-queries JNI in the
+    /// frames immediately after the app returns to the foreground.
+    ///
+    /// Clearing `SafeAreaInsets` to the default (all-zero) fires
+    /// `on_safe_area_changed` in `table_plugin`, which emits a synthetic
+    /// `WindowResized`.  `on_window_resized` then recomputes the layout;
+    /// once `refresh_insets` resolves the real values a second synthetic
+    /// `WindowResized` fires and the layout converges to the correct position.
+    pub(super) fn rearm_on_resumed(
+        mut lifecycle: MessageReader<AppLifecycle>,
+        mut poll: ResMut<SafeAreaPollTries>,
+        mut insets: ResMut<SafeAreaInsets>,
+    ) {
+        for event in lifecycle.read() {
+            if matches!(event, AppLifecycle::WillResume) {
+                poll.0 = 0;
+                *insets = SafeAreaInsets::default();
+            }
+        }
+    }
+
     fn query_insets() -> Result<SafeAreaInsets, String> {
         use bevy::android::ANDROID_APP;
         use jni::{objects::JObject, JavaVM};