ci: pin toolchain to 1.95.0 and install Bevy native deps

Review feedback on #135: floating 'stable' + -D warnings lets every new
clippy release redden master with new lints — pin 1.95.0 like the
web-wasm-rebuild workflow. And ubuntu-latest lacks the ALSA/udev/X11/
Wayland dev packages the Bevy crates link against; install the standard
Bevy CI set (the project's own builder images have no desktop-Bevy
precedent — android-builder targets the NDK and web-e2e only builds the
server).

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

.gitea/workflows/test.yml

@@ -0,0 +1,66 @@
+# Workspace gate: the same clippy + test commands CLAUDE.md §6 requires
+# locally, run on every master push and pull request. Until this workflow
+# existed, nothing in CI ran the test suite at all — a direct push to
+# master (or the web-wasm-rebuild bot commit) was entirely unguarded.
+name: Test
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'solitaire_app/**'
+      - 'solitaire_assetgen/**'
+      - 'solitaire_core/**'
+      - 'solitaire_data/**'
+      - 'solitaire_engine/**'
+      - 'solitaire_server/src/**'
+      - 'solitaire_server/tests/**'
+      - 'solitaire_server/migrations/**'
+      - 'solitaire_sync/**'
+      - 'solitaire_wasm/**'
+      - 'solitaire_web/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - '.cargo/**'
+      - '.sqlx/**'
+      - '.gitea/workflows/test.yml'
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Rust 1.95.0
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.95.0
+          components: clippy
+
+      - name: Cache cargo build
+        uses: Swatinem/rust-cache@v2
+
+      # Native link deps for the Bevy crates (engine/app/web) on a bare
+      # ubuntu runner: ALSA + udev for input/audio, X11 + Wayland for winit.
+      - name: Install Bevy native dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libasound2-dev libudev-dev pkg-config libx11-dev libxcursor-dev \
+            libxrandr-dev libxi-dev libwayland-dev libxkbcommon-dev
+
+      # SQLX_OFFLINE uses the checked-in `.sqlx/` query cache (no live DB),
+      # same as the web-e2e workflow's server prebuild.
+      - name: Clippy (deny warnings)
+        env:
+          SQLX_OFFLINE: 'true'
+        run: cargo clippy --workspace --all-targets -- -D warnings
+
+      - name: Test
+        env:
+          SQLX_OFFLINE: 'true'
+        run: cargo test --workspace

ARCHITECTURE.md

@@ -1,9 +1,11 @@
 # Ferrous Solitaire — Architecture Document
 
-> **Version:** 1.3  
+> **Version:** 1.4  
 > **Language:** Rust (Edition 2024)  
 > **Engine:** Bevy (latest stable)  
-> **Last Updated:** 2026-05-12
+> **Last Updated:** 2026-07-06 — post card_game/klondike migration (PR #88):
+> core card/pile types come from the upstream `card_game` workspace and
+> score/undo/recycle are derived from the upstream session, not stored.
 
 ---
 
@@ -82,13 +84,15 @@ ferrous_solitaire/
 │       ├── win_fanfare.wav
 │       └── ambient_loop.wav
 │
-├── solitaire_core/             # Pure Rust game logic — zero external deps beyond rand/serde
+├── solitaire_core/             # Pure Rust game rules — wraps upstream card_game/klondike (serde + thiserror only otherwise)
 ├── solitaire_sync/             # Shared API types — used by client and server
 ├── solitaire_data/             # Persistence, sync client, settings
 ├── solitaire_engine/           # Bevy ECS systems, components, plugins
-├── solitaire_server/           # Self-hosted sync server (Axum + SQLite)
-├── solitaire_wasm/             # WebAssembly bindings — browser-side replay player
-└── solitaire_app/              # Main binary entry point
+├── solitaire_server/           # Self-hosted sync server (Axum + SQLite) + web frontend
+├── solitaire_wasm/             # WebAssembly bindings — browser-side logic/replay + debug bridge
+├── solitaire_web/              # Bevy WASM canvas build for the browser /play route
+├── solitaire_assetgen/         # One-shot generator for card/background PNG assets
+└── solitaire_app/              # Main binary entry point (desktop + Android cdylib)
 ```
 
 ---
@@ -96,18 +100,30 @@ ferrous_solitaire/
 ## 3. Crate Responsibilities
 
 ### `solitaire_core`
-**Dependencies:** `rand`, `serde`, `chrono` only.
+**Dependencies:** `serde`, `thiserror`, plus the upstream `card_game` and
+`klondike` crates (pinned via the Quaternions registry — never edit upstream).
 
-The entire game rules engine. No Bevy, no network, no file I/O. Designed to be tested in isolation with `cargo test -p solitaire_core`.
+The game rules layer. No Bevy, no network, no file I/O. Designed to be tested
+in isolation with `cargo test -p solitaire_core`.
+
+Since the card_game migration (2026-06-22, PR #88) the primitive types are
+**upstream**: `Card`, `Deck`, `Suit`, `Rank`, `Session` come from `card_game`;
+`Klondike`, `KlondikePile`, `KlondikeInstruction`, `DrawStockConfig`,
+`Foundation`, `Tableau` come from `klondike`. `solitaire_core` re-exports them
+so downstream crates import from one place and never depend on the upstream
+crates directly.
 
 Owns:
-- All game data models (`Card`, `Suit`, `Rank`, `Pile`, `GameState`)
-- Move validation logic
-- Scoring engine
-- Undo stack
+- `GameState` — a wrapper around the upstream `Session<Klondike>`; the session
+  is the single source of truth for board state and stats
+- `MoveError` and the `Result`-based mutation API
+- `KlondikeConfig` adaptation (`klondike_adapter`) — draw mode, scoring,
+  take-from-foundation
+- `GameMode` (Classic / Zen / Challenge / TimeAttack) and mode-aware scoring
+- Solvability check API (`SolveOutcome`, delegating to `Session::solve`)
 - Win / auto-complete detection
 - Achievement unlock condition evaluation
-- Seeded RNG for reproducible deals
+- Seeded deals (same seed ⇒ same layout, via the upstream dealer)
 
 **Rules decisions:**
 - **Stock recycling is unlimited in every draw mode — by design.** Extra
@@ -189,9 +205,13 @@ Owns:
 Because `ReplayPlayer` uses the same `solitaire_core::GameState` as the desktop client, the two implementations cannot drift: the same seed + move list produces identical pile state at every step on both platforms.
 
 ### `solitaire_app`
-**Dependencies:** `bevy`, `solitaire_engine`.
+**Dependencies:** `bevy`, `solitaire_engine`, `solitaire_data` (+ `jni` on Android).
 
-Thin binary entry point. Registers all Bevy plugins and sets initial window properties.
+Thin entry point (desktop binary + Android `cdylib`). Registers all Bevy
+plugins and sets initial window properties. The one crate in the workspace
+allowed `unsafe`: the Android entry point reconstructs the raw JNI handles and
+hands them to the safe `solitaire_data::android_jni` bridge; everything else
+is `forbid(unsafe_code)`.
 
 ---
 
@@ -559,26 +579,32 @@ This ensures all players worldwide get the same challenge for a given date, rega
 
 ### Core Game Models (`solitaire_core`)
 
+Since the card_game migration, the primitives are upstream types re-exported
+through `solitaire_core`:
+
 ```rust
-pub enum Suit { Clubs, Diamonds, Hearts, Spades }
-pub enum Rank { Ace, Two, Three, Four, Five, Six, Seven, Eight, Nine, Ten, Jack, Queen, King }
+// From `card_game` (upstream — never edit):
+pub enum Suit { /* Clubs, Diamonds, Hearts, Spades */ }
+pub enum Rank { /* Ace ..= King */ }
+pub struct Card { /* deck + suit + rank; identity type, no face_up flag —
+                     facing is positional, tracked by the Klondike board */ }
+pub struct Session<G> { /* replayable instruction log + derived stats */ }
 
-pub struct Card {
-    pub id: u32,
-    pub suit: Suit,
-    pub rank: Rank,
-    pub face_up: bool,
-}
-
-pub enum PileType {
+// From `klondike` (upstream — never edit):
+pub enum KlondikePile {
     Stock,
     Waste,
-    Foundation(Suit),
-    Tableau(usize),   // 0–6
+    Foundation(Foundation),   // 4 slots, any suit may claim any slot
+    Tableau(Tableau),         // 7 columns
 }
+pub enum DrawStockConfig { DrawOne, DrawThree }
+pub enum KlondikeInstruction { /* RotateStock, DstFoundation, ... — the
+                                  serialized move format (schema v4+) */ }
+```
 
-pub enum DrawMode { DrawOne, DrawThree }
+Owned by `solitaire_core`:
 
+```rust
 /// Active game mode. Classic is the default; others unlock at level 5.
 pub enum GameMode { Classic, Zen, Challenge, TimeAttack }
 
@@ -589,24 +615,30 @@ pub enum MoveError {
     RuleViolation(String),
     UndoStackEmpty,
     GameAlreadyWon,
+    StockEmpty,
 }
 
 pub struct GameState {
-    pub piles: HashMap<PileType, Vec<Card>>,
-    pub draw_mode: DrawMode,
     pub mode: GameMode,
-    pub score: i32,
-    pub move_count: u32,
-    pub undo_count: u32,        // number of undos used in this game
-    pub recycle_count: u32,     // number of stock recycles
     pub elapsed_seconds: u64,
-    pub seed: u64,
-    pub is_won: bool,
-    pub is_auto_completable: bool,
-    undo_stack: VecDeque<StateSnapshot>,   // private, max 64 (VecDeque for O(1) pop_front)
+    pub seed: u64,                 // same seed ⇒ same deal
+    pub take_from_foundation: bool,
+    session: Session<Klondike>,    // private — the single source of truth
 }
 ```
 
+**Derived, not stored:** `score()`, `move_count()`, `undo_count()`,
+`recycle_count()`, `is_won()`, `is_auto_completable()`, and all pile
+accessors read through the session. Undo replays the instruction log
+(no snapshot stack); the −15 undo penalty is applied by the upstream
+score formula via the session config. Persistence (schema v5) saves
+`saved_moves` as upstream `KlondikeInstruction`s and rebuilds the
+session by replay on load — older files carrying `score`/`undo_count`/
+`recycle_count` keys load fine, the extra fields are ignored.
+
+**Rules decision:** stock recycling is unlimited in every draw mode
+(see the "Rules decisions" note in §3 `solitaire_core`).
+
 ### Persistence Models (`solitaire_data`)
 
 ```rust
@@ -644,7 +676,7 @@ pub struct AchievementRecord {
 }
 
 pub struct Settings {
-    pub draw_mode: DrawMode,
+    pub draw_mode: DrawStockConfig,
     pub sfx_volume: f32,                       // 0.0–1.0
     pub music_volume: f32,
     pub animation_speed: AnimSpeed,

CHANGELOG.md

@@ -6,6 +6,24 @@ project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.41.1] — 2026-07-06
+
+### Fixed
+
+- **Oversized pile-marker frames after fold/unfold.** `on_window_resized`
+  resized the marker fill sprite but never its children, so the outline frame
+  and the "A"/"K" watermark kept their spawn-time size after any resize —
+  rendering as oversized grey slabs over empty foundation slots on foldables
+  (found during Galaxy Fold 7 on-device verification of v0.41.0, fixed and
+  re-verified on the same device). Both children are now re-derived from the
+  new layout on every relayout.
+
+### Added
+
+- **Android relayout diagnostics.** Every layout recompute on Android now
+  logs its window dimensions and insets (`layout: resize to WxH …`) — the
+  evidence channel for foldable layout reports (#130).
+
 ## [0.41.0] — 2026-07-06
 
 > Consolidates everything shipped since v0.39.0, including the v0.40.0–v0.40.3

CLAUDE.md

@@ -30,7 +30,9 @@ solitaire_data/    # Persistence + sync client
 solitaire_engine/  # Bevy ECS + UI + gameplay orchestration
 solitaire_server/  # Axum backend (optional sync layer)
 solitaire_wasm/    # WASM bindings for browser-side replay player
-solitaire_app/     # Entry binary
+solitaire_web/     # Bevy WASM canvas build for the browser /play route
+solitaire_assetgen/ # One-shot card/background PNG asset generator
+solitaire_app/     # Entry binary (desktop + Android cdylib)
 assets/            # Runtime assets (except audio + default theme)
 ```
 

Cargo.toml

@@ -156,3 +156,19 @@ opt-level = 3
 [profile.release]
 opt-level = 3
 lto = "thin"
+
+# Size-focused profile for the browser canvas build (solitaire_web →
+# canvas_bg.wasm). Download size is the constraint on the web, not peak
+# throughput: fat LTO + one codegen unit + opt-level "s" cut the Bevy wasm
+# bundle substantially versus plain release. This is rustc-side sizing only —
+# the binaryen pass in build_wasm.sh stays at wasm-opt -O2 because -Oz has
+# miscompiled Bevy's render pipeline before (grey screen on first load).
+[profile.wasm-release]
+inherits = "release"
+opt-level = "s"
+lto = "fat"
+codegen-units = 1
+# No `strip`: on wasm it also removes the target_features custom section,
+# which makes wasm-opt reject the module ("all used features should be
+# allowed" on trunc_sat). wasm-opt drops the name section in its output
+# anyway, so strip buys nothing here.

SESSION_HANDOFF.md

@@ -1,16 +1,57 @@
 # Ferrous Solitaire — Session Handoff
 
-**Last updated:** 2026-06-25 — v0.40.0 released (Android APK published); physical-device gate remains.
+**Last updated:** 2026-07-06 — v0.41.0 + v0.41.1 released and verified on a
+physical Galaxy Fold 7; issue tracker empty except low-priority #130.
 
 ---
 
 ## Current state
 
-- **Branch state:** `master` pushed to origin; latest commits are the Draw-Three waste fan fix, its regression tests, and the NDK doc update (PRs #105–#108).
-- **Latest tag:** `v0.40.0` (released — signed arm64-v8a APK published to the Gitea release for Obtainium/sideload). `v0.39.1` was the prior published release.
-- **Working tree:** clean. Local `scripts/` helpers (incl. `scripts/watch_deploy.sh`) are intentionally not committed.
-- **Latest verification this session:** `cargo clippy --workspace --all-targets -- -D warnings`; `cargo test --workspace`; `cargo build -p solitaire_app`; Android cross-compile + clippy for `aarch64-linux-android` (clean); full local signed arm64-v8a APK via `scripts/build_android_apk.sh`; CI `android-release` for `v0.40.0` completed/success with APK download HTTP 200.
-- **Full previous gate:** card_game work pushed to origin with `cargo test` / `clippy` gates passing.
+- **Branch state:** `master` pushed to origin; latest work is the 2026-07-06
+  arc (PRs #121–#131): scripted repo review, five issues filed and fixed,
+  plugin module splits, two releases.
+- **Latest tags:** `v0.41.1` (pile-marker child-resize fix + Android relayout
+  logging) on top of `v0.41.0` (consolidated release for everything since
+  v0.39.0). Both released via tag push → CI signed APK; both verified
+  installed on hardware (`versionCode 4101`).
+- **Working tree:** clean. Local `scripts/*.go` helpers are intentionally
+  gitignored (`.gitignore:43`); `scripts/watch_deploy.sh` is now committed.
+- **Latest verification:** workspace clippy `--all-targets -D warnings`,
+  full test suite, `cargo ndk` clippy for `aarch64-linux-android`, CI release
+  builds green, and an on-device pass on the Fold 7 (fold/unfold layout,
+  safe-area resume, marker fix).
+- **Issue tracker:** #116/#117/#118/#119/#120 all closed 2026-07-06. #130
+  (transient tableau clip after fold) open at low priority — did not
+  reproduce in repeat testing; v0.41.1's relayout logging is the evidence
+  channel if it recurs.
+
+---
+
+## 2026-07-06 session summary (v0.40.3 → v0.41.1)
+
+- **Scripted repo review** (cratemap/todoctx/cargoclip/testfail): clippy
+  clean, tests green, error/SQL policies compliant. Five issues filed and
+  all resolved same-day.
+- **#116 safe-area re-poll after resume** (PR #121): `refresh_insets` now
+  gates on the poll counter, settles per cycle, and rewrites insets only on
+  change. Verified on Fold 7 — note both Fold screens report identical
+  insets (top=110 bottom=0), so the re-poll path is a no-op on this device.
+- **#117 Draw-1 recycle** (PR #122): unlimited recycling documented as an
+  intentional rules decision (ARCHITECTURE.md "Rules decisions" +
+  `draw_one_recycling_is_unlimited_by_design` lock-in test). A hard limit
+  would invalidate the difficulty seed catalog and the winnable-deal solver.
+- **#118 module splits** (PRs #124/#125/#127/#128/#129): card, hud,
+  settings, game, and input plugins are now module directories; tests in
+  sibling `tests.rs`, runtime code split along system boundaries
+  (`pub(super)` items, mod.rs glob-imports children). Largest runtime file
+  is now `card_plugin/sync.rs` at 748 lines (was `card_plugin.rs` at 4,129).
+- **v0.41.1 pile-marker fix** (PR #131): marker outline + "A"/"K" watermark
+  children are re-derived from the layout on every resize — previously
+  spawn-time-sized, rendering as oversized grey slabs on empty foundations
+  after fold/unfold. Found via photo evidence, fixed, re-verified on device.
+- **Obtainium note:** reported "no suitable release" for v0.41.0 even though
+  the anonymous releases API, `releases/latest`, and the APK download were
+  all verified fine — client-side issue; sideload via adb was used instead.
 
 ---
 
@@ -127,32 +168,17 @@ Three bugs fixed:
 
 ## Open punch list
 
-### 1. Physical-device smoke test — THE ONLY REMAINING v0.40.0 ITEM
+### 1. Physical-device smoke test — DONE (2026-07-06, Galaxy Fold 7)
 
-This is the **single outstanding task** for the v0.40.0 Android release. Everything
-else is done and verified: workspace gates, `aarch64-linux-android` cross-compile +
-clippy, release manifest sanity, a full local signed APK, the published release, and
-Obtainium-facing delivery (public releases API, latest non-draft release, APK
-downloadable anonymously). The only thing that cannot be done without hardware is
-running the app on a real phone.
+v0.41.1 installed via adb and the full device checklist passed on hardware:
+fold/unfold layout on both screens (incl. the #116 resume path and the
+pile-marker fix), safe-area inset resolution, Draw-Three waste fan tap
+accuracy (#106), modal centring on both screens, drag-and-drop across all
+pile types, text rendering, kill-and-restore, and the sync token flow.
+Reminder for future gates: AVD is not a substitute — `adb shell input tap`
+doesn't deliver real touch events.
 
-Install the published APK on a real Android device (not AVD) and run the checklist
-in `docs/ANDROID.md §4`. This has never been gated in CI — AVD `adb shell input tap`
-doesn't deliver real touch events, so physical-device smoke testing is the only gate.
-
-The signed release APK is published (grab it from the release page, or use the local
-`target/debug/apk/ferrous-solitaire.apk`). When testing, specifically exercise the
-Draw-Three waste fan fixed in #106: switch to Draw-Three, draw several cards, and
-confirm dragging the visible top waste card plays *that* card, not the one beneath it.
-
-Latest AVD smoke (2026-06-08 local / 2026-06-09 UTC): built
-`target/debug/apk/ferrous-solitaire.apk` for `x86_64-linux-android`, installed
-it on AVD `Pixel_7`, launched `android.app.NativeActivity`, confirmed Bevy
-rendered the board, safe-area insets resolved as `top=136 bottom=63 left=0
-right=0` after 2 frames, onboarding could be dismissed via AVD input, and
-filtered logcat showed no Ferrous panic/fatal/ANR.
-
-### 2. Matomo analytics live validation (independent — NOT a v0.40.0 release blocker)
+### 2. Matomo analytics live validation (independent — NOT a release blocker)
 
 Separate, ongoing task unrelated to the Android release. `Settings` has
 `analytics_enabled`, `matomo_url`, and `matomo_site_id`; the engine consumes them via
@@ -164,6 +190,24 @@ validation checklist and the current web/WASM decision notes.
 
 ## Architectural notes for next session
 
+- **Plugin submodule pattern (2026-07-06 splits):** big plugins are module
+  directories: `mod.rs` holds types/markers/plugin-build and glob-imports the
+  children (`use input::*;`); children hold `pub(super)` systems and start
+  with `use super::*;` plus their own external imports. Tests (`tests.rs`)
+  may need explicit imports for names no longer used by `mod.rs` itself.
+
+- **Marker child-resize rule:** anything spawned as a *child* of a
+  layout-sized entity (outline frames, watermark text) must be re-derived in
+  `on_window_resized` too — resizing only the parent sprite leaves children
+  at spawn-time size (the v0.41.1 foldable bug).
+
+- **Fold 7 quirks:** both screens report identical safe-area insets
+  (top=110, bottom=0), so inset-driven relayout never fires on fold; layout
+  correctness across folds rides entirely on `WindowResized`. winit 0.30
+  logs `TODO: find a way to notify application of content rect change` on
+  resume — see #130 if a stale-width layout ever reproduces; v0.41.1 logs
+  every Android relayout (`layout: resize to WxH`) for exactly this.
+
 - **Reduce-motion pattern:** always gate in the `start_*` / `detect_*` system
   (the trigger), not the `tick_*` system. If the component is never inserted, the
   tick path never runs. See `hud_plugin.rs::detect_score_change` and

build_wasm.sh

@@ -67,7 +67,9 @@ if ! command -v wasm-bindgen &> /dev/null; then
 fi
 
 echo "Building solitaire_web (Bevy WASM app)..."
-cargo build --release --target wasm32-unknown-unknown -p solitaire_web
+# wasm-release is the size-focused profile (fat LTO, CGU=1, opt-level "s") —
+# see [profile.wasm-release] in Cargo.toml. Download size is the constraint.
+cargo build --profile wasm-release --target wasm32-unknown-unknown -p solitaire_web
 
 echo "Running wasm-bindgen for solitaire_web..."
 wasm-bindgen \
@@ -75,7 +77,7 @@ wasm-bindgen \
     --out-name canvas \
     --target web \
     --no-typescript \
-    "$REPO_ROOT/target/wasm32-unknown-unknown/release/solitaire_web.wasm"
+    "$REPO_ROOT/target/wasm32-unknown-unknown/wasm-release/solitaire_web.wasm"
 
 # Optional size optimisation — Bevy bundles are large (~5-15 MB uncompressed).
 # wasm-opt passes are skipped silently when the tool is not installed.

solitaire_engine/src/card_plugin/anim.rs

@@ -0,0 +1,200 @@
+//! Card flip animation and drag shadows.
+
+use super::*;
+
+use std::collections::HashSet;
+
+use solitaire_core::Card;
+
+use crate::animation_plugin::EffectiveSlideDuration;
+use crate::events::{CardFaceRevealedEvent, CardFlippedEvent};
+use crate::layout::LayoutResource;
+use crate::resources::DragState;
+use crate::ui_theme::{
+    CARD_SHADOW_ALPHA_DRAG, CARD_SHADOW_COLOR, CARD_SHADOW_LOCAL_Z,
+};
+
+/// Listens for `CardFlippedEvent` and inserts a `CardFlipAnim` on the entity.
+///
+/// Skipped when `EffectiveSlideDuration::slide_secs == 0.0` (Instant speed).
+pub(super) fn start_flip_anim(
+    mut events: MessageReader<CardFlippedEvent>,
+    slide_dur: Option<Res<EffectiveSlideDuration>>,
+    mut commands: Commands,
+    card_entities: Query<(Entity, &CardEntity)>,
+) {
+    if slide_dur.is_some_and(|d| d.slide_secs == 0.0) {
+        // Instant animation speed — skip the flip effect entirely.
+        events.clear();
+        return;
+    }
+
+    for CardFlippedEvent(flipped_card) in events.read() {
+        for (entity, marker) in &card_entities {
+            if marker.card == *flipped_card {
+                commands.entity(entity).insert(CardFlipAnim {
+                    timer: 0.0,
+                    phase: FlipPhase::ScalingDown,
+                });
+                break;
+            }
+        }
+    }
+}
+
+/// Advances `CardFlipAnim` each frame, modifying `Transform::scale.x`.
+///
+/// - Phase `ScalingDown`: lerps scale.x from 1.0 → 0.0 over `FLIP_HALF_SECS`.
+/// - At the midpoint the phase switches to `ScalingUp`, scale.x resets to 0,
+///   and a `CardFaceRevealedEvent` is fired so audio plays in sync with the reveal.
+/// - Phase `ScalingUp`:  lerps scale.x from 0.0 → 1.0 over `FLIP_HALF_SECS`.
+/// - When complete the component is removed and scale.x is restored to 1.0.
+pub(super) fn tick_flip_anim(
+    mut commands: Commands,
+    time: Res<Time>,
+    mut anims: Query<(Entity, &CardEntity, &mut Transform, &mut CardFlipAnim)>,
+    mut reveal_events: MessageWriter<CardFaceRevealedEvent>,
+) {
+    let dt = time.delta_secs();
+    for (entity, card_entity, mut transform, mut anim) in &mut anims {
+        anim.timer += dt;
+        match anim.phase {
+            FlipPhase::ScalingDown => {
+                let t = (anim.timer / FLIP_HALF_SECS).min(1.0);
+                transform.scale.x = 1.0 - t;
+                if t >= 1.0 {
+                    anim.phase = FlipPhase::ScalingUp;
+                    anim.timer = 0.0;
+                    transform.scale.x = 0.0;
+                    // Fire the reveal event exactly once, at the phase transition,
+                    // so the flip sound is synchronised with the visual face reveal.
+                    reveal_events.write(CardFaceRevealedEvent(card_entity.card.clone()));
+                }
+            }
+            FlipPhase::ScalingUp => {
+                let t = (anim.timer / FLIP_HALF_SECS).min(1.0);
+                transform.scale.x = t;
+                if t >= 1.0 {
+                    transform.scale.x = 1.0;
+                    commands.entity(entity).remove::<CardFlipAnim>();
+                }
+            }
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Task #38 — Drag-elevation shadow
+// ---------------------------------------------------------------------------
+
+/// Maintains a single `ShadowEntity` while cards are being dragged.
+///
+/// - If a drag is active, spawns (or repositions) a semi-transparent dark
+///   sprite behind the top dragged card.
+/// - If no drag is active, despawns the shadow entity.
+pub(super) fn update_drag_shadow(
+    mut commands: Commands,
+    drag: Res<DragState>,
+    layout: Option<Res<LayoutResource>>,
+    card_entities: Query<(&CardEntity, &Transform)>,
+    card_index: Res<CardEntityIndex>,
+    mut shadow: Local<Option<Entity>>,
+) {
+    if drag.is_idle() {
+        // No drag in progress — remove shadow if it exists.
+        if let Some(e) = shadow.take() {
+            commands.entity(e).despawn();
+        }
+        return;
+    }
+
+    let Some(layout) = layout else { return };
+    let card_w = layout.0.card_size.x;
+    let card_h = layout.0.card_size.y;
+
+    // Find the world position of the first (top) dragged card.
+    let top_pos = drag.cards.first().and_then(|first_card| {
+        card_index
+            .get(first_card)
+            .and_then(|entity| card_entities.get(entity).ok())
+            .map(|(_, t)| t.translation)
+    });
+
+    let Some(top_pos) = top_pos else { return };
+
+    // Shadow is slightly larger, offset behind-and-below, at a z slightly
+    // below the dragged cards.
+    let shadow_pos = top_pos + Vec3::new(-4.0, 4.0, -1.0);
+
+    match *shadow {
+        Some(e) => {
+            // Reposition the existing shadow.
+            commands
+                .entity(e)
+                .insert(Transform::from_translation(shadow_pos));
+        }
+        None => {
+            // Spawn a new shadow sprite. Alpha tracks the per-card
+            // CARD_SHADOW_ALPHA_DRAG token so the Terminal palette's
+            // "no box-shadow" policy disables this stack shadow in
+            // lockstep with the per-card shadows. Re-enabling shadows
+            // is then a one-line change in `ui_theme`, not a hunt
+            // through plugin code.
+            let e = commands
+                .spawn((
+                    ShadowEntity,
+                    Sprite {
+                        color: CARD_SHADOW_COLOR.with_alpha(CARD_SHADOW_ALPHA_DRAG),
+                        custom_size: Some(Vec2::new(card_w + 8.0, card_h + 8.0)),
+                        ..default()
+                    },
+                    Transform::from_translation(shadow_pos),
+                    Visibility::default(),
+                ))
+                .id();
+            *shadow = Some(e);
+        }
+    }
+}
+
+/// Snaps every per-card [`CardShadow`] between its idle and lifted tunings
+/// based on whether the parent [`CardEntity`] is currently in
+/// [`DragState::cards`]. Runs every frame; the transition is an instant snap
+/// (no lerp) — the existing shake / settle feedback already handles motion
+/// at drag-end, so an additional shadow tween would compete with those cues.
+///
+/// The shadow size is rebuilt from the parent card's current `Sprite`
+/// `custom_size` plus the appropriate padding, so the resize handler does
+/// not need to pre-tune shadow sizes for the drag state — this system fixes
+/// the geometry within one frame.
+pub(super) fn update_card_shadows_on_drag(
+    drag: Res<DragState>,
+    cards: Query<(&CardEntity, &Sprite, &Children), Without<CardShadow>>,
+    mut shadows: Query<(&mut Sprite, &mut Transform), With<CardShadow>>,
+) {
+    let dragged: HashSet<&Card> = drag.cards.iter().collect();
+
+    for (card_entity, card_sprite, children) in cards.iter() {
+        let is_dragged = dragged.contains(&card_entity.card);
+        let (offset, padding, alpha) = card_shadow_params(is_dragged);
+        let Some(card_size) = card_sprite.custom_size else {
+            continue;
+        };
+
+        for child in children.iter() {
+            let Ok((mut shadow_sprite, mut shadow_transform)) = shadows.get_mut(child) else {
+                continue;
+            };
+            shadow_sprite.color = CARD_SHADOW_COLOR.with_alpha(alpha);
+            shadow_sprite.custom_size = Some(card_size + padding);
+            shadow_transform.translation.x = offset.x;
+            shadow_transform.translation.y = offset.y;
+            shadow_transform.translation.z = CARD_SHADOW_LOCAL_Z;
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Task #28 — Hint highlight tick system
+// ---------------------------------------------------------------------------
+

solitaire_engine/src/card_plugin/highlights.rs

@@ -0,0 +1,276 @@
+//! Hint and right-click highlights, plus cursor hit-testing helpers.
+
+use super::*;
+
+
+use bevy::color::Color;
+use solitaire_core::Card;
+use solitaire_core::game_state::GameState;
+
+use crate::events::StateChangedEvent;
+use crate::layout::{Layout, LayoutResource};
+use crate::pause_plugin::PausedResource;
+use crate::resources::{DragState, GameStateResource};
+use crate::settings_plugin::SettingsResource;
+use crate::table_plugin::{PILE_MARKER_DEFAULT_COLOUR, PileMarker};
+
+/// Counts down `HintHighlight::remaining` each frame. When it reaches zero,
+/// removes both `HintHighlight` and `HintHighlightTimer` (if present) and
+/// resets the card sprite to its normal face-up colour.
+pub(super) fn tick_hint_highlight(
+    time: Res<Time>,
+    mut commands: Commands,
+    mut query: Query<(Entity, &mut HintHighlight, &mut Sprite, &CardEntity)>,
+    game: Res<GameStateResource>,
+    settings: Option<Res<SettingsResource>>,
+    card_images: Option<Res<CardImageSet>>,
+) {
+    let back_idx = settings.as_ref().map_or(0, |s| s.0.selected_card_back);
+    let use_images = card_images.is_some();
+    for (entity, mut hint, mut sprite, card_entity) in query.iter_mut() {
+        hint.remaining -= time.delta_secs();
+        if hint.remaining <= 0.0 {
+            // Restore the normal sprite colour.
+            // When image-based rendering is active, WHITE is the neutral tint;
+            // otherwise restore the solid colour appropriate to the card state.
+            sprite.color = if use_images {
+                Color::WHITE
+            } else {
+                let is_face_up = all_cards(&game.0)
+                    .iter()
+                    .find(|(c, _face_up)| *c == card_entity.card)
+                    .is_some_and(|(_, face_up)| *face_up);
+                if is_face_up {
+                    CARD_FACE_COLOUR
+                } else {
+                    card_back_colour(back_idx)
+                }
+            };
+            commands
+                .entity(entity)
+                .remove::<HintHighlight>()
+                .remove::<HintHighlightTimer>();
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Task #46 — Right-click legal destination highlights
+// ---------------------------------------------------------------------------
+
+/// Lime tint applied to a `PileMarker` sprite when it is a legal
+/// destination for the right-clicked card. Same RGB as the design-
+/// system [`STATE_SUCCESS`] token at 60% alpha. Spelled as a literal
+/// because `Alpha::with_alpha` is not yet a `const` trait method on
+/// stable; the tracking test below pins the RGB to `STATE_SUCCESS`
+/// so a palette swap can't drift the two apart silently.
+pub(super) const RIGHT_CLICK_HIGHLIGHT_COLOUR: Color = Color::srgba(0.675, 0.761, 0.404, 0.6);
+
+/// Counts down `RightClickHighlightTimer` each frame and clears the highlight
+/// when the timer expires.
+///
+/// This is a fallback expiry: highlights also clear immediately on
+/// `StateChangedEvent` (move made) or when the game is paused, whichever comes
+/// first. The 1.5 s timer ensures highlights always disappear even if the
+/// player takes no further action.
+pub(super) fn tick_right_click_highlights(
+    mut commands: Commands,
+    time: Res<Time>,
+    paused: Option<Res<PausedResource>>,
+    mut highlights: Query<
+        (Entity, &mut RightClickHighlightTimer, &mut Sprite),
+        With<RightClickHighlight>,
+    >,
+) {
+    if paused.is_some_and(|p| p.0) {
+        return;
+    }
+    let dt = time.delta_secs();
+    for (entity, mut timer, mut sprite) in &mut highlights {
+        timer.0 -= dt;
+        if timer.0 <= 0.0 {
+            // Restore the pile marker to its default colour before removing
+            // the highlight marker component.
+            sprite.color = PILE_MARKER_DEFAULT_COLOUR;
+            commands
+                .entity(entity)
+                .remove::<RightClickHighlight>()
+                .remove::<RightClickHighlightTimer>();
+        }
+    }
+}
+
+/// Removes the `RightClickHighlight` marker from every highlighted pile and
+/// resets its sprite colour to `PILE_MARKER_DEFAULT_COLOUR`.
+///
+/// Shared by the on-state-change and on-pause clear systems to avoid
+/// duplicating the removal logic.
+pub(super) fn clear_right_click_highlights(
+    commands: &mut Commands,
+    highlighted: &Query<Entity, With<RightClickHighlight>>,
+    pile_markers: &mut Query<(Entity, &PileMarker, &mut Sprite)>,
+) {
+    for entity in highlighted.iter() {
+        commands.entity(entity).remove::<RightClickHighlight>();
+    }
+    for (_entity, _, mut sprite) in pile_markers.iter_mut() {
+        if sprite.color == RIGHT_CLICK_HIGHLIGHT_COLOUR {
+            sprite.color = PILE_MARKER_DEFAULT_COLOUR;
+        }
+    }
+}
+
+/// Clears all right-click destination highlights whenever any game-state
+/// mutation succeeds (`StateChangedEvent` fires).
+///
+/// This ensures stale highlights do not linger after a card is moved.
+pub(super) fn clear_right_click_highlights_on_state_change(
+    mut events: MessageReader<StateChangedEvent>,
+    mut commands: Commands,
+    highlighted: Query<Entity, With<RightClickHighlight>>,
+    mut pile_markers: Query<(Entity, &PileMarker, &mut Sprite)>,
+) {
+    if events.read().next().is_none() {
+        return;
+    }
+    clear_right_click_highlights(&mut commands, &highlighted, &mut pile_markers);
+}
+
+/// Clears all right-click destination highlights when the game is paused
+/// (`PausedResource` changes to `true`).
+///
+/// Prevents highlighted pile markers from remaining visible behind the pause
+/// overlay.
+pub(super) fn clear_right_click_highlights_on_pause(
+    paused: Option<Res<PausedResource>>,
+    mut commands: Commands,
+    highlighted: Query<Entity, With<RightClickHighlight>>,
+    mut pile_markers: Query<(Entity, &PileMarker, &mut Sprite)>,
+) {
+    let Some(paused) = paused else { return };
+    if paused.is_changed() && paused.0 {
+        clear_right_click_highlights(&mut commands, &highlighted, &mut pile_markers);
+    }
+}
+
+/// Handles right-click: highlights legal destination piles for the clicked card,
+/// and clears highlights on any subsequent right- or left-click.
+///
+/// This system lives in `CardPlugin` to keep `InputPlugin` untouched.
+#[allow(clippy::too_many_arguments)]
+pub(super) fn handle_right_click(
+    buttons: Option<Res<ButtonInput<MouseButton>>>,
+    paused: Option<Res<PausedResource>>,
+    drag: Res<DragState>,
+    windows: Query<&Window, With<bevy::window::PrimaryWindow>>,
+    cameras: Query<(&Camera, &GlobalTransform)>,
+    layout: Option<Res<LayoutResource>>,
+    game: Res<GameStateResource>,
+    mut commands: Commands,
+    mut pile_markers: Query<(Entity, &PileMarker, &mut Sprite)>,
+    card_entities: Query<(Entity, &CardEntity, &Transform)>,
+    highlighted: Query<Entity, With<RightClickHighlight>>,
+) {
+    if paused.is_some_and(|p| p.0) {
+        return;
+    }
+
+    let Some(buttons) = buttons else { return };
+    let left_pressed = buttons.just_pressed(MouseButton::Left);
+    let right_pressed = buttons.just_pressed(MouseButton::Right);
+
+    // Clear existing highlights on any click.
+    if left_pressed || right_pressed {
+        for entity in &highlighted {
+            commands.entity(entity).remove::<RightClickHighlight>();
+        }
+        for (_entity, _, mut sprite) in &mut pile_markers {
+            if sprite.color == RIGHT_CLICK_HIGHLIGHT_COLOUR {
+                sprite.color = PILE_MARKER_DEFAULT_COLOUR;
+            }
+        }
+    }
+
+    // Only proceed for right-clicks while not dragging.
+    if !right_pressed || !drag.is_idle() {
+        return;
+    }
+
+    let Some(layout) = layout else { return };
+
+    // Convert cursor to world-space position.
+    let Some(world) = cursor_world_pos(&windows, &cameras) else {
+        return;
+    };
+
+    // Find the topmost face-up card under the cursor.
+    let Some(card) = find_top_card_at(world, &game.0, &layout.0, &card_entities) else {
+        return;
+    };
+
+    let Some(source_pile) = game.0.pile_containing_card(card.clone()) else {
+        return;
+    };
+
+    // Tint piles that legally accept the card.
+    for (entity, pile_marker, mut sprite) in &mut pile_markers {
+        let legal = game.0.can_move_cards(&source_pile, &pile_marker.0, 1);
+        if legal {
+            sprite.color = RIGHT_CLICK_HIGHLIGHT_COLOUR;
+            commands
+                .entity(entity)
+                .insert(RightClickHighlight)
+                .insert(RightClickHighlightTimer(1.5));
+        }
+    }
+}
+
+/// Converts cursor position to 2-D world coordinates.
+pub(super) fn cursor_world_pos(
+    windows: &Query<&Window, With<bevy::window::PrimaryWindow>>,
+    cameras: &Query<(&Camera, &GlobalTransform)>,
+) -> Option<Vec2> {
+    let window = windows.single().ok()?;
+    let cursor = window.cursor_position()?;
+    let (camera, camera_transform) = cameras.single().ok()?;
+    camera.viewport_to_world_2d(camera_transform, cursor).ok()
+}
+
+/// Returns the topmost face-up `Card` under `cursor` by checking axis-aligned
+/// bounding rectangles of all card sprites, picking the highest Z.
+pub(super) fn find_top_card_at(
+    cursor: Vec2,
+    game: &GameState,
+    layout: &Layout,
+    card_entities: &Query<(Entity, &CardEntity, &Transform)>,
+) -> Option<Card> {
+    let half = layout.card_size / 2.0;
+    let mut best: Option<(f32, Card)> = None;
+
+    for (_, card_entity, transform) in card_entities.iter() {
+        let pos = transform.translation.truncate();
+        if cursor.x < pos.x - half.x
+            || cursor.x > pos.x + half.x
+            || cursor.y < pos.y - half.y
+            || cursor.y > pos.y + half.y
+        {
+            continue;
+        }
+        let found = all_cards(game)
+            .into_iter()
+            .find(|(c, face_up)| *c == card_entity.card && *face_up);
+        if let Some((card, _)) = found {
+            let z = transform.translation.z;
+            if best.as_ref().is_none_or(|(bz, _)| z > *bz) {
+                best = Some((z, card));
+            }
+        }
+    }
+    best.map(|(_, card)| card)
+}
+
+// ---------------------------------------------------------------------------
+// Task #28 — Stock-empty visual indicator
+// ---------------------------------------------------------------------------
+
+

solitaire_engine/src/card_plugin/labels.rs

@@ -0,0 +1,208 @@
+//! Card face labels: desktop text labels and Android corner labels.
+
+use super::*;
+
+
+use bevy::color::Color;
+use bevy::sprite::Anchor;
+use solitaire_core::{Card, Rank, Suit};
+
+use crate::ui_theme::TEXT_PRIMARY_HC;
+
+pub(super) fn label_for(card: &Card) -> String {
+    let rank = match card.rank() {
+        Rank::Ace => "A",
+        Rank::Two => "2",
+        Rank::Three => "3",
+        Rank::Four => "4",
+        Rank::Five => "5",
+        Rank::Six => "6",
+        Rank::Seven => "7",
+        Rank::Eight => "8",
+        Rank::Nine => "9",
+        Rank::Ten => "10",
+        Rank::Jack => "J",
+        Rank::Queen => "Q",
+        Rank::King => "K",
+    };
+    let suit = match card.suit() {
+        Suit::Clubs => "C",
+        Suit::Diamonds => "D",
+        Suit::Hearts => "H",
+        Suit::Spades => "S",
+    };
+    format!("{rank}{suit}")
+}
+
+/// Suit colour for the rank/suit overlay rendered atop the constant
+/// fallback sprite (only fires under `MinimalPlugins` — production
+/// renders the suit glyph baked into the PNG). 2-colour traditional
+/// pairing — hearts + diamonds share the saturated red, clubs +
+/// spades share the near-white. Two accessibility flags compose:
+///
+/// - `color_blind`: red-suit cards swap to `RED_SUIT_COLOUR_CBM`
+///   (lime) — the "Settings toggle swaps red→lime" half of the
+///   design system's colour-blind support. CBM is a hue-replacement
+///   for red, so HC has no further effect on red when CBM is on
+///   (the lime is itself a high-luminance colour).
+/// - `high_contrast`: when CBM is off, red suits boost to
+///   `RED_SUIT_COLOUR_HC` (`#ff6868`); black suits boost from
+///   `#e8e8e8` (near-white) to `#f5f5f5` (`TEXT_PRIMARY_HC`).
+///
+/// The other half of CBM support (always-on filled-vs-outlined
+/// glyph differentiation for ♥♠ vs ♦♣) is baked into the PNG art
+/// and has no constant-fallback equivalent.
+pub(super) fn text_colour(card: &Card, color_blind: bool, high_contrast: bool) -> Color {
+    if card.suit().is_red() {
+        if color_blind {
+            // CBM lime wins — the colour-blind swap replaces the
+            // red hue entirely, and the lime is already high-
+            // luminance, so an HC boost on top has nothing to do.
+            RED_SUIT_COLOUR_CBM
+        } else if high_contrast {
+            RED_SUIT_COLOUR_HC
+        } else {
+            RED_SUIT_COLOUR
+        }
+    } else if high_contrast {
+        TEXT_PRIMARY_HC
+    } else {
+        BLACK_SUIT_COLOUR
+    }
+}
+
+pub(super) fn label_visibility(face_up: bool) -> Visibility {
+    if face_up {
+        Visibility::Inherited
+    } else {
+        Visibility::Hidden
+    }
+}
+
+/// Rank+suit string for the readability overlay on touch HUD layouts.
+/// Uses Unicode suit glyphs (♠♥♦♣ — U+2660–U+2666, covered by FiraMono).
+pub(super) fn mobile_label_for(card: &Card) -> String {
+    let rank = match card.rank() {
+        Rank::Ace => "A",
+        Rank::Two => "2",
+        Rank::Three => "3",
+        Rank::Four => "4",
+        Rank::Five => "5",
+        Rank::Six => "6",
+        Rank::Seven => "7",
+        Rank::Eight => "8",
+        Rank::Nine => "9",
+        Rank::Ten => "10",
+        Rank::Jack => "J",
+        Rank::Queen => "Q",
+        Rank::King => "K",
+    };
+    let suit = match card.suit() {
+        Suit::Clubs => "♣",
+        Suit::Diamonds => "♦",
+        Suit::Hearts => "♥",
+        Suit::Spades => "♠",
+    };
+    format!("{rank}{suit}")
+}
+
+/// 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).
+pub(super) fn add_android_corner_label(
+    parent: &mut ChildSpawnerCommands,
+    card: &Card,
+    face_up: bool,
+    card_size: Vec2,
+    color_blind: bool,
+    high_contrast: bool,
+    font_handle: Option<&Handle<Font>>,
+) {
+    if !face_up {
+        return;
+    }
+    let font_size = card_size.x * FONT_SIZE_FRAC_MOBILE;
+    let inset = 3.0_f32;
+    // Background covers ~3 monospace chars wide × 1 line tall.
+    // FiraMono char width ≈ 0.6 × font_size; 2.0× gives room for "10♠"
+    // (3 chars = 1.8× font_size) plus a small margin.
+    let bg_w = font_size * 2.0;
+    let bg_h = font_size * 1.25;
+
+    // Background covers the PNG's baked-in small corner text (top-left).
+    // Classic PNG cards have a white face, so the background must be white too.
+    // (CARD_FACE_COLOUR is the Terminal theme's dark face colour — wrong here.)
+    parent.spawn((
+        AndroidCornerBg,
+        Sprite {
+            color: Color::WHITE,
+            custom_size: Some(Vec2::new(bg_w, bg_h)),
+            ..default()
+        },
+        Transform::from_xyz(
+            -card_size.x / 2.0 + inset + bg_w / 2.0,
+            card_size.y / 2.0 - inset - bg_h / 2.0,
+            0.015,
+        ),
+    ));
+    // Cover the matching rotated baked-in text at the bottom-right corner.
+    parent.spawn((
+        AndroidCornerBg,
+        Sprite {
+            color: Color::WHITE,
+            custom_size: Some(Vec2::new(bg_w, bg_h)),
+            ..default()
+        },
+        Transform::from_xyz(
+            card_size.x / 2.0 - inset - bg_w / 2.0,
+            -card_size.y / 2.0 + inset + bg_h / 2.0,
+            0.015,
+        ),
+    ));
+
+    // 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.
+    //
+    // Classic PNG cards have a white face: red suits stay the same saturated
+    // red, but black suits must use a dark colour (CARD_FACE_COLOUR ≈ #1a1a1a)
+    // rather than the near-white BLACK_SUIT_COLOUR designed for the dark
+    // Terminal theme background.
+    let text_col = if card.suit().is_red() {
+        if color_blind {
+            RED_SUIT_COLOUR_CBM
+        } else if high_contrast {
+            RED_SUIT_COLOUR_HC
+        } else {
+            RED_SUIT_COLOUR
+        }
+    } else {
+        CARD_FACE_COLOUR
+    };
+    let label_text = mobile_label_for(card);
+    parent.spawn((
+        AndroidCornerLabel(label_text.clone()),
+        CardLabel,
+        Text2d::new(label_text),
+        TextFont {
+            font: font_handle.cloned().unwrap_or_default(),
+            font_size,
+            ..default()
+        },
+        TextColor(text_col),
+        Anchor::TOP_LEFT,
+        Transform::from_xyz(-card_size.x / 2.0 + inset, card_size.y / 2.0 - inset, 0.02),
+    ));
+}
+
+// ---------------------------------------------------------------------------
+// Task #34 — Card-flip animation systems
+// ---------------------------------------------------------------------------
+

solitaire_engine/src/card_plugin/layout.rs

@@ -0,0 +1,351 @@
+//! Resize handling: window-resize snapping, in-place card resizing,
+//! and tableau fan spread.
+
+use super::*;
+
+use std::collections::HashMap;
+
+use bevy::window::WindowResized;
+use solitaire_core::Card;
+use solitaire_core::game_state::GameState;
+
+use crate::animation_plugin::CardAnim;
+use crate::events::StateChangedEvent;
+use crate::font_plugin::FontResource;
+use crate::layout::{Layout, LayoutResource};
+use crate::resources::GameStateResource;
+use crate::table_plugin::PileMarker;
+use crate::ui_theme::{
+    CARD_SHADOW_ALPHA_DRAG, CARD_SHADOW_PADDING_DRAG,
+    CARD_SHADOW_PADDING_IDLE,
+};
+
+/// Coalesces every `WindowResized` event arriving this frame into the latest
+/// pending size on [`ResizeThrottle`].
+///
+/// `WindowResized` fires per pixel of resize drag, so a fast corner drag can
+/// emit many events per frame. Reading `.last()` keeps only the final size —
+/// every frame's snap target is the most recent window size, never a stale
+/// one. Pending stays set across frames until the throttled applier consumes
+/// it; that's how we still flush the final "release" position when the user
+/// stops dragging.
+pub(super) fn collect_resize_events(
+    mut events: MessageReader<WindowResized>,
+    mut throttle: ResMut<ResizeThrottle>,
+) {
+    if let Some(ev) = events.read().last() {
+        throttle.pending = Some(Vec2::new(ev.width, ev.height));
+    }
+}
+
+/// Snaps every card sprite to its target position, size, and (in the
+/// fallback Text2d label path) font size when the window is resized.
+///
+/// **In-place mutation only.** Resize is the hot path — events fire per
+/// pixel of drag, so this system cannot afford the despawn/respawn churn
+/// `update_card_entity` does. We mutate `Sprite.custom_size`, `Transform`,
+/// and child `TextFont.font_size` directly, leaving the card image handle,
+/// suit/rank, and `CardLabel` entity untouched. Cards keep their identity
+/// across resizes; only their size and position change. The full repaint
+/// path lives in [`update_card_entity`] and is still used by every non-resize
+/// caller (deals, moves, flips, settings toggles).
+///
+/// **Throttled to ~20 Hz.** [`ResizeThrottle::pending`] is consumed at most
+/// once per [`RESIZE_THROTTLE_SECS`]. When events stop arriving, the next
+/// tick past the throttle window flushes the final size and clears
+/// `pending`, so the steady-state always matches the user's release size.
+///
+/// **Cancels in-flight slides.** Any `CardAnim` is removed so a mid-slide
+/// tween is not retargeted relative to the previous card-size's position.
+///
+/// The "↺" stock-empty label's `font_size` is derived from
+/// `layout.card_size.x`, so this system also reapplies the stock indicator —
+/// otherwise the label would not rescale on resize.
+///
+/// Scheduled after [`collect_resize_events`] (which itself runs after
+/// `LayoutSystem::UpdateOnResize`) so `LayoutResource` reflects the latest
+/// window size before we read it.
+#[allow(clippy::too_many_arguments, clippy::type_complexity)]
+pub(super) fn snap_cards_on_window_resize(
+    mut commands: Commands,
+    time: Res<Time>,
+    mut throttle: ResMut<ResizeThrottle>,
+    game: Option<Res<GameStateResource>>,
+    layout: Option<Res<LayoutResource>>,
+    card_images: Option<Res<CardImageSet>>,
+    font_res: Option<Res<FontResource>>,
+    entities: Query<
+        (Entity, &CardEntity, &mut Sprite, &mut Transform),
+        (
+            Without<CardLabel>,
+            Without<CardShadow>,
+            Without<CardBackFrame>,
+        ),
+    >,
+    label_query: Query<&mut TextFont, (With<CardLabel>, Without<StockEmptyLabel>)>,
+    shadow_query: Query<
+        &mut Sprite,
+        (
+            With<CardShadow>,
+            Without<CardEntity>,
+            Without<PileMarker>,
+            Without<CardBackFrame>,
+        ),
+    >,
+    frame_query: Query<
+        &mut Sprite,
+        (
+            With<CardBackFrame>,
+            Without<CardEntity>,
+            Without<CardShadow>,
+            Without<PileMarker>,
+        ),
+    >,
+    mut pile_markers: Query<
+        (Entity, &PileMarker, &mut Sprite),
+        (
+            Without<CardEntity>,
+            Without<CardShadow>,
+            Without<CardBackFrame>,
+        ),
+    >,
+    label_children: Query<(Entity, &ChildOf), With<StockEmptyLabel>>,
+) {
+    if throttle.pending.is_none() {
+        return;
+    }
+    let now = time.elapsed_secs();
+    if !should_apply_resize(now, throttle.last_applied_secs) {
+        return;
+    }
+
+    let Some(game) = game else {
+        // Nothing to apply — clear pending so we don't busy-loop.
+        throttle.pending = None;
+        return;
+    };
+    let Some(layout) = layout else {
+        throttle.pending = None;
+        return;
+    };
+
+    resize_cards_in_place(
+        &mut commands,
+        &game.0,
+        &layout.0,
+        card_images.as_deref(),
+        entities,
+        label_query,
+        shadow_query,
+        frame_query,
+    );
+
+    let font = font_res.as_ref().map(|f| f.0.clone()).unwrap_or_default();
+    apply_stock_empty_indicator(
+        &mut commands,
+        &game.0,
+        &mut pile_markers,
+        &label_children,
+        &layout.0,
+        font,
+    );
+
+    throttle.last_applied_secs = now;
+    throttle.pending = None;
+}
+
+/// In-place "size-only" sibling of [`sync_cards`]: walks every existing card
+/// entity, updates `Sprite.custom_size` and the snap-`Transform` to match the
+/// fresh layout, and (in fallback solid-colour mode) also updates the child
+/// `TextFont.font_size` of any `CardLabel`. No despawning, no `Sprite`
+/// replacement, no children rebuild — that's the entire point of this path.
+///
+/// Called only from the resize handler. Game-state changes (deals, moves,
+/// flips, settings toggles) still flow through [`sync_cards`] /
+/// [`update_card_entity`], which handle add/remove/repaint correctly.
+///
+/// Any in-flight `CardAnim` slide is removed so a mid-tween card is not
+/// retargeted relative to the previous card-size's position.
+#[allow(clippy::type_complexity, clippy::too_many_arguments)]
+pub(super) fn resize_cards_in_place(
+    commands: &mut Commands,
+    game: &GameState,
+    layout: &Layout,
+    card_images: Option<&CardImageSet>,
+    mut entities: Query<
+        (Entity, &CardEntity, &mut Sprite, &mut Transform),
+        (
+            Without<CardLabel>,
+            Without<CardShadow>,
+            Without<CardBackFrame>,
+        ),
+    >,
+    mut label_query: Query<&mut TextFont, (With<CardLabel>, Without<StockEmptyLabel>)>,
+    mut shadow_query: Query<
+        &mut Sprite,
+        (
+            With<CardShadow>,
+            Without<CardEntity>,
+            Without<PileMarker>,
+            Without<CardBackFrame>,
+        ),
+    >,
+    mut frame_query: Query<
+        &mut Sprite,
+        (
+            With<CardBackFrame>,
+            Without<CardEntity>,
+            Without<CardShadow>,
+            Without<PileMarker>,
+        ),
+    >,
+) {
+    let positions = card_positions(game, layout);
+    let pos_by_id: HashMap<Card, (Vec2, f32)> = positions
+        .into_iter()
+        .map(|((c, _face_up), p, z)| (c, (p, z)))
+        .collect();
+
+    for (entity, marker, mut sprite, mut transform) in entities.iter_mut() {
+        let Some(&(pos, z)) = pos_by_id.get(&marker.card) else {
+            continue;
+        };
+        sprite.custom_size = Some(layout.card_size);
+        transform.translation.x = pos.x;
+        transform.translation.y = pos.y;
+        transform.translation.z = z;
+        // Cancel any in-flight slide so it doesn't retarget from a stale
+        // mid-animation position computed against the previous card size.
+        commands.entity(entity).remove::<CardAnim>();
+    }
+
+    // Resize every per-card shadow halo to match the new card size. Both
+    // idle and drag states scale with the card body, so we preserve the
+    // *current* padding (idle vs drag) by keeping the alpha as-is and only
+    // recomputing the geometry. The drag-tracking system runs every frame
+    // and will retune offset / alpha / padding-mode within one frame if the
+    // drag state diverges from the resized geometry.
+    let idle_padding = CARD_SHADOW_PADDING_IDLE;
+    let drag_padding = CARD_SHADOW_PADDING_DRAG;
+    for mut shadow_sprite in shadow_query.iter_mut() {
+        // Choose padding based on the shadow's current alpha — preserves
+        // a lifted shadow's larger halo across resize without needing to
+        // plumb DragState through the resize handler.
+        let alpha = shadow_sprite.color.alpha();
+        let padding = if alpha >= CARD_SHADOW_ALPHA_DRAG - 0.001 {
+            drag_padding
+        } else {
+            idle_padding
+        };
+        shadow_sprite.custom_size = Some(layout.card_size + padding);
+    }
+
+    // Only the solid-colour fallback path uses CardLabel/Text2d overlays;
+    // when PNG faces are loaded the rank/suit are baked into the image and
+    // there is nothing to resize on the label side.
+    if card_images.is_none() {
+        let new_font_size = layout.card_size.x * FONT_SIZE_FRAC;
+        for mut font in label_query.iter_mut() {
+            font.font_size = new_font_size;
+        }
+    }
+
+    // Resize every face-down border frame to match the new card size.
+    let frame_size = layout.card_size + Vec2::splat(CARD_BACK_FRAME_PADDING);
+    for mut frame_sprite in frame_query.iter_mut() {
+        frame_sprite.custom_size = Some(frame_size);
+    }
+}
+
+/// Updates font size and top-left anchor transform of every
+/// [`AndroidCornerLabel`] entity when `LayoutResource` changes (orientation
+/// change or any window resize). The full despawn/respawn path in
+/// `update_card_entity` already handles game-state changes; this system
+/// covers the resize-only path where children are mutated in place.
+pub(super) fn resize_android_corner_labels(
+    layout: Res<LayoutResource>,
+    card_images: Option<Res<CardImageSet>>,
+    mut text_query: Query<(
+        &AndroidCornerLabel,
+        &mut Text2d,
+        &mut TextFont,
+        &mut Transform,
+    )>,
+    mut bg_query: Query<(&mut Sprite, &mut Transform), AndroidCornerBgFilter>,
+) {
+    if !layout.is_changed() || card_images.is_none() {
+        return;
+    }
+    let font_size = layout.0.card_size.x * FONT_SIZE_FRAC_MOBILE;
+    let inset = 3.0_f32;
+    let bg_w = font_size * 2.0;
+    let bg_h = font_size * 1.25;
+    let text_x = -layout.0.card_size.x / 2.0 + inset;
+    let text_y = layout.0.card_size.y / 2.0 - inset;
+
+    for (label, mut text2d, mut font, mut transform) in text_query.iter_mut() {
+        text2d.0 = label.0.clone();
+        font.font_size = font_size;
+        transform.translation.x = text_x;
+        transform.translation.y = text_y;
+    }
+    for (mut sprite, mut transform) in bg_query.iter_mut() {
+        sprite.custom_size = Some(Vec2::new(bg_w, bg_h));
+        transform.translation.x = text_x + bg_w / 2.0;
+        transform.translation.y = text_y - bg_h / 2.0;
+    }
+}
+
+/// Adjusts `LayoutResource.tableau_fan_frac` (and the face-down companion) so
+/// the deepest tableau column fills the available vertical space at every stage
+/// of play. Runs after every `StateChangedEvent`.
+///
+/// Depth is measured across *all* cards in a column, weighting each face-down
+/// card by the fixed face-down/face-up step ratio. Counting the face-down
+/// portion — not just the face-up tail — is what fills the lower screen on a
+/// fresh deal (the deepest column is then six face-down cards under one face-up
+/// one): the earlier face-up-only depth was 1, so the fan never spread and the
+/// bottom half of a near-square viewport (e.g. an unfolded foldable) sat empty.
+///
+/// Deeper columns drive the fraction down so everything still fits the window;
+/// [`crate::layout::TABLEAU_FAN_FRAC`] floors it to the desktop feel and
+/// [`MAX_DYNAMIC_FAN_FRAC`] caps it so a near-empty column doesn't fling its few
+/// cards far apart.
+pub(super) fn update_tableau_fan_frac(
+    mut events: MessageReader<StateChangedEvent>,
+    game: Option<Res<GameStateResource>>,
+    mut layout: Option<ResMut<LayoutResource>>,
+) {
+    if events.read().next().is_none() {
+        return;
+    }
+    let Some(game) = game else {
+        return;
+    };
+    let Some(layout) = layout.as_mut() else {
+        return;
+    };
+    crate::layout::apply_dynamic_tableau_fan(&game.0, &mut layout.0);
+}
+
+/// PostStartup sibling of [`update_tableau_fan_frac`]. The initial deal is
+/// inserted directly as `GameStateResource` at startup without a
+/// `StateChangedEvent`, so the event-driven system never fires for it. This
+/// runs once, before [`sync_cards_startup`] renders, so the very first board
+/// (cold start) already fills the viewport — otherwise a fresh deal on a tall /
+/// near-square screen (e.g. an unfolded foldable) renders with the unspread fan
+/// and a large empty band below the tableau until the first move.
+pub(super) fn fill_tableau_fan_on_startup(
+    game: Option<Res<GameStateResource>>,
+    mut layout: Option<ResMut<LayoutResource>>,
+) {
+    let Some(game) = game else {
+        return;
+    };
+    let Some(layout) = layout.as_mut() else {
+        return;
+    };
+    crate::layout::apply_dynamic_tableau_fan(&game.0, &mut layout.0);
+}
+
+

solitaire_engine/src/card_plugin/stock.rs

@@ -0,0 +1,291 @@
+//! Stock-pile indicators: the empty-stock recycle hint and count badge.
+
+use super::*;
+
+
+use bevy::color::Color;
+use solitaire_core::KlondikePile;
+use solitaire_core::game_state::GameState;
+
+use crate::events::StateChangedEvent;
+use crate::font_plugin::FontResource;
+use crate::layout::{Layout, LayoutResource};
+use crate::resources::GameStateResource;
+use crate::table_plugin::{PILE_MARKER_DEFAULT_COLOUR, PileMarker};
+use crate::ui_theme::{
+    STOCK_BADGE_BG, STOCK_BADGE_FG, TEXT_PRIMARY,
+    TYPE_BODY, Z_STOCK_BADGE,
+};
+
+/// Sprite colour applied to the stock `PileMarker` when the stock pile is empty,
+/// to signal to the player that there are no more cards to draw. Pure white
+/// at 0.4 alpha — a deliberate brightness-boost over the default marker so
+/// the "empty" state is more visible, not less. Not derived from a palette
+/// token: this is a sprite tint, not chrome colour.
+const STOCK_EMPTY_DIM_COLOUR: Color = Color::srgba(1.0, 1.0, 1.0, 0.4);
+
+/// Sprite colour applied to the stock `PileMarker` when cards remain in
+/// stock. Aliased to [`PILE_MARKER_DEFAULT_COLOUR`] so it tracks the rest
+/// of the engine's idle pile-marker tint automatically.
+const STOCK_NORMAL_COLOUR: Color = PILE_MARKER_DEFAULT_COLOUR;
+
+/// Shared logic for updating the stock pile marker's dim state and "↺" label.
+///
+/// If the stock pile is empty the marker sprite is dimmed to
+/// `STOCK_EMPTY_DIM_COLOUR` and a child `Text2d` with `StockEmptyLabel` is
+/// spawned (if not already present). When the stock is non-empty the marker is
+/// restored to `STOCK_NORMAL_COLOUR` and any `StockEmptyLabel` children are
+/// despawned.
+pub(super) fn apply_stock_empty_indicator<F: bevy::ecs::query::QueryFilter>(
+    commands: &mut Commands,
+    game: &GameState,
+    pile_markers: &mut Query<(Entity, &PileMarker, &mut Sprite), F>,
+    label_children: &Query<(Entity, &ChildOf), With<StockEmptyLabel>>,
+    layout: &Layout,
+    font: Handle<Font>,
+) {
+    let stock_empty = game.stock_cards().is_empty();
+
+    for (entity, pile_marker, mut sprite) in pile_markers.iter_mut() {
+        if pile_marker.0 != KlondikePile::Stock {
+            continue;
+        }
+
+        if stock_empty {
+            // Dim the marker sprite.
+            sprite.color = STOCK_EMPTY_DIM_COLOUR;
+
+            // Spawn the "↺" label only if one does not already exist.
+            let already_has_label = label_children
+                .iter()
+                .any(|(_, parent)| parent.parent() == entity);
+            if !already_has_label {
+                let font_size = layout.card_size.x * 0.4;
+                commands.entity(entity).with_children(|b| {
+                    b.spawn((
+                        StockEmptyLabel,
+                        Text2d::new("↺"),
+                        TextFont {
+                            font: font.clone(),
+                            font_size,
+                            ..default()
+                        },
+                        TextColor(TEXT_PRIMARY.with_alpha(0.7)),
+                        Transform::from_xyz(0.0, 0.0, 0.1),
+                    ));
+                });
+            }
+        } else {
+            // Restore normal brightness.
+            sprite.color = STOCK_NORMAL_COLOUR;
+
+            // Despawn any existing "↺" label children.
+            for (label_entity, parent) in label_children.iter() {
+                if parent.parent() == entity {
+                    commands.entity(label_entity).despawn();
+                }
+            }
+        }
+    }
+}
+
+/// Runs at `PostStartup` to apply the stock-empty indicator for the initial
+/// game state (before any `StateChangedEvent` fires).
+pub(super) fn update_stock_empty_indicator_startup(
+    mut commands: Commands,
+    game: Res<GameStateResource>,
+    layout: Option<Res<LayoutResource>>,
+    font_res: Option<Res<FontResource>>,
+    mut pile_markers: Query<(Entity, &PileMarker, &mut Sprite)>,
+    label_children: Query<(Entity, &ChildOf), With<StockEmptyLabel>>,
+) {
+    let Some(layout) = layout else { return };
+    let font = font_res.as_ref().map(|f| f.0.clone()).unwrap_or_default();
+    apply_stock_empty_indicator(
+        &mut commands,
+        &game.0,
+        &mut pile_markers,
+        &label_children,
+        &layout.0,
+        font,
+    );
+}
+
+/// Runs each `Update` tick when a `StateChangedEvent` arrives, keeping the
+/// stock pile marker dim state and "↺" label in sync with the current stock.
+pub(super) fn update_stock_empty_indicator(
+    mut events: MessageReader<StateChangedEvent>,
+    mut commands: Commands,
+    game: Res<GameStateResource>,
+    layout: Option<Res<LayoutResource>>,
+    font_res: Option<Res<FontResource>>,
+    mut pile_markers: Query<(Entity, &PileMarker, &mut Sprite)>,
+    label_children: Query<(Entity, &ChildOf), With<StockEmptyLabel>>,
+) {
+    if events.read().next().is_none() {
+        return;
+    }
+    let Some(layout) = layout else { return };
+    let font = font_res.as_ref().map(|f| f.0.clone()).unwrap_or_default();
+    apply_stock_empty_indicator(
+        &mut commands,
+        &game.0,
+        &mut pile_markers,
+        &label_children,
+        &layout.0,
+        font,
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Stock-pile remaining-count badge
+//
+// Shows a small "N" chip pinned to the bottom-right corner of the stock pile so
+// the player can see how many cards remain before the next recycle. The
+// existing `StockEmptyLabel` (`↺` overlay) covers the empty-stock case, so
+// the badge hides itself when the stock has zero cards — the two indicators
+// never render at the same time.
+// ---------------------------------------------------------------------------
+
+/// Inset (in pixels) from the bottom-right corner of the stock pile sprite to
+/// the centre of the count badge. Anchoring to the bottom-right keeps the chip
+/// clear of the rank/suit pip in the card's top-left corner. Both components
+/// move the centre *inward* from that corner: `x` is subtracted from the right
+/// edge, `y` is added to the bottom edge. The `x` magnitude must satisfy
+/// `x >= STOCK_BADGE_SIZE.x / 2` so the badge right edge stays inside the stock
+/// pile and never overlaps the adjacent waste pile — critical on Android where
+/// `H_GAP_DIVISOR = 32` gives an inter-pile gap of only ~4 px.
+const STOCK_BADGE_INSET: Vec2 = Vec2::new(20.0, 8.0);
+
+/// Width / height of the badge background sprite, in world pixels. Sized so
+/// a 2-digit count (max "24") fits comfortably with `TYPE_BODY` (14 pt) text.
+const STOCK_BADGE_SIZE: Vec2 = Vec2::new(34.0, 20.0);
+
+/// Returns the count of cards currently in the stock pile.
+///
+/// Pure helper extracted so the count source is identical between the spawn
+/// system, the update system, and the unit tests.
+pub(super) fn stock_card_count(game: &GameState) -> usize {
+    game.stock_cards().len()
+}
+
+/// Returns the world-space `Vec3` for the centre of the stock-count badge,
+/// given the current `Layout`. The badge sits at the bottom-right corner of
+/// the stock pile sprite, inset by [`STOCK_BADGE_INSET`], so it stays clear of
+/// the rank/suit pip in the card's top-left corner.
+pub(super) fn stock_badge_translation(layout: &Layout) -> Vec3 {
+    // Empty layouts don't contain a Stock entry — fall back to origin so
+    // the badge stays in a deterministic spot until the layout is filled.
+    let pile_pos = layout
+        .pile_positions
+        .get(&KlondikePile::Stock)
+        .copied()
+        .unwrap_or(Vec2::ZERO);
+    let half = layout.card_size * 0.5;
+    // Anchor to the bottom-right corner, then move the centre inward.
+    let x = pile_pos.x + half.x - STOCK_BADGE_INSET.x;
+    let y = pile_pos.y - half.y + STOCK_BADGE_INSET.y;
+    Vec3::new(x, y, Z_STOCK_BADGE)
+}
+
+/// Spawns the stock-count badge entity (background sprite + child text)
+/// into the world. Called once, when the badge does not yet exist.
+pub(super) fn spawn_stock_count_badge(
+    commands: &mut Commands,
+    layout: &Layout,
+    font: Option<&Handle<Font>>,
+    count: usize,
+) {
+    let translation = stock_badge_translation(layout);
+    let visibility = if count == 0 {
+        Visibility::Hidden
+    } else {
+        Visibility::Inherited
+    };
+    let text_font = TextFont {
+        font: font.cloned().unwrap_or_default(),
+        font_size: TYPE_BODY,
+        ..default()
+    };
+
+    commands
+        .spawn((
+            StockCountBadge,
+            Sprite {
+                color: STOCK_BADGE_BG,
+                custom_size: Some(STOCK_BADGE_SIZE),
+                ..default()
+            },
+            Transform::from_translation(translation),
+            visibility,
+        ))
+        .with_children(|b| {
+            b.spawn((
+                StockCountBadgeText,
+                Text2d::new(format!("{count}")),
+                text_font,
+                TextColor(STOCK_BADGE_FG),
+                // Slightly above the chip background so the digits aren't
+                // occluded by the sprite they sit on.
+                Transform::from_xyz(0.0, 0.0, 0.1),
+            ));
+        });
+}
+
+/// Spawns the stock-pile remaining-count badge if it does not yet exist,
+/// and otherwise updates its text and visibility in place.
+///
+/// Visibility rule: hidden when the stock is empty (the existing `↺`
+/// `StockEmptyLabel` overlay covers that state), shown when one or more
+/// cards remain.
+///
+/// Position is recomputed from `LayoutResource` every tick so the badge
+/// follows the stock pile across `WindowResized` layout updates without
+/// needing a dedicated resize handler.
+#[allow(clippy::too_many_arguments)]
+pub(super) fn update_stock_count_badge(
+    mut commands: Commands,
+    game: Option<Res<GameStateResource>>,
+    layout: Option<Res<LayoutResource>>,
+    font: Option<Res<FontResource>>,
+    mut badges: Query<(Entity, &mut Transform, &mut Visibility), With<StockCountBadge>>,
+    children: Query<&Children, With<StockCountBadge>>,
+    mut texts: Query<&mut Text2d, With<StockCountBadgeText>>,
+) {
+    let Some(game) = game else { return };
+    let Some(layout) = layout else { return };
+
+    let count = stock_card_count(&game.0);
+    let translation = stock_badge_translation(&layout.0);
+    let target_visibility = if count == 0 {
+        Visibility::Hidden
+    } else {
+        Visibility::Inherited
+    };
+
+    if badges.is_empty() {
+        spawn_stock_count_badge(&mut commands, &layout.0, font.as_ref().map(|f| &f.0), count);
+        return;
+    }
+
+    for (entity, mut transform, mut visibility) in badges.iter_mut() {
+        transform.translation = translation;
+        if *visibility != target_visibility {
+            *visibility = target_visibility;
+        }
+        // Update the child text to reflect the latest count. The text node
+        // is created at spawn time, so under normal operation we always
+        // have exactly one child here.
+        if let Ok(badge_children) = children.get(entity) {
+            for child in badge_children.iter() {
+                if let Ok(mut text) = texts.get_mut(child) {
+                    let new = format!("{count}");
+                    if text.0 != new {
+                        text.0 = new;
+                    }
+                }
+            }
+        }
+    }
+}
+

solitaire_engine/src/card_plugin/sync.rs

@@ -0,0 +1,748 @@
+//! Card asset loading and entity lifecycle: the sync systems that
+//! spawn, update, and position card entities from `GameStateResource`.
+
+use super::*;
+
+use std::collections::{HashMap, HashSet};
+
+use bevy::color::Color;
+use solitaire_core::{Foundation, KlondikePile, Tableau};
+use solitaire_core::{Card, Rank, Suit};
+use solitaire_core::{DrawStockConfig, game_state::GameState};
+
+use crate::animation_plugin::{CARD_ANIM_Z_LIFT, CardAnim, EffectiveSlideDuration};
+use crate::card_animation::CardAnimation;
+use crate::events::StateChangedEvent;
+use crate::font_plugin::FontResource;
+use crate::layout::{Layout, LayoutResource};
+use crate::platform::USE_TOUCH_UI_LAYOUT;
+use crate::resources::GameStateResource;
+use crate::settings_plugin::{SettingsChangedEvent, SettingsResource};
+
+/// Rebuild the [`CardEntityIndex`] from the live `CardEntity` set.
+///
+/// Runs in `PostUpdate` so that all spawn/despawn `Commands` issued by
+/// [`sync_cards_on_change`] and [`snap_cards_on_window_resize`] in `Update`
+/// have been flushed at the `Update -> PostUpdate` apply-deferred boundary.
+/// Rebuilding from scratch (rather than incrementally patching at every
+/// spawn/despawn site — waste cards churn on every draw) keeps a single writer
+/// and makes a stale entry structurally impossible.
+///
+/// Gated to changed frames only: `Changed<CardEntity>` fires the frame a card
+/// is spawned, `RemovedComponents<CardEntity>` the frame one is despawned. The
+/// `card` field is write-once (never mutated in place), so card-reposition
+/// frames don't trip `Changed` and correctly skip the O(52) rebuild.
+pub(super) fn rebuild_card_entity_index(
+    mut index: ResMut<CardEntityIndex>,
+    cards: Query<(Entity, &CardEntity)>,
+    changed: Query<(), Changed<CardEntity>>,
+    removed: RemovedComponents<CardEntity>,
+) {
+    if changed.is_empty() && removed.is_empty() {
+        return;
+    }
+    let map = &mut index.0;
+    map.clear();
+    for (entity, ce) in &cards {
+        map.insert(ce.card.clone(), entity);
+    }
+}
+
+/// 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.
+pub(super) 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`].
+///
+/// Faces: `assets/cards/faces/{RANK}{SUIT}.png`  (e.g. `AC.png`, `10H.png`)
+/// Backs: `assets/cards/backs/back_{0..4}.png`
+///
+/// Under `MinimalPlugins` (tests) `AssetServer` is absent, so the system
+/// returns without inserting `CardImageSet` and the plugin falls back to
+/// solid-colour sprites.
+pub(super) fn load_card_images(asset_server: Option<Res<AssetServer>>, mut commands: Commands) {
+    let Some(asset_server) = asset_server else {
+        return;
+    };
+
+    const SUITS: [Suit; 4] = [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades];
+    const RANKS: [Rank; 13] = [
+        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 faces: [[Handle<Image>; 13]; 4] = std::array::from_fn(|si| {
+        std::array::from_fn(|ri| asset_server.load(card_face_asset_path(RANKS[ri], SUITS[si])))
+    });
+    let backs =
+        std::array::from_fn(|i| asset_server.load(format!("cards/backs/classic/back_{i}.png")));
+    commands.insert_resource(CardImageSet {
+        faces,
+        backs,
+        // Populated by the theme plugin once a `CardTheme` finishes loading.
+        // Until then the legacy back fallback (`backs[selected_card_back]`)
+        // is used.
+        theme_back: None,
+    });
+}
+
+/// Builds the [`Sprite`] for a card, using PNG artwork when [`CardImageSet`] is
+/// available and falling back to a solid-colour sprite in tests.
+pub(super) fn card_sprite(
+    card: &Card,
+    face_up: bool,
+    card_size: Vec2,
+    back_colour: Color,
+    card_images: Option<&CardImageSet>,
+    selected_back: usize,
+) -> Sprite {
+    if let Some(set) = card_images {
+        let image = if face_up {
+            let suit_idx = match card.suit() {
+                Suit::Clubs => 0,
+                Suit::Diamonds => 1,
+                Suit::Hearts => 2,
+                Suit::Spades => 3,
+            };
+            let rank_idx = match card.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,
+            };
+            set.faces[suit_idx][rank_idx].clone()
+        } else if let Some(theme_back) = &set.theme_back {
+            // Active theme provides its own back — always wins over the
+            // legacy `selected_card_back` picker, so a theme switch swaps
+            // faces *and* the back. The picker is treated as informational
+            // only while a theme back is active (see settings_plugin).
+            theme_back.clone()
+        } else {
+            let idx = selected_back.min(set.backs.len() - 1);
+            set.backs[idx].clone()
+        };
+        Sprite {
+            image,
+            color: Color::WHITE,
+            custom_size: Some(card_size),
+            ..default()
+        }
+    } else {
+        // Terminal aesthetic: face background is uniformly CARD_FACE_COLOUR
+        // regardless of colour-blind mode (CBM differentiation now lives in
+        // the suit glyph colour, applied by `text_colour`, not the face
+        // background). Pre-Terminal this branch dispatched through a
+        // separate `face_colour(card, color_blind)` helper.
+        let body_colour = if face_up {
+            CARD_FACE_COLOUR
+        } else {
+            back_colour
+        };
+        Sprite {
+            color: body_colour,
+            custom_size: Some(card_size),
+            ..default()
+        }
+    }
+}
+
+/// When card-back selection changes in Settings, re-render all cards so the
+/// new back colour is applied immediately (without waiting for a state change).
+pub(super) fn resync_cards_on_settings_change(
+    mut setting_events: MessageReader<SettingsChangedEvent>,
+    mut state_events: MessageWriter<StateChangedEvent>,
+) {
+    if setting_events.read().next().is_some() {
+        state_events.write(StateChangedEvent);
+    }
+}
+
+/// 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)]
+pub(super) fn sync_cards_startup(
+    commands: Commands,
+    game: Res<GameStateResource>,
+    layout: Option<Res<LayoutResource>>,
+    slide_dur: Option<Res<EffectiveSlideDuration>>,
+    settings: Option<Res<SettingsResource>>,
+    entities: Query<CardSyncData>,
+    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);
+        let selected_back = settings.as_ref().map_or(0, |s| s.0.selected_card_back);
+        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);
+        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,
+        );
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn sync_cards_on_change(
+    mut events: MessageReader<StateChangedEvent>,
+    commands: Commands,
+    game: Res<GameStateResource>,
+    layout: Option<Res<LayoutResource>>,
+    slide_dur: Option<Res<EffectiveSlideDuration>>,
+    settings: Option<Res<SettingsResource>>,
+    entities: Query<CardSyncData>,
+    card_images: Option<Res<CardImageSet>>,
+    font_res: Option<Res<FontResource>>,
+) {
+    if events.read().next().is_none() {
+        return;
+    }
+    if let Some(layout) = layout {
+        let slide_secs = slide_dur.map_or(0.15, |d| d.slide_secs);
+        let selected_back = settings.as_ref().map_or(0, |s| s.0.selected_card_back);
+        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);
+        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,
+        );
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn sync_cards(
+    mut commands: Commands,
+    game: &GameState,
+    layout: &Layout,
+    slide_secs: f32,
+    back_colour: Color,
+    color_blind: bool,
+    high_contrast: bool,
+    entities: &Query<CardSyncData>,
+    card_images: Option<&CardImageSet>,
+    selected_back: usize,
+    font_handle: Option<&Handle<Font>>,
+) {
+    let positions = card_positions(game, layout);
+
+    // The waste buffer card exists only to keep its entity alive while the new
+    // top card's slide animation plays — it must never be visible to the player.
+    // Without this, the buffer sits at waste_base uncovered during the animation
+    // and its rank/suit peek behind the incoming card.
+    let waste_buffer_id: Option<Card> = {
+        let visible = match game.draw_mode() {
+            DrawStockConfig::DrawOne => 1_usize,
+            DrawStockConfig::DrawThree => 3_usize,
+        };
+        let waste_cards = game.waste_cards();
+        (waste_cards.len() > visible)
+            .then_some(waste_cards)
+            .and_then(|w| w.get(w.len().saturating_sub(visible + 1)).cloned())
+            .map(|(c, _face_up)| c)
+    };
+
+    // Map Card -> (Entity, current_translation, anim_end) for in-place
+    // updates.  `anim_end` is `Some(end_xy)` when a curve-based `CardAnimation`
+    // is currently driving the card (e.g. a drag-rejection return tween).
+    //
+    // In the position loop below we compare `anim_end` against the new game-
+    // state target position to decide whether to honour or cancel the tween:
+    //   • end ≈ target  → animation is still heading to the right place; let
+    //                      it finish (skip the snap/slide path).
+    //   • end ≠ target  → the game state has changed (e.g. a new game started
+    //                      while the win-cascade was mid-flight); cancel the
+    //                      stale `CardAnimation` and apply the new position.
+    let mut existing: HashMap<Card, (Entity, Vec3, Option<Vec2>, Option<CardChildrenKey>)> =
+        HashMap::new();
+    for (entity, marker, transform, anim, children_key) in entities.iter() {
+        existing.insert(
+            marker.card.clone(),
+            (
+                entity,
+                transform.translation,
+                anim.map(|a| a.end),
+                children_key.copied(),
+            ),
+        );
+    }
+
+    let live_ids: HashSet<Card> = positions.iter().map(|(c, _, _)| c.0.clone()).collect();
+
+    // Despawn any entity whose card is no longer tracked.
+    for (card, (entity, _, _, _)) in &existing {
+        if !live_ids.contains(card) {
+            commands.entity(*entity).despawn();
+        }
+    }
+
+    // For each card in the current state: spawn or update its entity, then
+    // apply visibility. The waste buffer card is hidden so it cannot peek
+    // behind the incoming top card during the draw slide animation.
+    for ((card, face_up), position, z) in positions {
+        let entity = match existing.get(&card) {
+            Some(&(entity, cur, anim_end, children_key)) => {
+                // If a CardAnimation is in flight, check whether its destination
+                // still matches the game-state target.  If the game moved the card
+                // elsewhere (e.g. new game started during a win-cascade scatter),
+                // cancel the stale tween so the card snaps/slides to its new home.
+                let has_anim = match anim_end {
+                    Some(end_xy) if (end_xy - position).length() > 2.0 => {
+                        commands.entity(entity).remove::<CardAnimation>();
+                        false
+                    }
+                    Some(_) => true,
+                    None => false,
+                };
+                update_card_entity(
+                    &mut commands,
+                    entity,
+                    &card,
+                    face_up,
+                    position,
+                    z,
+                    layout,
+                    slide_secs,
+                    back_colour,
+                    color_blind,
+                    high_contrast,
+                    cur,
+                    has_anim,
+                    children_key,
+                    card_images,
+                    selected_back,
+                    font_handle,
+                );
+                entity
+            }
+            None => spawn_card_entity(
+                &mut commands,
+                &card,
+                face_up,
+                position,
+                z,
+                layout,
+                back_colour,
+                color_blind,
+                high_contrast,
+                card_images,
+                selected_back,
+                font_handle,
+            ),
+        };
+        let visibility = if waste_buffer_id.as_ref() == Some(&card) {
+            Visibility::Hidden
+        } else {
+            Visibility::Inherited
+        };
+        commands.entity(entity).insert(visibility);
+    }
+}
+
+/// Returns an ordered vec of ((card, face_up), position, z) for every card in the game.
+pub(super) fn card_positions(game: &GameState, layout: &Layout) -> Vec<((Card, bool), Vec2, f32)> {
+    let mut out: Vec<((Card, bool), Vec2, f32)> = Vec::with_capacity(52);
+    let piles = [
+        (KlondikePile::Stock, true),
+        (KlondikePile::Stock, false),
+        (KlondikePile::Foundation(Foundation::Foundation1), false),
+        (KlondikePile::Foundation(Foundation::Foundation2), false),
+        (KlondikePile::Foundation(Foundation::Foundation3), false),
+        (KlondikePile::Foundation(Foundation::Foundation4), false),
+        (KlondikePile::Tableau(Tableau::Tableau1), false),
+        (KlondikePile::Tableau(Tableau::Tableau2), false),
+        (KlondikePile::Tableau(Tableau::Tableau3), false),
+        (KlondikePile::Tableau(Tableau::Tableau4), false),
+        (KlondikePile::Tableau(Tableau::Tableau5), false),
+        (KlondikePile::Tableau(Tableau::Tableau6), false),
+        (KlondikePile::Tableau(Tableau::Tableau7), false),
+    ];
+
+    // Draw-Three waste fan step, proportional to the column spacing so it scales
+    // with the platform's H_GAP_DIVISOR. Shared with input_plugin's hit-test via
+    // `waste_fan_step` so the two never drift (a drift puts the top fanned card's
+    // click target on the card beneath it).
+    let waste_fan_step = waste_fan_step(layout);
+
+    for (pile_type, is_stock_area) in piles {
+        let Some(mut base) = layout.pile_positions.get(&pile_type).copied() else {
+            continue;
+        };
+        if matches!(pile_type, KlondikePile::Stock) && is_stock_area {
+            base.x -= tableau_col_step(layout);
+        }
+        let is_tableau = matches!(pile_type, KlondikePile::Tableau(_));
+        let is_waste = matches!(pile_type, KlondikePile::Stock) && !is_stock_area;
+        let cards = if matches!(pile_type, KlondikePile::Stock) {
+            if is_stock_area {
+                game.stock_cards()
+            } else {
+                game.waste_cards()
+            }
+        } else {
+            game.pile(pile_type)
+        };
+
+        // Tableau uses a two-speed fan: face-down cards are packed tighter
+        // than face-up cards so the visible (playable) portion stands out.
+        // Non-tableau piles stack with a negligible offset.
+        //
+        // Waste pile: only the top N cards are rendered to prevent bleed-through
+        // while new cards animate in from the stock. Draw-One shows 1; Draw-Three
+        // shows up to 3 fanned in X (matching the standard Klondike presentation).
+        let render_start = if is_waste {
+            let visible = match game.draw_mode() {
+                DrawStockConfig::DrawOne => 1_usize,
+                DrawStockConfig::DrawThree => 3_usize,
+            };
+            // Render one extra card so that the card sliding off the waste
+            // during a draw animation is still present in the world at z=0
+            // (hidden under the stack) rather than vanishing mid-tween.
+            cards.len().saturating_sub(visible + 1)
+        } else {
+            0
+        };
+
+        let mut y_offset = 0.0_f32;
+        let rendered_len = cards[render_start..].len();
+        for (slot, (card, face_up)) in cards[render_start..].iter().enumerate() {
+            let x_offset = if is_waste && matches!(game.draw_mode(), DrawStockConfig::DrawThree) {
+                // When len > visible, slot 0 is a hidden buffer card kept at
+                // x=0 to prevent a flash during the draw tween. When len ≤
+                // visible (small pile), every card is visible and should fan
+                // 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 * waste_fan_step
+            } else {
+                0.0
+            };
+            let pos = Vec2::new(base.x + x_offset, base.y + y_offset);
+            let z = 1.0 + (slot as f32) * STACK_FAN_FRAC;
+            out.push(((card.clone(), *face_up), pos, z));
+            if is_tableau {
+                let step = if *face_up {
+                    layout.tableau_fan_frac
+                } else {
+                    layout.tableau_facedown_fan_frac
+                };
+                y_offset -= layout.card_size.y * step;
+            }
+        }
+    }
+    out
+}
+
+pub(super) fn all_cards(game: &GameState) -> Vec<(Card, bool)> {
+    let mut cards: Vec<(Card, bool)> = Vec::with_capacity(52);
+    cards.extend(game.stock_cards());
+    cards.extend(game.waste_cards());
+    for foundation in [
+        Foundation::Foundation1,
+        Foundation::Foundation2,
+        Foundation::Foundation3,
+        Foundation::Foundation4,
+    ] {
+        cards.extend(game.pile(KlondikePile::Foundation(foundation)));
+    }
+    for tableau in [
+        Tableau::Tableau1,
+        Tableau::Tableau2,
+        Tableau::Tableau3,
+        Tableau::Tableau4,
+        Tableau::Tableau5,
+        Tableau::Tableau6,
+        Tableau::Tableau7,
+    ] {
+        cards.extend(game.pile(KlondikePile::Tableau(tableau)));
+    }
+    cards
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn spawn_card_entity(
+    commands: &mut Commands,
+    card: &Card,
+    face_up: bool,
+    pos: Vec2,
+    z: f32,
+    layout: &Layout,
+    back_colour: Color,
+    color_blind: bool,
+    high_contrast: bool,
+    card_images: Option<&CardImageSet>,
+    selected_back: usize,
+    font_handle: Option<&Handle<Font>>,
+) -> Entity {
+    let sprite = card_sprite(
+        card,
+        face_up,
+        layout.card_size,
+        back_colour,
+        card_images,
+        selected_back,
+    );
+
+    let mut entity = commands.spawn((
+        CardEntity { card: card.clone() },
+        sprite,
+        Transform::from_xyz(pos.x, pos.y, z),
+        Visibility::default(),
+    ));
+    let entity_id = entity.id();
+    // Every card gets a subtle drop-shadow child so the play surface reads
+    // as physical instead of flat. Spawned in idle state; the drag-tracking
+    // system retunes its offset / alpha when this card joins the dragged
+    // stack.
+    entity.with_children(|b| {
+        add_card_shadow_child(b, layout.card_size);
+    });
+    // Every card gets a thin border frame so it reads as a distinct
+    // rectangle against the dark felt, regardless of face state.
+    entity.with_children(|b| {
+        add_card_back_frame_child(b, layout.card_size);
+    });
+    // When PNG faces are loaded the rank/suit are baked into the image.
+    // Only spawn the Text2d overlay in the solid-colour fallback (tests).
+    // On Android we additionally spawn a large-print corner label even in
+    // image mode so the rank/suit are legible at phone scale.
+    if card_images.is_none() {
+        entity.with_children(|b| {
+            b.spawn((
+                CardLabel,
+                Text2d::new(label_for(card)),
+                TextFont {
+                    font_size: layout.card_size.x * FONT_SIZE_FRAC,
+                    ..default()
+                },
+                TextColor(text_colour(card, color_blind, high_contrast)),
+                Transform::from_xyz(0.0, 0.0, 0.01),
+                label_visibility(face_up),
+            ));
+        });
+    }
+    if USE_TOUCH_UI_LAYOUT && card_images.is_some() {
+        entity.with_children(|b| {
+            add_android_corner_label(
+                b,
+                card,
+                face_up,
+                layout.card_size,
+                color_blind,
+                high_contrast,
+                font_handle,
+            );
+        });
+    }
+    // Record the appearance signature so subsequent `update_card_entity` calls
+    // can skip rebuilding these children until one of the inputs changes.
+    entity.insert(CardChildrenKey {
+        face_up,
+        card_size: layout.card_size,
+        color_blind,
+        high_contrast,
+    });
+    entity_id
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn update_card_entity(
+    commands: &mut Commands,
+    entity: Entity,
+    card: &Card,
+    face_up: bool,
+    pos: Vec2,
+    z: f32,
+    layout: &Layout,
+    slide_secs: f32,
+    back_colour: Color,
+    color_blind: bool,
+    high_contrast: bool,
+    cur: Vec3,
+    has_card_animation: bool,
+    existing_children_key: Option<CardChildrenKey>,
+    card_images: Option<&CardImageSet>,
+    selected_back: usize,
+    font_handle: Option<&Handle<Font>>,
+) {
+    let target = Vec3::new(pos.x, pos.y, z);
+
+    // Always refresh the visual appearance.
+    commands.entity(entity).insert(card_sprite(
+        card,
+        face_up,
+        layout.card_size,
+        back_colour,
+        card_images,
+        selected_back,
+    ));
+
+    // Skip the snap/slide path entirely when a curve-based `CardAnimation`
+    // is driving this card (e.g. the drag-rejection return tween). Writing
+    // `Transform` here would race that animation each frame and cause a
+    // visible jump. The animation system snaps the final position itself
+    // when it completes.
+    if !has_card_animation {
+        // Slide to the new position when it differs meaningfully; snap otherwise.
+        if (cur.truncate() - target.truncate()).length() > 1.0 && slide_secs > 0.0 {
+            // Lift the card immediately on the first frame of the animation so
+            // it never appears behind a card that is already resting at the
+            // destination slot. `advance_card_anims` will maintain this lift
+            // throughout the tween and snap to `target` (without lift) on
+            // completion.
+            let start = Vec3::new(cur.x, cur.y, z + CARD_ANIM_Z_LIFT);
+            commands
+                .entity(entity)
+                .insert(Transform::from_translation(start))
+                .insert(CardAnim {
+                    start,
+                    target,
+                    elapsed: 0.0,
+                    duration: slide_secs,
+                    delay: 0.0,
+                });
+        } else {
+            commands
+                .entity(entity)
+                .remove::<CardAnim>()
+                .insert(Transform::from_xyz(pos.x, pos.y, z));
+        }
+    }
+
+    // Rebuild the card's child visuals (drop-shadow, border frame, and the
+    // rank/suit label / large-print corner overlay) only when an input that
+    // affects them actually changed. The child set depends solely on
+    // `CardChildrenKey`; the face/back image is carried by the always-refreshed
+    // `Sprite` above, so theme/card-back swaps need no child rebuild. Skipping
+    // this on a position-only move avoids despawning and respawning the child
+    // entities (incl. a `Text2d` glyph re-layout) for all 52 cards on every
+    // `StateChangedEvent` — the spike that stuttered the slide animation on
+    // high-resolution devices.
+    let new_children_key = CardChildrenKey {
+        face_up,
+        card_size: layout.card_size,
+        color_blind,
+        high_contrast,
+    };
+    if existing_children_key != Some(new_children_key) {
+        commands.entity(entity).despawn_related::<Children>();
+        commands.entity(entity).with_children(|b| {
+            add_card_shadow_child(b, layout.card_size);
+        });
+        commands.entity(entity).with_children(|b| {
+            add_card_back_frame_child(b, layout.card_size);
+        });
+        if card_images.is_none() {
+            commands.entity(entity).with_children(|b| {
+                b.spawn((
+                    CardLabel,
+                    Text2d::new(label_for(card)),
+                    TextFont {
+                        font_size: layout.card_size.x * FONT_SIZE_FRAC,
+                        ..default()
+                    },
+                    TextColor(text_colour(card, color_blind, high_contrast)),
+                    Transform::from_xyz(0.0, 0.0, 0.01),
+                    label_visibility(face_up),
+                ));
+            });
+        }
+        if USE_TOUCH_UI_LAYOUT && card_images.is_some() {
+            commands.entity(entity).with_children(|b| {
+                add_android_corner_label(
+                    b,
+                    card,
+                    face_up,
+                    layout.card_size,
+                    color_blind,
+                    high_contrast,
+                    font_handle,
+                );
+            });
+        }
+        commands.entity(entity).insert(new_children_key);
+    }
+}
+

solitaire_engine/src/card_plugin/tests.rs

@@ -3,6 +3,15 @@ use crate::game_plugin::GamePlugin;
 use crate::layout::TABLEAU_FAN_FRAC;
 use crate::table_plugin::TablePlugin;
 use solitaire_core::Deck;
+use bevy::window::WindowResized;
+use solitaire_core::{Card, Rank, Suit};
+use std::collections::HashSet;
+use crate::events::StateChangedEvent;
+use crate::layout::LayoutResource;
+use crate::resources::DragState;
+use crate::ui_theme::TEXT_PRIMARY_HC;
+use solitaire_core::{DrawStockConfig, game_state::GameState};
+
 
 /// Convenience constructor — all unit tests use Deck1.
 fn make_card(suit: Suit, rank: Rank) -> Card {

solitaire_engine/src/hud_plugin/fx.rs

@@ -0,0 +1,430 @@
+//! HUD feedback effects: action-bar fades, score pulses and floaters,
+//! and streak flourishes.
+
+use super::*;
+
+
+
+/// Auto-fade state for the action button bar. The bar fades out when
+/// the cursor is in the play area (below the HUD band) and back in when
+/// the cursor approaches the top of the window — same UX as a video
+/// player's auto-hide controls. Buttons remain fully interactive when
+/// visible; when faded out they're geometrically out of cursor reach
+/// (hover requires the cursor to be on a button), so no extra
+/// pointer-events guard is needed.
+#[derive(Resource, Debug, Clone, Copy)]
+pub struct HudActionFade {
+    /// Currently displayed alpha. Lerped toward `target` each frame.
+    pub alpha: f32,
+    /// Where `alpha` is heading — 0.0 (faded out) or 1.0 (visible).
+    pub target: f32,
+}
+
+impl Default for HudActionFade {
+    fn default() -> Self {
+        // Start visible so the player sees the controls on first launch
+        // before they've moved the cursor anywhere.
+        Self {
+            alpha: 1.0,
+            target: 1.0,
+        }
+    }
+}
+
+/// How many pixels from the bottom edge the cursor must be to reveal the bar.
+/// Set slightly taller than `HUD_BAND_HEIGHT` so the bar fades in as the
+/// cursor approaches, not only when it crosses into the band itself.
+#[cfg(not(target_os = "android"))]
+const ACTION_FADE_REVEAL_PX: f32 = HUD_BAND_HEIGHT + 32.0;
+
+/// Lerp rate for fading (per second). 6.0 ≈ 167 ms for a full
+/// transition — fast enough to feel responsive without flashing on
+/// brief cursor wanders into the reveal zone.
+#[cfg(not(target_os = "android"))]
+const ACTION_FADE_RATE_PER_SEC: f32 = 6.0;
+
+/// Updates the fade state from cursor position. Sets `target = 1.0` if
+/// the cursor is in the reveal zone (bottom of window) or off-screen
+/// (player is using keyboard); `0.0` otherwise. Lerps `alpha` toward
+/// `target` at a fixed rate so the visual transition is smooth across
+/// variable framerates.
+#[cfg(not(target_os = "android"))]
+pub(super) fn update_action_fade(windows: Query<&Window>, time: Res<Time>, mut fade: ResMut<HudActionFade>) {
+    let Ok(window) = windows.single() else {
+        return;
+    };
+    let height = window.resolution.height();
+    fade.target = match window.cursor_position() {
+        Some(pos) if pos.y >= height - ACTION_FADE_REVEAL_PX => 1.0,
+        Some(_) => 0.0,
+        // Off-window cursor: assume keyboard navigation and keep the
+        // bar visible so Tab cycling doesn't lead to invisible focus.
+        None => 1.0,
+    };
+
+    let dt = time.delta_secs();
+    let max_step = ACTION_FADE_RATE_PER_SEC * dt;
+    let diff = fade.target - fade.alpha;
+    fade.alpha = (fade.alpha + diff.clamp(-max_step, max_step)).clamp(0.0, 1.0);
+}
+
+/// Applies the current fade alpha to every action button's
+/// `BackgroundColor` and to its child label / hotkey-chip text. Runs in
+/// `Last` (after `paint_action_buttons`) so a hover-state change in the
+/// same frame doesn't override the fade with an opaque idle / hover
+/// colour.
+#[cfg(not(target_os = "android"))]
+#[allow(clippy::type_complexity)]
+pub(super) fn apply_action_fade(
+    fade: Res<HudActionFade>,
+    // Excludes `PopoverRow` so the auto-fade only applies to the
+    // top-level action bar buttons. Popover rows live inside an
+    // explicitly-opened dropdown panel and need to stay visible
+    // regardless of the bar's fade state — without the exclusion
+    // the rows fade to invisible while the popover container stays
+    // visible, leaving a solid background block with no readable
+    // content.
+    mut buttons: Query<
+        (&Children, &mut BackgroundColor),
+        (With<ActionButton>, Without<PopoverRow>),
+    >,
+    mut text_q: Query<&mut TextColor>,
+) {
+    for (children, mut bg) in &mut buttons {
+        let mut c = bg.0;
+        c.set_alpha(fade.alpha);
+        bg.0 = c;
+        for child in children.iter() {
+            if let Ok(mut tc) = text_q.get_mut(child) {
+                let mut cc = tc.0;
+                cc.set_alpha(fade.alpha);
+                tc.0 = cc;
+            }
+        }
+    }
+}
+
+/// Visual feedback for every action button — paints idle / hover / pressed
+/// states by mutating `BackgroundColor` whenever the interaction state
+/// changes. One query covers all action buttons via the shared
+/// `ActionButton` marker.
+#[allow(clippy::type_complexity)]
+pub(super) fn paint_action_buttons(
+    mut buttons: Query<
+        (&Interaction, &mut BackgroundColor),
+        (With<ActionButton>, Changed<Interaction>),
+    >,
+) {
+    for (interaction, mut bg) in &mut buttons {
+        bg.0 = match interaction {
+            Interaction::Pressed => ACTION_BTN_PRESSED,
+            Interaction::Hovered => ACTION_BTN_HOVER,
+            Interaction::None => ACTION_BTN_IDLE,
+        };
+    }
+}
+
+/// Triangular 1.0 → 1.1 → 1.0 curve used by the score pulse. Pure
+/// function so the test suite can assert on the curve directly
+/// without spinning up a Bevy app.
+///
+/// The brief proposed `if t < 0.5 { 1.0 + 0.2*t } else { 1.2 - 0.2*(t-0.5) }`,
+/// but that yields a discontinuity at t=0.5 (jumps from 1.1 → 1.2) and
+/// ends at 1.1 instead of 1.0. The corrected form below preserves the
+/// intent ("1.0 → 1.1 → 1.0 over the duration") with a continuous
+/// triangle peaking at 1.1.
+pub(super) fn score_pulse_scale(t: f32) -> f32 {
+    let clamped = t.clamp(0.0, 1.0);
+    if clamped < 0.5 {
+        1.0 + 0.2 * clamped
+    } else {
+        1.1 - 0.2 * (clamped - 0.5)
+    }
+}
+
+/// Vertical pixels the floating "+N" drifts up over its lifetime.
+const FLOATER_DRIFT_PX: f32 = 40.0;
+
+/// Diffs the current `GameStateResource.score` against
+/// [`PreviousScore`]. On a positive delta:
+///
+/// - Inserts (or refreshes) a [`ScorePulse`] on every [`HudScore`] entity
+///   so the readout pulses 1.0 → 1.1 → 1.0.
+/// - When the delta is ≥ [`SCORE_FLOATER_THRESHOLD`], spawns a floating
+///   "+N" UI text in `ACCENT_PRIMARY` anchored just below the score
+///   readout (see the doc comment on [`ScoreFloater`] for why this is a
+///   UI Node rather than a `Text2d`).
+pub(super) fn detect_score_change(
+    game: Res<GameStateResource>,
+    settings: Option<Res<SettingsResource>>,
+    mut prev: ResMut<PreviousScore>,
+    font_res: Option<Res<FontResource>>,
+    score_q: Query<Entity, With<HudScore>>,
+    mut commands: Commands,
+) {
+    let current = game.0.score();
+    let delta = current - prev.0;
+    prev.0 = current;
+    if delta <= 0 {
+        return;
+    }
+
+    let reduce_motion = settings.as_deref().is_some_and(|s| s.0.reduce_motion_mode);
+    if reduce_motion {
+        return;
+    }
+
+    let speed = settings
+        .as_ref()
+        .map(|s| s.0.animation_speed)
+        .unwrap_or_default();
+    let pulse_secs = scaled_duration(MOTION_SCORE_PULSE_SECS, speed);
+    let floater_secs = scaled_duration(MOTION_SCORE_PULSE_SECS * 2.0, speed);
+
+    // Refresh ScorePulse on every score readout entity (in practice
+    // there's exactly one, but iterating is cheaper than asserting).
+    for entity in &score_q {
+        commands.entity(entity).insert(ScorePulse {
+            elapsed: 0.0,
+            duration: pulse_secs,
+        });
+    }
+
+    if delta < SCORE_FLOATER_THRESHOLD {
+        return;
+    }
+
+    let font = TextFont {
+        font: font_res.as_ref().map(|f| f.0.clone()).unwrap_or_default(),
+        font_size: TYPE_BODY_LG,
+        ..default()
+    };
+    // Spawned as an absolutely-positioned UI Node so the floater rides
+    // the same screen-coordinate system as the score readout. Using a
+    // `Text2d` here would require translating UI layout coordinates to
+    // world space every frame; a UI node piggybacks on the same
+    // anchoring `update_hud` already uses for the score and stays
+    // testable under `MinimalPlugins`.
+    commands.spawn((
+        ScoreFloater {
+            elapsed: 0.0,
+            duration: floater_secs,
+        },
+        Node {
+            position_type: PositionType::Absolute,
+            // Anchored next to the HUD column; matches the
+            // `spawn_hud` left/top offsets so the floater appears
+            // overlaid on the score line and drifts up from there.
+            left: VAL_SPACE_3,
+            top: Val::Px(0.0),
+            ..default()
+        },
+        ZIndex(Z_HUD_TOP),
+        Text::new(format!("+{delta}")),
+        font,
+        TextColor(ACCENT_PRIMARY),
+    ));
+}
+
+/// Advances every [`ScorePulse`], scaling its entity's `Transform`
+/// using [`score_pulse_scale`]. Removes the component once
+/// `elapsed >= duration` (or immediately under
+/// [`AnimSpeed::Instant`](solitaire_data::AnimSpeed) where duration is
+/// 0) and pins the scale back to 1.0 so no float drift survives.
+pub(super) fn advance_score_pulse(
+    time: Res<Time>,
+    mut commands: Commands,
+    mut q: Query<(Entity, &mut ScorePulse, &mut Transform)>,
+) {
+    let dt = time.delta_secs();
+    for (entity, mut pulse, mut transform) in &mut q {
+        let t = if pulse.duration <= 0.0 {
+            1.0
+        } else {
+            pulse.elapsed += dt;
+            (pulse.elapsed / pulse.duration).clamp(0.0, 1.0)
+        };
+        let scale = score_pulse_scale(t);
+        transform.scale = Vec3::new(scale, scale, 1.0);
+        if t >= 1.0 {
+            transform.scale = Vec3::ONE;
+            commands.entity(entity).remove::<ScorePulse>();
+        }
+    }
+}
+
+/// Advances every [`ScoreFloater`]: drifts the node upward by up to
+/// [`FLOATER_DRIFT_PX`] and fades the text colour to transparent over
+/// its lifetime. Despawns the entity once `elapsed >= duration`.
+pub(super) fn advance_score_floater(
+    time: Res<Time>,
+    mut commands: Commands,
+    mut nodes: Query<(Entity, &mut ScoreFloater, &mut Node, &mut TextColor)>,
+) {
+    let dt = time.delta_secs();
+    for (entity, mut floater, mut node, mut color) in &mut nodes {
+        let t = if floater.duration <= 0.0 {
+            1.0
+        } else {
+            floater.elapsed += dt;
+            (floater.elapsed / floater.duration).clamp(0.0, 1.0)
+        };
+        // Drift upward: top decreases as t grows. Starting top=0 keeps
+        // the floater on the score line; ending at -FLOATER_DRIFT_PX
+        // pulls it up off the readout.
+        node.top = Val::Px(-FLOATER_DRIFT_PX * t);
+        // Linear fade: ACCENT_PRIMARY at t=0 → fully transparent at t=1.
+        let mut c = ACCENT_PRIMARY;
+        c.set_alpha(1.0 - t);
+        color.0 = c;
+        if t >= 1.0 {
+            commands.entity(entity).despawn();
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Streak-milestone flourish
+//
+// Per the 2026-04-30 UX overhaul plan, the foundation flourish is the per-suit
+// completion celebration; the streak flourish is its lifetime equivalent —
+// when the player's `win_streak_current` crosses 3, 5, or 10, the HUD score
+// readout pulses larger than a normal score-change pulse and tints magenta
+// (`ACCENT_SECONDARY`) before snapping back to its resting state.
+//
+// Why the score readout: there is no always-on streak number on the HUD
+// today (the readout lives in the Stats overlay), and the score is the
+// most prominent always-visible HUD figure. The accompanying `InfoToastEvent`
+// fired by `stats_plugin` carries the explicit "Win streak: N!" text so a
+// player who isn't watching the score still sees the celebration land.
+// ---------------------------------------------------------------------------
+
+/// Pure helper for unit tests — returns the per-frame scale factor for
+/// the streak flourish at `elapsed_secs` over `duration_secs`.
+///
+/// Triangular curve, mirroring [`foundation_flourish_scale`](crate::feedback_anim_plugin::foundation_flourish_scale):
+/// at `t = 0.0` returns `1.0`, at `t = 0.5` returns
+/// [`STREAK_FLOURISH_PEAK_SCALE`], at `t = 1.0` returns `1.0`.
+/// Out-of-range values are clamped so the score readout never freezes
+/// at a non-1.0 scale on the frame after the flourish ends.
+///
+/// Returns `1.0` whenever `duration_secs <= 0.0` so callers running
+/// under `AnimSpeed::Instant` (zeroed durations) skip the flourish
+/// without dividing by zero.
+pub fn streak_flourish_scale(elapsed_secs: f32, duration_secs: f32) -> f32 {
+    if duration_secs <= 0.0 {
+        return 1.0;
+    }
+    let t = (elapsed_secs / duration_secs).clamp(0.0, 1.0);
+    let peak = STREAK_FLOURISH_PEAK_SCALE;
+    if t < 0.5 {
+        // Climb from 1.0 at t=0 to peak at t=0.5.
+        1.0 + (peak - 1.0) * (t / 0.5)
+    } else {
+        // Descend from peak at t=0.5 back to 1.0 at t=1.0.
+        peak - (peak - 1.0) * ((t - 0.5) / 0.5)
+    }
+}
+
+/// Inserts a [`StreakFlourish`] on every [`HudScore`] entity when a
+/// [`WinStreakMilestoneEvent`] fires. Captures the readout's current
+/// `TextColor` so `advance_streak_flourish` can restore it when the
+/// timer expires; reuses any existing flourish's `original_color` so
+/// re-entering the system mid-flourish doesn't snapshot the magenta
+/// tint as the new "original".
+///
+/// Removes any concurrent [`ScorePulse`] from the same entity so the
+/// flourish takes over the scale slot cleanly — score pulses last
+/// 250 ms, the flourish 600 ms, and the streak crossing always
+/// coincides with a positive score delta, so the flourish is the
+/// louder of the two celebrations.
+pub(super) fn start_streak_flourish(
+    mut events: MessageReader<WinStreakMilestoneEvent>,
+    settings: Option<Res<SettingsResource>>,
+    score_q: Query<(Entity, &TextColor, Option<&StreakFlourish>), With<HudScore>>,
+    mut commands: Commands,
+) {
+    let Some(latest) = events.read().last() else {
+        return;
+    };
+    if settings.as_deref().is_some_and(|s| s.0.reduce_motion_mode) {
+        return;
+    }
+    let speed = settings
+        .as_ref()
+        .map(|s| s.0.animation_speed)
+        .unwrap_or_default();
+    let duration = scaled_duration(MOTION_STREAK_FLOURISH_SECS, speed);
+    for (entity, color, existing) in &score_q {
+        let original_color = existing.map_or(color.0, |f| f.original_color);
+        commands
+            .entity(entity)
+            .remove::<ScorePulse>()
+            .insert(StreakFlourish {
+                streak: latest.streak,
+                elapsed: 0.0,
+                duration,
+                original_color,
+            });
+    }
+}
+
+/// Advances every [`StreakFlourish`], scaling its entity's `Transform`
+/// using [`streak_flourish_scale`] and lerping the `TextColor` toward
+/// [`ACCENT_SECONDARY`] for the first half then back to the captured
+/// `original_color`. Removes the component once `elapsed >= duration`
+/// (or immediately under [`AnimSpeed::Instant`](solitaire_data::AnimSpeed)
+/// where duration is 0) and pins the scale back to 1.0 / restores the
+/// original colour so no half-state is ever shown.
+///
+/// Filtered with `Without<ScorePulse>` so the streak flourish never
+/// races a score pulse for the same `Transform.scale` slot —
+/// `start_streak_flourish` strips any concurrent `ScorePulse` from the
+/// score entity before this system runs, so the filter is purely a
+/// belt-and-braces invariant.
+pub(super) fn advance_streak_flourish(
+    time: Res<Time>,
+    mut commands: Commands,
+    mut q: Query<
+        (Entity, &mut StreakFlourish, &mut Transform, &mut TextColor),
+        Without<ScorePulse>,
+    >,
+) {
+    let dt = time.delta_secs();
+    for (entity, mut anim, mut transform, mut color) in &mut q {
+        let t = if anim.duration <= 0.0 {
+            1.0
+        } else {
+            anim.elapsed += dt;
+            (anim.elapsed / anim.duration).clamp(0.0, 1.0)
+        };
+        let scale = streak_flourish_scale(anim.elapsed, anim.duration);
+        transform.scale = Vec3::new(scale, scale, 1.0);
+        // Tint mix: full magenta at t=0..=0.5, fades back to the
+        // original colour over t=0.5..=1.0.
+        let mix = if t < 0.5 { 1.0 } else { 1.0 - (t - 0.5) / 0.5 };
+        color.0 = lerp_text_color(anim.original_color, ACCENT_SECONDARY, mix);
+        if t >= 1.0 {
+            transform.scale = Vec3::ONE;
+            color.0 = anim.original_color;
+            commands.entity(entity).remove::<StreakFlourish>();
+        }
+    }
+}
+
+/// sRGB-space linear interpolation between two `Color`s — small local
+/// helper so `advance_streak_flourish` stays readable. sRGB-space
+/// lerping is fine for a brief decorative tint (a perceptually-uniform
+/// space would be overkill).
+pub(super) fn lerp_text_color(from: Color, to: Color, t: f32) -> Color {
+    let from = from.to_srgba();
+    let to = to.to_srgba();
+    let t = t.clamp(0.0, 1.0);
+    Color::srgba(
+        from.red + (to.red - from.red) * t,
+        from.green + (to.green - from.green) * t,
+        from.blue + (to.blue - from.blue) * t,
+        from.alpha + (to.alpha - from.alpha) * t,
+    )
+}
+

solitaire_engine/src/hud_plugin/interaction.rs

@@ -0,0 +1,616 @@
+//! HUD interaction: action-button handlers, Modes/Menu popovers, and
+//! the chrome tap-to-toggle gesture.
+
+use super::*;
+
+
+
+/// `Changed<Interaction>` filter ensures we only react on the frame the
+/// interaction state transitions, avoiding repeat events while the button
+/// is held down. Each click handler fires the corresponding request event,
+/// which `pause_plugin` / `help_plugin` / `game_plugin` consume alongside
+/// their existing keyboard handlers.
+pub(super) fn handle_new_game_button(
+    interaction_query: Query<&Interaction, (With<NewGameButton>, Changed<Interaction>)>,
+    mut new_game: MessageWriter<NewGameRequestEvent>,
+) {
+    for interaction in &interaction_query {
+        if *interaction == Interaction::Pressed {
+            new_game.write(NewGameRequestEvent::default());
+        }
+    }
+}
+
+pub(super) fn handle_undo_button(
+    interaction_query: Query<&Interaction, (With<UndoButton>, Changed<Interaction>)>,
+    mut undo: MessageWriter<UndoRequestEvent>,
+) {
+    for interaction in &interaction_query {
+        if *interaction == Interaction::Pressed {
+            undo.write(UndoRequestEvent);
+        }
+    }
+}
+
+pub(super) fn handle_pause_button(
+    interaction_query: Query<&Interaction, (With<PauseButton>, Changed<Interaction>)>,
+    mut pause: MessageWriter<PauseRequestEvent>,
+) {
+    for interaction in &interaction_query {
+        if *interaction == Interaction::Pressed {
+            pause.write(PauseRequestEvent);
+        }
+    }
+}
+
+pub(super) fn handle_help_button(
+    interaction_query: Query<&Interaction, (With<HelpButton>, Changed<Interaction>)>,
+    mut help: MessageWriter<HelpRequestEvent>,
+) {
+    for interaction in &interaction_query {
+        if *interaction == Interaction::Pressed {
+            help.write(HelpRequestEvent);
+        }
+    }
+}
+
+pub(super) fn handle_hint_button(
+    interaction_query: Query<&Interaction, (With<HintButton>, Changed<Interaction>)>,
+    paused: Option<Res<PausedResource>>,
+    game: Option<Res<GameStateResource>>,
+    solver_config: Option<Res<crate::input_plugin::HintSolverConfig>>,
+    mut pending_hint: Option<ResMut<crate::pending_hint::PendingHintTask>>,
+    mut info_toast: MessageWriter<InfoToastEvent>,
+) {
+    for interaction in &interaction_query {
+        if *interaction != Interaction::Pressed {
+            continue;
+        }
+        if paused.as_ref().is_some_and(|p| p.0) {
+            return;
+        }
+        let Some(ref g) = game else { return };
+        if g.0.is_won() {
+            info_toast.write(InfoToastEvent(HINT_WON_MSG.to_string()));
+            return;
+        }
+        if let (Some(cfg), Some(hint)) = (solver_config.as_ref(), pending_hint.as_mut()) {
+            hint.spawn(g.0.clone(), cfg.moves_budget, cfg.states_budget);
+        }
+    }
+}
+
+/// Toggles the [`ModesPopover`]: spawns it on first click, despawns it on
+/// second click. Mode rows are populated per the player's current level so
+/// only unlocked options appear.
+pub(super) fn handle_modes_button(
+    interaction_query: Query<&Interaction, (With<ModesButton>, Changed<Interaction>)>,
+    popovers: Query<Entity, With<ModesPopover>>,
+    backdrops: Query<Entity, With<ModesPopoverBackdrop>>,
+    progress: Option<Res<ProgressResource>>,
+    daily: Option<Res<DailyChallengeResource>>,
+    font_res: Option<Res<FontResource>>,
+    mut commands: Commands,
+) {
+    let pressed = interaction_query.iter().any(|i| *i == Interaction::Pressed);
+    if !pressed {
+        return;
+    }
+    if let Ok(entity) = popovers.single() {
+        commands.entity(entity).despawn();
+        for e in &backdrops {
+            commands.entity(e).despawn();
+        }
+    } else {
+        spawn_modes_popover(
+            &mut commands,
+            progress.as_deref(),
+            daily.as_deref(),
+            font_res.as_deref(),
+        );
+    }
+}
+
+/// Spawns the modes popover anchored just below the action bar's right
+/// edge. Always includes Classic; includes Daily Challenge when a daily
+/// resource is loaded; includes Zen / Challenge / Time Attack once the
+/// player reaches the challenge unlock level.
+pub(super) fn spawn_modes_popover(
+    commands: &mut Commands,
+    progress: Option<&ProgressResource>,
+    daily: Option<&DailyChallengeResource>,
+    font_res: Option<&FontResource>,
+) {
+    let level = progress.map_or(0, |p| p.0.level);
+    let font = TextFont {
+        font: font_res.map(|f| f.0.clone()).unwrap_or_default(),
+        font_size: 15.0,
+        ..default()
+    };
+
+    // Each row carries a tooltip alongside its label so hover reveals
+    // a one-line description of what the mode does — mirroring the
+    // tooltips on the action-bar buttons that opened this popover.
+    let mut rows: Vec<(ModeOption, &'static str, &'static str)> = vec![(
+        ModeOption::Classic,
+        "Classic",
+        "Standard Klondike. Score, timer, and full progression.",
+    )];
+    if daily.is_some() {
+        rows.push((
+            ModeOption::DailyChallenge,
+            "Daily Challenge",
+            "Today's seeded deal. Same for every player worldwide.",
+        ));
+    }
+    if level >= CHALLENGE_UNLOCK_LEVEL {
+        rows.push((
+            ModeOption::Zen,
+            "Zen",
+            "No timer, no score, no penalties. Just play.",
+        ));
+        rows.push((
+            ModeOption::Challenge,
+            "Challenge",
+            "Hand-picked hard seeds. No undo allowed.",
+        ));
+        rows.push((
+            ModeOption::TimeAttack,
+            "Time Attack",
+            "Win as many games as you can in ten minutes.",
+        ));
+    }
+
+    // Popover opens upward from just above the bottom action bar.
+    // Use a platform-aware offset that clears the bar height + safe-area
+    // gesture zone on Android, and the flat bar height on desktop.
+    let popover_bottom = Val::Px(ACTION_POPOVER_BOTTOM_PX);
+
+    commands
+        .spawn((
+            ModesPopover,
+            HudPopoverOpen,
+            Node {
+                position_type: PositionType::Absolute,
+                right: VAL_SPACE_3,
+                bottom: popover_bottom,
+                flex_direction: FlexDirection::Column,
+                row_gap: VAL_SPACE_1,
+                padding: UiRect::all(VAL_SPACE_2),
+                border_radius: BorderRadius::all(Val::Px(RADIUS_MD)),
+                ..default()
+            },
+            BackgroundColor(BG_ELEVATED),
+            ZIndex(Z_HUD_POPOVER),
+        ))
+        .with_children(|panel| {
+            for (option, label, tooltip) in rows {
+                panel
+                    .spawn((
+                        option,
+                        ActionButton,
+                        PopoverRow,
+                        Button,
+                        Tooltip::new(tooltip),
+                        Node {
+                            padding: UiRect::axes(VAL_SPACE_3, Val::Px(6.0)),
+                            justify_content: JustifyContent::FlexStart,
+                            align_items: AlignItems::Center,
+                            min_width: Val::Px(150.0),
+                            border_radius: BorderRadius::all(Val::Px(RADIUS_SM)),
+                            ..default()
+                        },
+                        BackgroundColor(ACTION_BTN_IDLE),
+                    ))
+                    .with_children(|b| {
+                        b.spawn((Text::new(label), font.clone(), TextColor(TEXT_PRIMARY)));
+                    });
+            }
+        });
+
+    // Fullscreen transparent backdrop at Z_HUD_POPOVER_BACKDROP (below the
+    // popover at Z_HUD_POPOVER) so tapping outside light-dismisses it.
+    commands.spawn((
+        ModesPopoverBackdrop,
+        Button,
+        Node {
+            position_type: PositionType::Absolute,
+            left: Val::Px(0.0),
+            top: Val::Px(0.0),
+            width: Val::Percent(100.0),
+            height: Val::Percent(100.0),
+            ..default()
+        },
+        BackgroundColor(Color::NONE),
+        ZIndex(Z_HUD_POPOVER_BACKDROP),
+    ));
+}
+
+/// Dispatches the click on a popover row to the matching request event,
+/// then despawns the popover.
+///
+/// Classic uses [`NewGameRequestEvent`] directly; the other modes use
+/// their `Start*RequestEvent` so the existing keyboard handler runs
+/// (level gates, `TimeAttackResource` setup, daily seed lookup, etc.) —
+/// the popover stays a thin entry point and never duplicates that logic.
+#[allow(clippy::too_many_arguments)]
+pub(super) fn handle_mode_option_click(
+    interaction_query: Query<(&Interaction, &ModeOption), Changed<Interaction>>,
+    popovers: Query<Entity, With<ModesPopover>>,
+    backdrops: Query<Entity, With<ModesPopoverBackdrop>>,
+    mut new_game: MessageWriter<NewGameRequestEvent>,
+    mut zen: MessageWriter<StartZenRequestEvent>,
+    mut challenge: MessageWriter<StartChallengeRequestEvent>,
+    mut time_attack: MessageWriter<StartTimeAttackRequestEvent>,
+    mut daily: MessageWriter<StartDailyChallengeRequestEvent>,
+    mut commands: Commands,
+) {
+    let mut clicked_any = false;
+    for (interaction, option) in &interaction_query {
+        if *interaction != Interaction::Pressed {
+            continue;
+        }
+        clicked_any = true;
+        match option {
+            ModeOption::Classic => {
+                new_game.write(NewGameRequestEvent::default());
+            }
+            ModeOption::DailyChallenge => {
+                daily.write(StartDailyChallengeRequestEvent);
+            }
+            ModeOption::Zen => {
+                zen.write(StartZenRequestEvent);
+            }
+            ModeOption::Challenge => {
+                challenge.write(StartChallengeRequestEvent);
+            }
+            ModeOption::TimeAttack => {
+                time_attack.write(StartTimeAttackRequestEvent);
+            }
+        }
+    }
+    if clicked_any && let Ok(entity) = popovers.single() {
+        commands.entity(entity).despawn();
+        for e in &backdrops {
+            commands.entity(e).despawn();
+        }
+    }
+}
+
+/// Toggles the [`MenuPopover`]: spawns it on first click, despawns it on
+/// second click. The popover lists the five overlays previously only
+/// reachable via the S / A / P / O / L hotkeys.
+pub(super) fn handle_menu_button(
+    interaction_query: Query<&Interaction, (With<MenuButton>, Changed<Interaction>)>,
+    popovers: Query<Entity, With<MenuPopover>>,
+    backdrops: Query<Entity, With<MenuPopoverBackdrop>>,
+    scrims: Query<(), With<ModalScrim>>,
+    font_res: Option<Res<FontResource>>,
+    mut commands: Commands,
+) {
+    let pressed = interaction_query.iter().any(|i| *i == Interaction::Pressed);
+    if !pressed {
+        return;
+    }
+    if let Ok(entity) = popovers.single() {
+        commands.entity(entity).despawn();
+        for e in &backdrops {
+            commands.entity(e).despawn();
+        }
+    } else if scrims.is_empty() {
+        spawn_menu_popover(&mut commands, font_res.as_deref());
+    }
+}
+
+/// Spawns the menu popover anchored just below the action bar, with one
+/// row per overlay. Each row dispatches its corresponding
+/// `Toggle*RequestEvent` so the existing toggle handler runs (and the
+/// HUD never duplicates spawn / despawn / fetch logic).
+pub(super) fn spawn_menu_popover(commands: &mut Commands, font_res: Option<&FontResource>) {
+    let font = TextFont {
+        font: font_res.map(|f| f.0.clone()).unwrap_or_default(),
+        font_size: 15.0,
+        ..default()
+    };
+
+    // Each row carries a tooltip alongside its label so hover reveals
+    // a one-line description of what each overlay shows — mirroring
+    // the tooltips on the action-bar buttons that opened this popover.
+    let rows: [(MenuOption, &'static str, &'static str); 7] = [
+        (
+            MenuOption::Help,
+            "Help",
+            "Show controls, rules, and keyboard shortcuts.",
+        ),
+        (
+            MenuOption::Modes,
+            "Game Modes",
+            "Switch modes: Classic, Daily, Zen, Challenge, Time Attack.",
+        ),
+        (
+            MenuOption::Stats,
+            "Stats",
+            "Lifetime totals: wins, streaks, fastest time, best score.",
+        ),
+        (
+            MenuOption::Achievements,
+            "Achievements",
+            "Browse unlocked achievements and the rewards still ahead.",
+        ),
+        (
+            MenuOption::Profile,
+            "Profile",
+            "Your level, XP progress, and sync status.",
+        ),
+        (
+            MenuOption::Settings,
+            "Settings",
+            "Audio, animations, theme, draw mode, and sync.",
+        ),
+        (
+            MenuOption::Leaderboard,
+            "Leaderboard",
+            "Top players from your sync server. Opt in from Profile.",
+        ),
+    ];
+
+    // Same upward-opening placement as ModesPopover.
+    let popover_bottom = Val::Px(ACTION_POPOVER_BOTTOM_PX);
+
+    commands
+        .spawn((
+            MenuPopover,
+            HudPopoverOpen,
+            Node {
+                position_type: PositionType::Absolute,
+                right: VAL_SPACE_3,
+                bottom: popover_bottom,
+                flex_direction: FlexDirection::Column,
+                row_gap: VAL_SPACE_1,
+                padding: UiRect::all(VAL_SPACE_2),
+                border_radius: BorderRadius::all(Val::Px(RADIUS_MD)),
+                ..default()
+            },
+            BackgroundColor(BG_ELEVATED),
+            ZIndex(Z_HUD_POPOVER),
+        ))
+        .with_children(|panel| {
+            for (option, label, tooltip) in rows {
+                panel
+                    .spawn((
+                        option,
+                        ActionButton,
+                        PopoverRow,
+                        Button,
+                        Tooltip::new(tooltip),
+                        Node {
+                            padding: UiRect::axes(VAL_SPACE_3, Val::Px(6.0)),
+                            justify_content: JustifyContent::FlexStart,
+                            align_items: AlignItems::Center,
+                            min_width: Val::Px(150.0),
+                            border_radius: BorderRadius::all(Val::Px(RADIUS_SM)),
+                            ..default()
+                        },
+                        BackgroundColor(ACTION_BTN_IDLE),
+                    ))
+                    .with_children(|b| {
+                        b.spawn((Text::new(label), font.clone(), TextColor(TEXT_PRIMARY)));
+                    });
+            }
+        });
+
+    // Transparent fullscreen backdrop behind the popover — tapping anywhere
+    // outside the panel light-dismisses it via handle_menu_backdrop_click.
+    commands.spawn((
+        MenuPopoverBackdrop,
+        Button,
+        Node {
+            position_type: PositionType::Absolute,
+            left: Val::Px(0.0),
+            top: Val::Px(0.0),
+            width: Val::Percent(100.0),
+            height: Val::Percent(100.0),
+            ..default()
+        },
+        BackgroundColor(Color::NONE),
+        ZIndex(Z_HUD_POPOVER_BACKDROP),
+    ));
+}
+
+/// Dispatches the click on a menu row to the matching toggle event,
+/// then despawns the popover.
+#[allow(clippy::too_many_arguments)]
+pub(super) fn handle_menu_option_click(
+    interaction_query: Query<(&Interaction, &MenuOption), Changed<Interaction>>,
+    popovers: Query<Entity, With<MenuPopover>>,
+    backdrops: Query<Entity, With<MenuPopoverBackdrop>>,
+    mut stats: MessageWriter<ToggleStatsRequestEvent>,
+    mut achievements: MessageWriter<ToggleAchievementsRequestEvent>,
+    mut profile: MessageWriter<ToggleProfileRequestEvent>,
+    mut settings: MessageWriter<ToggleSettingsRequestEvent>,
+    mut leaderboard: MessageWriter<ToggleLeaderboardRequestEvent>,
+    mut help: MessageWriter<HelpRequestEvent>,
+    progress: Option<Res<ProgressResource>>,
+    daily: Option<Res<DailyChallengeResource>>,
+    font_res: Option<Res<FontResource>>,
+    mut commands: Commands,
+) {
+    let mut clicked_any = false;
+    let mut open_modes = false;
+    for (interaction, option) in &interaction_query {
+        if *interaction != Interaction::Pressed {
+            continue;
+        }
+        clicked_any = true;
+        match option {
+            MenuOption::Help => {
+                help.write(HelpRequestEvent);
+            }
+            MenuOption::Modes => {
+                open_modes = true;
+            }
+            MenuOption::Stats => {
+                stats.write(ToggleStatsRequestEvent);
+            }
+            MenuOption::Achievements => {
+                achievements.write(ToggleAchievementsRequestEvent);
+            }
+            MenuOption::Profile => {
+                profile.write(ToggleProfileRequestEvent);
+            }
+            MenuOption::Settings => {
+                settings.write(ToggleSettingsRequestEvent);
+            }
+            MenuOption::Leaderboard => {
+                leaderboard.write(ToggleLeaderboardRequestEvent);
+            }
+        }
+    }
+    if clicked_any && let Ok(entity) = popovers.single() {
+        commands.entity(entity).despawn();
+        for e in &backdrops {
+            commands.entity(e).despawn();
+        }
+    }
+    if open_modes {
+        spawn_modes_popover(
+            &mut commands,
+            progress.as_deref(),
+            daily.as_deref(),
+            font_res.as_deref(),
+        );
+    }
+}
+
+/// Despawns the [`ModesPopover`] and its backdrop when Escape / Android back
+/// is pressed while the popover is open. Runs so `PausePlugin`'s guard (which
+/// checks [`HudPopoverOpen`]) sees an empty world and stays idle.
+pub(super) fn close_modes_popover_on_escape(
+    keys: Res<ButtonInput<KeyCode>>,
+    popovers: Query<Entity, With<ModesPopover>>,
+    backdrops: Query<Entity, With<ModesPopoverBackdrop>>,
+    mut commands: Commands,
+) {
+    if !keys.just_pressed(KeyCode::Escape) || popovers.is_empty() {
+        return;
+    }
+    for e in popovers.iter().chain(backdrops.iter()) {
+        commands.entity(e).despawn();
+    }
+}
+
+/// Despawns the [`MenuPopover`] and its backdrop when Escape / Android back
+/// is pressed while the popover is open.
+pub(super) fn close_menu_popover_on_escape(
+    keys: Res<ButtonInput<KeyCode>>,
+    popovers: Query<Entity, With<MenuPopover>>,
+    backdrops: Query<Entity, With<MenuPopoverBackdrop>>,
+    mut commands: Commands,
+) {
+    if !keys.just_pressed(KeyCode::Escape) || popovers.is_empty() {
+        return;
+    }
+    for e in popovers.iter().chain(backdrops.iter()) {
+        commands.entity(e).despawn();
+    }
+}
+
+/// Despawns the [`ModesPopover`] and its backdrop when the player taps
+/// anywhere outside the panel.
+pub(super) fn handle_modes_backdrop_click(
+    interaction_query: Query<&Interaction, (With<ModesPopoverBackdrop>, Changed<Interaction>)>,
+    popovers: Query<Entity, With<ModesPopover>>,
+    backdrops: Query<Entity, With<ModesPopoverBackdrop>>,
+    mut commands: Commands,
+) {
+    let pressed = interaction_query.iter().any(|i| *i == Interaction::Pressed);
+    if !pressed {
+        return;
+    }
+    for e in popovers.iter().chain(backdrops.iter()) {
+        commands.entity(e).despawn();
+    }
+}
+
+/// Despawns the [`MenuPopover`] and its backdrop when the player taps
+/// anywhere outside the panel (i.e. the transparent backdrop is pressed).
+pub(super) fn handle_menu_backdrop_click(
+    interaction_query: Query<&Interaction, (With<MenuPopoverBackdrop>, Changed<Interaction>)>,
+    popovers: Query<Entity, With<MenuPopover>>,
+    backdrops: Query<Entity, With<MenuPopoverBackdrop>>,
+    mut commands: Commands,
+) {
+    let pressed = interaction_query.iter().any(|i| *i == Interaction::Pressed);
+    if !pressed {
+        return;
+    }
+    for e in popovers.iter().chain(backdrops.iter()) {
+        commands.entity(e).despawn();
+    }
+}
+
+#[cfg(target_os = "android")]
+#[allow(clippy::too_many_arguments)]
+pub(super) fn toggle_hud_on_tap(
+    mut touch_events: MessageReader<TouchInput>,
+    drag: Res<DragState>,
+    scrims: Query<(), With<ModalScrim>>,
+    paused: Option<Res<PausedResource>>,
+    mut tracker: ResMut<HudTapTracker>,
+    mut hud_vis: ResMut<HudVisibility>,
+    buttons: Query<&Interaction, With<ActionButton>>,
+    mut game_consumed: ResMut<GameInputConsumedResource>,
+) {
+    use bevy::input::touch::TouchPhase;
+    if !scrims.is_empty() || paused.is_some_and(|p| p.0) {
+        // Drain buffered events so they don't replay in the frame after
+        // the scrim despawns, which would trigger a spurious visibility
+        // toggle as the resume/close button tap's Started+Ended pair
+        // replays in the now-scrim-free frame.
+        for _ in touch_events.read() {}
+        tracker.start_pos = None;
+        tracker.started_on_button = false;
+        game_consumed.0 = false;
+        return;
+    }
+    for event in touch_events.read() {
+        match event.phase {
+            TouchPhase::Started => {
+                tracker.start_pos = Some(event.position);
+                // Record whether the finger-down landed on a button so
+                // the finger-up doesn't double-fire (toggle bar + press
+                // button at the same time).
+                tracker.started_on_button = buttons.iter().any(|i| *i != Interaction::None);
+            }
+            TouchPhase::Ended if drag.is_idle() => {
+                // Also treat taps where game logic consumed the touch (e.g.
+                // drawing from stock) as "on button" so they don't toggle
+                // the HUD. The flag is set on TouchPhase::Started by the
+                // input system that consumed the tap and must be cleared here
+                // regardless of whether we toggle.
+                let on_button = tracker.started_on_button || game_consumed.0;
+                game_consumed.0 = false;
+                if let Some(start) = tracker.start_pos.take()
+                    && !on_button
+                    && (event.position - start).length() < HUD_TAP_SLOP_PX
+                {
+                    *hud_vis = match *hud_vis {
+                        HudVisibility::Visible => HudVisibility::Hidden,
+                        HudVisibility::Hidden => HudVisibility::Visible,
+                    };
+                }
+                tracker.started_on_button = false;
+            }
+            // Moved: don't clear start_pos — Android fires Moved for normal
+            // tap jitter, and the distance check at Ended already rejects
+            // real drags. Clearing here would silently swallow tap toggles.
+            TouchPhase::Canceled => {
+                tracker.start_pos = None;
+                tracker.started_on_button = false;
+                game_consumed.0 = false;
+            }
+            _ => {}
+        }
+    }
+}
+

solitaire_engine/src/hud_plugin/spawn.rs

@@ -0,0 +1,552 @@
+//! HUD construction: band, columns, avatar, and action-bar spawning.
+
+use super::*;
+
+
+#[cfg(not(target_arch = "wasm32"))]
+use crate::avatar_plugin::AvatarResource;
+
+/// Spawns the invisible HUD band that reserves vertical space at the top of
+/// the screen so the card layout (computed by `layout::compute_layout` using
+/// `HUD_BAND_HEIGHT`) aligns correctly below the score readouts.
+///
+/// The entity carries no `BackgroundColor` — the green felt shows through.
+/// A slim grey background is handled by each content section individually
+/// (the bottom action bar has its own `BG_HUD_BAND` background).
+pub(super) fn spawn_hud_band(mut commands: Commands) {
+    const BASE_TOP: f32 = 0.0;
+    commands.spawn((
+        Node {
+            position_type: PositionType::Absolute,
+            top: Val::Px(BASE_TOP),
+            left: Val::Px(0.0),
+            width: Val::Percent(100.0),
+            height: Val::Px(HUD_BAND_HEIGHT),
+            ..default()
+        },
+        ZIndex(Z_HUD - 1),
+        SafeAreaAnchoredTop { base_top: BASE_TOP },
+        HudBand,
+    ));
+}
+
+/// Spawns the in-game HUD as a 4-tier vertical column anchored to the
+/// top-left of the play area.
+///
+/// Tiers (top to bottom):
+///   1. **Primary** — Score (display weight) · Moves · Timer.
+///      Always visible during gameplay.
+///   2. **Mode context** — Mode badge · Daily-challenge constraint ·
+///      Draw-cycle indicator. Each cell is empty when not relevant; the
+///      row collapses visually when all cells are empty.
+///   3. **Penalty / bonus** — Undos · Recycles · Auto-complete badge.
+///      Both penalty counters share `STATE_WARNING` (the audit found
+///      they were inconsistent: Undos amber, Recycles white).
+///   4. **Selection** — keyboard-driven pile selector chip.
+///
+/// The audit identified the original single-row layout (10 readouts in
+/// one horizontal flex row, 5+ colour families competing) as the
+/// player's #1 complaint. This restructure groups by purpose, lets
+/// transient items disappear cleanly, and uses the typography scale to
+/// make Score the visual protagonist.
+pub(super) fn spawn_hud(font_res: Option<Res<FontResource>>, mut commands: Commands) {
+    let font_handle = font_res.as_ref().map(|f| f.0.clone()).unwrap_or_default();
+    let font_score = TextFont {
+        font: font_handle.clone(),
+        font_size: TYPE_HEADLINE,
+        ..default()
+    };
+    let font_lg = TextFont {
+        font: font_handle.clone(),
+        font_size: TYPE_BODY_LG,
+        ..default()
+    };
+    let font_body = TextFont {
+        font: font_handle,
+        font_size: TYPE_BODY,
+        ..default()
+    };
+
+    let row_node = || Node {
+        flex_direction: FlexDirection::Row,
+        column_gap: VAL_SPACE_3,
+        // On a narrow viewport the four tier rows (Score/Moves/Timer,
+        // Mode/Challenge/Draw-cycle/Won-previously, Undos/Recycles/
+        // Auto-complete, selection chip) can collectively be wider than
+        // the available space and overflow into the action-button column
+        // on the right. `flex_wrap: Wrap` lets each tier soft-wrap onto
+        // a second line; on a desktop window the rows stay single-line
+        // because the parent column has no width cap and the row never
+        // exceeds the natural line width.
+        flex_wrap: FlexWrap::Wrap,
+        row_gap: VAL_SPACE_1,
+        align_items: AlignItems::Baseline,
+        ..default()
+    };
+
+    commands
+        .spawn((
+            Node {
+                position_type: PositionType::Absolute,
+                left: VAL_SPACE_3,
+                top: Val::Px(SPACE_2),
+                flex_direction: FlexDirection::Column,
+                // Cap the column at 50% of viewport so on narrow
+                // (mobile) widths the inner tier rows have a bounded
+                // width to wrap against, and the column can't bleed
+                // into the right-anchored action button row (also
+                // capped at 50%). On desktop 50% of 1920 = 960 px,
+                // wider than any tier row's natural width, so the
+                // visible layout is unaffected.
+                max_width: Val::Percent(50.0),
+                row_gap: VAL_SPACE_1,
+                ..default()
+            },
+            ZIndex(Z_HUD),
+            SafeAreaAnchoredTop { base_top: SPACE_2 },
+            HudColumn,
+        ))
+        .with_children(|hud| {
+            // Tier 1 — primary readouts. Score is the protagonist (HEADLINE);
+            // Moves and Timer are supporting context (BODY_LG, secondary tone).
+            hud.spawn(row_node()).with_children(|t1| {
+                t1.spawn((
+                    HudScore,
+                    Tooltip::new("Points earned this game. Hidden in Zen mode."),
+                    Text::new("Score: 0"),
+                    font_score.clone(),
+                    TextColor(TEXT_PRIMARY),
+                ));
+                t1.spawn((
+                    HudMoves,
+                    Tooltip::new("Moves you've made this game. Counts placements and stock draws."),
+                    Text::new("Moves: 0"),
+                    font_lg.clone(),
+                    TextColor(TEXT_SECONDARY),
+                ));
+                t1.spawn((
+                    HudTime,
+                    Tooltip::new("Time on this game. Counts down in Time Attack."),
+                    Text::new("0:00"),
+                    font_lg.clone(),
+                    TextColor(TEXT_SECONDARY),
+                ));
+            });
+
+            // Tier 2 — mode context. Each cell is empty until update_hud
+            // populates it (and clears it when no longer relevant), so the
+            // row collapses when nothing in this tier applies.
+            hud.spawn(row_node()).with_children(|t2| {
+                t2.spawn((
+                    HudMode,
+                    Tooltip::new("Active game mode. Click Modes to switch."),
+                    Text::new(""),
+                    font_body.clone(),
+                    TextColor(ACCENT_PRIMARY),
+                ));
+                t2.spawn((
+                    HudChallenge,
+                    Tooltip::new("Today's daily challenge target. Beat it for bonus XP."),
+                    Text::new(""),
+                    font_body.clone(),
+                    TextColor(STATE_INFO),
+                ));
+                t2.spawn((
+                    HudDrawCycle,
+                    Tooltip::new("Cards drawn on the next stock click in Draw-Three."),
+                    Text::new(""),
+                    font_body.clone(),
+                    TextColor(STATE_INFO),
+                ));
+                t2.spawn((
+                    HudWonPreviously,
+                    Tooltip::new("You've won this deal before. Same seed in your replay history."),
+                    Text::new(""),
+                    font_body.clone(),
+                    TextColor(STATE_SUCCESS),
+                ));
+            });
+
+            // Tier 3 — penalty / bonus. Undos and Recycles share the
+            // warning hue so they read as the same category ("you took a
+            // penalty"); the auto-complete badge stays success-green.
+            hud.spawn(row_node()).with_children(|t3| {
+                t3.spawn((
+                    HudUndos,
+                    Tooltip::new("Undos used this game. Any undo blocks the No Undo achievement."),
+                    Text::new(""),
+                    font_body.clone(),
+                    TextColor(STATE_WARNING),
+                ));
+                t3.spawn((
+                    HudRecycles,
+                    Tooltip::new(
+                        "Times you've recycled the stock. Three or more unlocks Comeback.",
+                    ),
+                    Text::new(""),
+                    font_body.clone(),
+                    TextColor(STATE_WARNING),
+                ));
+                t3.spawn((
+                    HudAutoComplete,
+                    Tooltip::new("Board is solvable from here. Press Enter to auto-finish."),
+                    Text::new(""),
+                    font_body.clone(),
+                    TextColor(STATE_SUCCESS),
+                ));
+            });
+
+            // Tier 4 — selection chip. Stays in HUD for now; a future
+            // pass can reposition it next to the selected pile.
+            hud.spawn(row_node()).with_children(|t4| {
+                t4.spawn((
+                    HudSelection,
+                    Tooltip::new("Pile selected with Tab. Use arrows or Enter to act."),
+                    Text::new(""),
+                    font_body,
+                    TextColor(ACCENT_SECONDARY),
+                ));
+            });
+        });
+}
+
+/// Spawns the circular avatar / initials button anchored to the top-right
+/// of the HUD band. Initial content is seeded from whatever resources are
+/// available at startup; `update_hud_avatar` replaces the children whenever
+/// `AvatarResource` or `SettingsResource` later changes.
+pub(super) fn spawn_hud_avatar(
+    font_res: Option<Res<FontResource>>,
+    avatar: Option<Res<AvatarResource>>,
+    settings: Option<Res<SettingsResource>>,
+    mut commands: Commands,
+) {
+    const SIZE: f32 = 32.0;
+    let id = commands
+        .spawn((
+            HudAvatar,
+            Button,
+            Tooltip::new("Your profile — tap to open."),
+            Node {
+                position_type: PositionType::Absolute,
+                top: Val::Px(SPACE_2),
+                right: VAL_SPACE_3,
+                width: Val::Px(SIZE),
+                height: Val::Px(SIZE),
+                border_radius: BorderRadius::all(Val::Px(SIZE / 2.0)),
+                align_items: AlignItems::Center,
+                justify_content: JustifyContent::Center,
+                ..default()
+            },
+            BackgroundColor(ACCENT_PRIMARY),
+            ZIndex(Z_HUD),
+            SafeAreaAnchoredTop { base_top: SPACE_2 },
+        ))
+        .id();
+    spawn_avatar_child(
+        &mut commands,
+        id,
+        avatar.as_deref(),
+        settings.as_deref(),
+        font_res.as_deref(),
+    );
+}
+
+/// Re-spawns the avatar circle content (image or initials) whenever either
+/// [`AvatarResource`] or [`SettingsResource`] changes — covers both the
+/// image arriving after download and the username changing after login.
+pub(super) fn update_hud_avatar(
+    avatar: Option<Res<AvatarResource>>,
+    settings: Option<Res<SettingsResource>>,
+    font_res: Option<Res<FontResource>>,
+    q: Query<Entity, With<HudAvatar>>,
+    mut commands: Commands,
+) {
+    let avatar_changed = avatar.as_ref().is_some_and(|r| r.is_changed());
+    let settings_changed = settings.as_ref().is_some_and(|r| r.is_changed());
+    if !avatar_changed && !settings_changed {
+        return;
+    }
+    let Ok(entity) = q.single() else {
+        return;
+    };
+    commands.entity(entity).despawn_related::<Children>();
+    spawn_avatar_child(
+        &mut commands,
+        entity,
+        avatar.as_deref(),
+        settings.as_deref(),
+        font_res.as_deref(),
+    );
+}
+
+/// Populates the avatar container with either the downloaded image or an
+/// initials fallback disc. Called from both the startup spawn and the
+/// reactive update system so the rendering logic lives in one place.
+pub(super) fn spawn_avatar_child(
+    commands: &mut Commands,
+    parent: Entity,
+    avatar: Option<&AvatarResource>,
+    settings: Option<&SettingsResource>,
+    font_res: Option<&FontResource>,
+) {
+    const SIZE: f32 = 32.0;
+    if let Some(handle) = avatar.and_then(|a| a.0.clone()) {
+        // Logged-in with a downloaded avatar: keep the accent disc behind it.
+        commands.entity(parent).insert(BackgroundColor(ACCENT_PRIMARY));
+        // Image fills the circle container; border_radius clips it to a disc.
+        commands.entity(parent).with_children(|b| {
+            b.spawn((
+                ImageNode::new(handle),
+                Node {
+                    width: Val::Px(SIZE),
+                    height: Val::Px(SIZE),
+                    border_radius: BorderRadius::all(Val::Px(SIZE / 2.0)),
+                    ..default()
+                },
+            ));
+        });
+    } else {
+        let initial = settings
+            .and_then(|s| match &s.0.sync_backend {
+                SyncBackend::SolitaireServer { username, .. } => username.chars().next(),
+                SyncBackend::Local => None,
+            })
+            .and_then(|c| c.to_uppercase().next())
+            .unwrap_or('?');
+        // Real initial (logged in) keeps the red accent disc; the '?'
+        // unauthenticated fallback uses a neutral grey so it reads as a
+        // "tap to log in" affordance rather than an error.
+        let disc_bg = if initial == '?' {
+            BG_ELEVATED_HI
+        } else {
+            ACCENT_PRIMARY
+        };
+        commands.entity(parent).insert(BackgroundColor(disc_bg));
+        commands.entity(parent).with_children(|b| {
+            b.spawn((
+                Text::new(initial.to_string()),
+                TextFont {
+                    font: font_res.map(|f| f.0.clone()).unwrap_or_default(),
+                    font_size: 14.0,
+                    ..default()
+                },
+                TextColor(TEXT_PRIMARY),
+            ));
+        });
+    }
+}
+
+/// Opens the Profile overlay when the avatar button is pressed.
+pub(super) fn handle_avatar_button(
+    interaction_query: Query<&Interaction, (With<HudAvatar>, Changed<Interaction>)>,
+    mut toggle_profile: MessageWriter<ToggleProfileRequestEvent>,
+) {
+    for interaction in &interaction_query {
+        if *interaction == Interaction::Pressed {
+            toggle_profile.write(ToggleProfileRequestEvent);
+        }
+    }
+}
+
+/// Spawns the action button bar anchored to the top-right of the window.
+/// Each child is a clickable button mirroring a keyboard accelerator —
+/// per the UI-first principle (CLAUDE.md / ARCHITECTURE.md §1) the buttons
+/// are the primary entry point and the hotkeys are optional.
+///
+/// Order (left → right): Undo, Pause, Help, New Game. New Game is rightmost
+/// because it's the most consequential action; the destructive button sits
+/// on its own visual edge.
+pub(super) fn spawn_action_buttons(
+    font_res: Option<Res<FontResource>>,
+    windows: Query<&Window>,
+    mut commands: Commands,
+) {
+    let action_font_size =
+        action_bar_font_size(windows.iter().next().map_or(900.0, |win| win.width()));
+    let font = TextFont {
+        font: font_res.as_ref().map(|f| f.0.clone()).unwrap_or_default(),
+        font_size: action_font_size,
+        ..default()
+    };
+
+    // Bottom bar: full-width, centered, sits above the gesture-navigation zone.
+    // `SafeAreaAnchoredBottom` applies the correct logical-pixel inset once
+    // Android reports it (frames 1-3); initial value is 0.0.
+    commands
+        .spawn((
+            Node {
+                position_type: PositionType::Absolute,
+                bottom: Val::Px(0.0),
+                left: Val::Px(0.0),
+                width: Val::Percent(100.0),
+                flex_direction: FlexDirection::Row,
+                flex_wrap: FlexWrap::Wrap,
+                justify_content: JustifyContent::Center,
+                column_gap: ACTION_BAR_COLUMN_GAP,
+                row_gap: VAL_SPACE_2,
+                align_items: AlignItems::Center,
+                padding: UiRect {
+                    left: VAL_SPACE_3,
+                    right: VAL_SPACE_3,
+                    top: VAL_SPACE_2,
+                    bottom: VAL_SPACE_2,
+                },
+                ..default()
+            },
+            BackgroundColor(BG_HUD_BAND),
+            ZIndex(Z_HUD),
+            SafeAreaAnchoredBottom { base_bottom: 0.0 },
+            HudActionBar,
+        ))
+        .with_children(|row| {
+            // The trailing `order` argument feeds `Focusable { group: Hud, order }`
+            // so Tab cycles the action bar in visual reading order.
+            // Undo and Pause are the primary gameplay actions — full brightness.
+            // Menu, Help, Hint, Modes, New are navigation/utility — dimmed.
+            spawn_action_button(
+                row,
+                MenuButton,
+                ACTION_BAR_LABELS[0],
+                None,
+                "Open Stats, Achievements, Profile, Settings, or Leaderboard.",
+                &font,
+                0,
+                TEXT_SECONDARY,
+            );
+            spawn_action_button(
+                row,
+                UndoButton,
+                ACTION_BAR_LABELS[1],
+                Some("U"),
+                "Take back your last move. Costs points and blocks No Undo.",
+                &font,
+                1,
+                TEXT_PRIMARY,
+            );
+            spawn_action_button(
+                row,
+                PauseButton,
+                ACTION_BAR_LABELS[2],
+                Some("Esc"),
+                "Pause the game and freeze the timer.",
+                &font,
+                2,
+                TEXT_PRIMARY,
+            );
+            spawn_action_button(
+                row,
+                HelpButton,
+                ACTION_BAR_LABELS[3],
+                Some("F1"),
+                "Show controls, rules, and keyboard shortcuts.",
+                &font,
+                3,
+                TEXT_SECONDARY,
+            );
+            spawn_action_button(
+                row,
+                HintButton,
+                ACTION_BAR_LABELS[4],
+                Some("H"),
+                "Highlight a suggested move. Cycles through alternatives on repeat taps.",
+                &font,
+                4,
+                TEXT_SECONDARY,
+            );
+            spawn_action_button(
+                row,
+                ModesButton,
+                ACTION_BAR_LABELS[5],
+                None,
+                "Switch modes: Classic, Daily, Zen, Challenge, Time Attack.",
+                &font,
+                5,
+                TEXT_SECONDARY,
+            );
+            spawn_action_button(
+                row,
+                NewGameButton,
+                ACTION_BAR_LABELS[6],
+                Some("N"),
+                "Start a fresh deal. Confirms first if a game is in progress.",
+                &font,
+                6,
+                TEXT_SECONDARY,
+            );
+        });
+}
+
+/// Spawns a single action button as a child of `row`. Each button shares
+/// the same node geometry, idle colour, and `ActionButton` marker so
+/// `paint_action_buttons` can recolour all of them with one query.
+///
+/// `order` is the button's index inside the action bar (0 for the
+/// leftmost). It propagates into the [`Focusable`] this function inserts
+/// so Phase 2's keyboard focus ring cycles the HUD in visual order.
+///
+/// `tooltip` is the hover-reveal caption attached via [`Tooltip`]. Every
+/// action button ships with one — there is no opt-out — because each button
+/// represents a player-triggered action and benefits from a one-line
+/// reminder of what it does.
+#[allow(clippy::too_many_arguments)]
+pub(super) fn spawn_action_button<M: Component>(
+    row: &mut ChildSpawnerCommands,
+    marker: M,
+    label: &str,
+    hotkey: Option<&'static str>,
+    tooltip: &'static str,
+    font: &TextFont,
+    order: i32,
+    text_color: Color,
+) {
+    // Hotkey hint chips ("U", "Esc", "F1", "N") are meaningless on a
+    // touch device — the button itself is the affordance — and they
+    // visibly clutter the narrow-viewport action row. The chevrons on
+    // Menu/Modes remain because they indicate dropdown behaviour.
+    let hotkey = if SHOW_KEYBOARD_ACCELERATORS {
+        hotkey
+    } else {
+        None
+    };
+
+    let hotkey_font = TextFont {
+        font: font.font.clone(),
+        font_size: TYPE_CAPTION,
+        ..default()
+    };
+    let (pad, min_w, min_h) = action_button_metrics();
+
+    row.spawn((
+        marker,
+        ActionButton,
+        Button,
+        Tooltip::new(tooltip),
+        Focusable {
+            group: FocusGroup::Hud,
+            order,
+        },
+        Node {
+            padding: pad,
+            min_width: min_w,
+            min_height: min_h,
+            justify_content: JustifyContent::Center,
+            align_items: AlignItems::Center,
+            border_radius: BorderRadius::all(Val::Px(RADIUS_MD)),
+            column_gap: VAL_SPACE_2,
+            ..default()
+        },
+        BackgroundColor(ACTION_BTN_IDLE),
+        BorderColor::all(BORDER_SUBTLE),
+        HighContrastBorder::with_default(BORDER_SUBTLE),
+    ))
+    .with_children(|b| {
+        spawn_action_button_label(b, label, font, text_color);
+        if let Some(key) = hotkey {
+            // Hotkey hint rendered as a dim caption next to the label —
+            // keeps the keyboard accelerator discoverable without
+            // hijacking the button's primary affordance.
+            b.spawn((Text::new(key), hotkey_font, TextColor(TEXT_SECONDARY)));
+        }
+    });
+}
+

solitaire_engine/src/hud_plugin/tests.rs

@@ -1,4 +1,5 @@
 use super::*;
+use crate::auto_complete_plugin::AutoCompleteState;
 use crate::game_plugin::GamePlugin;
 use crate::table_plugin::TablePlugin;
 use chrono::Local;

solitaire_engine/src/hud_plugin/updates.rs

@@ -0,0 +1,612 @@
+//! Per-frame HUD text/typography/visibility updater systems.
+
+use super::*;
+
+use bevy::window::WindowResized;
+use solitaire_core::{Foundation, KlondikePile, Tableau};
+use solitaire_core::Suit;
+use solitaire_core::{DrawStockConfig, game_state::GameMode};
+
+use crate::auto_complete_plugin::AutoCompleteState;
+
+/// Formats a time-limit value in seconds as `"mm:ss"` for HUD display.
+///
+/// For example `format_time_limit(300)` returns `"5:00"`.
+pub fn format_time_limit(secs: u64) -> String {
+    let m = secs / 60;
+    let s = secs % 60;
+    format!("{m}:{s:02}")
+}
+
+// ---------------------------------------------------------------------------
+// Score-change feedback (G2)
+//
+// The flow for each Update tick:
+//   1. `detect_score_change` diffs `GameStateResource.score` against
+//      `PreviousScore`. On any positive delta it inserts/refreshes
+//      `ScorePulse` on the score readout; on a delta ≥
+//      `SCORE_FLOATER_THRESHOLD` it also spawns a floating "+N" UI text
+//      anchored just below the score.
+//   2. `advance_score_pulse` ticks the pulse component, applies the
+//      triangular 1.0 → 1.1 → 1.0 scale curve, and removes the
+//      component on completion.
+//   3. `advance_score_floater` drifts each floater upward, fades it to
+//      transparent, and despawns it when its lifetime expires.
+//
+// The threshold of 50 (a foundation promotion's typical bonus) keeps
+// floaters rare and meaningful — see `SCORE_FLOATER_THRESHOLD`.
+// ---------------------------------------------------------------------------
+
+/// Sets the [`HudWonPreviously`] text to "✓ Won before" whenever the
+/// current deal's seed + draw_mode + mode triple matches an entry in
+/// the rolling [`ReplayHistory`]. Cleared while the active game is won
+/// (the on-screen "Game won!" cue already conveys victory) and on
+/// fresh deals the player hasn't won before.
+///
+/// Lives in its own system rather than `update_hud` to keep this
+/// orthogonal: `update_hud`'s query disambiguation is already busy
+/// enough; threading another marker through every Without filter
+/// would touch ~10 unrelated queries for no benefit.
+pub(super) fn update_won_previously(
+    game: Res<GameStateResource>,
+    // Optional because the HUD plugin's headless tests run without
+    // `StatsPlugin` and therefore without this resource. With the
+    // resource absent there's no history to compare against; the
+    // indicator just stays empty.
+    history: Option<Res<crate::stats_plugin::ReplayHistoryResource>>,
+    mut q: Query<&mut Text, With<HudWonPreviously>>,
+) {
+    let Ok(mut text) = q.single_mut() else {
+        return;
+    };
+    let won_before = !game.0.is_won()
+        && history.as_ref().is_some_and(|h| {
+            h.0.replays.iter().any(|r| {
+                r.seed == game.0.seed && r.draw_mode == game.0.draw_mode() && r.mode == game.0.mode
+            })
+        });
+    let next = if won_before {
+        "\u{2713} Won before"
+    } else {
+        ""
+    };
+    if text.0 != next {
+        text.0 = next.to_string();
+    }
+}
+
+#[allow(clippy::type_complexity, clippy::too_many_arguments)]
+pub(super) fn update_hud(
+    game: Res<GameStateResource>,
+    time_attack: Option<Res<TimeAttackResource>>,
+    daily: Option<Res<DailyChallengeResource>>,
+    auto_complete: Option<Res<AutoCompleteState>>,
+    mut score_q: Query<
+        &mut Text,
+        (
+            With<HudScore>,
+            Without<HudMoves>,
+            Without<HudTime>,
+            Without<HudMode>,
+            Without<HudChallenge>,
+            Without<HudUndos>,
+            Without<HudAutoComplete>,
+            Without<HudRecycles>,
+            Without<HudDrawCycle>,
+            Without<HudSelection>,
+        ),
+    >,
+    mut moves_q: Query<
+        &mut Text,
+        (
+            With<HudMoves>,
+            Without<HudScore>,
+            Without<HudTime>,
+            Without<HudMode>,
+            Without<HudChallenge>,
+            Without<HudUndos>,
+            Without<HudAutoComplete>,
+            Without<HudRecycles>,
+            Without<HudDrawCycle>,
+            Without<HudSelection>,
+        ),
+    >,
+    mut time_q: Query<
+        &mut Text,
+        (
+            With<HudTime>,
+            Without<HudScore>,
+            Without<HudMoves>,
+            Without<HudMode>,
+            Without<HudChallenge>,
+            Without<HudUndos>,
+            Without<HudAutoComplete>,
+            Without<HudRecycles>,
+            Without<HudDrawCycle>,
+            Without<HudSelection>,
+        ),
+    >,
+    mut mode_q: Query<
+        &mut Text,
+        (
+            With<HudMode>,
+            Without<HudScore>,
+            Without<HudMoves>,
+            Without<HudTime>,
+            Without<HudChallenge>,
+            Without<HudUndos>,
+            Without<HudAutoComplete>,
+            Without<HudRecycles>,
+            Without<HudDrawCycle>,
+            Without<HudSelection>,
+        ),
+    >,
+    mut challenge_q: Query<
+        (&mut Text, &mut TextColor),
+        (
+            With<HudChallenge>,
+            Without<HudScore>,
+            Without<HudMoves>,
+            Without<HudTime>,
+            Without<HudMode>,
+            Without<HudUndos>,
+            Without<HudAutoComplete>,
+            Without<HudRecycles>,
+            Without<HudDrawCycle>,
+            Without<HudSelection>,
+        ),
+    >,
+    mut undos_q: Query<
+        (&mut Text, &mut TextColor),
+        (
+            With<HudUndos>,
+            Without<HudScore>,
+            Without<HudMoves>,
+            Without<HudTime>,
+            Without<HudMode>,
+            Without<HudChallenge>,
+            Without<HudAutoComplete>,
+            Without<HudRecycles>,
+            Without<HudDrawCycle>,
+            Without<HudSelection>,
+        ),
+    >,
+    mut auto_q: Query<
+        &mut Text,
+        (
+            With<HudAutoComplete>,
+            Without<HudScore>,
+            Without<HudMoves>,
+            Without<HudTime>,
+            Without<HudMode>,
+            Without<HudChallenge>,
+            Without<HudUndos>,
+            Without<HudRecycles>,
+            Without<HudDrawCycle>,
+            Without<HudSelection>,
+        ),
+    >,
+    mut recycles_q: Query<
+        &mut Text,
+        (
+            With<HudRecycles>,
+            Without<HudScore>,
+            Without<HudMoves>,
+            Without<HudTime>,
+            Without<HudMode>,
+            Without<HudChallenge>,
+            Without<HudUndos>,
+            Without<HudAutoComplete>,
+            Without<HudDrawCycle>,
+            Without<HudSelection>,
+        ),
+    >,
+    mut draw_cycle_q: Query<
+        &mut Text,
+        (
+            With<HudDrawCycle>,
+            Without<HudScore>,
+            Without<HudMoves>,
+            Without<HudTime>,
+            Without<HudMode>,
+            Without<HudChallenge>,
+            Without<HudUndos>,
+            Without<HudAutoComplete>,
+            Without<HudRecycles>,
+            Without<HudSelection>,
+        ),
+    >,
+) {
+    let ta_active = time_attack.as_ref().is_some_and(|ta| ta.active);
+
+    // Score, moves, mode, challenge, and undos only need updating when game state changes.
+    if game.is_changed() {
+        let g = &game.0;
+        let is_zen = g.mode == GameMode::Zen;
+        if let Ok(mut t) = score_q.single_mut() {
+            // Zen mode suppresses score display per spec ("No score display").
+            **t = if is_zen {
+                String::new()
+            } else {
+                format!("Score: {}", g.score())
+            };
+        }
+        if let Ok(mut t) = moves_q.single_mut() {
+            **t = format!("Moves: {}", g.move_count());
+        }
+        if let Ok(mut t) = mode_q.single_mut() {
+            **t = match g.mode {
+                GameMode::Classic => match g.draw_mode() {
+                    DrawStockConfig::DrawOne => String::new(),
+                    DrawStockConfig::DrawThree => "Draw 3".to_string(),
+                },
+                GameMode::Zen => "ZEN".to_string(),
+                GameMode::Challenge => "CHALLENGE".to_string(),
+                GameMode::TimeAttack => "TIME ATTACK".to_string(),
+                GameMode::Difficulty(level) => level.label().to_uppercase(),
+            };
+        }
+
+        // --- Daily challenge constraint (with time-low colour warning) ---
+        if let Ok((mut t, mut color)) = challenge_q.single_mut() {
+            if g.is_won() {
+                **t = String::new();
+            } else if let Some(dc) = daily.as_deref() {
+                **t = challenge_hud_text(dc);
+                if let Some(max_secs) = dc.max_time_secs {
+                    let remaining = max_secs.saturating_sub(g.elapsed_seconds);
+                    *color = TextColor(challenge_time_color(remaining));
+                }
+            } else {
+                **t = String::new();
+            }
+        }
+
+        // --- Undo count ---
+        if let Ok((mut t, mut color)) = undos_q.single_mut() {
+            let count = g.undo_count();
+            if count == 0 {
+                **t = String::new();
+                *color = TextColor(TEXT_PRIMARY);
+            } else {
+                **t = format!("Undos: {count}");
+                // STATE_WARNING signals "you took a penalty" — same hue
+                // as the Recycles counter so they read as one category.
+                *color = TextColor(STATE_WARNING);
+            }
+        }
+
+        // --- Recycle counter (both modes, hidden until first recycle) ---
+        if let Ok(mut t) = recycles_q.single_mut() {
+            **t = if g.recycle_count() > 0 {
+                format!("Recycles: {}", g.recycle_count())
+            } else {
+                String::new()
+            };
+        }
+
+        // --- Draw-cycle indicator (Draw-Three mode only) ---
+        if let Ok(mut t) = draw_cycle_q.single_mut() {
+            **t = if g.is_won() || g.draw_mode() != DrawStockConfig::DrawThree {
+                // Hide when not in Draw-Three or after the game is won.
+                String::new()
+            } else {
+                let stock_len = g.stock_cards().len();
+                let next_draw = stock_len.min(3);
+                format!("Cycle: {next_draw}/3")
+            };
+        }
+    }
+
+    // Time display: show Time Attack countdown every frame when active;
+    // Zen mode suppresses the timer per spec ("No timer") — cleared unconditionally
+    // every frame so it disappears immediately on the frame Z is pressed.
+    // Otherwise show game elapsed time (updates once per second via game.is_changed()).
+    let is_zen = game.0.mode == GameMode::Zen;
+    let update_time = (ta_active || game.is_changed()) && !is_zen;
+    if update_time {
+        if let Ok(mut t) = time_q.single_mut() {
+            if let Some(ta) = time_attack.as_ref().filter(|ta| ta.active) {
+                let remaining = ta.remaining_secs.max(0.0) as u64;
+                let m = remaining / 60;
+                let s = remaining % 60;
+                **t = format!("{m}:{s:02}");
+            } else {
+                let secs = game.0.elapsed_seconds;
+                let m = secs / 60;
+                let s = secs % 60;
+                **t = format!("{m}:{s:02}");
+            }
+        }
+    } else if is_zen {
+        // Clear the time display immediately whenever Zen mode is active —
+        // do not guard on game.is_changed() so it clears on the same frame
+        // the player presses Z, before any move is made.
+        if let Ok(mut t) = time_q.single_mut() {
+            **t = String::new();
+        }
+    }
+
+    // --- Auto-complete badge ---
+    // Reflects the AutoCompleteState resource; update whenever it changes or game changes.
+    let ac_active = auto_complete.as_ref().is_some_and(|ac| ac.active);
+    let ac_changed = auto_complete.as_ref().is_some_and(|ac| ac.is_changed());
+    if (ac_changed || game.is_changed())
+        && let Ok(mut t) = auto_q.single_mut()
+    {
+        **t = if ac_active {
+            "AUTO".to_string()
+        } else {
+            String::new()
+        };
+    }
+}
+
+/// Updates the `HudSelection` text node to show which pile is Tab-selected.
+///
+/// Displays `"▶ {pile_name}"` while `SelectionState::selected_pile` is `Some`,
+/// or an empty string when no pile is selected. Runs every frame so the
+/// indicator stays in sync with the selection resource.
+pub(super) fn update_selection_hud(
+    selection: Option<Res<SelectionState>>,
+    game: Option<Res<GameStateResource>>,
+    mut q: Query<&mut Text, With<HudSelection>>,
+) {
+    let Ok(mut t) = q.single_mut() else { return };
+    let label = match selection.as_deref().and_then(|s| s.selected_pile.as_ref()) {
+        None => String::new(),
+        Some(KlondikePile::Stock) => "▶ Waste".to_string(),
+        Some(KlondikePile::Foundation(slot)) => match game.as_deref() {
+            Some(g) => foundation_selection_label(*slot, &g.0),
+            // No game resource means we can't probe claimed_suit; show the
+            // slot-based placeholder so the HUD still surfaces the selection.
+            None => format!("▶ Foundation {}", foundation_number(*slot)),
+        },
+        Some(KlondikePile::Tableau(idx)) => format!("▶ Column {}", tableau_number(*idx)),
+    };
+    **t = label;
+}
+
+/// Returns the HUD selection label for a foundation slot.
+///
+/// When the slot has a claimed suit (any card has landed) the announcement is
+/// "▶ {Suit} Foundation"; while the slot is empty it falls back to a
+/// "▶ Foundation N" placeholder labelled by the 1-based slot index.
+pub(super) fn foundation_selection_label(
+    slot: Foundation,
+    game: &solitaire_core::game_state::GameState,
+) -> String {
+    let claimed = game
+        .pile(KlondikePile::Foundation(slot))
+        .first()
+        .map(|c| c.0.suit());
+    match claimed {
+        Some(suit) => {
+            let s = match suit {
+                Suit::Clubs => "Clubs",
+                Suit::Diamonds => "Diamonds",
+                Suit::Hearts => "Hearts",
+                Suit::Spades => "Spades",
+            };
+            format!("▶ {s} Foundation")
+        }
+        None => format!("▶ Foundation {}", foundation_number(slot)),
+    }
+}
+
+const fn foundation_number(foundation: Foundation) -> u8 {
+    match foundation {
+        Foundation::Foundation1 => 1,
+        Foundation::Foundation2 => 2,
+        Foundation::Foundation3 => 3,
+        Foundation::Foundation4 => 4,
+    }
+}
+
+const fn tableau_number(tableau: Tableau) -> u8 {
+    match tableau {
+        Tableau::Tableau1 => 1,
+        Tableau::Tableau2 => 2,
+        Tableau::Tableau3 => 3,
+        Tableau::Tableau4 => 4,
+        Tableau::Tableau5 => 5,
+        Tableau::Tableau6 => 6,
+        Tableau::Tableau7 => 7,
+    }
+}
+
+/// Fires `InfoToastEvent("Auto-completing...")` exactly once each time
+/// `AutoCompleteState` transitions from inactive to active. Uses a `Local<bool>`
+/// to debounce so the toast only appears on the leading edge.
+pub(super) fn announce_auto_complete(
+    auto_complete: Option<Res<AutoCompleteState>>,
+    mut toast: MessageWriter<InfoToastEvent>,
+    mut was_active: Local<bool>,
+) {
+    let now_active = auto_complete.as_ref().is_some_and(|ac| ac.active);
+    if now_active && !*was_active {
+        toast.write(InfoToastEvent("Auto-completing...".to_string()));
+    }
+    *was_active = now_active;
+}
+
+/// Builds the HUD text for the active daily challenge constraints.
+///
+/// Returns `"Limit: mm:ss"` when a time limit is set, `"Goal: N pts"` when a
+/// score target is set, or an empty string when the challenge has no extra
+/// constraints.
+pub(super) fn challenge_hud_text(dc: &DailyChallengeResource) -> String {
+    if let Some(secs) = dc.max_time_secs {
+        format!("Limit: {}", format_time_limit(secs))
+    } else if let Some(score) = dc.target_score {
+        format!("Goal: {score} pts")
+    } else {
+        String::new()
+    }
+}
+
+/// Returns the colour for the challenge time-limit HUD label based on
+/// seconds remaining. Uses theme tokens so the urgency ramp picks up
+/// palette changes for free.
+///
+/// | Remaining   | Token            |
+/// |-------------|------------------|
+/// | ≥ 60 s      | `STATE_INFO`     |
+/// | 30 – 59 s   | `STATE_WARNING`  |
+/// | < 30 s      | `STATE_DANGER`   |
+pub fn challenge_time_color(remaining: u64) -> Color {
+    if remaining < 30 {
+        STATE_DANGER
+    } else if remaining < 60 {
+        STATE_WARNING
+    } else {
+        STATE_INFO
+    }
+}
+
+/// Scales HUD Tier-1 font sizes to fit a narrow viewport.
+///
+/// Fires on every `WindowResized` event. Below 480 logical pixels wide the
+/// score drops from `TYPE_HEADLINE` (26 px) to `TYPE_BODY_LG` (18 px) and the
+/// Moves/Timer labels drop from `TYPE_BODY_LG` to `TYPE_CAPTION` (11 px), so
+/// all three items remain on one row inside the 50 %-wide HUD column
+/// (≈ 180 dp on a 360 dp phone).  At ≥ 480 px the original sizes are
+/// restored so desktop/tablet layouts are unaffected.
+type HudScoreFont<'w, 's> =
+    Query<'w, 's, &'static mut TextFont, (With<HudScore>, Without<HudMoves>, Without<HudTime>)>;
+type HudMovesFont<'w, 's> =
+    Query<'w, 's, &'static mut TextFont, (With<HudMoves>, Without<HudScore>, Without<HudTime>)>;
+type HudTimeFont<'w, 's> =
+    Query<'w, 's, &'static mut TextFont, (With<HudTime>, Without<HudScore>, Without<HudMoves>)>;
+
+pub(super) fn update_hud_typography(
+    mut events: MessageReader<WindowResized>,
+    mut score_q: HudScoreFont,
+    mut moves_q: HudMovesFont,
+    mut time_q: HudTimeFont,
+) {
+    let Some(ev) = events.read().last() else {
+        return;
+    };
+    let (score_size, secondary_size) = if ev.width < 480.0 {
+        (TYPE_BODY_LG, TYPE_CAPTION)
+    } else {
+        (TYPE_HEADLINE, TYPE_BODY_LG)
+    };
+    for mut font in &mut score_q {
+        font.font_size = score_size;
+    }
+    for mut font in &mut moves_q {
+        font.font_size = secondary_size;
+    }
+    for mut font in &mut time_q {
+        font.font_size = secondary_size;
+    }
+}
+
+pub(super) fn apply_hud_visibility(
+    hud_vis: Res<HudVisibility>,
+    mut action_bar: Query<&mut Visibility, With<HudActionBar>>,
+) {
+    if !hud_vis.is_changed() {
+        return;
+    }
+    let v = if *hud_vis == HudVisibility::Visible {
+        Visibility::Visible
+    } else {
+        Visibility::Hidden
+    };
+    for mut vis in &mut action_bar {
+        *vis = v;
+    }
+    // The bottom action bar is a pure overlay — it does not claim any
+    // space in the card layout, so no WindowResized event is needed.
+}
+
+pub(super) fn restore_hud_on_modal(
+    new_scrims: Query<(), (With<ModalScrim>, Added<ModalScrim>)>,
+    mut hud_vis: ResMut<HudVisibility>,
+) {
+    if !new_scrims.is_empty() {
+        *hud_vis = HudVisibility::Visible;
+    }
+}
+
+/// Returns the action-bar label font size for a given logical window width.
+pub(super) fn action_bar_font_size(window_width: f32) -> f32 {
+    if USE_TOUCH_UI_LAYOUT {
+        // Seven word-labels ("Menu","Undo","Pause","Help","Hint","Mode","New")
+        // must share one row. The widest characters are in FiraMono (a
+        // monospace whose advance is ~0.62 of the font size). On a 900
+        // logical-px phone the row budget after bar padding (2*12) and six
+        // 4 px column gaps is ~852 px for ~28 label chars + 7*2*3 px button
+        // padding. Solving 28*0.62*size + 42 <= 852 gives size <= ~46, so the
+        // labels are advance-bound only on very narrow viewports; the real
+        // constraint is legibility, not fit. ~1/60 of the width yields ~15 px
+        // at 900 px — comfortably one row with margin to spare — clamped so it
+        // never drops below the 12 px legibility floor or grows past 18 px on
+        // landscape tablets where it would crowd the row again.
+        (window_width / 60.0).clamp(12.0, 18.0)
+    } else {
+        TYPE_BODY
+    }
+}
+
+pub(super) fn action_button_metrics() -> (UiRect, Val, Val) {
+    if USE_TOUCH_UI_LAYOUT {
+        // Tight 3 px horizontal padding (down from 4) trims 14 px off the row
+        // total across 7 buttons, and a 44 px min_width (down from 52) lets the
+        // shortest labels ("New", "Help") shrink to their text rather than
+        // padding the row out past the 900 logical-px viewport. min_height
+        // stays at 44 px to preserve the comfortable touch target.
+        (
+            UiRect::axes(Val::Px(3.0), Val::Px(4.0)),
+            Val::Px(44.0),
+            Val::Px(44.0),
+        )
+    } else {
+        (
+            UiRect::axes(VAL_SPACE_2, VAL_SPACE_2),
+            Val::Px(48.0),
+            Val::Px(48.0),
+        )
+    }
+}
+
+pub(super) fn spawn_action_button_label(
+    parent: &mut ChildSpawnerCommands,
+    label: &str,
+    font: &TextFont,
+    text_color: Color,
+) {
+    if USE_TOUCH_UI_LAYOUT {
+        parent.spawn((
+            ActionButtonLabel,
+            Text::new(label),
+            font.clone(),
+            TextColor(text_color),
+        ));
+    } else {
+        parent.spawn((Text::new(label), font.clone(), TextColor(text_color)));
+    }
+}
+
+/// Resizes the glyph text inside every [`ActionButtonLabel`] to match the
+/// current viewport width whenever [`LayoutResource`] changes (orientation
+/// change or window resize).
+#[cfg(target_os = "android")]
+pub(super) fn resize_action_bar_labels(
+    layout: Res<crate::layout::LayoutResource>,
+    windows: Query<&Window>,
+    mut labels: Query<&mut TextFont, With<ActionButtonLabel>>,
+) {
+    let w = windows
+        .iter()
+        .next()
+        .map_or(layout.0.card_size.x * 7.25, |win| win.width());
+    let new_size = action_bar_font_size(w);
+    for mut font in &mut labels {
+        font.font_size = new_size;
+    }
+}
+

solitaire_engine/src/settings_plugin/input.rs

@@ -0,0 +1,627 @@
+//! Input handling for the Settings panel: button presses, keyboard
+//! accelerators, focus attachment, and scrolling.
+
+use super::*;
+
+use bevy::input::mouse::{MouseScrollUnit, MouseWheel};
+use bevy::ui::{ComputedNode, UiGlobalTransform};
+use solitaire_core::DrawStockConfig;
+use solitaire_data::{
+    AnimSpeed, REPLAY_MOVE_INTERVAL_STEP_SECS, TIME_BONUS_MULTIPLIER_STEP, TOOLTIP_DELAY_STEP_SECS,
+    settings::Theme,
+};
+
+use crate::events::{
+    DeleteAccountRequestEvent, InfoToastEvent, ManualSyncRequestEvent, SyncConfigureRequestEvent,
+    SyncLogoutRequestEvent, ToggleSettingsRequestEvent,
+};
+use crate::ui_focus::{FocusGroup, Focusable, FocusedButton};
+use crate::ui_modal::{ModalButton, ModalScrim};
+use crate::ui_theme::SPACE_2;
+
+pub(super) fn handle_volume_keys(
+    keys: Res<ButtonInput<KeyCode>>,
+    mut settings: ResMut<SettingsResource>,
+    path: Res<SettingsStoragePath>,
+    mut changed: MessageWriter<SettingsChangedEvent>,
+    mut toast: MessageWriter<InfoToastEvent>,
+) {
+    let mut delta = 0.0_f32;
+    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 {
+        return;
+    }
+    persist(&path, &settings.0);
+    changed.write(SettingsChangedEvent(settings.0.clone()));
+    toast.write(InfoToastEvent(format!(
+        "SFX volume: {}%",
+        (after * 100.0).round() as i32
+    )));
+}
+
+/// Opens or closes the Settings panel — `O` keyboard accelerator or
+/// `ToggleSettingsRequestEvent` from the HUD Menu popover.
+pub(super) fn toggle_settings_screen(
+    keys: Res<ButtonInput<KeyCode>>,
+    mut requests: MessageReader<ToggleSettingsRequestEvent>,
+    mut screen: ResMut<SettingsScreen>,
+) {
+    let button_clicked = requests.read().count() > 0;
+    if keys.just_pressed(KeyCode::KeyO) || button_clicked {
+        screen.0 = !screen.0;
+    }
+}
+
+/// Reacts to button presses inside the Settings panel.
+#[allow(clippy::too_many_arguments, clippy::type_complexity)]
+pub(super) fn handle_settings_buttons(
+    interaction_query: Query<(&Interaction, &SettingsButton), Changed<Interaction>>,
+    mut settings: ResMut<SettingsResource>,
+    mut screen: ResMut<SettingsScreen>,
+    path: Res<SettingsStoragePath>,
+    mut changed: MessageWriter<SettingsChangedEvent>,
+    mut sfx_text: Query<
+        &mut Text,
+        (
+            With<SfxVolumeText>,
+            Without<MusicVolumeText>,
+            Without<DrawModeText>,
+            Without<ThemeText>,
+            Without<AnimSpeedText>,
+            Without<ColorBlindText>,
+            Without<HighContrastText>,
+            Without<ReduceMotionText>,
+        ),
+    >,
+    mut music_text: Query<
+        &mut Text,
+        (
+            With<MusicVolumeText>,
+            Without<SfxVolumeText>,
+            Without<DrawModeText>,
+            Without<ThemeText>,
+            Without<AnimSpeedText>,
+            Without<ColorBlindText>,
+            Without<HighContrastText>,
+            Without<ReduceMotionText>,
+        ),
+    >,
+    mut draw_text: Query<
+        &mut Text,
+        (
+            With<DrawModeText>,
+            Without<SfxVolumeText>,
+            Without<MusicVolumeText>,
+            Without<ThemeText>,
+            Without<AnimSpeedText>,
+            Without<ColorBlindText>,
+            Without<HighContrastText>,
+            Without<ReduceMotionText>,
+        ),
+    >,
+    mut theme_text: Query<
+        &mut Text,
+        (
+            With<ThemeText>,
+            Without<SfxVolumeText>,
+            Without<MusicVolumeText>,
+            Without<DrawModeText>,
+            Without<AnimSpeedText>,
+            Without<ColorBlindText>,
+            Without<HighContrastText>,
+            Without<ReduceMotionText>,
+        ),
+    >,
+    mut anim_speed_text: Query<
+        &mut Text,
+        (
+            With<AnimSpeedText>,
+            Without<SfxVolumeText>,
+            Without<MusicVolumeText>,
+            Without<DrawModeText>,
+            Without<ThemeText>,
+            Without<ColorBlindText>,
+            Without<HighContrastText>,
+            Without<ReduceMotionText>,
+        ),
+    >,
+    mut color_blind_text: Query<
+        &mut Text,
+        (
+            With<ColorBlindText>,
+            Without<SfxVolumeText>,
+            Without<MusicVolumeText>,
+            Without<DrawModeText>,
+            Without<ThemeText>,
+            Without<AnimSpeedText>,
+            Without<HighContrastText>,
+            Without<ReduceMotionText>,
+        ),
+    >,
+    mut high_contrast_text: Query<
+        &mut Text,
+        (
+            With<HighContrastText>,
+            Without<SfxVolumeText>,
+            Without<MusicVolumeText>,
+            Without<DrawModeText>,
+            Without<ThemeText>,
+            Without<AnimSpeedText>,
+            Without<ColorBlindText>,
+            Without<ReduceMotionText>,
+        ),
+    >,
+    mut reduce_motion_text: Query<
+        &mut Text,
+        (
+            With<ReduceMotionText>,
+            Without<SfxVolumeText>,
+            Without<MusicVolumeText>,
+            Without<DrawModeText>,
+            Without<ThemeText>,
+            Without<AnimSpeedText>,
+            Without<ColorBlindText>,
+            Without<HighContrastText>,
+        ),
+    >,
+) {
+    for (interaction, button) in &interaction_query {
+        if *interaction != Interaction::Pressed {
+            continue;
+        }
+        match button {
+            SettingsButton::SfxDown => {
+                let before = settings.0.sfx_volume;
+                let after = settings.0.adjust_sfx_volume(-SFX_STEP);
+                if (before - after).abs() > f32::EPSILON {
+                    persist(&path, &settings.0);
+                    changed.write(SettingsChangedEvent(settings.0.clone()));
+                    if let Ok(mut t) = sfx_text.single_mut() {
+                        **t = format!("{after:.2}");
+                    }
+                }
+            }
+            SettingsButton::SfxUp => {
+                let before = settings.0.sfx_volume;
+                let after = settings.0.adjust_sfx_volume(SFX_STEP);
+                if (before - after).abs() > f32::EPSILON {
+                    persist(&path, &settings.0);
+                    changed.write(SettingsChangedEvent(settings.0.clone()));
+                    if let Ok(mut t) = sfx_text.single_mut() {
+                        **t = format!("{after:.2}");
+                    }
+                }
+            }
+            SettingsButton::MusicDown => {
+                let before = settings.0.music_volume;
+                let after = settings.0.adjust_music_volume(-SFX_STEP);
+                if (before - after).abs() > f32::EPSILON {
+                    persist(&path, &settings.0);
+                    changed.write(SettingsChangedEvent(settings.0.clone()));
+                    if let Ok(mut t) = music_text.single_mut() {
+                        **t = format!("{after:.2}");
+                    }
+                }
+            }
+            SettingsButton::MusicUp => {
+                let before = settings.0.music_volume;
+                let after = settings.0.adjust_music_volume(SFX_STEP);
+                if (before - after).abs() > f32::EPSILON {
+                    persist(&path, &settings.0);
+                    changed.write(SettingsChangedEvent(settings.0.clone()));
+                    if let Ok(mut t) = music_text.single_mut() {
+                        **t = format!("{after:.2}");
+                    }
+                }
+            }
+            SettingsButton::ToggleDrawMode => {
+                settings.0.draw_mode = match settings.0.draw_mode {
+                    DrawStockConfig::DrawOne => DrawStockConfig::DrawThree,
+                    DrawStockConfig::DrawThree => DrawStockConfig::DrawOne,
+                };
+                persist(&path, &settings.0);
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+                if let Ok(mut t) = draw_text.single_mut() {
+                    **t = draw_mode_label(&settings.0.draw_mode);
+                }
+            }
+            SettingsButton::CycleAnimSpeed => {
+                settings.0.animation_speed = match settings.0.animation_speed {
+                    AnimSpeed::Normal => AnimSpeed::Fast,
+                    AnimSpeed::Fast => AnimSpeed::Instant,
+                    AnimSpeed::Instant => AnimSpeed::Normal,
+                };
+                persist(&path, &settings.0);
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+                if let Ok(mut t) = anim_speed_text.single_mut() {
+                    **t = anim_speed_label(&settings.0.animation_speed);
+                }
+            }
+            SettingsButton::TooltipDelayDown => {
+                let before = settings.0.tooltip_delay_secs;
+                let after = settings.0.adjust_tooltip_delay(-TOOLTIP_DELAY_STEP_SECS);
+                if (before - after).abs() > f32::EPSILON {
+                    persist(&path, &settings.0);
+                    changed.write(SettingsChangedEvent(settings.0.clone()));
+                    // The Text node is refreshed by `update_tooltip_delay_text`
+                    // on the next frame via `settings.is_changed()`.
+                }
+            }
+            SettingsButton::TooltipDelayUp => {
+                let before = settings.0.tooltip_delay_secs;
+                let after = settings.0.adjust_tooltip_delay(TOOLTIP_DELAY_STEP_SECS);
+                if (before - after).abs() > f32::EPSILON {
+                    persist(&path, &settings.0);
+                    changed.write(SettingsChangedEvent(settings.0.clone()));
+                }
+            }
+            SettingsButton::TimeBonusDown => {
+                let before = settings.0.time_bonus_multiplier;
+                let after = settings
+                    .0
+                    .adjust_time_bonus_multiplier(-TIME_BONUS_MULTIPLIER_STEP);
+                if (before - after).abs() > f32::EPSILON {
+                    persist(&path, &settings.0);
+                    changed.write(SettingsChangedEvent(settings.0.clone()));
+                    // The Text node is refreshed by
+                    // `update_time_bonus_multiplier_text` on the next
+                    // frame via `settings.is_changed()`.
+                }
+            }
+            SettingsButton::TimeBonusUp => {
+                let before = settings.0.time_bonus_multiplier;
+                let after = settings
+                    .0
+                    .adjust_time_bonus_multiplier(TIME_BONUS_MULTIPLIER_STEP);
+                if (before - after).abs() > f32::EPSILON {
+                    persist(&path, &settings.0);
+                    changed.write(SettingsChangedEvent(settings.0.clone()));
+                }
+            }
+            SettingsButton::ReplayMoveIntervalDown => {
+                let before = settings.0.replay_move_interval_secs;
+                let after = settings
+                    .0
+                    .adjust_replay_move_interval(-REPLAY_MOVE_INTERVAL_STEP_SECS);
+                if (before - after).abs() > f32::EPSILON {
+                    persist(&path, &settings.0);
+                    changed.write(SettingsChangedEvent(settings.0.clone()));
+                    // The Text node is refreshed by
+                    // `update_replay_move_interval_text` on the next
+                    // frame via `settings.is_changed()`.
+                }
+            }
+            SettingsButton::ReplayMoveIntervalUp => {
+                let before = settings.0.replay_move_interval_secs;
+                let after = settings
+                    .0
+                    .adjust_replay_move_interval(REPLAY_MOVE_INTERVAL_STEP_SECS);
+                if (before - after).abs() > f32::EPSILON {
+                    persist(&path, &settings.0);
+                    changed.write(SettingsChangedEvent(settings.0.clone()));
+                }
+            }
+            SettingsButton::ToggleTheme => {
+                settings.0.theme = match settings.0.theme {
+                    Theme::Green => Theme::Blue,
+                    Theme::Blue => Theme::Dark,
+                    Theme::Dark => Theme::Green,
+                };
+                persist(&path, &settings.0);
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+                if let Ok(mut t) = theme_text.single_mut() {
+                    **t = theme_label(&settings.0.theme);
+                }
+            }
+            SettingsButton::ToggleColorBlind => {
+                settings.0.color_blind_mode = !settings.0.color_blind_mode;
+                persist(&path, &settings.0);
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+                if let Ok(mut t) = color_blind_text.single_mut() {
+                    **t = color_blind_label(settings.0.color_blind_mode);
+                }
+            }
+            SettingsButton::ToggleHighContrast => {
+                settings.0.high_contrast_mode = !settings.0.high_contrast_mode;
+                persist(&path, &settings.0);
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+                if let Ok(mut t) = high_contrast_text.single_mut() {
+                    **t = on_off_label(settings.0.high_contrast_mode);
+                }
+            }
+            SettingsButton::ToggleReduceMotion => {
+                settings.0.reduce_motion_mode = !settings.0.reduce_motion_mode;
+                persist(&path, &settings.0);
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+                if let Ok(mut t) = reduce_motion_text.single_mut() {
+                    **t = on_off_label(settings.0.reduce_motion_mode);
+                }
+            }
+            SettingsButton::ToggleTouchInputMode => {
+                use solitaire_data::settings::TouchInputMode;
+                settings.0.touch_input_mode = match settings.0.touch_input_mode {
+                    TouchInputMode::OneTap => TouchInputMode::TapToSelect,
+                    TouchInputMode::TapToSelect => TouchInputMode::OneTap,
+                };
+                persist(&path, &settings.0);
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+                // Text refreshed by `update_touch_input_mode_text` next frame.
+            }
+            SettingsButton::ToggleWinnableDealsOnly => {
+                settings.0.winnable_deals_only = !settings.0.winnable_deals_only;
+                persist(&path, &settings.0);
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+                // The Text node is refreshed by `update_winnable_deals_only_text`
+                // on the next frame via `settings.is_changed()`.
+            }
+            SettingsButton::ToggleAnalytics => {
+                settings.0.analytics_enabled = !settings.0.analytics_enabled;
+                persist(&path, &settings.0);
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+                // Text refreshed by `update_analytics_enabled_text` next frame.
+            }
+            SettingsButton::ToggleSmartDefaultSize => {
+                settings.0.disable_smart_default_size = !settings.0.disable_smart_default_size;
+                persist(&path, &settings.0);
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+                // The Text node is refreshed by
+                // `update_smart_default_size_text` next frame. The
+                // sizer system is gated only at startup, so flipping
+                // this mid-session takes effect on the next launch —
+                // documented on the field in `solitaire_data::Settings`.
+            }
+            SettingsButton::SelectCardBack(idx) => {
+                settings.0.selected_card_back = *idx;
+                persist(&path, &settings.0);
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+            }
+            SettingsButton::SelectBackground(idx) => {
+                settings.0.selected_background = *idx;
+                persist(&path, &settings.0);
+                changed.write(SettingsChangedEvent(settings.0.clone()));
+            }
+            SettingsButton::SelectTheme(theme_id) => {
+                if settings.0.selected_theme_id != *theme_id {
+                    settings.0.selected_theme_id = theme_id.clone();
+                    persist(&path, &settings.0);
+                    changed.write(SettingsChangedEvent(settings.0.clone()));
+                }
+            }
+            #[cfg(not(target_arch = "wasm32"))]
+            SettingsButton::ScanThemes => {
+                // Handled by `handle_scan_themes`.
+            }
+            SettingsButton::SyncNow
+            | SettingsButton::ConnectSync
+            | SettingsButton::DisconnectSync
+            | SettingsButton::DeleteAccount => {
+                // Handled by `handle_sync_buttons`.
+            }
+            SettingsButton::Done => {
+                screen.0 = false;
+            }
+        }
+    }
+}
+
+/// Handles sync-related settings buttons: Sync Now, Connect, Disconnect,
+/// and Delete Account. Split from `handle_settings_buttons` to stay within
+/// Bevy's 16-parameter system limit.
+pub(super) fn handle_sync_buttons(
+    interaction_query: Query<(&Interaction, &SettingsButton), Changed<Interaction>>,
+    mut manual_sync: MessageWriter<ManualSyncRequestEvent>,
+    mut configure_sync: MessageWriter<SyncConfigureRequestEvent>,
+    mut logout_sync: MessageWriter<SyncLogoutRequestEvent>,
+    mut delete_account: MessageWriter<DeleteAccountRequestEvent>,
+    mut screen: ResMut<SettingsScreen>,
+) {
+    for (interaction, button) in &interaction_query {
+        if *interaction != Interaction::Pressed {
+            continue;
+        }
+        match button {
+            SettingsButton::SyncNow => {
+                manual_sync.write(ManualSyncRequestEvent);
+            }
+            SettingsButton::ConnectSync => {
+                // Close settings before the sync-setup modal opens so the
+                // guard in open_sync_setup_modal doesn't block on our own scrim.
+                screen.0 = false;
+                configure_sync.write(SyncConfigureRequestEvent);
+            }
+            SettingsButton::DisconnectSync => {
+                logout_sync.write(SyncLogoutRequestEvent);
+            }
+            SettingsButton::DeleteAccount => {
+                delete_account.write(DeleteAccountRequestEvent);
+            }
+            _ => {}
+        }
+    }
+}
+
+/// Auto-attaches [`Focusable`] to every bespoke Settings button — icon
+/// buttons (volume +/−, toggle, cycle), swatch buttons (card-back,
+/// background pickers), and the "Sync Now" button. The "Done" button is
+/// already tagged by `attach_focusable_to_modal_buttons` (it carries
+/// [`ModalButton`]) and is filtered out here.
+///
+/// Walks ancestors via [`ChildOf`] to find the [`ModalScrim`] that owns
+/// the panel so the new [`Focusable`]'s group is bound to that scrim —
+/// same defensive shape as the Phase 1 / 2 attach systems.
+#[allow(clippy::type_complexity)]
+pub(super) fn attach_focusable_to_settings_buttons(
+    mut commands: Commands,
+    new_buttons: Query<
+        (Entity, &SettingsButton),
+        (With<Button>, Without<Focusable>, Without<ModalButton>),
+    >,
+    parents: Query<&ChildOf>,
+    scrims: Query<(), With<ModalScrim>>,
+) {
+    for (button, settings_button) in &new_buttons {
+        let mut current = button;
+        let mut scrim_entity: Option<Entity> = None;
+        for _ in 0..32 {
+            if scrims.get(current).is_ok() {
+                scrim_entity = Some(current);
+                break;
+            }
+            match parents.get(current) {
+                Ok(parent) => current = parent.parent(),
+                Err(_) => break,
+            }
+        }
+        if let Some(scrim) = scrim_entity {
+            commands.entity(button).insert(Focusable {
+                group: FocusGroup::Modal(scrim),
+                order: settings_button.focus_order(),
+            });
+        }
+    }
+}
+
+/// Vertical padding (logical px) added around the focused button when
+/// scrolling it into view. Keeps the focus ring's halo visible above /
+/// below the viewport edge.
+const FOCUS_SCROLL_PADDING: f32 = SPACE_2;
+
+/// When the focused entity sits outside the visible Settings scroll
+/// viewport, adjust the viewport's [`ScrollPosition`] so the button is
+/// fully visible. No-op when:
+///
+/// - `FocusedButton` is `None`
+/// - the focused entity has no [`UiGlobalTransform`] / [`ComputedNode`]
+///   (e.g. a freshly-spawned modal hasn't laid out yet)
+/// - the focused entity is not a descendant of the
+///   [`SettingsPanelScrollable`] container
+///
+/// The viewport's visible Y range is `[scroll_y, scroll_y +
+/// viewport_height]` in physical pixels (matching `ComputedNode.size`).
+/// The focused button's vertical extent is computed from its
+/// `UiGlobalTransform.translation.y` (centre, physical) ± half its
+/// `ComputedNode.size.y`. Because the scroll container's local
+/// coordinates run [0, content_height] and the visible window is
+/// [scroll_y, scroll_y + viewport], we convert the button's window-
+/// space Y to container-local Y by subtracting the container's window-
+/// space top and adding the current scroll offset.
+#[allow(clippy::type_complexity)]
+pub(super) fn scroll_focus_into_view(
+    focused: Res<FocusedButton>,
+    parents: Query<&ChildOf>,
+    nodes: Query<(&UiGlobalTransform, &ComputedNode)>,
+    mut containers: Query<
+        (&mut ScrollPosition, &UiGlobalTransform, &ComputedNode),
+        With<SettingsPanelScrollable>,
+    >,
+) {
+    let Some(target) = focused.0 else { return };
+    // Gather button geometry.
+    let Ok((target_transform, target_node)) = nodes.get(target) else {
+        return;
+    };
+
+    // Walk ancestors looking for the scroll container. Bounded to keep
+    // a malformed hierarchy from hanging the system.
+    let mut current = target;
+    let mut container_entity: Option<Entity> = None;
+    for _ in 0..32 {
+        if containers.get(current).is_ok() {
+            container_entity = Some(current);
+            break;
+        }
+        match parents.get(current) {
+            Ok(parent) => current = parent.parent(),
+            Err(_) => break,
+        }
+    }
+    let Some(container) = container_entity else {
+        return;
+    };
+
+    let Ok((mut scroll, container_transform, container_node)) = containers.get_mut(container)
+    else {
+        return;
+    };
+
+    // Geometry is reported in physical pixels by `ComputedNode.size` and
+    // `UiGlobalTransform.translation`. `ScrollPosition` is in logical px,
+    // so convert via `inverse_scale_factor` before we write.
+    let inv = target_node.inverse_scale_factor;
+    let target_height = target_node.size().y;
+    let target_centre_y = target_transform.translation.y;
+    let target_top = target_centre_y - target_height * 0.5;
+    let target_bottom = target_centre_y + target_height * 0.5;
+
+    let container_height = container_node.size().y;
+    let container_top = container_transform.translation.y - container_height * 0.5;
+
+    // Convert button window-space Y to container-local Y. The container
+    // is currently scrolled by `scroll.0.y` *logical* pixels — multiply
+    // by physical-per-logical to compare with physical pixel extents.
+    let scroll_phys = scroll.0.y / inv.max(f32::EPSILON);
+    let viewport_top = container_top + scroll_phys;
+    let viewport_bottom = viewport_top + container_height;
+
+    // Layout may not have run yet (zero size on first frame) — no
+    // sensible scroll target until the container has dimensions.
+    if container_height <= 0.0 {
+        return;
+    }
+
+    let pad_phys = FOCUS_SCROLL_PADDING / inv.max(f32::EPSILON);
+    if target_top < viewport_top {
+        // Button extends above the viewport — scroll up.
+        let new_top = target_top - pad_phys;
+        let delta = new_top - viewport_top;
+        scroll.0.y = ((scroll_phys + delta) * inv).max(0.0);
+    } else if target_bottom > viewport_bottom {
+        // Button extends below the viewport — scroll down.
+        let new_bottom = target_bottom + pad_phys;
+        let delta = new_bottom - viewport_bottom;
+        scroll.0.y = ((scroll_phys + delta) * inv).max(0.0);
+    }
+}
+
+/// Scrolls the settings panel inner card in response to mouse-wheel events.
+///
+/// `offset_y` increases downward (0 = top of content). Scrolling down (ev.y < 0)
+/// adds to the offset; scrolling up subtracts. Clamped to >= 0 so it never
+/// scrolls past the top.
+pub(super) fn scroll_settings_panel(
+    mut scroll_evr: MessageReader<MouseWheel>,
+    screen: Res<SettingsScreen>,
+    mut scrollables: Query<&mut ScrollPosition, With<SettingsPanelScrollable>>,
+) {
+    if !screen.0 {
+        scroll_evr.clear();
+        return;
+    }
+    let delta_y: f32 = scroll_evr
+        .read()
+        .map(|ev| match ev.unit {
+            MouseScrollUnit::Line => ev.y * 50.0,
+            MouseScrollUnit::Pixel => ev.y,
+        })
+        .sum();
+    if delta_y == 0.0 {
+        return;
+    }
+    for mut sp in scrollables.iter_mut() {
+        sp.0.y = (sp.0.y - delta_y).max(0.0);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Window geometry persistence
+// ---------------------------------------------------------------------------

solitaire_engine/src/settings_plugin/tests.rs

@@ -1,4 +1,7 @@
 use super::*;
+use crate::ui_focus::{FocusRow, Focusable};
+use crate::ui_modal::ModalButton;
+use crate::ui_tooltip::Tooltip;
 
 fn headless_app() -> App {
     let mut app = App::new();
@@ -326,9 +329,7 @@ fn settings_buttons_carry_tooltip() {
         .world_mut()
         .query::<(&SettingsButton, &Tooltip)>()
         .iter(app.world())
-        .find_map(|(btn, tip)| {
-            matches!(btn, SettingsButton::ConnectSync).then(|| tip.0.clone())
-        })
+        .find_map(|(btn, tip)| matches!(btn, SettingsButton::ConnectSync).then(|| tip.0.clone()))
         .expect("Connect button should spawn with a Tooltip when backend is Local");
     assert_eq!(
         connect_tip.as_ref(),

solitaire_engine/src/settings_plugin/updates.rs

@@ -0,0 +1,487 @@
+//! Per-frame value-text updater systems and their label helpers.
+
+use super::*;
+
+use solitaire_core::DrawStockConfig;
+use solitaire_data::{AnimSpeed, settings::Theme};
+
+use crate::font_plugin::FontResource;
+use crate::progress_plugin::ProgressResource;
+use crate::resources::{SettingsScrollPos, SyncStatus, SyncStatusResource};
+use crate::theme::ThemeThumbnailCache;
+use crate::ui_modal::ModalScrim;
+use crate::ui_theme::{BORDER_SUBTLE_HC, HighContrastBackground, HighContrastBorder};
+
+/// Spawns the Settings panel when `SettingsScreen` becomes `true`;
+/// despawns it when it becomes `false`.
+#[allow(clippy::too_many_arguments)]
+pub(super) fn sync_settings_panel_visibility(
+    screen: Res<SettingsScreen>,
+    panels: Query<Entity, With<SettingsPanel>>,
+    other_modal_scrims: Query<(), (With<ModalScrim>, Without<SettingsPanel>)>,
+    scroll_nodes: Query<&ScrollPosition, With<SettingsScrollNode>>,
+    mut scroll_pos: ResMut<SettingsScrollPos>,
+    mut commands: Commands,
+    settings: Res<SettingsResource>,
+    sync_status: Option<Res<SyncStatusResource>>,
+    progress: Option<Res<ProgressResource>>,
+    font_res: Option<Res<FontResource>>,
+    theme_registry: Option<Res<crate::theme::ThemeRegistry>>,
+    theme_thumbs: Option<Res<ThemeThumbnailCache>>,
+    card_images: Option<Res<crate::card_plugin::CardImageSet>>,
+) {
+    if !screen.is_changed() {
+        return;
+    }
+    if screen.0 {
+        if panels.is_empty() && other_modal_scrims.is_empty() {
+            let status_label = sync_status.map_or_else(
+                || "Status: local only".to_string(),
+                |s| sync_status_label(&s.0),
+            );
+            let unlocked_backs = progress
+                .as_ref()
+                .map_or(&[0][..], |p| p.0.unlocked_card_backs.as_slice());
+            let unlocked_bgs = progress
+                .as_ref()
+                .map_or(&[0][..], |p| p.0.unlocked_backgrounds.as_slice());
+            // Snapshot themes by id, display_name and (optional)
+            // thumbnail pair so spawn_settings_panel doesn't have to
+            // know about the registry / cache shapes. Empty when
+            // ThemeRegistryPlugin isn't installed (tests under
+            // MinimalPlugins) — the picker row simply won't render.
+            // Missing thumbnails (cache not ready, or partial user
+            // theme) leave `thumbnails: None` so the chip renders its
+            // plain-text fallback instead of a broken sprite.
+            let themes: Vec<ThemePickerEntry> = theme_registry
+                .as_deref()
+                .map(|r| {
+                    r.iter()
+                        .map(|e| ThemePickerEntry {
+                            id: e.id.clone(),
+                            display_name: e.display_name.clone(),
+                            thumbnails: theme_thumbs
+                                .as_deref()
+                                .and_then(|c| c.get(&e.id))
+                                .filter(|p| p.is_fully_populated())
+                                .cloned(),
+                        })
+                        .collect()
+                })
+                .unwrap_or_default();
+            // The active card-art theme can supply its own back image —
+            // see `card_plugin::CardImageSet::theme_back`. When that is
+            // populated the legacy "Card Back" picker has no visible
+            // effect, so we render it muted with an explanatory caption
+            // rather than letting the player click swatches that do
+            // nothing. Absent under `MinimalPlugins`; treated as
+            // "no override" in that case.
+            let theme_overrides_back = card_images
+                .as_ref()
+                .is_some_and(|cs| cs.theme_back.is_some());
+            spawn_settings_panel(
+                &mut commands,
+                &settings.0,
+                &status_label,
+                unlocked_backs,
+                unlocked_bgs,
+                &themes,
+                scroll_pos.0,
+                font_res.as_deref(),
+                theme_overrides_back,
+            );
+        }
+    } else {
+        // Save the current scroll offset before despawning the panel.
+        if let Ok(sp) = scroll_nodes.single() {
+            scroll_pos.0 = sp.0.y;
+        }
+        for entity in &panels {
+            commands.entity(entity).despawn();
+        }
+    }
+}
+
+/// Keeps the sync-status text node current while the panel is open.
+pub(super) fn update_sync_status_text(
+    sync_status: Option<Res<SyncStatusResource>>,
+    mut text_nodes: Query<&mut Text, With<SyncStatusText>>,
+) {
+    let Some(status) = sync_status else {
+        return;
+    };
+    if !status.is_changed() {
+        return;
+    }
+    let label = sync_status_label(&status.0);
+    for mut text in &mut text_nodes {
+        **text = label.clone();
+    }
+}
+
+pub(super) fn update_card_back_text(
+    settings: Res<SettingsResource>,
+    mut text_nodes: Query<&mut Text, With<CardBackText>>,
+) {
+    if !settings.is_changed() {
+        return;
+    }
+    for mut text in &mut text_nodes {
+        **text = card_back_label(settings.0.selected_card_back);
+    }
+}
+
+pub(super) fn update_background_text(
+    settings: Res<SettingsResource>,
+    mut text_nodes: Query<&mut Text, With<BackgroundText>>,
+) {
+    if !settings.is_changed() {
+        return;
+    }
+    for mut text in &mut text_nodes {
+        **text = background_label(settings.0.selected_background);
+    }
+}
+
+pub(super) fn update_anim_speed_text(
+    settings: Res<SettingsResource>,
+    mut text_nodes: Query<&mut Text, With<AnimSpeedText>>,
+) {
+    if !settings.is_changed() {
+        return;
+    }
+    for mut text in &mut text_nodes {
+        **text = anim_speed_label(&settings.0.animation_speed);
+    }
+}
+
+pub(super) fn update_color_blind_text(
+    settings: Res<SettingsResource>,
+    mut text_nodes: Query<&mut Text, With<ColorBlindText>>,
+) {
+    if !settings.is_changed() {
+        return;
+    }
+    for mut text in &mut text_nodes {
+        **text = color_blind_label(settings.0.color_blind_mode);
+    }
+}
+
+pub(super) fn update_high_contrast_text(
+    settings: Res<SettingsResource>,
+    mut text_nodes: Query<&mut Text, With<HighContrastText>>,
+) {
+    if !settings.is_changed() {
+        return;
+    }
+    for mut text in &mut text_nodes {
+        **text = on_off_label(settings.0.high_contrast_mode);
+    }
+}
+
+/// Repaints `BorderColor` on every entity tagged with
+/// [`HighContrastBorder`] based on `Settings::high_contrast_mode`.
+/// Off → the marker's `default_color`; on → `BORDER_SUBTLE_HC`
+/// (`#a0a0a0`). Compares against the current border colour and
+/// only mutates when different so Bevy's change-detection
+/// doesn't trigger repaints every frame.
+///
+/// Spec at `design-system.md` §Accessibility (#2): under HC,
+/// outlines boost from `#505050` (BORDER_STRONG) to `#a0a0a0` so
+/// modal panels, popover edges, and focus-ring carriers stay
+/// legible on low-quality displays / for low-vision users.
+///
+/// Tagged sites in v0.21.x: the modal scaffold's card border
+/// (`ui_modal::spawn_modal`). More sites can be tagged in
+/// follow-ups by adding `HighContrastBorder::with_default(...)`
+/// to their spawn tuple.
+pub(super) fn update_high_contrast_borders(
+    settings: Res<SettingsResource>,
+    mut borders: Query<(&HighContrastBorder, &mut BorderColor)>,
+) {
+    let high_contrast = settings.0.high_contrast_mode;
+    for (marker, mut border) in borders.iter_mut() {
+        let target = if high_contrast {
+            BORDER_SUBTLE_HC
+        } else {
+            marker.default_color
+        };
+        // Only mutate when actually different — avoids per-frame
+        // change-detection churn. `border.left` is representative
+        // because every tagged site uses `BorderColor::all(...)`.
+        if border.left != target {
+            *border = BorderColor::all(target);
+        }
+    }
+}
+
+/// Repaints `BackgroundColor` on every entity tagged with
+/// [`HighContrastBackground`] based on `Settings::high_contrast_mode`.
+/// Off → the marker's `default_color`; on → `BORDER_SUBTLE_HC`
+/// (`#a0a0a0`). Compares against the current background and only
+/// mutates when different so Bevy's change-detection doesn't trigger
+/// repaints every frame.
+///
+/// Parallel to [`update_high_contrast_borders`]. Same on/off rule,
+/// same change-suppression idiom, different colour channel —
+/// `BackgroundColor` for tick marks, decorative strips, fine
+/// separators that paint their shape directly rather than via a
+/// `BorderColor` on a wider Node.
+///
+/// Tagged sites in v0.21.x: the replay overlay's 1 px scrub track
+/// + 5 quarter-mark notch ticks (`replay_overlay::spawn_overlay`).
+///
+/// More sites can be tagged in follow-ups by adding
+/// `HighContrastBackground::with_default(...)` to their spawn tuple.
+pub(super) fn update_high_contrast_backgrounds(
+    settings: Res<SettingsResource>,
+    mut backgrounds: Query<(&HighContrastBackground, &mut BackgroundColor)>,
+) {
+    let high_contrast = settings.0.high_contrast_mode;
+    for (marker, mut bg) in backgrounds.iter_mut() {
+        let target = if high_contrast {
+            marker.hc_color
+        } else {
+            marker.default_color
+        };
+        if bg.0 != target {
+            *bg = BackgroundColor(target);
+        }
+    }
+}
+
+pub(super) fn update_reduce_motion_text(
+    settings: Res<SettingsResource>,
+    mut text_nodes: Query<&mut Text, With<ReduceMotionText>>,
+) {
+    if !settings.is_changed() {
+        return;
+    }
+    for mut text in &mut text_nodes {
+        **text = on_off_label(settings.0.reduce_motion_mode);
+    }
+}
+
+pub(super) fn update_touch_input_mode_text(
+    settings: Res<SettingsResource>,
+    mut text_nodes: Query<&mut Text, With<TouchInputModeText>>,
+) {
+    if !settings.is_changed() {
+        return;
+    }
+    for mut text in &mut text_nodes {
+        **text = touch_input_mode_label(&settings.0.touch_input_mode);
+    }
+}
+
+/// Refreshes the live "Winnable deals only" toggle value in the
+/// Gameplay section whenever `SettingsResource` changes (button click,
+/// hand-edited `settings.json` reload, etc.).
+pub(super) fn update_winnable_deals_only_text(
+    settings: Res<SettingsResource>,
+    mut text_nodes: Query<&mut Text, With<WinnableDealsOnlyText>>,
+) {
+    if !settings.is_changed() {
+        return;
+    }
+    for mut text in &mut text_nodes {
+        **text = winnable_deals_only_label(settings.0.winnable_deals_only);
+    }
+}
+
+/// Refreshes the live "Share usage data" toggle value in the Privacy section
+/// whenever `SettingsResource` changes.
+pub(super) fn update_analytics_enabled_text(
+    settings: Res<SettingsResource>,
+    mut text_nodes: Query<&mut Text, With<AnalyticsEnabledText>>,
+) {
+    if !settings.is_changed() {
+        return;
+    }
+    for mut text in &mut text_nodes {
+        **text = on_off_label(settings.0.analytics_enabled);
+    }
+}
+
+/// Refreshes the live "Smart window size" toggle value whenever
+/// `SettingsResource` changes. The flag is stored negatively as
+/// `disable_smart_default_size`, so the label inverts.
+pub(super) fn update_smart_default_size_text(
+    settings: Res<SettingsResource>,
+    mut text_nodes: Query<&mut Text, With<SmartDefaultSizeText>>,
+) {
+    if !settings.is_changed() {
+        return;
+    }
+    for mut text in &mut text_nodes {
+        **text = smart_default_size_label(!settings.0.disable_smart_default_size);
+    }
+}
+
+/// Refreshes the live tooltip-delay value in the Gameplay section
+/// whenever `SettingsResource` changes (slider buttons, hand-edited
+/// settings.json reload, etc.).
+pub(super) fn update_tooltip_delay_text(
+    settings: Res<SettingsResource>,
+    mut text_nodes: Query<&mut Text, With<TooltipDelayText>>,
+) {
+    if !settings.is_changed() {
+        return;
+    }
+    for mut text in &mut text_nodes {
+        **text = tooltip_delay_label(settings.0.tooltip_delay_secs);
+    }
+}
+
+/// Refreshes the live time-bonus-multiplier value in the Gameplay
+/// section whenever `SettingsResource` changes.
+pub(super) fn update_time_bonus_multiplier_text(
+    settings: Res<SettingsResource>,
+    mut text_nodes: Query<&mut Text, With<TimeBonusMultiplierText>>,
+) {
+    if !settings.is_changed() {
+        return;
+    }
+    for mut text in &mut text_nodes {
+        **text = time_bonus_label(settings.0.time_bonus_multiplier);
+    }
+}
+
+/// Refreshes the live replay-playback per-move-interval value in the
+/// Gameplay section whenever `SettingsResource` changes (slider buttons,
+/// hand-edited settings.json reload, etc.).
+pub(super) fn update_replay_move_interval_text(
+    settings: Res<SettingsResource>,
+    mut text_nodes: Query<&mut Text, With<ReplayMoveIntervalText>>,
+) {
+    if !settings.is_changed() {
+        return;
+    }
+    for mut text in &mut text_nodes {
+        **text = replay_move_interval_label(settings.0.replay_move_interval_secs);
+    }
+}
+
+pub(super) fn card_back_label(idx: usize) -> String {
+    if idx == 0 {
+        "Default".to_string()
+    } else {
+        format!("Style {idx}")
+    }
+}
+
+pub(super) fn background_label(idx: usize) -> String {
+    if idx == 0 {
+        "Default".to_string()
+    } else {
+        format!("Style {idx}")
+    }
+}
+
+pub(super) fn sync_status_label(status: &SyncStatus) -> String {
+    match status {
+        SyncStatus::Idle => "Status: idle".to_string(),
+        SyncStatus::Syncing => "Status: syncing…".to_string(),
+        SyncStatus::LastSynced(t) => {
+            let secs = chrono::Utc::now()
+                .signed_duration_since(*t)
+                .num_seconds()
+                .max(0);
+            if secs < 60 {
+                format!("Last synced: {secs}s ago")
+            } else {
+                format!("Last synced: {}m ago", secs / 60)
+            }
+        }
+        SyncStatus::Error(e) => format!("Sync error: {e}"),
+    }
+}
+
+pub(super) fn draw_mode_label(mode: &DrawStockConfig) -> String {
+    match mode {
+        DrawStockConfig::DrawOne => "Draw 1".into(),
+        DrawStockConfig::DrawThree => "Draw 3".into(),
+    }
+}
+
+pub(super) fn anim_speed_label(speed: &AnimSpeed) -> String {
+    match speed {
+        AnimSpeed::Normal => "Normal".into(),
+        AnimSpeed::Fast => "Fast".into(),
+        AnimSpeed::Instant => "Instant".into(),
+    }
+}
+
+pub(super) fn theme_label(theme: &Theme) -> String {
+    match theme {
+        Theme::Green => "Green".into(),
+        Theme::Blue => "Blue".into(),
+        Theme::Dark => "Dark".into(),
+    }
+}
+
+pub(super) fn color_blind_label(enabled: bool) -> String {
+    if enabled { "ON".into() } else { "OFF".into() }
+}
+
+/// Generic ON/OFF label shared by the high-contrast and reduce-
+/// motion accessibility toggles. Same format as
+/// [`color_blind_label`] / [`winnable_deals_only_label`] —
+/// keeping all simple boolean toggle rows visually uniform.
+pub(super) fn on_off_label(enabled: bool) -> String {
+    if enabled { "ON".into() } else { "OFF".into() }
+}
+
+/// Display string for the "Winnable deals only" toggle. Mirrors
+/// [`color_blind_label`] — "ON" / "OFF" — so the layout is uniform
+/// with the rest of the Gameplay-section toggles.
+pub(super) fn winnable_deals_only_label(enabled: bool) -> String {
+    if enabled { "ON".into() } else { "OFF".into() }
+}
+
+pub(super) fn touch_input_mode_label(mode: &solitaire_data::settings::TouchInputMode) -> String {
+    use solitaire_data::settings::TouchInputMode;
+    match mode {
+        TouchInputMode::OneTap => "One-tap".into(),
+        TouchInputMode::TapToSelect => "Tap to select".into(),
+    }
+}
+
+/// 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
+/// the player intuitive ON/OFF semantics.
+pub(super) fn smart_default_size_label(enabled: bool) -> String {
+    if enabled { "ON".into() } else { "OFF".into() }
+}
+
+/// Formats the tooltip-hover delay for display in the Settings panel.
+/// `0.0` reads as `"Instant"` so the zero-delay case has a name; any
+/// other value prints as `"{n:.1} s"` (e.g. `"0.5 s"`, `"1.2 s"`).
+pub(super) fn tooltip_delay_label(secs: f32) -> String {
+    if secs <= 0.0 {
+        "Instant".into()
+    } else {
+        format!("{secs:.1} s")
+    }
+}
+
+/// Formats the cosmetic time-bonus multiplier for display in the
+/// Settings panel. `0.0` reads as `"Off"` so the player understands the
+/// time-bonus row will be hidden; any other value prints as
+/// `"{n:.1}×"` (e.g. `"1.0×"`, `"1.5×"`).
+pub(super) fn time_bonus_label(value: f32) -> String {
+    if value <= 0.0 {
+        "Off".into()
+    } else {
+        format!("{value:.1}×")
+    }
+}
+
+/// Formats the replay-playback per-move interval for display in the
+/// Settings panel. Mirrors [`tooltip_delay_label`] for parity — the
+/// readout is `"{n:.2} s/move"` (e.g. `"0.45 s/move"`, `"0.10 s/move"`),
+/// using two decimal places because the step is 0.05 s.
+pub(super) fn replay_move_interval_label(secs: f32) -> String {
+    format!("{secs:.2} s/move")
+}

solitaire_engine/src/table_plugin.rs

@@ -362,7 +362,15 @@ fn on_window_resized(
         (&mut Sprite, &mut Transform),
         (With<TableBackground>, Without<PileMarker>),
     >,
-    mut markers: Query<(&PileMarker, &mut Sprite, &mut Transform), Without<TableBackground>>,
+    mut markers: Query<
+        (&PileMarker, &mut Sprite, &mut Transform, Option<&Children>),
+        Without<TableBackground>,
+    >,
+    mut marker_outlines: Query<
+        &mut Sprite,
+        (Without<PileMarker>, Without<TableBackground>, Without<Text2d>),
+    >,
+    mut marker_labels: Query<&mut TextFont, With<Text2d>>,
 ) {
     let Some(ev) = events.read().last() else {
         return;
@@ -373,6 +381,14 @@ fn on_window_resized(
     let safe_area_top = insets.top / scale;
     let safe_area_bottom = insets.bottom / scale;
     let hud_visible = hud_vis.as_deref().copied().unwrap_or_default() == HudVisibility::Visible;
+    // Android surface sizes after fold/unfold are unreliable (winit does not
+    // forward every content-rect change), so make each relayout observable
+    // in logcat — this is the primary evidence channel for foldable bugs.
+    #[cfg(target_os = "android")]
+    info!(
+        "layout: resize to {:.0}x{:.0} (insets top={:.0} bottom={:.0}, hud={hud_visible})",
+        window_size.x, window_size.y, insets.top, insets.bottom
+    );
     let mut new_layout = compute_layout(window_size, safe_area_top, safe_area_bottom, hud_visible);
 
     // compute_layout sizes the fan for a worst-case column; refine it to the
@@ -394,11 +410,27 @@ fn on_window_resized(
         transform.translation.y = 0.0;
     }
 
-    for (marker, mut sprite, mut transform) in &mut markers {
+    for (marker, mut sprite, mut transform, children) in &mut markers {
         if let Some(pos) = new_layout.pile_positions.get(&marker.0) {
             sprite.custom_size = Some(new_layout.card_size);
             transform.translation.x = pos.x;
             transform.translation.y = pos.y;
+            // Children carry the outline frame and the "A"/"K" watermark.
+            // They are sized at spawn from that layout's card size, so they
+            // must be re-derived here too or a resize (fold/unfold, rotation)
+            // leaves them at the stale size — visible as oversized grey
+            // frames on empty piles.
+            let outline_size =
+                new_layout.card_size + Vec2::splat(PILE_MARKER_OUTLINE_WIDTH * 2.0);
+            let font_size = new_layout.card_size.x * 0.28;
+            for child in children.into_iter().flatten() {
+                if let Ok(mut outline) = marker_outlines.get_mut(*child) {
+                    outline.custom_size = Some(outline_size);
+                }
+                if let Ok(mut label) = marker_labels.get_mut(*child) {
+                    label.font_size = font_size;
+                }
+            }
         }
     }
 
@@ -623,6 +655,58 @@ mod tests {
         assert_eq!(types.len(), 12);
     }
 
+    #[test]
+    fn resize_updates_marker_outline_and_watermark_children() {
+        // Regression (found on Galaxy Fold 7, v0.41.0): `on_window_resized`
+        // resized the marker fill sprite but never its children, so after a
+        // fold/unfold the outline frame and "A"/"K" watermark stayed at
+        // spawn-time size — rendering as oversized grey slabs on empty piles.
+        let mut app = headless_app();
+        // Shrink the window well below the 1280×800 spawn default.
+        app.world_mut().write_message(WindowResized {
+            window: Entity::PLACEHOLDER,
+            width: 640.0,
+            height: 480.0,
+        });
+        app.update();
+
+        let card_size = app.world().resource::<LayoutResource>().0.card_size;
+        let expected_outline = card_size + Vec2::splat(PILE_MARKER_OUTLINE_WIDTH * 2.0);
+        let expected_font = card_size.x * 0.28;
+
+        let marker_children: Vec<Entity> = {
+            let mut q = app.world_mut().query::<(&PileMarker, &Children)>();
+            q.iter(app.world())
+                .flat_map(|(_, c)| c.iter().collect::<Vec<_>>())
+                .collect()
+        };
+        assert!(
+            !marker_children.is_empty(),
+            "pile markers must have outline/watermark children"
+        );
+        let mut outlines = 0;
+        let mut labels = 0;
+        for child in marker_children {
+            if let Some(sprite) = app.world().entity(child).get::<Sprite>() {
+                assert_eq!(
+                    sprite.custom_size,
+                    Some(expected_outline),
+                    "outline child must track the resized card size",
+                );
+                outlines += 1;
+            }
+            if let Some(font) = app.world().entity(child).get::<TextFont>() {
+                assert!(
+                    (font.font_size - expected_font).abs() < 0.01,
+                    "watermark font must track the resized card size",
+                );
+                labels += 1;
+            }
+        }
+        assert_eq!(outlines, 12, "all 12 markers carry an outline child");
+        assert!(labels >= 11, "tableau + foundation markers carry watermarks");
+    }
+
     #[test]
     fn pile_markers_hide_when_pile_is_occupied() {
         // After a fresh deal: the 7 tableau piles + the stock pile are

solitaire_server/web/pkg/canvas.js

@@ -1649,62 +1649,62 @@ function __wbg_get_imports() {
             return ret;
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 114857, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 114880, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__hfb2e9a2f0bbd9ecc);
             return ret;
         },
         __wbindgen_cast_0000000000000002: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 9853, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a);
             return ret;
         },
         __wbindgen_cast_0000000000000003: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("Array<any>"), NamedExternref("ResizeObserver")], shim_idx: 9843, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("Array<any>"), NamedExternref("ResizeObserver")], shim_idx: 9866, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h876550298b312ff8);
             return ret;
         },
         __wbindgen_cast_0000000000000004: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("Array<any>")], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("Array<any>")], shim_idx: 9853, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_3);
             return ret;
         },
         __wbindgen_cast_0000000000000005: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("Event")], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("Event")], shim_idx: 9853, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_4);
             return ret;
         },
         __wbindgen_cast_0000000000000006: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("FocusEvent")], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("FocusEvent")], shim_idx: 9853, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_5);
             return ret;
         },
         __wbindgen_cast_0000000000000007: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("KeyboardEvent")], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("KeyboardEvent")], shim_idx: 9853, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_6);
             return ret;
         },
         __wbindgen_cast_0000000000000008: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("PageTransitionEvent")], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("PageTransitionEvent")], shim_idx: 9853, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_7);
             return ret;
         },
         __wbindgen_cast_0000000000000009: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("PointerEvent")], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("PointerEvent")], shim_idx: 9853, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_8);
             return ret;
         },
         __wbindgen_cast_000000000000000a: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("WheelEvent")], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("WheelEvent")], shim_idx: 9853, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_9);
             return ret;
         },
         __wbindgen_cast_000000000000000b: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Option(NamedExternref("Blob"))], shim_idx: 9840, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Option(NamedExternref("Blob"))], shim_idx: 9863, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h657f46feffff6fe4);
             return ret;
         },
         __wbindgen_cast_000000000000000c: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [], shim_idx: 9834, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [], shim_idx: 9857, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h545edb23183e448a);
             return ret;
         },