Merge pull request 'refactor(engine): split hud_plugin runtime code into submodules' (#128) from refactor/hud-plugin-submodules into master

Continues #118 after settings_plugin (PR #127): the 2,725-line mod.rs
becomes five focused submodules along existing system boundaries —

  mod.rs        553  markers, resources, popover enums, plugin build
  spawn.rs      552  band / columns / avatar / action-bar construction
  interaction.rs 616 button handlers, Modes/Menu popovers, tap gesture
  fx.rs         430  action fades, score pulses/floaters, streak flourish
  updates.rs    612  HUD text / typography / visibility updaters

Moved items are pub(super) (fx re-exported pub for HudActionFade and
format_time_limit consumers). Code moved verbatim; no behaviour change;
all 44 hud tests pass unchanged.

Refs #118

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

ARCHITECTURE.md

@@ -109,6 +109,18 @@ Owns:
 - Achievement unlock condition evaluation
 - Seeded RNG for reproducible deals
 
+**Rules decisions:**
+- **Stock recycling is unlimited in every draw mode — by design.** Extra
+  passes through the stock are discouraged via the upstream score penalty
+  (applied by the `card_game`/`klondike` session), never blocked with a
+  `MoveError`. This matches mainstream digital solitaire (unlimited redeals
+  in Draw-1) rather than strict tournament rules (3-pass cap). It is load-
+  bearing: the difficulty seed catalog and the winnable-deal solver are
+  verified under unlimited recycling, so introducing a hard pass limit would
+  invalidate both. Locked in by the
+  `draw_one_recycling_is_unlimited_by_design` test in
+  `solitaire_core/src/game_state.rs`. (Decision record: Gitea issue #117.)
+
 ### `solitaire_sync`
 **Dependencies:** `serde`, `serde_json`, `uuid`, `chrono` only.
 

CHANGELOG.md

@@ -6,8 +6,19 @@ project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.41.0] — 2026-07-06
+
+> Consolidates everything shipped since v0.39.0, including the v0.40.0–v0.40.3
+> patch tags (which were cut from this section without renaming it at the time).
+
 ### Added
 
+- **Rules decision record: unlimited stock recycling.** Documented in
+  `ARCHITECTURE.md` that unlimited recycling with score penalties (matching
+  mainstream digital solitaire) is intentional, and locked it in with a core
+  test — the difficulty seed catalog and winnable-deal solver are verified
+  under this rule. Resolves the last open finding from the June 500-game
+  audit (issue #117).
 - **Analytics validation runbook.** Documented native Matomo live validation,
   expected event payloads, and the current web/WASM analytics split.
 - **Android smoke-test runbook.** Updated the Android doc with the current
@@ -26,6 +37,10 @@ project follows [Semantic Versioning](https://semver.org/).
 
 ### Changed
 
+- **Engine plugin modules restructured.** The five oversized plugin files
+  (card, hud, settings, game, input) are now module directories with their
+  test suites in sibling `tests.rs` files — no behaviour change; first phase
+  of the module-split plan (#118).
 - **Core type ownership.** Routed all klondike/card imports through
   `solitaire_core` and unified local `Suit` / `Rank` with upstream `card_game`
   types.
@@ -37,6 +52,12 @@ project follows [Semantic Versioning](https://semver.org/).
 
 ### Fixed
 
+- **Safe-area insets now re-polled after app resume.** The inset poller settled
+  permanently once insets first resolved, so inset changes while backgrounded
+  (fold/unfold, rotation, gesture ↔ 3-button nav switch) kept stale layout until
+  the app was killed. Each resume now re-arms a fresh poll window; the cached
+  value is rewritten only when it actually changed, so unchanged resumes still
+  cause no relayout flash. (#116)
 - **Tableau fill on foldables / tall screens.** The tableau fan now spreads from
   each column's total depth (face-down cards included) and refills on the
   cold-start deal, every move, and on resize (incl. the Android safe-area-inset

scripts/watch_deploy.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Live-watch the Gitea Actions deploy pipeline for Ferrous Solitaire.
+#
+# Polls recent workflow runs and prints a compact status block each cycle.
+# Stops when the newest docker-build (the deploy) has completed and no
+# web-wasm-rebuild is still pending — i.e. the full fix is live.
+#
+# Usage:  ./scripts/watch_deploy.sh [interval_seconds]
+#   token is read from ~/.config/tea/config.yml (never printed).
+set -uo pipefail
+
+REPO="funman300/Ferrous-Solitaire"
+BASE="https://git.aleshym.co/api/v1/repos/${REPO}"
+INTERVAL="${1:-20}"
+CFG="${HOME}/.config/tea/config.yml"
+
+TOKEN="$(grep -E '^[[:space:]]*token:' "$CFG" | head -1 | sed -E 's/.*token:[[:space:]]*//' | tr -d '"'\'' ')"
+[ -z "$TOKEN" ] && { echo "error: no token in $CFG" >&2; exit 1; }
+
+echo "── watching ${REPO} deploy (poll ${INTERVAL}s, Ctrl-C to stop) ──"
+
+while :; do
+  json="$(curl -s --max-time 20 -H "Authorization: token ${TOKEN}" "${BASE}/actions/runs?limit=6")"
+  # Print rows + emit the deploy state on the last line (parsed below).
+  # JSON is passed via env var because `python3 -` reads its program from the
+  # heredoc on stdin, so stdin can't also carry the data.
+  out="$(JSON_DATA="$json" python3 - <<'PY'
+import os, sys, json, datetime
+now = datetime.datetime.now().strftime("%H:%M:%S")
+raw = os.environ.get("JSON_DATA", "").strip()
+try:
+    d = json.loads(raw)
+except Exception:
+    print("[%s] (api unavailable, retrying)" % now)
+    print("STATE=DEPLOYING")
+    sys.exit(0)
+runs = d.get("workflow_runs", [])[:6]
+icons = {("completed","success"):"OK  ", ("completed","failure"):"FAIL",
+         ("completed","cancelled"):"CXL "}
+def ic(s, c):
+    if s == "queued": return "queue"
+    if s == "in_progress": return "run.."
+    return icons.get((s, c), s or "?")
+print("[%s]" % datetime.datetime.now().strftime("%H:%M:%S"))
+for r in runs:
+    wf = str(r.get("path","")).split("@")[0].split("/")[-1].replace(".yml","")
+    print("   %-5s %-5s %-7s %-18s %s/%s" % (
+        ic(r.get("status"), r.get("conclusion")),
+        r.get("id"), str(r.get("head_sha"))[:7], wf[:18],
+        r.get("status"), r.get("conclusion")))
+db = [r for r in runs if "docker-build" in str(r.get("path"))]
+wr_pending = any(r.get("status") != "completed" for r in runs if "web-wasm-rebuild" in str(r.get("path")))
+top = db[0] if db else None
+live = bool(top and top.get("status")=="completed" and top.get("conclusion")=="success" and not wr_pending)
+print("STATE=%s" % ("LIVE" if live else ("WAIT_WASM" if wr_pending else "DEPLOYING")))
+PY
+)"
+  echo "$out" | grep -v '^STATE='
+  if echo "$out" | grep -q '^STATE=LIVE'; then
+    echo ""
+    echo "DEPLOY LIVE — newest docker-build succeeded, no wasm rebuild pending."
+    echo "   Test: https://klondike.aleshym.co/play?v=${RANDOM}"
+    break
+  fi
+  sleep "$INTERVAL"
+done

solitaire_core/src/game_state.rs

@@ -863,6 +863,13 @@ impl GameState {
     }
 
     /// Draw cards from stock to waste. When stock is empty, recycles waste back to stock.
+    ///
+    /// Recycling is deliberately unlimited in every draw mode: extra passes
+    /// are discouraged through the upstream score penalty, never rejected
+    /// with a [`MoveError`]. The difficulty seed catalog and the
+    /// winnable-deal solver are verified under this rule — see the
+    /// "Rules decisions" note in `ARCHITECTURE.md` (`solitaire_core`
+    /// section) before considering a hard pass limit.
     pub fn draw(&mut self) -> Result<(), MoveError> {
         if self.is_won() {
             return Err(MoveError::GameAlreadyWon);
@@ -1222,6 +1229,30 @@ mod tests {
         );
     }
 
+    #[test]
+    fn draw_one_recycling_is_unlimited_by_design() {
+        // Rules decision (Gitea #117): stock recycling is unlimited in every
+        // draw mode. Extra passes are discouraged via the upstream score
+        // penalty, never blocked with a MoveError. The difficulty seed
+        // catalog and the winnable-deal solver are verified under this rule,
+        // so a hard pass limit must not be introduced casually — see the
+        // "Rules decisions" note in ARCHITECTURE.md (`solitaire_core`).
+        let mut game = game_at_first_recycle().expect("could not reach recycle");
+        // ~24 draws per Draw-1 pass; 2_000 draws is ample budget for 10 passes.
+        for _ in 0..2_000 {
+            if game.recycle_count() >= 10 {
+                break;
+            }
+            game.draw()
+                .expect("unlimited recycling: draw must never fail on pass count");
+        }
+        assert!(
+            game.recycle_count() >= 10,
+            "expected at least 10 recycles within the draw budget, got {}",
+            game.recycle_count(),
+        );
+    }
+
     #[test]
     fn undo_applies_minus_15_penalty_via_upstream_score() {
         // A foundation move scores +10 upstream; undoing it nets the move score

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/mod.rs

@@ -0,0 +1,553 @@
+//! Persistent in-game HUD: score, move count, elapsed time, mode badge,
+//! daily-challenge constraint, and undo count.
+//!
+//! The HUD spawns once at startup and lives for the app's lifetime. Text is
+//! refreshed whenever `GameStateResource` changes (which happens on every move
+//! and every elapsed-time tick), so score, moves, and timer all stay current
+//! without a separate tick system.
+
+use bevy::prelude::*;
+use bevy::window::WindowResized;
+
+mod fx;
+mod interaction;
+mod spawn;
+mod updates;
+
+pub use fx::*;
+use interaction::*;
+use spawn::*;
+use updates::*;
+
+
+// On wasm32 AvatarPlugin is gated out; define a placeholder type so the
+// Option<Res<AvatarResource>> parameters below compile without changes.
+// The resource is never inserted on wasm, so every call resolves to None.
+#[cfg(target_arch = "wasm32")]
+#[derive(bevy::prelude::Resource)]
+struct AvatarResource(Option<bevy::prelude::Handle<bevy::prelude::Image>>);
+use crate::challenge_plugin::CHALLENGE_UNLOCK_LEVEL;
+use crate::daily_challenge_plugin::DailyChallengeResource;
+use crate::events::{
+    HelpRequestEvent, InfoToastEvent, NewGameRequestEvent, PauseRequestEvent,
+    StartChallengeRequestEvent, StartDailyChallengeRequestEvent, StartTimeAttackRequestEvent,
+    StartZenRequestEvent, ToggleAchievementsRequestEvent, ToggleLeaderboardRequestEvent,
+    ToggleProfileRequestEvent, ToggleSettingsRequestEvent, ToggleStatsRequestEvent,
+    UndoRequestEvent, WinStreakMilestoneEvent,
+};
+use crate::font_plugin::FontResource;
+use crate::game_plugin::GameMutation;
+#[cfg(target_os = "android")]
+use crate::input_plugin::TouchDragSet;
+use crate::layout::HUD_BAND_HEIGHT;
+use crate::layout::LayoutSystem;
+use crate::pause_plugin::PausedResource;
+use crate::platform::{SHOW_KEYBOARD_ACCELERATORS, USE_TOUCH_UI_LAYOUT};
+use crate::progress_plugin::ProgressResource;
+use crate::resources::GameStateResource;
+#[cfg(target_os = "android")]
+use crate::resources::{DragState, GameInputConsumedResource};
+use crate::safe_area::{SafeAreaAnchoredBottom, SafeAreaAnchoredTop};
+use crate::selection_plugin::SelectionState;
+use crate::settings_plugin::SettingsResource;
+use crate::time_attack_plugin::TimeAttackResource;
+use crate::ui_focus::{FocusGroup, Focusable};
+use crate::ui_modal::ModalScrim;
+use crate::ui_theme::SPACE_2;
+use crate::ui_theme::{
+    ACCENT_PRIMARY, ACCENT_SECONDARY, BG_ELEVATED, BG_ELEVATED_HI, BG_ELEVATED_PRESSED,
+    BG_HUD_BAND, BORDER_SUBTLE, HighContrastBorder, MOTION_SCORE_PULSE_SECS,
+    MOTION_STREAK_FLOURISH_SECS, RADIUS_MD, RADIUS_SM, STATE_DANGER, STATE_INFO, STATE_SUCCESS,
+    STATE_WARNING, STREAK_FLOURISH_PEAK_SCALE, TEXT_PRIMARY, TEXT_SECONDARY, TYPE_BODY,
+    TYPE_BODY_LG, TYPE_CAPTION, TYPE_HEADLINE, VAL_SPACE_1, VAL_SPACE_2, VAL_SPACE_3,
+    scaled_duration,
+};
+use crate::ui_tooltip::Tooltip;
+use solitaire_data::SyncBackend;
+
+/// Marker on the score text node.
+#[derive(Component, Debug)]
+pub struct HudScore;
+
+/// Marker on the move-count text node.
+#[derive(Component, Debug)]
+pub struct HudMoves;
+
+/// Marker on the elapsed-time text node.
+#[derive(Component, Debug)]
+pub struct HudTime;
+
+/// Marker on the mode badge text node.
+#[derive(Component, Debug)]
+pub struct HudMode;
+
+/// Marker on the daily-challenge constraint text node.
+///
+/// Displays the active goal (time limit or score target) when a daily challenge
+/// is in progress. Empty string when no challenge is active or the game is won.
+#[derive(Component, Debug)]
+pub struct HudChallenge;
+
+/// Marker on the "won this deal before" indicator text node.
+///
+/// Displays `"✓ Won before"` when the current deal's seed + draw_mode +
+/// mode triple matches one of the entries in `ReplayHistoryResource`.
+/// Empty string otherwise (including won games — the score readout
+/// already conveys the win on the active deal). Only meaningful for
+/// Classic / Zen / Challenge — daily-challenge and time-attack seeds
+/// are filtered out implicitly because their replay entries always
+/// carry a different mode tag.
+#[derive(Component, Debug)]
+pub struct HudWonPreviously;
+
+/// Marker on the undo-count text node.
+///
+/// Shows how many undos have been used this game. Displayed in amber when
+/// `undo_count > 0` because using undo blocks the no-undo achievement.
+#[derive(Component, Debug)]
+pub struct HudUndos;
+
+/// Marker on the auto-complete badge text node.
+///
+/// Displays `"AUTO"` in green while `AutoCompleteState.active` is true;
+/// empty string otherwise.
+#[derive(Component, Debug)]
+pub struct HudAutoComplete;
+
+/// Marker on the stock-recycle counter text node.
+///
+/// Displays `"Recycles: N"` whenever `recycle_count > 0`, regardless of draw
+/// mode, so the player can track stock recycling in both Draw-One and
+/// Draw-Three (relevant to the `comeback` achievement). Hidden (empty string)
+/// until the first recycle occurs.
+#[derive(Component, Debug)]
+pub struct HudRecycles;
+
+/// Marker on the draw-cycle indicator text node.
+///
+/// Only shown in Draw-Three mode. Displays `"Cycle: N/3"` where N is the
+/// number of cards that will be drawn on the next stock click
+/// (`min(stock_len, 3)`). Shows `"Cycle: 0/3"` when the stock is empty
+/// (recycle available). Hidden (empty string) in Draw-One mode or after the
+/// game is won.
+#[derive(Component, Debug)]
+pub struct HudDrawCycle;
+
+/// Marker on the keyboard-selection indicator text node.
+///
+/// Displays `"▶ {pile_name}"` while a pile is selected via Tab, or an empty
+/// string when no pile is selected. Uses a light-yellow colour so it stands
+/// out from the other white HUD items.
+#[derive(Component, Debug)]
+pub struct HudSelection;
+
+/// Marker on the HUD band background node (the translucent band behind buttons).
+#[derive(Component, Debug)]
+pub struct HudBand;
+
+/// Marker on the HUD score/info column root node.
+#[derive(Component, Debug)]
+pub struct HudColumn;
+
+/// Marker on the action button bar root node.
+#[derive(Component, Debug)]
+pub struct HudActionBar;
+
+/// Marker on the text node inside each touch-layout action-bar button.
+/// Used by `resize_action_bar_labels` to update font size on window resize.
+#[derive(Component, Debug)]
+struct ActionButtonLabel;
+
+/// Marker on the circular profile-picture button anchored to the
+/// top-right of the HUD band. Pressing it opens the Profile overlay.
+/// Shows the server avatar image when loaded; falls back to the player's
+/// initial on a filled disc when no image is available.
+#[derive(Component, Debug)]
+pub struct HudAvatar;
+
+/// Controls whether the in-game HUD (band, score column, action buttons) is
+/// visible. Toggled on Android by tapping empty board space; always `Visible`
+/// on desktop. Resets to `Visible` whenever a modal opens.
+#[derive(Resource, Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum HudVisibility {
+    #[default]
+    Visible,
+    Hidden,
+}
+
+#[cfg(target_os = "android")]
+#[derive(Resource, Debug, Default)]
+struct HudTapTracker {
+    start_pos: Option<Vec2>,
+    /// Set `true` when the finger-down hit an action button so the
+    /// finger-up never toggles bar visibility.
+    started_on_button: bool,
+}
+
+#[cfg(target_os = "android")]
+const HUD_TAP_SLOP_PX: f32 = 25.0;
+
+/// Drives the score-readout pulse: scales the [`HudScore`] text from
+/// 1.0 → 1.1 → 1.0 over [`MOTION_SCORE_PULSE_SECS`] (scaled by
+/// [`AnimSpeed`](solitaire_data::AnimSpeed)). Inserted on the score
+/// entity whenever the score increases; removed once `elapsed >=
+/// duration`.
+#[derive(Component, Debug, Clone, Copy)]
+pub struct ScorePulse {
+    /// Seconds elapsed since the pulse started.
+    pub elapsed: f32,
+    /// Total duration. Zero under `AnimSpeed::Instant` — the system
+    /// snaps the scale back to 1.0 on first tick so no half-state
+    /// is ever shown.
+    pub duration: f32,
+}
+
+/// Marker on a transient floating "+N" text spawned next to the score
+/// readout when the score jumps by [`SCORE_FLOATER_THRESHOLD`] or more.
+/// Drifts upward and fades out over `MOTION_SCORE_PULSE_SECS * 2`,
+/// then despawns. Kept rare/meaningful by the threshold gate.
+#[derive(Component, Debug, Clone, Copy)]
+pub struct ScoreFloater {
+    /// Seconds elapsed since the floater spawned.
+    pub elapsed: f32,
+    /// Total lifetime. Zero under `AnimSpeed::Instant` — the system
+    /// despawns it on first tick.
+    pub duration: f32,
+}
+
+/// Drives the streak-milestone flourish: scales the [`HudScore`] text
+/// from `1.0 → STREAK_FLOURISH_PEAK_SCALE → 1.0` over
+/// [`MOTION_STREAK_FLOURISH_SECS`] (scaled by
+/// [`AnimSpeed`](solitaire_data::AnimSpeed)) and tints it
+/// [`ACCENT_SECONDARY`] for the same window before restoring the
+/// original colour.
+///
+/// The streak readout currently lives in the Stats overlay (press
+/// `S`) — there is no always-on HUD streak counter — so the flourish
+/// piggybacks on the score readout, which is the most prominent
+/// always-visible HUD number. Mirrors the `FoundationFlourish`
+/// pattern: triangular scale curve, fixed duration, restores state
+/// when the timer expires.
+///
+/// Inserted on `HudScore` entities by `start_streak_flourish` when a
+/// `WinStreakMilestoneEvent` fires; removed once `elapsed >=
+/// duration` so the readout returns to its rest state for the next
+/// frame's transform sync.
+///
+/// Coexists with [`ScorePulse`]: the streak flourish lives on a
+/// dedicated marker so a streak-crossing win that also ticks the
+/// score (every win does) doesn't have the two animations stomp on
+/// each other's `Transform.scale` writes — the streak flourish runs
+/// in a `Without<ScorePulse>` query so only the loudest of the two
+/// celebrations is active at a time.
+#[derive(Component, Debug, Clone, Copy)]
+pub struct StreakFlourish {
+    /// The streak milestone that triggered this flourish (3, 5, 10).
+    /// Carried for diagnostic logging only — the visual is identical
+    /// for every threshold so play-testing can decide later whether
+    /// to differentiate.
+    pub streak: u32,
+    /// Seconds elapsed since the flourish began.
+    pub elapsed: f32,
+    /// Total animation length in seconds. Zero under
+    /// [`AnimSpeed::Instant`](solitaire_data::AnimSpeed) — the system
+    /// snaps the scale back to 1.0 on the first tick so no half-state
+    /// is ever shown.
+    pub duration: f32,
+    /// The score readout's colour before the flourish began —
+    /// restored when the timer expires so the readout returns to its
+    /// resting `TEXT_PRIMARY` (or whatever it was) tint.
+    pub original_color: Color,
+}
+
+/// Tracks the score from the previous frame so the HUD can detect
+/// changes without a `ScoreChangedEvent`. The plugin wires this to the
+/// pulse + floater systems on every `Update`.
+#[derive(Resource, Debug, Default, Clone, Copy)]
+pub struct PreviousScore(pub i32);
+
+/// Score increase (in points) below which no floating "+N" is spawned.
+/// 50 keeps the feedback for foundation drops and tableau-to-foundation
+/// promotions; single-card placements (which can earn as little as +5)
+/// stay quiet so the floater feels like a reward instead of noise.
+pub const SCORE_FLOATER_THRESHOLD: i32 = 50;
+
+/// Marker shared by every clickable HUD action button so a single
+/// `paint_action_buttons` system can recolour them on hover/press without
+/// each button needing its own paint handler.
+#[derive(Component, Debug)]
+pub struct ActionButton;
+
+/// Marker on rows inside a popover panel ([`ModesPopover`] or
+/// [`MenuPopover`]). Popover rows already carry `ActionButton` so the
+/// hover/press paint path applies to them, but the auto-fade applied
+/// to the top-level action bar must NOT also fade these rows — the
+/// popover only renders when the player has explicitly opened it, so
+/// its content should always be at full opacity. `apply_action_fade`
+/// excludes entities with this marker via `Without<PopoverRow>`.
+#[derive(Component, Debug)]
+pub struct PopoverRow;
+
+/// Marker on the "New Game" action button anchored top-right of the play
+/// area. Click fires [`NewGameRequestEvent`]; the existing
+/// `ConfirmNewGameScreen` modal handles confirmation when a game is in
+/// progress.
+#[derive(Component, Debug)]
+pub struct NewGameButton;
+
+/// Marker on the "Undo" action button. Click fires [`UndoRequestEvent`],
+/// mirroring the `U` keyboard accelerator.
+#[derive(Component, Debug)]
+pub struct UndoButton;
+
+/// Marker on the "Pause" action button. Click fires [`PauseRequestEvent`],
+/// mirroring the `Esc` keyboard accelerator. The pause overlay's own resume
+/// affordance dismisses it from the paused state.
+#[derive(Component, Debug)]
+pub struct PauseButton;
+
+/// Marker on the "Help" action button. Click fires [`HelpRequestEvent`],
+/// mirroring the `F1` keyboard accelerator.
+#[derive(Component, Debug)]
+pub struct HelpButton;
+
+/// Marker on the "Hint" action button. Click spawns an async solver task
+/// (same as the `H` keyboard accelerator) and highlights the suggested card.
+#[derive(Component, Debug)]
+pub struct HintButton;
+
+/// Android HUD label for the Hint button — shared with the help screen's
+/// controls reference so both always agree.
+#[cfg(target_os = "android")]
+pub(crate) const ANDROID_HINT_LABEL: &str = "Hint";
+
+#[cfg(target_os = "android")]
+const ACTION_BAR_LABELS: [&str; 7] = [
+    "Menu",
+    "Undo",
+    "Pause",
+    "Help",
+    ANDROID_HINT_LABEL,
+    "Mode",
+    "New",
+];
+#[cfg(not(target_os = "android"))]
+const ACTION_BAR_LABELS: [&str; 7] = [
+    "Menu \u{2193}",
+    "Undo",
+    "Pause",
+    "Help",
+    "Hint",
+    "Modes \u{2193}",
+    "New Game",
+];
+#[cfg(target_os = "android")]
+const ACTION_BAR_COLUMN_GAP: Val = Val::Px(4.0);
+#[cfg(not(target_os = "android"))]
+const ACTION_BAR_COLUMN_GAP: Val = VAL_SPACE_2;
+#[cfg(target_os = "android")]
+const ACTION_POPOVER_BOTTOM_PX: f32 = 200.0;
+#[cfg(not(target_os = "android"))]
+const ACTION_POPOVER_BOTTOM_PX: f32 = 80.0;
+#[cfg(target_os = "android")]
+const HINT_WON_MSG: &str = "Game won! Tap New Game to play again";
+#[cfg(not(target_os = "android"))]
+const HINT_WON_MSG: &str = "Game won! Press N for a new game";
+
+/// Marker on the "Modes" action button. Click toggles the [`ModesPopover`]
+/// (a small dropdown panel) below the action bar. Each popover row starts
+/// the corresponding game mode.
+#[derive(Component, Debug)]
+pub struct ModesButton;
+
+/// Marker on the dropdown panel that opens below the [`ModesButton`].
+/// Spawned on first click, despawned on second click or on mode select.
+#[derive(Component, Debug)]
+pub struct ModesPopover;
+
+/// One row inside the [`ModesPopover`]. The variant carries which event
+/// the click handler should fire — Classic uses `NewGameRequestEvent`
+/// directly, the others go through their `Start*RequestEvent` so the
+/// existing keyboard handler's level gate / resource setup runs.
+#[derive(Component, Debug, Clone, Copy)]
+pub enum ModeOption {
+    Classic,
+    DailyChallenge,
+    Zen,
+    Challenge,
+    TimeAttack,
+}
+
+/// Marker on the "Menu" action button. Click toggles the [`MenuPopover`]
+/// which exposes the Stats / Achievements / Profile / Settings /
+/// Leaderboard overlays without needing the S/A/P/O/L hotkeys.
+#[derive(Component, Debug)]
+pub struct MenuButton;
+
+/// Marker on the dropdown panel that opens below the [`MenuButton`].
+#[derive(Component, Debug)]
+pub struct MenuPopover;
+
+/// Shared marker placed on both [`MenuPopover`] and [`ModesPopover`] entities
+/// while they are open. External systems (e.g. `PausePlugin`) query this to
+/// determine whether a HUD popover is currently visible without importing the
+/// individual popover types.
+#[derive(Component, Debug)]
+pub struct HudPopoverOpen;
+
+/// Fullscreen transparent backdrop spawned behind the [`MenuPopover`].
+/// Pressing it (tap anywhere outside the popover) light-dismisses the menu.
+#[derive(Component, Debug)]
+struct MenuPopoverBackdrop;
+
+/// Fullscreen transparent backdrop spawned behind the [`ModesPopover`].
+/// Pressing it (tap anywhere outside the popover) light-dismisses it.
+#[derive(Component, Debug)]
+struct ModesPopoverBackdrop;
+
+/// One row inside the [`MenuPopover`]. The variant selects which
+/// `Toggle*RequestEvent` the click handler fires.
+#[derive(Component, Debug, Clone, Copy)]
+pub enum MenuOption {
+    Help,
+    Modes,
+    Stats,
+    Achievements,
+    Profile,
+    Settings,
+    Leaderboard,
+}
+
+/// HUD Z-layer — above cards (which start at z=0) but below overlay screens.
+/// Mirrors `ui_theme::Z_HUD` and is duplicated here only so the hud module
+/// can use it as a `const` without a non-const expression in `ZIndex(...)`.
+const Z_HUD: i32 = crate::ui_theme::Z_HUD;
+const Z_HUD_POPOVER_BACKDROP: i32 = crate::ui_theme::Z_HUD_POPOVER_BACKDROP;
+const Z_HUD_POPOVER: i32 = crate::ui_theme::Z_HUD_POPOVER;
+const Z_HUD_TOP: i32 = crate::ui_theme::Z_HUD_TOP;
+
+/// Idle / hover / pressed colours shared by every action button. Aliased
+/// to the theme tokens so the HUD picks up palette changes for free.
+const ACTION_BTN_IDLE: Color = BG_ELEVATED;
+const ACTION_BTN_HOVER: Color = BG_ELEVATED_HI;
+const ACTION_BTN_PRESSED: Color = BG_ELEVATED_PRESSED;
+
+/// Renders the in-game HUD: score counter, move counter, elapsed timer, draw-mode indicator, and the auto-complete badge that lights up when the game is solvable without further input.
+pub struct HudPlugin;
+
+impl Plugin for HudPlugin {
+    fn build(&self, app: &mut App) {
+        // The click handlers write to messages registered elsewhere by their
+        // owning plugins (`GamePlugin`, `PausePlugin`, `HelpPlugin`,
+        // `challenge_plugin`, `daily_challenge_plugin`, `time_attack_plugin`,
+        // `input_plugin`). Re-register defensively so the HUD plugin works in
+        // isolation under `MinimalPlugins` (tests). `add_message` is
+        // idempotent.
+        app.add_message::<NewGameRequestEvent>()
+            .add_message::<UndoRequestEvent>()
+            .add_message::<PauseRequestEvent>()
+            .add_message::<HelpRequestEvent>()
+            .add_message::<StartZenRequestEvent>()
+            .add_message::<StartChallengeRequestEvent>()
+            .add_message::<StartTimeAttackRequestEvent>()
+            .add_message::<StartDailyChallengeRequestEvent>()
+            .add_message::<ToggleStatsRequestEvent>()
+            .add_message::<ToggleAchievementsRequestEvent>()
+            .add_message::<ToggleProfileRequestEvent>()
+            .add_message::<ToggleSettingsRequestEvent>()
+            .add_message::<ToggleLeaderboardRequestEvent>()
+            .add_message::<WinStreakMilestoneEvent>()
+            .init_resource::<PreviousScore>()
+            .init_resource::<HudActionFade>()
+            .init_resource::<HudVisibility>()
+            // Escape-close handlers for popovers read this; init defensively
+            // so HudPlugin works under MinimalPlugins in tests.
+            .init_resource::<ButtonInput<KeyCode>>()
+            // WindowResized is registered by table_plugin; re-register
+            // defensively so the HUD plugin works standalone in tests.
+            .add_message::<WindowResized>()
+            .add_systems(Startup, (spawn_hud_band, spawn_hud, spawn_action_buttons, spawn_hud_avatar))
+            .add_systems(Update, update_hud.after(GameMutation))
+            .add_systems(
+                Update,
+                apply_hud_visibility.before(LayoutSystem::UpdateOnResize),
+            )
+            .add_systems(Update, restore_hud_on_modal)
+            .add_systems(Update, (update_hud_avatar, handle_avatar_button))
+            .add_systems(Update, update_won_previously.after(GameMutation))
+            .add_systems(Update, announce_auto_complete.after(GameMutation))
+            .add_systems(
+                Update,
+                update_selection_hud.run_if(
+                    resource_exists_and_changed::<SelectionState>
+                        .or(resource_exists_and_changed::<GameStateResource>),
+                ),
+            )
+            .add_systems(Update, update_hud_typography)
+            .add_systems(
+                Update,
+                (
+                    detect_score_change,
+                    advance_score_pulse,
+                    advance_score_floater,
+                )
+                    .chain()
+                    .after(GameMutation),
+            )
+            .add_systems(
+                Update,
+                (start_streak_flourish, advance_streak_flourish)
+                    .chain()
+                    .after(GameMutation),
+            )
+            .add_systems(
+                Update,
+                (
+                    handle_new_game_button,
+                    handle_undo_button,
+                    handle_pause_button,
+                    handle_help_button,
+                    handle_hint_button,
+                    handle_modes_button,
+                    handle_mode_option_click,
+                    handle_modes_backdrop_click,
+                    close_modes_popover_on_escape,
+                    handle_menu_button,
+                    handle_menu_option_click,
+                    handle_menu_backdrop_click,
+                    close_menu_popover_on_escape,
+                    paint_action_buttons,
+                ),
+            )
+            // Fade lives in `Last` so it always overrides whatever the
+            // hover/paint pass set on `BackgroundColor` this frame.
+            // Otherwise on a hover-state change (`Changed<Interaction>`),
+            // `paint_action_buttons` would clobber the alpha back to 1.0
+            // mid-fade and produce a visible blip.
+            ;
+        // Desktop-only: cursor-proximity fade. On Android the bar
+        // visibility is toggled explicitly; cursor_position() returning
+        // Some(touch_pos) during a tap would otherwise fade the bar out.
+        #[cfg(not(target_os = "android"))]
+        app.add_systems(Last, (update_action_fade, apply_action_fade).chain());
+        #[cfg(target_os = "android")]
+        {
+            app.init_resource::<HudTapTracker>()
+                .add_message::<TouchInput>()
+                .add_systems(
+                    Update,
+                    toggle_hud_on_tap
+                        .after(TouchDragSet::AfterStartDrag)
+                        .in_set(TouchDragSet::BeforeEndDrag),
+                );
+            app.add_systems(
+                Update,
+                resize_action_bar_labels
+                    .run_if(resource_exists_and_changed::<crate::layout::LayoutResource>),
+            );
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests;

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

@@ -0,0 +1,873 @@
+use super::*;
+use crate::auto_complete_plugin::AutoCompleteState;
+use crate::game_plugin::GamePlugin;
+use crate::table_plugin::TablePlugin;
+use chrono::Local;
+use solitaire_core::{DrawStockConfig, game_state::GameState};
+
+fn headless_app() -> App {
+    let mut app = App::new();
+    app.add_plugins(MinimalPlugins)
+        .add_plugins(GamePlugin)
+        .add_plugins(TablePlugin)
+        .add_plugins(HudPlugin);
+    app.update();
+    app
+}
+
+#[test]
+fn hud_plugin_registers_without_panic() {
+    let _app = headless_app();
+}
+
+#[test]
+fn update_hud_runs_after_game_mutation_without_panic() {
+    let mut app = headless_app();
+    app.world_mut().resource_mut::<GameStateResource>().0 =
+        GameState::new(42, DrawStockConfig::DrawOne);
+    app.update();
+}
+
+fn read_hud_text<M: Component>(app: &mut App) -> String {
+    app.world_mut()
+        .query_filtered::<&Text, With<M>>()
+        .iter(app.world())
+        .next()
+        .map(|t| t.0.clone())
+        .unwrap_or_default()
+}
+
+#[test]
+fn score_reflects_game_state() {
+    let mut app = headless_app();
+    let score = app.world_mut().resource_mut::<GameStateResource>().0.force_test_score(20);
+    app.update();
+    assert_eq!(read_hud_text::<HudScore>(&mut app), format!("Score: {score}"));
+}
+
+#[test]
+fn moves_reflects_game_state() {
+    let mut app = headless_app();
+    app.world_mut()
+        .resource_mut::<GameStateResource>()
+        .0
+        .set_test_move_count(42);
+    app.update();
+    assert_eq!(read_hud_text::<HudMoves>(&mut app), "Moves: 42");
+}
+
+#[test]
+fn draw_three_mode_shows_draw_3_badge() {
+    use solitaire_core::game_state::GameMode;
+    let mut app = headless_app();
+    app.world_mut().resource_mut::<GameStateResource>().0 =
+        GameState::new_with_mode(42, DrawStockConfig::DrawThree, GameMode::Classic);
+    app.update();
+    assert_eq!(read_hud_text::<HudMode>(&mut app), "Draw 3");
+}
+
+#[test]
+fn zen_mode_hides_score() {
+    use solitaire_core::game_state::GameMode;
+    let mut app = headless_app();
+    app.world_mut().resource_mut::<GameStateResource>().0 =
+        GameState::new_with_mode(42, DrawStockConfig::DrawOne, GameMode::Zen);
+    app.update();
+    // Zen mode spec: "No score display" → text must be empty.
+    assert_eq!(read_hud_text::<HudScore>(&mut app), "");
+}
+
+#[test]
+fn time_display_uses_mm_ss_format() {
+    let mut app = headless_app();
+    app.world_mut()
+        .resource_mut::<GameStateResource>()
+        .0
+        .elapsed_seconds = 125;
+    app.update();
+    // 125 seconds = 2 minutes 5 seconds → "2:05"
+    assert_eq!(read_hud_text::<HudTime>(&mut app), "2:05");
+}
+
+// -----------------------------------------------------------------------
+// format_time_limit (pure function)
+// -----------------------------------------------------------------------
+
+#[test]
+fn format_time_limit_300_is_5_00() {
+    assert_eq!(format_time_limit(300), "5:00");
+}
+
+#[test]
+fn format_time_limit_zero() {
+    assert_eq!(format_time_limit(0), "0:00");
+}
+
+#[test]
+fn format_time_limit_pads_seconds() {
+    assert_eq!(format_time_limit(65), "1:05");
+}
+
+// -----------------------------------------------------------------------
+// challenge_hud_text (pure function)
+// -----------------------------------------------------------------------
+
+#[test]
+fn challenge_hud_text_shows_time_limit() {
+    let dc = DailyChallengeResource {
+        date: Local::now().date_naive(),
+        seed: 1,
+        goal_description: None,
+        target_score: None,
+        max_time_secs: Some(300),
+    };
+    assert_eq!(challenge_hud_text(&dc), "Limit: 5:00");
+}
+
+#[test]
+fn challenge_hud_text_shows_score_goal() {
+    let dc = DailyChallengeResource {
+        date: Local::now().date_naive(),
+        seed: 1,
+        goal_description: None,
+        target_score: Some(4000),
+        max_time_secs: None,
+    };
+    assert_eq!(challenge_hud_text(&dc), "Goal: 4000 pts");
+}
+
+#[test]
+fn challenge_hud_text_empty_when_no_constraints() {
+    let dc = DailyChallengeResource {
+        date: Local::now().date_naive(),
+        seed: 1,
+        goal_description: None,
+        target_score: None,
+        max_time_secs: None,
+    };
+    assert_eq!(challenge_hud_text(&dc), "");
+}
+
+#[test]
+fn challenge_time_color_above_60_is_info() {
+    let c = challenge_time_color(61);
+    assert_eq!(c, STATE_INFO);
+}
+
+#[test]
+fn challenge_time_color_exactly_60_is_info() {
+    let c = challenge_time_color(60);
+    assert_eq!(c, STATE_INFO);
+}
+
+#[test]
+fn challenge_time_color_59_is_warning() {
+    let c = challenge_time_color(59);
+    assert_eq!(c, STATE_WARNING);
+}
+
+#[test]
+fn challenge_time_color_30_is_warning() {
+    let c = challenge_time_color(30);
+    assert_eq!(c, STATE_WARNING);
+}
+
+#[test]
+fn challenge_time_color_29_is_danger() {
+    let c = challenge_time_color(29);
+    assert_eq!(c, STATE_DANGER);
+}
+
+#[test]
+fn challenge_time_color_zero_is_danger() {
+    let c = challenge_time_color(0);
+    assert_eq!(c, STATE_DANGER);
+}
+
+// -----------------------------------------------------------------------
+// HudChallenge in-app tests
+// -----------------------------------------------------------------------
+
+#[test]
+fn challenge_hud_empty_when_no_daily_resource() {
+    // No DailyChallengeResource inserted → HudChallenge must be empty.
+    let mut app = headless_app();
+    app.world_mut().resource_mut::<GameStateResource>().set_changed();
+    app.update();
+    assert_eq!(read_hud_text::<HudChallenge>(&mut app), "");
+}
+
+#[test]
+fn challenge_hud_shows_time_limit_when_resource_present() {
+    let mut app = headless_app();
+    app.world_mut().insert_resource(DailyChallengeResource {
+        date: Local::now().date_naive(),
+        seed: 42,
+        goal_description: Some("Win fast".to_string()),
+        target_score: None,
+        max_time_secs: Some(300),
+    });
+    app.world_mut().resource_mut::<GameStateResource>().set_changed();
+    app.update();
+    assert_eq!(read_hud_text::<HudChallenge>(&mut app), "Limit: 5:00");
+}
+
+#[test]
+fn challenge_hud_shows_score_goal_when_resource_present() {
+    let mut app = headless_app();
+    app.world_mut().insert_resource(DailyChallengeResource {
+        date: Local::now().date_naive(),
+        seed: 42,
+        goal_description: None,
+        target_score: Some(4000),
+        max_time_secs: None,
+    });
+    app.world_mut().resource_mut::<GameStateResource>().set_changed();
+    app.update();
+    assert_eq!(read_hud_text::<HudChallenge>(&mut app), "Goal: 4000 pts");
+}
+
+#[test]
+fn challenge_hud_clears_on_win() {
+    let mut app = headless_app();
+    app.world_mut().insert_resource(DailyChallengeResource {
+        date: Local::now().date_naive(),
+        seed: 42,
+        goal_description: None,
+        target_score: None,
+        max_time_secs: Some(300),
+    });
+    // Mark the game as won — HudChallenge should be empty.
+    app.world_mut().resource_mut::<GameStateResource>().0.set_test_won(true);
+    app.update();
+    assert_eq!(read_hud_text::<HudChallenge>(&mut app), "");
+}
+
+// -----------------------------------------------------------------------
+// HudUndos in-app tests
+// -----------------------------------------------------------------------
+
+#[test]
+fn undos_hud_empty_at_game_start() {
+    let mut app = headless_app();
+    app.update();
+    assert_eq!(read_hud_text::<HudUndos>(&mut app), "");
+}
+
+#[test]
+fn undos_hud_shows_count_after_undo() {
+    let mut app = headless_app();
+    app.world_mut()
+        .resource_mut::<GameStateResource>()
+        .0
+        .force_test_undos(3);
+    app.update();
+    assert_eq!(read_hud_text::<HudUndos>(&mut app), "Undos: 3");
+}
+
+// -----------------------------------------------------------------------
+// HudAutoComplete in-app tests (Task #56)
+// -----------------------------------------------------------------------
+
+fn headless_app_with_auto_complete() -> App {
+    let mut app = App::new();
+    app.add_plugins(MinimalPlugins)
+        .add_plugins(GamePlugin)
+        .add_plugins(TablePlugin)
+        .add_plugins(HudPlugin);
+    app.init_resource::<AutoCompleteState>();
+    app.update();
+    app
+}
+
+#[test]
+fn auto_complete_badge_shows_auto_when_active() {
+    let mut app = headless_app_with_auto_complete();
+    app.world_mut().resource_mut::<AutoCompleteState>().active = true;
+    // Also trigger game state change so the update fires.
+    app.world_mut()
+        .resource_mut::<GameStateResource>()
+        .0
+        .set_test_move_count(1);
+    app.update();
+    assert_eq!(read_hud_text::<HudAutoComplete>(&mut app), "AUTO");
+}
+
+#[test]
+fn auto_complete_badge_empty_when_inactive() {
+    let mut app = headless_app_with_auto_complete();
+    // active is false by default.
+    app.world_mut()
+        .resource_mut::<GameStateResource>()
+        .0
+        .set_test_move_count(1);
+    app.update();
+    assert_eq!(read_hud_text::<HudAutoComplete>(&mut app), "");
+}
+
+// -----------------------------------------------------------------------
+// HudRecycles in-app tests
+// -----------------------------------------------------------------------
+
+#[test]
+fn recycles_hud_hidden_when_zero_in_draw_one_mode() {
+    let mut app = headless_app();
+    // Draw-One, no recycles yet — text must be empty.
+    app.world_mut().resource_mut::<GameStateResource>().0 =
+        GameState::new(42, DrawStockConfig::DrawOne);
+    app.update();
+    assert_eq!(read_hud_text::<HudRecycles>(&mut app), "");
+}
+
+#[test]
+fn recycles_hud_hidden_when_zero_in_draw_three_mode() {
+    let mut app = headless_app();
+    // Draw-Three, no recycles yet — text must also be empty.
+    app.world_mut().resource_mut::<GameStateResource>().0 =
+        GameState::new(42, DrawStockConfig::DrawThree);
+    app.update();
+    assert_eq!(read_hud_text::<HudRecycles>(&mut app), "");
+}
+
+#[test]
+fn recycles_hud_shows_count_draw_three() {
+    let mut app = headless_app();
+    let mut gs = GameState::new(42, DrawStockConfig::DrawThree);
+    gs.force_test_recycles(3);
+    app.world_mut().resource_mut::<GameStateResource>().0 = gs;
+    app.update();
+    assert_eq!(read_hud_text::<HudRecycles>(&mut app), "Recycles: 3");
+}
+
+#[test]
+fn recycles_hud_shows_count_draw_one() {
+    let mut app = headless_app();
+    // Draw-One with recycle_count > 0 must now show the counter too.
+    let mut gs = GameState::new(42, DrawStockConfig::DrawOne);
+    gs.force_test_recycles(2);
+    app.world_mut().resource_mut::<GameStateResource>().0 = gs;
+    app.update();
+    assert_eq!(read_hud_text::<HudRecycles>(&mut app), "Recycles: 2");
+}
+
+// -----------------------------------------------------------------------
+// Score-change feedback (G2)
+// -----------------------------------------------------------------------
+
+/// Tells `TimePlugin` to advance by `secs` on every subsequent
+/// `app.update()`. Mirrors the helper in `ui_modal::tests`; kept
+/// local to avoid coupling the two test modules.
+fn set_manual_time_step(app: &mut App, secs: f32) {
+    use bevy::time::TimeUpdateStrategy;
+    use std::time::Duration;
+    app.insert_resource(TimeUpdateStrategy::ManualDuration(Duration::from_secs_f32(
+        secs,
+    )));
+}
+
+/// Counts entities matching component `M` currently in the world.
+fn count_with<M: Component>(app: &mut App) -> usize {
+    app.world_mut().query::<&M>().iter(app.world()).count()
+}
+
+/// A score jump ≥ `SCORE_FLOATER_THRESHOLD` spawns a floating
+/// `ScoreFloater` entity coloured `ACCENT_PRIMARY`. The pulse
+/// component is also inserted on the score readout — both signals
+/// fire from the same delta detection.
+#[test]
+fn score_increase_above_threshold_spawns_floater_in_accent_primary() {
+    let mut app = headless_app();
+    // Pin `Time::delta_secs()` to 0 so the floater's RGB and alpha
+    // can be asserted exactly: with Automatic strategy a few ms
+    // of wall-clock time leaks in between updates and the alpha
+    // drifts below 1.0 by `dt / lifetime`.
+    set_manual_time_step(&mut app, 0.0);
+    // Initial state has score=0; bumping by 50 (the threshold)
+    // is the smallest jump that triggers the floater.
+    app.world_mut().resource_mut::<GameStateResource>().0.force_test_score(50);
+    app.update();
+
+    // One floater should now exist.
+    let count = count_with::<ScoreFloater>(&mut app);
+    assert_eq!(count, 1, "expected a single ScoreFloater for a +50 jump");
+
+    // Its TextColor must be ACCENT_PRIMARY at full alpha. The
+    // detect system spawns the floater coloured ACCENT_PRIMARY
+    // and at dt=0 the first advance tick leaves alpha = 1.0.
+    let world = app.world_mut();
+    let mut q = world.query::<(&ScoreFloater, &TextColor)>();
+    let (_floater, color) = q.iter(world).next().expect("floater missing TextColor");
+    assert_eq!(color.0, ACCENT_PRIMARY);
+}
+
+/// After enough time for `MOTION_SCORE_PULSE_SECS * 2` to elapse
+/// the floater has reached the end of its lifetime and despawned.
+#[test]
+fn score_floater_despawns_after_full_lifetime() {
+    let mut app = headless_app();
+    app.world_mut().resource_mut::<GameStateResource>().0.force_test_score(50);
+    app.update();
+    assert_eq!(count_with::<ScoreFloater>(&mut app), 1);
+
+    // Advance by a delta well past the floater's lifetime — the
+    // single oversized tick clamps t at 1.0 and the entity is
+    // despawned in the same `Update`.
+    set_manual_time_step(&mut app, MOTION_SCORE_PULSE_SECS * 2.0 * 2.0 + 0.1);
+    app.update();
+    app.update(); // first update propagates the new strategy; second runs the system with non-zero dt.
+
+    assert_eq!(
+        count_with::<ScoreFloater>(&mut app),
+        0,
+        "floater should have despawned after its full lifetime"
+    );
+}
+
+/// A small score change (below the threshold) inserts a pulse on
+/// the readout but never spawns a floater — keeping the floating
+/// "+N" reserved for meaningful score jumps.
+#[test]
+fn score_increase_below_threshold_does_not_spawn_floater() {
+    let mut app = headless_app();
+    // +5 mirrors a single tableau-to-foundation move; well below
+    // the 50-point threshold so the floater path stays dormant.
+    app.world_mut().resource_mut::<GameStateResource>().0.force_test_score(5);
+    app.update();
+    assert_eq!(
+        count_with::<ScoreFloater>(&mut app),
+        0,
+        "delta of +5 must not spawn a floater"
+    );
+}
+
+/// The triangular pulse curve hits its peak (1.1) at t=0.5 and
+/// returns to 1.0 at the endpoints. Pure-function check that
+/// guards the curve shape against future tweaks.
+#[test]
+fn score_pulse_scale_is_triangular() {
+    assert!((score_pulse_scale(0.0) - 1.0).abs() < 1e-6);
+    assert!((score_pulse_scale(0.5) - 1.1).abs() < 1e-6);
+    assert!((score_pulse_scale(1.0) - 1.0).abs() < 1e-6);
+    // Values outside [0,1] are clamped before the curve runs.
+    assert!((score_pulse_scale(-0.2) - 1.0).abs() < 1e-6);
+    assert!((score_pulse_scale(2.0) - 1.0).abs() < 1e-6);
+}
+
+/// Streak flourish curve must be 1.0 at t=0, peak at t=0.5, and
+/// return to 1.0 at t=duration. Mirrors the `foundation_flourish_scale`
+/// curve test — the two animations share a triangular shape so a
+/// future tweak that desyncs them shows up here.
+#[test]
+fn streak_flourish_scale_curves_through_one_one_one() {
+    let dur = MOTION_STREAK_FLOURISH_SECS;
+    assert!(
+        (streak_flourish_scale(0.0, dur) - 1.0).abs() < 1e-5,
+        "streak flourish scale at t=0 must be 1.0",
+    );
+    assert!(
+        (streak_flourish_scale(dur / 2.0, dur) - STREAK_FLOURISH_PEAK_SCALE).abs() < 1e-5,
+        "streak flourish scale at midpoint must be STREAK_FLOURISH_PEAK_SCALE",
+    );
+    assert!(
+        (streak_flourish_scale(dur, dur) - 1.0).abs() < 1e-5,
+        "streak flourish scale at t=duration must return to 1.0",
+    );
+}
+
+/// Out-of-range values are clamped, not extrapolated. Matches the
+/// foundation flourish's clamp behaviour so the score readout never
+/// freezes at a non-1.0 scale on the frame after the flourish ends.
+#[test]
+fn streak_flourish_scale_clamps_out_of_range() {
+    let dur = MOTION_STREAK_FLOURISH_SECS;
+    assert!((streak_flourish_scale(-1.0, dur) - 1.0).abs() < 1e-5);
+    assert!((streak_flourish_scale(dur * 5.0, dur) - 1.0).abs() < 1e-5);
+}
+
+/// Zero duration (e.g. `AnimSpeed::Instant`) returns identity, never
+/// divides by zero.
+#[test]
+fn streak_flourish_scale_zero_duration_is_one() {
+    assert!((streak_flourish_scale(0.0, 0.0) - 1.0).abs() < 1e-5);
+    assert!((streak_flourish_scale(0.5, 0.0) - 1.0).abs() < 1e-5);
+}
+
+// -----------------------------------------------------------------------
+// Reduce-motion gates — ScorePulse, ScoreFloater, StreakFlourish
+// -----------------------------------------------------------------------
+
+/// Under `Settings::reduce_motion_mode`, a score bump must NOT spawn
+/// a `ScorePulse` on the readout or a `ScoreFloater` on the stage.
+#[test]
+fn score_change_skips_pulse_and_floater_under_reduce_motion() {
+    use solitaire_data::Settings;
+    let mut app = headless_app();
+    app.insert_resource(SettingsResource(Settings {
+        reduce_motion_mode: true,
+        ..Settings::default()
+    }));
+    // +100 would normally create both a ScorePulse and a ScoreFloater.
+    app.world_mut().resource_mut::<GameStateResource>().0.force_test_score(50);
+    app.update();
+    assert_eq!(
+        count_with::<ScorePulse>(&mut app),
+        0,
+        "ScorePulse must not spawn under reduce-motion"
+    );
+    assert_eq!(
+        count_with::<ScoreFloater>(&mut app),
+        0,
+        "ScoreFloater must not spawn under reduce-motion"
+    );
+}
+
+// -----------------------------------------------------------------------
+// Phase 2: keyboard focus ring — HUD action bar
+// -----------------------------------------------------------------------
+
+/// Returns the `Focusable` carried by the unique entity matching
+/// marker `M`. Helper for the HUD focus tests.
+fn focusable_for<M: Component>(app: &mut App) -> Focusable {
+    app.world_mut()
+        .query_filtered::<&Focusable, With<M>>()
+        .iter(app.world())
+        .next()
+        .copied()
+        .unwrap_or_else(|| panic!("no Focusable on the {} button", std::any::type_name::<M>()))
+}
+
+#[test]
+fn hud_buttons_get_focusable_marker() {
+    let mut app = headless_app();
+    // Every action-bar button is in `FocusGroup::Hud`.
+    for f in [
+        focusable_for::<MenuButton>(&mut app),
+        focusable_for::<UndoButton>(&mut app),
+        focusable_for::<PauseButton>(&mut app),
+        focusable_for::<HelpButton>(&mut app),
+        focusable_for::<HintButton>(&mut app),
+        focusable_for::<ModesButton>(&mut app),
+        focusable_for::<NewGameButton>(&mut app),
+    ] {
+        assert_eq!(
+            f.group,
+            FocusGroup::Hud,
+            "every HUD action button must be in FocusGroup::Hud"
+        );
+    }
+}
+
+/// Returns the tooltip string carried by the unique entity matching
+/// marker `M`. Panics if zero or more than one such entity exists,
+/// which is the invariant we want to enforce for HUD readouts and
+/// action buttons (each marker is spawned exactly once).
+fn tooltip_for<M: Component>(app: &mut App) -> String {
+    let mut q = app.world_mut().query_filtered::<&Tooltip, With<M>>();
+    let world = app.world();
+    let mut iter = q.iter(world);
+    let first = iter
+        .next()
+        .unwrap_or_else(|| {
+            panic!(
+                "expected a Tooltip on the {} entity",
+                std::any::type_name::<M>()
+            )
+        })
+        .0
+        .clone()
+        .into_owned();
+    assert!(
+        iter.next().is_none(),
+        "expected exactly one Tooltip-bearing entity for {}",
+        std::any::type_name::<M>()
+    );
+    first
+}
+
+/// Every HUD readout and action button must spawn with a `Tooltip`
+/// carrying the approved canonical microcopy. Mirrors the structure
+/// of `hud_buttons_get_focusable_marker` (Phase 2 focus test) so the
+/// invariant — one marker entity, one tooltip, exact text — is
+/// asserted consistently across every element.
+#[test]
+fn hud_elements_carry_expected_tooltip_strings() {
+    let mut app = headless_app();
+
+    // HUD readouts (left column, top to bottom).
+    assert_eq!(
+        tooltip_for::<HudScore>(&mut app),
+        "Points earned this game. Hidden in Zen mode."
+    );
+    assert_eq!(
+        tooltip_for::<HudMoves>(&mut app),
+        "Moves you've made this game. Counts placements and stock draws."
+    );
+    assert_eq!(
+        tooltip_for::<HudTime>(&mut app),
+        "Time on this game. Counts down in Time Attack."
+    );
+    assert_eq!(
+        tooltip_for::<HudMode>(&mut app),
+        "Active game mode. Click Modes to switch."
+    );
+    assert_eq!(
+        tooltip_for::<HudChallenge>(&mut app),
+        "Today's daily challenge target. Beat it for bonus XP."
+    );
+    assert_eq!(
+        tooltip_for::<HudDrawCycle>(&mut app),
+        "Cards drawn on the next stock click in Draw-Three."
+    );
+    assert_eq!(
+        tooltip_for::<HudUndos>(&mut app),
+        "Undos used this game. Any undo blocks the No Undo achievement."
+    );
+    assert_eq!(
+        tooltip_for::<HudRecycles>(&mut app),
+        "Times you've recycled the stock. Three or more unlocks Comeback."
+    );
+    assert_eq!(
+        tooltip_for::<HudAutoComplete>(&mut app),
+        "Board is solvable from here. Press Enter to auto-finish."
+    );
+    assert_eq!(
+        tooltip_for::<HudSelection>(&mut app),
+        "Pile selected with Tab. Use arrows or Enter to act."
+    );
+
+    // Action bar (left to right).
+    assert_eq!(
+        tooltip_for::<MenuButton>(&mut app),
+        "Open Stats, Achievements, Profile, Settings, or Leaderboard."
+    );
+    assert_eq!(
+        tooltip_for::<UndoButton>(&mut app),
+        "Take back your last move. Costs points and blocks No Undo."
+    );
+    assert_eq!(
+        tooltip_for::<PauseButton>(&mut app),
+        "Pause the game and freeze the timer."
+    );
+    assert_eq!(
+        tooltip_for::<HelpButton>(&mut app),
+        "Show controls, rules, and keyboard shortcuts."
+    );
+    assert_eq!(
+        tooltip_for::<HintButton>(&mut app),
+        "Highlight a suggested move. Cycles through alternatives on repeat taps."
+    );
+    assert_eq!(
+        tooltip_for::<ModesButton>(&mut app),
+        "Switch modes: Classic, Daily, Zen, Challenge, Time Attack."
+    );
+    assert_eq!(
+        tooltip_for::<NewGameButton>(&mut app),
+        "Start a fresh deal. Confirms first if a game is in progress."
+    );
+}
+
+/// Every interior row of the Modes and Menu popovers must carry a
+/// `Tooltip`. The popovers open from action-bar buttons whose own
+/// tooltips are already covered above; this test extends the
+/// invariant inward so hover discoverability is uniform across the
+/// HUD's nested controls.
+///
+/// We invoke the popover spawn helpers directly with a maxed-out
+/// `ProgressResource` and a `DailyChallengeResource` so every row
+/// branch fires (Classic, Daily, Zen, Challenge, Time Attack).
+/// Headless click simulation isn't needed — the contract under
+/// test is "every popover row spawns with a tooltip", which is a
+/// property of the spawn helpers themselves.
+#[test]
+fn popover_rows_carry_tooltip_strings() {
+    use crate::progress_plugin::ProgressResource;
+    use solitaire_sync::progress::PlayerProgress;
+
+    let mut app = headless_app();
+
+    // Force every mode row to render: level past the challenge
+    // unlock threshold, plus a daily challenge resource so the
+    // Daily row appears.
+    let progress = ProgressResource(PlayerProgress {
+        level: CHALLENGE_UNLOCK_LEVEL,
+        ..Default::default()
+    });
+    let daily = DailyChallengeResource {
+        date: Local::now().date_naive(),
+        seed: 1,
+        goal_description: None,
+        target_score: None,
+        max_time_secs: None,
+    };
+
+    // Spawn both popovers via their helpers. Mirrors how the click
+    // handlers invoke them in production — we just skip the click.
+    {
+        let world = app.world_mut();
+        let mut commands = world.commands();
+        spawn_modes_popover(&mut commands, Some(&progress), Some(&daily), None);
+        spawn_menu_popover(&mut commands, None);
+        world.flush();
+    }
+    app.update();
+
+    // Every ModeOption-tagged entity must also carry a Tooltip,
+    // and the count must match the five canonical modes.
+    let mut mode_q = app
+        .world_mut()
+        .query_filtered::<&Tooltip, With<ModeOption>>();
+    let mode_tooltips: Vec<String> = mode_q
+        .iter(app.world())
+        .map(|t| t.0.clone().into_owned())
+        .collect();
+    assert_eq!(
+        mode_tooltips.len(),
+        5,
+        "expected a tooltip on each of the 5 mode rows, got {}",
+        mode_tooltips.len()
+    );
+    // Every approved mode tooltip string must be present somewhere
+    // among the ModeOption rows. Order isn't asserted — the spawn
+    // order test elsewhere already covers that.
+    for expected in [
+        "Standard Klondike. Score, timer, and full progression.",
+        "Today's seeded deal. Same for every player worldwide.",
+        "No timer, no score, no penalties. Just play.",
+        "Hand-picked hard seeds. No undo allowed.",
+        "Win as many games as you can in ten minutes.",
+    ] {
+        assert!(
+            mode_tooltips.iter().any(|s| s == expected),
+            "missing mode tooltip: {expected:?}"
+        );
+    }
+
+    // Same contract for MenuOption rows: seven entries, each with a
+    // tooltip, exact strings matching the approved microcopy.
+    let mut menu_q = app
+        .world_mut()
+        .query_filtered::<&Tooltip, With<MenuOption>>();
+    let menu_tooltips: Vec<String> = menu_q
+        .iter(app.world())
+        .map(|t| t.0.clone().into_owned())
+        .collect();
+    assert_eq!(
+        menu_tooltips.len(),
+        7,
+        "expected a tooltip on each of the 7 menu rows, got {}",
+        menu_tooltips.len()
+    );
+    for expected in [
+        "Show controls, rules, and keyboard shortcuts.",
+        "Switch modes: Classic, Daily, Zen, Challenge, Time Attack.",
+        "Lifetime totals: wins, streaks, fastest time, best score.",
+        "Browse unlocked achievements and the rewards still ahead.",
+        "Your level, XP progress, and sync status.",
+        "Audio, animations, theme, draw mode, and sync.",
+        "Top players from your sync server. Opt in from Profile.",
+    ] {
+        assert!(
+            menu_tooltips.iter().any(|s| s == expected),
+            "missing menu tooltip: {expected:?}"
+        );
+    }
+}
+
+#[test]
+fn hud_button_order_matches_spawn_order() {
+    let mut app = headless_app();
+    // Visual reading order (left → right): Menu, Undo, Pause, Help,
+    // Hint, Modes, New Game. Their `order` fields must be 0..=6 in
+    // that order so Tab cycles them as the player reads them.
+    assert_eq!(focusable_for::<MenuButton>(&mut app).order, 0);
+    assert_eq!(focusable_for::<UndoButton>(&mut app).order, 1);
+    assert_eq!(focusable_for::<PauseButton>(&mut app).order, 2);
+    assert_eq!(focusable_for::<HelpButton>(&mut app).order, 3);
+    assert_eq!(focusable_for::<HintButton>(&mut app).order, 4);
+    assert_eq!(focusable_for::<ModesButton>(&mut app).order, 5);
+    assert_eq!(focusable_for::<NewGameButton>(&mut app).order, 6);
+}
+
+#[test]
+fn hud_focus_only_engages_when_button_hovered() {
+    // Phase 2 declares membership in `FocusGroup::Hud`; the
+    // engagement rule lives in `handle_focus_keys`. Two halves to
+    // this test:
+    //   (a) no modal + no hover ⇒ Tab is a no-op (Phase 1 contract
+    //       still holds when nothing is hovered).
+    //   (b) no modal + a HUD button hovered ⇒ Tab advances
+    //       `FocusedButton` to a Hud-grouped entity.
+    use crate::ui_focus::{FocusedButton, UiFocusPlugin};
+    use crate::ui_modal::UiModalPlugin;
+
+    let mut app = App::new();
+    app.add_plugins(MinimalPlugins)
+        .add_plugins(UiModalPlugin)
+        .add_plugins(UiFocusPlugin)
+        .add_plugins(GamePlugin)
+        .add_plugins(TablePlugin)
+        .add_plugins(HudPlugin);
+    app.init_resource::<ButtonInput<KeyCode>>();
+    app.update();
+
+    // (a) Sanity: HUD buttons exist and are focusable, but no
+    // modal open and no hover ⇒ FocusedButton stays None.
+    assert!(
+        app.world().resource::<FocusedButton>().0.is_none(),
+        "no modal open, no auto-focus"
+    );
+
+    // Press Tab. With no modal and no hover, `handle_focus_keys`
+    // resolves no active group and returns early — Tab must not
+    // advance the HUD focus ring on its own.
+    {
+        let mut input = app.world_mut().resource_mut::<ButtonInput<KeyCode>>();
+        input.release_all();
+        input.clear();
+        input.press(KeyCode::Tab);
+    }
+    app.update();
+
+    assert!(
+        app.world().resource::<FocusedButton>().0.is_none(),
+        "Tab with no modal and no Hud hover must not engage the HUD focus ring"
+    );
+
+    // (b) Hover the Menu button — the leftmost HUD action — and
+    // Tab. The Hud-group cycle should pick a Hud-tagged entity.
+    let menu_entity = app
+        .world_mut()
+        .query_filtered::<Entity, With<MenuButton>>()
+        .iter(app.world())
+        .next()
+        .expect("MenuButton entity should exist");
+    app.world_mut()
+        .entity_mut(menu_entity)
+        .insert(Interaction::Hovered);
+
+    {
+        let mut input = app.world_mut().resource_mut::<ButtonInput<KeyCode>>();
+        input.release_all();
+        input.clear();
+        input.press(KeyCode::Tab);
+    }
+    app.update();
+
+    let focused = app
+        .world()
+        .resource::<FocusedButton>()
+        .0
+        .expect("Tab with a HUD button hovered must engage the HUD focus ring");
+    // The focused entity must itself be Hud-grouped (i.e. one of
+    // the action-bar buttons), not anything else in the world.
+    let focusable = app
+        .world()
+        .entity(focused)
+        .get::<Focusable>()
+        .expect("focused entity must carry Focusable");
+    assert_eq!(
+        focusable.group,
+        FocusGroup::Hud,
+        "Hud-engaged Tab must focus a Hud-grouped entity"
+    );
+}

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/input_plugin/mod.rs

@@ -1829,712 +1829,4 @@ pub fn find_hint(game: &GameState) -> Option<(KlondikePile, KlondikePile)> {
 const _VEC3_REFERENCED: Option<Vec3> = None;
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::layout::compute_layout;
-    use solitaire_core::{Deck, Foundation, Rank, Suit, Tableau};
-    use solitaire_core::{DrawStockConfig, game_state::GameState};
-
-    fn clear_test_piles(game: &mut GameState) {
-        game.set_test_stock_cards(Vec::new());
-        game.set_test_waste_cards(Vec::new());
-        for foundation in [
-            Foundation::Foundation1,
-            Foundation::Foundation2,
-            Foundation::Foundation3,
-            Foundation::Foundation4,
-        ] {
-            game.set_test_foundation_cards(foundation, Vec::new());
-        }
-        for tableau in [
-            Tableau::Tableau1,
-            Tableau::Tableau2,
-            Tableau::Tableau3,
-            Tableau::Tableau4,
-            Tableau::Tableau5,
-            Tableau::Tableau6,
-            Tableau::Tableau7,
-        ] {
-            game.set_test_tableau_cards(tableau, Vec::new());
-        }
-    }
-
-    #[test]
-    fn dragged_card_z_matches_resting_stack_step() {
-        assert!((dragged_card_z(0) - DRAG_Z).abs() < 1e-6);
-        let step = dragged_card_z(1) - dragged_card_z(0);
-        assert!(
-            step > 0.02,
-            "drag step must exceed Android overlay local_z, got {step}"
-        );
-        assert!(
-            step + 1e-4 >= STACK_FAN_FRAC,
-            "drag step must stay aligned with resting stack spacing, got {step}"
-        );
-    }
-
-    #[test]
-    fn point_in_rect_inside_returns_true() {
-        let center = Vec2::new(10.0, 20.0);
-        let size = Vec2::new(40.0, 60.0);
-        assert!(point_in_rect(Vec2::new(10.0, 20.0), center, size));
-        assert!(point_in_rect(Vec2::new(29.0, 49.0), center, size));
-        assert!(point_in_rect(Vec2::new(-9.0, -9.0), center, size));
-    }
-
-    #[test]
-    fn point_in_rect_on_edge_returns_true() {
-        let center = Vec2::ZERO;
-        let size = Vec2::new(10.0, 10.0);
-        assert!(point_in_rect(Vec2::new(5.0, 5.0), center, size));
-        assert!(point_in_rect(Vec2::new(-5.0, -5.0), center, size));
-    }
-
-    #[test]
-    fn point_in_rect_outside_returns_false() {
-        let center = Vec2::ZERO;
-        let size = Vec2::new(10.0, 10.0);
-        assert!(!point_in_rect(Vec2::new(6.0, 0.0), center, size));
-        assert!(!point_in_rect(Vec2::new(0.0, 6.0), center, size));
-        assert!(!point_in_rect(Vec2::new(-100.0, 0.0), center, size));
-    }
-
-    #[test]
-    fn find_draggable_picks_top_of_tableau() {
-        let game = GameState::new(42, DrawStockConfig::DrawOne);
-        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-
-        // In tableau 6, the visually topmost card is the last (face-up) one.
-        // Its position: base.y + fan * 6.
-        let top_pos = card_position(&game, &layout, &KlondikePile::Tableau(Tableau::Tableau7), 6);
-        let result = find_draggable_at(top_pos, &game, &layout).expect("hit");
-        assert_eq!(result.0, KlondikePile::Tableau(Tableau::Tableau7));
-        assert_eq!(result.1, 6);
-        assert_eq!(result.2.len(), 1);
-    }
-
-    #[test]
-    fn find_draggable_picks_waste_top_with_multiple_cards() {
-        // Reproduces the reported "drags the wrong waste card" bug: with several
-        // cards in the waste, clicking the visible top must pick the actual top
-        // (last index), not the buffer card underneath it.
-        let mut game = GameState::new(42, DrawStockConfig::DrawOne);
-        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-        clear_test_piles(&mut game);
-        let waste = vec![Card::new(Deck::Deck1, Suit::Clubs, Rank::Two),
-                         Card::new(Deck::Deck1, Suit::Hearts, Rank::Five),
-                         Card::new(Deck::Deck1, Suit::Spades, Rank::Nine)];
-        game.set_test_waste_cards(waste.clone());
-
-        let top_index = waste.len() - 1; // 2 = the visible top
-        let top_pos = card_position(&game, &layout, &KlondikePile::Stock, top_index);
-        let result = find_draggable_at(top_pos, &game, &layout).expect("waste top is draggable");
-        assert_eq!(result.0, KlondikePile::Stock, "origin is the waste pile");
-        assert_eq!(result.1, top_index, "picks the top index, not the buffer");
-        assert_eq!(result.2, vec![waste[top_index].clone()], "drags the top card only");
-    }
-
-    #[test]
-    fn find_draggable_picks_lone_waste_card() {
-        // "can't play the first card in the stock" — a waste of one card must
-        // still be draggable.
-        let mut game = GameState::new(42, DrawStockConfig::DrawOne);
-        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-        clear_test_piles(&mut game);
-        let card = Card::new(Deck::Deck1, Suit::Diamonds, Rank::Ace);
-        game.set_test_waste_cards(vec![card.clone()]);
-
-        let pos = card_position(&game, &layout, &KlondikePile::Stock, 0);
-        let result = find_draggable_at(pos, &game, &layout).expect("lone waste card is draggable");
-        assert_eq!(result.0, KlondikePile::Stock);
-        assert_eq!(result.1, 0);
-        assert_eq!(result.2, vec![card]);
-    }
-
-    #[test]
-    fn draw_three_waste_hit_test_matches_render_fan_step() {
-        // Regression: the Draw-Three waste hit-test must use the same fan step as
-        // the renderer (`card_plugin::waste_fan_step`). The previous hard-coded
-        // `card_size.x * 0.28` matched the renderer only on desktop (column step =
-        // 1.25*cw); under tighter Android-style spacing the two drift and the top
-        // fanned card's click target lands on the card beneath it — so dragging
-        // the visible top card plays the wrong one.
-        let mut game = GameState::new(7, DrawStockConfig::DrawThree);
-        let mut layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-
-        // Force tight (Android-like) column spacing: ~1.03 * card_width.
-        let cw = layout.card_size.x;
-        let base = layout.pile_positions[&KlondikePile::Stock];
-        let t1 = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau1)];
-        layout.pile_positions.insert(
-            KlondikePile::Tableau(Tableau::Tableau2),
-            Vec2::new(t1.x + cw * 1.03, t1.y),
-        );
-
-        clear_test_piles(&mut game);
-        let waste = vec![
-            Card::new(Deck::Deck1, Suit::Clubs, Rank::Two),
-            Card::new(Deck::Deck1, Suit::Hearts, Rank::Five),
-            Card::new(Deck::Deck1, Suit::Spades, Rank::Nine),
-            Card::new(Deck::Deck1, Suit::Diamonds, Rank::King),
-        ];
-        game.set_test_waste_cards(waste.clone());
-
-        // visible_start = len-3 = 1, so the top card sits at fan slot 2.
-        let top_index = waste.len() - 1;
-        let pos = card_position(&game, &layout, &KlondikePile::Stock, top_index);
-
-        let expected = base.x + 2.0 * waste_fan_step(&layout);
-        assert!(
-            (pos.x - expected).abs() < 1e-3,
-            "hit-test must use the shared waste fan step"
-        );
-        // The old fixed constant would have drifted from the renderer here.
-        let old = base.x + 2.0 * cw * 0.28;
-        assert!(
-            (pos.x - old).abs() > 1.0,
-            "shared step must differ from the old fixed step under tight spacing"
-        );
-    }
-
-    #[test]
-    fn find_draggable_skips_face_down_cards() {
-        let game = GameState::new(42, DrawStockConfig::DrawOne);
-        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-
-        // Tableau 6 has 7 cards: 6 face-down (indices 0..5) + 1 face-up at
-        // the bottom (index 6). Click at the topmost face-down card's
-        // position — its full body is partly visible above the fanned
-        // face-up card, but the iterator should skip face-down cards and
-        // the cursor sits above the face-up card's AABB, so the result
-        // is None.
-        let face_down_pos =
-            card_position(&game, &layout, &KlondikePile::Tableau(Tableau::Tableau7), 0);
-        let result = find_draggable_at(face_down_pos, &game, &layout);
-        assert!(result.is_none(), "face-down cards should not be draggable");
-    }
-
-    #[test]
-    fn find_draggable_hits_face_up_card_with_face_down_cards_above_it() {
-        // Regression test for the bug where input_plugin's hit-testing used
-        // a uniform 0.25 fan step but card_plugin renders face-down cards
-        // at 0.12 — so for any column with face-down cards above the
-        // face-up bottom card, clicking the visible card face missed the
-        // hit-test box and only the bottom strip of the card responded.
-        let game = GameState::new(42, DrawStockConfig::DrawOne);
-        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-
-        // Tableau 6 starts with 6 face-down + 1 face-up. The face-up card
-        // sits at base.y - 6 * TABLEAU_FACEDOWN_FAN_FRAC * card_h, NOT at
-        // base.y - 6 * TABLEAU_FAN_FRAC * card_h. Click the centre.
-        let face_up_pos =
-            card_position(&game, &layout, &KlondikePile::Tableau(Tableau::Tableau7), 6);
-        let result = find_draggable_at(face_up_pos, &game, &layout)
-            .expect("clicking the face-up card's visible centre must initiate a drag");
-        assert_eq!(result.0, KlondikePile::Tableau(Tableau::Tableau7));
-        assert_eq!(result.1, 6);
-        assert_eq!(result.2.len(), 1);
-    }
-
-    #[test]
-    fn find_draggable_returns_run_when_picking_mid_stack() {
-        // Manually construct a tableau with three face-up cards all stacked.
-        let mut game = GameState::new(1, DrawStockConfig::DrawOne);
-        use solitaire_core::Deck as D;
-        use solitaire_core::{Card, Rank, Suit};
-        let king = Card::new(D::Deck1, Suit::Spades, Rank::King);
-        let queen = Card::new(D::Deck1, Suit::Hearts, Rank::Queen);
-        let jack = Card::new(D::Deck1, Suit::Clubs, Rank::Jack);
-        game.set_test_tableau_cards(
-            Tableau::Tableau1,
-            vec![king, queen.clone(), jack.clone()],
-        );
-
-        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-        // The Queen's geometric center (index 1) is inside the Jack's bounding box
-        // (Jack fans 0.5h below base; its box spans [base-h, base]).  To hit the
-        // Queen we click in her visible strip: the 0.25h band above the Jack's top
-        // edge (base.y to base.y+0.25h).  Midpoint = queen_center + 0.375*card_h.
-        let queen_center =
-            card_position(&game, &layout, &KlondikePile::Tableau(Tableau::Tableau1), 1);
-        let pos = queen_center + Vec2::new(0.0, layout.card_size.y * 0.375);
-        let (pile, start, ids) = find_draggable_at(pos, &game, &layout).expect("hit");
-        assert_eq!(pile, KlondikePile::Tableau(Tableau::Tableau1));
-        assert_eq!(start, 1);
-        assert_eq!(ids, vec![queen, jack]);
-    }
-
-    #[test]
-    fn find_draggable_skips_non_top_waste_card() {
-        let mut game = GameState::new(1, DrawStockConfig::DrawOne);
-        use solitaire_core::Deck as D;
-        use solitaire_core::{Card, Rank, Suit};
-        let two_spades = Card::new(D::Deck1, Suit::Spades, Rank::Two);
-        let three_hearts = Card::new(D::Deck1, Suit::Hearts, Rank::Three);
-        game.set_test_waste_cards(vec![two_spades, three_hearts.clone()]);
-
-        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-        // Both cards in waste sit at the same (x, y). Clicking should pick
-        // the visually top card (three_hearts), with count = 1.
-        let pos = card_position(&game, &layout, &KlondikePile::Stock, 0);
-        let (pile, start, ids) = find_draggable_at(pos, &game, &layout).expect("hit");
-        assert_eq!(pile, KlondikePile::Stock);
-        assert_eq!(start, 1);
-        assert_eq!(ids, vec![three_hearts]);
-    }
-
-    #[test]
-    fn find_drop_target_hits_empty_tableau_pile_marker() {
-        let game = GameState::new(42, DrawStockConfig::DrawOne);
-        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-        // Move all cards out of tableau 0 so its marker is the only drop area.
-        let mut game = game;
-        game.set_test_tableau_cards(Tableau::Tableau1, Vec::new());
-        let pos = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau1)];
-        let target = find_drop_target(
-            pos,
-            &game,
-            &layout,
-            &KlondikePile::Tableau(Tableau::Tableau7),
-        );
-        assert_eq!(target, Some(KlondikePile::Tableau(Tableau::Tableau1)));
-    }
-
-    #[test]
-    fn find_drop_target_returns_none_for_origin() {
-        let game = GameState::new(42, DrawStockConfig::DrawOne);
-        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-        let pos = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau4)];
-        let target = find_drop_target(
-            pos,
-            &game,
-            &layout,
-            &KlondikePile::Tableau(Tableau::Tableau4),
-        );
-        assert_eq!(target, None);
-    }
-
-    #[test]
-    fn pile_drop_rect_extends_for_tableau_with_cards() {
-        let game = GameState::new(42, DrawStockConfig::DrawOne);
-        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-        // Tableau 6 has 7 cards.
-        let (_, size) = pile_drop_rect(&KlondikePile::Tableau(Tableau::Tableau7), &layout, &game);
-        // Expected: card_height + 6 fan steps.
-        let expected = layout.card_size.y * (1.0 + 6.0 * layout.tableau_fan_frac);
-        assert!(
-            (size.y - expected).abs() < 1e-3,
-            "expected {expected}, got {}",
-            size.y
-        );
-    }
-
-    #[test]
-    fn find_draggable_draw_three_waste_top_card_hit_at_fanned_position() {
-        use solitaire_core::Deck as D;
-        use solitaire_core::{Card, Rank, Suit};
-        use solitaire_core::{DrawStockConfig, game_state::GameMode};
-        let mut game = GameState::new_with_mode(1, DrawStockConfig::DrawThree, GameMode::Classic);
-        // Three waste cards; top (four_clubs) is rightmost in the fan.
-        let two_spades = Card::new(D::Deck1, Suit::Spades, Rank::Two);
-        let three_hearts = Card::new(D::Deck1, Suit::Hearts, Rank::Three);
-        let four_clubs = Card::new(D::Deck1, Suit::Clubs, Rank::Four);
-        game.set_test_waste_cards(vec![two_spades, three_hearts, four_clubs.clone()]);
-
-        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-        let waste_base = layout.pile_positions[&KlondikePile::Stock];
-        // Top card (slot=2) is at base.x + 2 * 0.28 * card_width.
-        let top_card_x = waste_base.x + 2.0 * 0.28 * layout.card_size.x;
-        let cursor = Vec2::new(top_card_x, waste_base.y);
-
-        let result = find_draggable_at(cursor, &game, &layout);
-        assert!(
-            result.is_some(),
-            "top fanned waste card must be hittable at its visual X position"
-        );
-        let (pile, _start, ids) = result.unwrap();
-        assert_eq!(pile, KlondikePile::Stock);
-        assert_eq!(ids, vec![four_clubs], "only the top card is draggable from waste");
-    }
-
-    #[test]
-    fn find_draggable_returns_none_for_click_on_empty_pile() {
-        let mut game = GameState::new(42, DrawStockConfig::DrawOne);
-        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-        // Clear tableau 0 so it's an empty slot.
-        game.set_test_tableau_cards(Tableau::Tableau1, Vec::new());
-        let pos = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau1)];
-        let result = find_draggable_at(pos, &game, &layout);
-        assert!(
-            result.is_none(),
-            "clicking an empty pile must not produce a draggable"
-        );
-    }
-
-    #[test]
-    fn pile_drop_rect_is_card_sized_for_non_tableau() {
-        let game = GameState::new(42, DrawStockConfig::DrawOne);
-        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-        for pile in [
-            KlondikePile::Stock,
-            KlondikePile::Foundation(Foundation::Foundation3),
-        ] {
-            let (_, size) = pile_drop_rect(&pile, &layout, &game);
-            assert_eq!(size, layout.card_size);
-        }
-    }
-
-    // -----------------------------------------------------------------------
-    // Task #27 — best_destination pure-function tests
-    // -----------------------------------------------------------------------
-
-    #[test]
-    fn best_destination_returns_none_when_no_legal_move() {
-        use solitaire_core::Deck as D;
-        use solitaire_core::{Card, Rank, Suit};
-        let mut game = GameState::new(1, DrawStockConfig::DrawOne);
-
-        // Clear everything except one card that has nowhere to go.
-        clear_test_piles(&mut game);
-
-        // A Two of Clubs with empty foundations and empty tableau has no destination.
-        let card = Card::new(D::Deck1, Suit::Clubs, Rank::Two);
-        assert!(best_destination(&card, &game).is_none());
-    }
-
-    // -----------------------------------------------------------------------
-    // best_tableau_destination_for_stack pure-function tests
-    // -----------------------------------------------------------------------
-
-    #[test]
-    fn best_tableau_destination_for_stack_skips_source_pile() {
-        use solitaire_core::Deck as D;
-        use solitaire_core::{Card, Rank, Suit};
-        let mut game = GameState::new(1, DrawStockConfig::DrawOne);
-
-        clear_test_piles(&mut game);
-
-        // Only tableau 0 has anything; every other column is empty.
-        // A King is the only card that can go on an empty tableau column.
-        // Source is Tableau(0), so the result must NOT be Tableau(0).
-        let king = Card::new(D::Deck1, Suit::Hearts, Rank::King);
-        game.set_test_tableau_cards(Tableau::Tableau1, vec![king.clone()]);
-
-        let result = best_tableau_destination_for_stack(
-            &king,
-            &KlondikePile::Tableau(Tableau::Tableau1),
-            &game,
-            1,
-        );
-        // Result must be some other empty tableau column, never the source.
-        if let Some((dest, _)) = result {
-            assert_ne!(dest, KlondikePile::Tableau(Tableau::Tableau1));
-        }
-    }
-
-    #[test]
-    fn best_tableau_destination_for_stack_returns_none_when_no_legal_move() {
-        use solitaire_core::Deck as D;
-        use solitaire_core::{Card, Rank, Suit};
-        let mut game = GameState::new(1, DrawStockConfig::DrawOne);
-
-        clear_test_piles(&mut game);
-
-        // Source: tableau 0 has a Two of Clubs (can't go on empty pile; not a King).
-        // All other piles are empty — no legal tableau target.
-        let two_clubs = Card::new(D::Deck1, Suit::Clubs, Rank::Two);
-        game.set_test_tableau_cards(Tableau::Tableau1, vec![two_clubs.clone()]);
-
-        let result = best_tableau_destination_for_stack(
-            &two_clubs,
-            &KlondikePile::Tableau(Tableau::Tableau1),
-            &game,
-            1,
-        );
-        assert!(
-            result.is_none(),
-            "Two of Clubs has no legal tableau destination on empty piles"
-        );
-    }
-
-    // -----------------------------------------------------------------------
-    // Task #28 — find_hint pure-function tests
-    // -----------------------------------------------------------------------
-
-    #[test]
-    fn find_hint_finds_ace_to_foundation() {
-        use solitaire_core::Deck as D;
-        use solitaire_core::{Card, Rank, Suit};
-        let mut game = GameState::new(1, DrawStockConfig::DrawOne);
-
-        // Place Ace of Clubs on top of tableau 0.
-        clear_test_piles(&mut game);
-        let ace_clubs = Card::new(D::Deck1, Suit::Clubs, Rank::Ace);
-        game.set_test_tableau_cards(Tableau::Tableau1, vec![ace_clubs]);
-
-        let hint = find_hint(&game);
-        assert!(hint.is_some(), "should find a hint");
-        let (from, to) = hint.unwrap();
-        assert_eq!(from, KlondikePile::Tableau(Tableau::Tableau1));
-        assert_eq!(to, KlondikePile::Foundation(Foundation::Foundation1));
-    }
-
-    // -----------------------------------------------------------------------
-    // G key fires ForfeitRequestEvent (modal-based forfeit flow)
-    // -----------------------------------------------------------------------
-
-    /// `handle_keyboard_forfeit` only checks `paused` and the G keypress;
-    /// the "is there actually a game?" gating lives in
-    /// `pause_plugin::handle_forfeit_request` so it can surface a
-    /// "No game to forfeit" toast instead of failing silently.
-    #[test]
-    fn g_key_paused_check_keeps_handler_silent_while_pause_modal_owns_input() {
-        // Build the system param state by hand so we don't rely on a
-        // full Bevy app: the assertion is that the function returns
-        // early on the paused branch without calling write_message.
-        // This is verified by the plain `if paused { return; }` shape;
-        // the body is small enough to inspect by reading.
-        // (Higher-level integration coverage lives in the pause-plugin
-        // tests where `forfeit_app` simulates the full flow.)
-        let _ = handle_keyboard_forfeit; // proves the symbol still compiles
-    }
-
-    // -----------------------------------------------------------------------
-    // all_hints / new-game window — pure-function tests added during refactor
-    // -----------------------------------------------------------------------
-
-    /// Pass 3 of `all_hints` should suggest drawing from the stock when there
-    /// are no other moves and the stock is non-empty.
-    #[test]
-    fn all_hints_suggests_draw_when_no_moves_and_stock_nonempty() {
-        use solitaire_core::Deck as D;
-        use solitaire_core::{Card, Rank, Suit};
-        let mut game = GameState::new(1, DrawStockConfig::DrawOne);
-
-        // Remove all foundation, tableau, and waste cards so no pile-to-pile
-        // move exists. Leave one card in the stock.
-        clear_test_piles(&mut game);
-        // Put one card back into the stock so "draw" is a valid suggestion.
-        game.set_test_stock_cards(vec![Card::new(D::Deck1, Suit::Clubs, Rank::Ace)]);
-
-        let hints = all_hints(&game);
-        assert_eq!(hints.len(), 1, "exactly one hint: draw from stock");
-        let (from, to) = &hints[0];
-        assert_eq!(*from, KlondikePile::Stock, "hint must come from Stock");
-        assert_eq!(*to, KlondikePile::Stock, "hint must point to Waste");
-    }
-
-    // `all_hints` must be empty when both stock and waste are empty and no
-    // pile-to-pile move exists — the game is truly stuck.
-    // -----------------------------------------------------------------------
-    // Drag-rejection return tween — `CardAnimation` replaces the legacy
-    // `ShakeAnim` on the dragged cards. The audio cue
-    // (`card_invalid.wav` via `MoveRejectedEvent`) is unchanged; only the
-    // visual response on the dragged cards swapped from a horizontal wiggle
-    // to a smooth ease-out glide back to the origin pile.
-    //
-    // These tests build the component values exactly as `end_drag` and
-    // `touch_end_drag` would, then assert the resulting `CardAnimation` is
-    // shaped correctly. Driving `end_drag` end-to-end requires a real window
-    // and mouse-button input, so we exercise the data path the same way the
-    // legacy `ShakeAnim` tests did.
-    // -----------------------------------------------------------------------
-
-    /// Helper: build the `CardAnimation` the rejection paths construct for
-    /// one dragged card. Mirrors the inline logic in `end_drag` and
-    /// `touch_end_drag` so the tests stay in sync with the production code.
-    fn build_drag_reject_animation(
-        drag_pos: Vec2,
-        drag_z: f32,
-        target_pos: Vec2,
-        stack_index: usize,
-    ) -> CardAnimation {
-        let end_z = 1.0 + (stack_index as f32) * STACK_FAN_FRAC;
-        CardAnimation::slide(drag_pos, drag_z, target_pos, end_z, MotionCurve::Responsive)
-            .with_duration(MOTION_DRAG_REJECT_SECS)
-    }
-
-    /// Every card in `drag.cards` should receive its own `CardAnimation` on
-    /// rejection. With the shake → tween migration, the assertion changes
-    /// from "every dragged card gets a ShakeAnim" to "every dragged card
-    /// gets a CardAnimation" — same coverage, new component.
-    #[test]
-    fn rejected_drag_inserts_card_animation_on_each_dragged_card() {
-        use solitaire_core::Deck as D;
-        use solitaire_core::{Card, Rank, Suit};
-        // Simulate a stack drag of two cards.
-        let dragged_cards: Vec<Card> = vec![
-            Card::new(D::Deck1, Suit::Hearts, Rank::King),
-            Card::new(D::Deck1, Suit::Spades, Rank::Queen),
-        ];
-
-        let mut animated: Vec<Card> = Vec::new();
-        for card in &dragged_cards {
-            // In `end_drag` we iterate `drag.cards` and look up each card in
-            // `card_entities`. The cards we would insert a `CardAnimation` on
-            // must exactly match the dragged set.
-            animated.push(card.clone());
-        }
-
-        assert_eq!(
-            animated, dragged_cards,
-            "every card in drag.cards must receive a CardAnimation on rejection"
-        );
-    }
-
-    /// The `end` field of the inserted tween must equal the card's resting
-    /// slot in its origin pile — the position the card belongs at after a
-    /// rejected drop. Without this, the tween would glide to the wrong spot
-    /// and `sync_cards` would have to fight it back.
-    #[test]
-    fn rejected_drag_animation_targets_origin_resting_position() {
-        let drag_pos = Vec2::new(640.0, 200.0); // somewhere mid-screen
-        let target_pos = Vec2::new(123.5, -50.0); // origin pile slot
-        let anim =
-            build_drag_reject_animation(drag_pos, DRAG_Z, target_pos, /* stack_index */ 3);
-
-        assert!(
-            (anim.end - target_pos).length() < 1e-6,
-            "CardAnimation.end must match the origin slot's resting position. \
-             Expected {target_pos:?}, got {:?}",
-            anim.end
-        );
-    }
-
-    /// The `start` field of the inserted tween must equal the card's
-    /// drop-time transform position — i.e. wherever the cursor or finger
-    /// released the card. This is what makes the glide feel like a
-    /// continuous return rather than a teleport-then-shake.
-    #[test]
-    fn rejected_drag_animation_starts_from_drag_position() {
-        let drag_pos = Vec2::new(640.0, 200.0);
-        let target_pos = Vec2::new(80.0, -120.0);
-        let anim =
-            build_drag_reject_animation(drag_pos, DRAG_Z, target_pos, /* stack_index */ 0);
-
-        assert!(
-            (anim.start - drag_pos).length() < 1e-6,
-            "CardAnimation.start must match the drop-time transform position \
-             (where the cursor released). Expected {drag_pos:?}, got {:?}",
-            anim.start
-        );
-        // And the start must be visibly distinct from the origin slot — the
-        // whole point of the tween is that it visibly travels.
-        assert!(
-            (anim.start - anim.end).length() > 1.0,
-            "rejected drag should travel a visible distance, got start={:?} end={:?}",
-            anim.start,
-            anim.end
-        );
-    }
-
-    /// The tween duration is taken from the project-wide motion token so
-    /// designers can retune the feel from one place. Keeps the constant and
-    /// the call site honest.
-    #[test]
-    fn rejected_drag_animation_uses_correct_duration() {
-        let anim = build_drag_reject_animation(
-            Vec2::new(640.0, 200.0),
-            DRAG_Z,
-            Vec2::new(80.0, -120.0),
-            0,
-        );
-        assert!(
-            (anim.duration - MOTION_DRAG_REJECT_SECS).abs() < 1e-6,
-            "drag-rejection tween duration must match MOTION_DRAG_REJECT_SECS \
-             ({MOTION_DRAG_REJECT_SECS}), got {}",
-            anim.duration
-        );
-    }
-
-    /// The curve must be a no-overshoot ease-out so the card decelerates
-    /// cleanly into its rest position — overshoot on a rejection feels
-    /// jittery rather than forgiving.
-    #[test]
-    fn rejected_drag_animation_uses_responsive_curve() {
-        let anim = build_drag_reject_animation(
-            Vec2::new(640.0, 200.0),
-            DRAG_Z,
-            Vec2::new(80.0, -120.0),
-            0,
-        );
-        assert_eq!(
-            anim.curve,
-            MotionCurve::Responsive,
-            "drag-rejection tween must use Responsive (quintic ease-out) \
-             so the card snaps back without bouncing past the slot"
-        );
-    }
-
-    /// The `start_z` of the tween must equal the card's drop-time z
-    /// (`DRAG_Z`) so the card stays above the rest of the table while it
-    /// travels home, then settles at the correct resting z.
-    #[test]
-    fn rejected_drag_animation_lifts_from_drag_z_to_resting_z() {
-        let stack_index = 2_usize;
-        let anim = build_drag_reject_animation(
-            Vec2::new(640.0, 200.0),
-            DRAG_Z,
-            Vec2::new(80.0, -120.0),
-            stack_index,
-        );
-        assert!(
-            (anim.start_z - DRAG_Z).abs() < 1e-6,
-            "tween must start at DRAG_Z so the card stays on top during the glide"
-        );
-        let expected_end_z = 1.0 + (stack_index as f32) * STACK_FAN_FRAC;
-        assert!(
-            (anim.end_z - expected_end_z).abs() < 1e-6,
-            "tween must end at the slot's resting z, got {} expected {expected_end_z}",
-            anim.end_z
-        );
-    }
-
-    // -----------------------------------------------------------------------
-    // Hint system — async port (v0.18.0+)
-    //
-    // `handle_keyboard_hint` no longer runs the solver inline; it
-    // spawns an `AsyncComputeTaskPool` task whose result the polling
-    // system in `pending_hint` turns into hint visuals one frame
-    // later. The behaviour contract this section pins is "pressing H
-    // populates `PendingHintTask`" — the spawn-to-emit pipeline is
-    // covered end-to-end in `pending_hint::tests`.
-    // -----------------------------------------------------------------------
-
-    /// Pressing H on a non-paused, non-won game with a live
-    /// `GameStateResource` + `LayoutResource` must populate
-    /// `PendingHintTask`. The polling system, exercised in
-    /// `pending_hint::tests`, drives the result to a visual event.
-    #[test]
-    fn pressing_h_spawns_pending_hint_task() {
-        let mut app = App::new();
-        app.add_plugins(MinimalPlugins);
-        app.add_message::<InfoToastEvent>();
-        app.add_message::<HintVisualEvent>();
-        app.init_resource::<HintCycleIndex>();
-        app.init_resource::<HintSolverConfig>();
-        app.init_resource::<crate::pending_hint::PendingHintTask>();
-        app.init_resource::<ButtonInput<KeyCode>>();
-        app.insert_resource(LayoutResource(
-            compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true),
-        ));
-        app.insert_resource(GameStateResource(GameState::new(42, DrawStockConfig::DrawOne)));
-        app.add_systems(Update, handle_keyboard_hint);
-
-        // Simulate the H key being pressed this frame.
-        {
-            let mut input = app.world_mut().resource_mut::<ButtonInput<KeyCode>>();
-            input.release(KeyCode::KeyH);
-            input.clear();
-            input.press(KeyCode::KeyH);
-        }
-        app.update();
-
-        assert!(
-            app.world()
-                .resource::<crate::pending_hint::PendingHintTask>()
-                .is_pending(),
-            "pressing H must spawn an async hint task",
-        );
-    }
-}
+mod tests;

solitaire_engine/src/input_plugin/tests.rs

@@ -0,0 +1,707 @@
+use super::*;
+use crate::layout::compute_layout;
+use solitaire_core::{Deck, Foundation, Rank, Suit, Tableau};
+use solitaire_core::{DrawStockConfig, game_state::GameState};
+
+fn clear_test_piles(game: &mut GameState) {
+    game.set_test_stock_cards(Vec::new());
+    game.set_test_waste_cards(Vec::new());
+    for foundation in [
+        Foundation::Foundation1,
+        Foundation::Foundation2,
+        Foundation::Foundation3,
+        Foundation::Foundation4,
+    ] {
+        game.set_test_foundation_cards(foundation, Vec::new());
+    }
+    for tableau in [
+        Tableau::Tableau1,
+        Tableau::Tableau2,
+        Tableau::Tableau3,
+        Tableau::Tableau4,
+        Tableau::Tableau5,
+        Tableau::Tableau6,
+        Tableau::Tableau7,
+    ] {
+        game.set_test_tableau_cards(tableau, Vec::new());
+    }
+}
+
+#[test]
+fn dragged_card_z_matches_resting_stack_step() {
+    assert!((dragged_card_z(0) - DRAG_Z).abs() < 1e-6);
+    let step = dragged_card_z(1) - dragged_card_z(0);
+    assert!(
+        step > 0.02,
+        "drag step must exceed Android overlay local_z, got {step}"
+    );
+    assert!(
+        step + 1e-4 >= STACK_FAN_FRAC,
+        "drag step must stay aligned with resting stack spacing, got {step}"
+    );
+}
+
+#[test]
+fn point_in_rect_inside_returns_true() {
+    let center = Vec2::new(10.0, 20.0);
+    let size = Vec2::new(40.0, 60.0);
+    assert!(point_in_rect(Vec2::new(10.0, 20.0), center, size));
+    assert!(point_in_rect(Vec2::new(29.0, 49.0), center, size));
+    assert!(point_in_rect(Vec2::new(-9.0, -9.0), center, size));
+}
+
+#[test]
+fn point_in_rect_on_edge_returns_true() {
+    let center = Vec2::ZERO;
+    let size = Vec2::new(10.0, 10.0);
+    assert!(point_in_rect(Vec2::new(5.0, 5.0), center, size));
+    assert!(point_in_rect(Vec2::new(-5.0, -5.0), center, size));
+}
+
+#[test]
+fn point_in_rect_outside_returns_false() {
+    let center = Vec2::ZERO;
+    let size = Vec2::new(10.0, 10.0);
+    assert!(!point_in_rect(Vec2::new(6.0, 0.0), center, size));
+    assert!(!point_in_rect(Vec2::new(0.0, 6.0), center, size));
+    assert!(!point_in_rect(Vec2::new(-100.0, 0.0), center, size));
+}
+
+#[test]
+fn find_draggable_picks_top_of_tableau() {
+    let game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+
+    // In tableau 6, the visually topmost card is the last (face-up) one.
+    // Its position: base.y + fan * 6.
+    let top_pos = card_position(&game, &layout, &KlondikePile::Tableau(Tableau::Tableau7), 6);
+    let result = find_draggable_at(top_pos, &game, &layout).expect("hit");
+    assert_eq!(result.0, KlondikePile::Tableau(Tableau::Tableau7));
+    assert_eq!(result.1, 6);
+    assert_eq!(result.2.len(), 1);
+}
+
+#[test]
+fn find_draggable_picks_waste_top_with_multiple_cards() {
+    // Reproduces the reported "drags the wrong waste card" bug: with several
+    // cards in the waste, clicking the visible top must pick the actual top
+    // (last index), not the buffer card underneath it.
+    let mut game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    clear_test_piles(&mut game);
+    let waste = vec![Card::new(Deck::Deck1, Suit::Clubs, Rank::Two),
+                     Card::new(Deck::Deck1, Suit::Hearts, Rank::Five),
+                     Card::new(Deck::Deck1, Suit::Spades, Rank::Nine)];
+    game.set_test_waste_cards(waste.clone());
+
+    let top_index = waste.len() - 1; // 2 = the visible top
+    let top_pos = card_position(&game, &layout, &KlondikePile::Stock, top_index);
+    let result = find_draggable_at(top_pos, &game, &layout).expect("waste top is draggable");
+    assert_eq!(result.0, KlondikePile::Stock, "origin is the waste pile");
+    assert_eq!(result.1, top_index, "picks the top index, not the buffer");
+    assert_eq!(result.2, vec![waste[top_index].clone()], "drags the top card only");
+}
+
+#[test]
+fn find_draggable_picks_lone_waste_card() {
+    // "can't play the first card in the stock" — a waste of one card must
+    // still be draggable.
+    let mut game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    clear_test_piles(&mut game);
+    let card = Card::new(Deck::Deck1, Suit::Diamonds, Rank::Ace);
+    game.set_test_waste_cards(vec![card.clone()]);
+
+    let pos = card_position(&game, &layout, &KlondikePile::Stock, 0);
+    let result = find_draggable_at(pos, &game, &layout).expect("lone waste card is draggable");
+    assert_eq!(result.0, KlondikePile::Stock);
+    assert_eq!(result.1, 0);
+    assert_eq!(result.2, vec![card]);
+}
+
+#[test]
+fn draw_three_waste_hit_test_matches_render_fan_step() {
+    // Regression: the Draw-Three waste hit-test must use the same fan step as
+    // the renderer (`card_plugin::waste_fan_step`). The previous hard-coded
+    // `card_size.x * 0.28` matched the renderer only on desktop (column step =
+    // 1.25*cw); under tighter Android-style spacing the two drift and the top
+    // fanned card's click target lands on the card beneath it — so dragging
+    // the visible top card plays the wrong one.
+    let mut game = GameState::new(7, DrawStockConfig::DrawThree);
+    let mut layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+
+    // Force tight (Android-like) column spacing: ~1.03 * card_width.
+    let cw = layout.card_size.x;
+    let base = layout.pile_positions[&KlondikePile::Stock];
+    let t1 = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau1)];
+    layout.pile_positions.insert(
+        KlondikePile::Tableau(Tableau::Tableau2),
+        Vec2::new(t1.x + cw * 1.03, t1.y),
+    );
+
+    clear_test_piles(&mut game);
+    let waste = vec![
+        Card::new(Deck::Deck1, Suit::Clubs, Rank::Two),
+        Card::new(Deck::Deck1, Suit::Hearts, Rank::Five),
+        Card::new(Deck::Deck1, Suit::Spades, Rank::Nine),
+        Card::new(Deck::Deck1, Suit::Diamonds, Rank::King),
+    ];
+    game.set_test_waste_cards(waste.clone());
+
+    // visible_start = len-3 = 1, so the top card sits at fan slot 2.
+    let top_index = waste.len() - 1;
+    let pos = card_position(&game, &layout, &KlondikePile::Stock, top_index);
+
+    let expected = base.x + 2.0 * waste_fan_step(&layout);
+    assert!(
+        (pos.x - expected).abs() < 1e-3,
+        "hit-test must use the shared waste fan step"
+    );
+    // The old fixed constant would have drifted from the renderer here.
+    let old = base.x + 2.0 * cw * 0.28;
+    assert!(
+        (pos.x - old).abs() > 1.0,
+        "shared step must differ from the old fixed step under tight spacing"
+    );
+}
+
+#[test]
+fn find_draggable_skips_face_down_cards() {
+    let game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+
+    // Tableau 6 has 7 cards: 6 face-down (indices 0..5) + 1 face-up at
+    // the bottom (index 6). Click at the topmost face-down card's
+    // position — its full body is partly visible above the fanned
+    // face-up card, but the iterator should skip face-down cards and
+    // the cursor sits above the face-up card's AABB, so the result
+    // is None.
+    let face_down_pos =
+        card_position(&game, &layout, &KlondikePile::Tableau(Tableau::Tableau7), 0);
+    let result = find_draggable_at(face_down_pos, &game, &layout);
+    assert!(result.is_none(), "face-down cards should not be draggable");
+}
+
+#[test]
+fn find_draggable_hits_face_up_card_with_face_down_cards_above_it() {
+    // Regression test for the bug where input_plugin's hit-testing used
+    // a uniform 0.25 fan step but card_plugin renders face-down cards
+    // at 0.12 — so for any column with face-down cards above the
+    // face-up bottom card, clicking the visible card face missed the
+    // hit-test box and only the bottom strip of the card responded.
+    let game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+
+    // Tableau 6 starts with 6 face-down + 1 face-up. The face-up card
+    // sits at base.y - 6 * TABLEAU_FACEDOWN_FAN_FRAC * card_h, NOT at
+    // base.y - 6 * TABLEAU_FAN_FRAC * card_h. Click the centre.
+    let face_up_pos =
+        card_position(&game, &layout, &KlondikePile::Tableau(Tableau::Tableau7), 6);
+    let result = find_draggable_at(face_up_pos, &game, &layout)
+        .expect("clicking the face-up card's visible centre must initiate a drag");
+    assert_eq!(result.0, KlondikePile::Tableau(Tableau::Tableau7));
+    assert_eq!(result.1, 6);
+    assert_eq!(result.2.len(), 1);
+}
+
+#[test]
+fn find_draggable_returns_run_when_picking_mid_stack() {
+    // Manually construct a tableau with three face-up cards all stacked.
+    let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    let king = Card::new(D::Deck1, Suit::Spades, Rank::King);
+    let queen = Card::new(D::Deck1, Suit::Hearts, Rank::Queen);
+    let jack = Card::new(D::Deck1, Suit::Clubs, Rank::Jack);
+    game.set_test_tableau_cards(
+        Tableau::Tableau1,
+        vec![king, queen.clone(), jack.clone()],
+    );
+
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    // The Queen's geometric center (index 1) is inside the Jack's bounding box
+    // (Jack fans 0.5h below base; its box spans [base-h, base]).  To hit the
+    // Queen we click in her visible strip: the 0.25h band above the Jack's top
+    // edge (base.y to base.y+0.25h).  Midpoint = queen_center + 0.375*card_h.
+    let queen_center =
+        card_position(&game, &layout, &KlondikePile::Tableau(Tableau::Tableau1), 1);
+    let pos = queen_center + Vec2::new(0.0, layout.card_size.y * 0.375);
+    let (pile, start, ids) = find_draggable_at(pos, &game, &layout).expect("hit");
+    assert_eq!(pile, KlondikePile::Tableau(Tableau::Tableau1));
+    assert_eq!(start, 1);
+    assert_eq!(ids, vec![queen, jack]);
+}
+
+#[test]
+fn find_draggable_skips_non_top_waste_card() {
+    let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    let two_spades = Card::new(D::Deck1, Suit::Spades, Rank::Two);
+    let three_hearts = Card::new(D::Deck1, Suit::Hearts, Rank::Three);
+    game.set_test_waste_cards(vec![two_spades, three_hearts.clone()]);
+
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    // Both cards in waste sit at the same (x, y). Clicking should pick
+    // the visually top card (three_hearts), with count = 1.
+    let pos = card_position(&game, &layout, &KlondikePile::Stock, 0);
+    let (pile, start, ids) = find_draggable_at(pos, &game, &layout).expect("hit");
+    assert_eq!(pile, KlondikePile::Stock);
+    assert_eq!(start, 1);
+    assert_eq!(ids, vec![three_hearts]);
+}
+
+#[test]
+fn find_drop_target_hits_empty_tableau_pile_marker() {
+    let game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    // Move all cards out of tableau 0 so its marker is the only drop area.
+    let mut game = game;
+    game.set_test_tableau_cards(Tableau::Tableau1, Vec::new());
+    let pos = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau1)];
+    let target = find_drop_target(
+        pos,
+        &game,
+        &layout,
+        &KlondikePile::Tableau(Tableau::Tableau7),
+    );
+    assert_eq!(target, Some(KlondikePile::Tableau(Tableau::Tableau1)));
+}
+
+#[test]
+fn find_drop_target_returns_none_for_origin() {
+    let game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    let pos = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau4)];
+    let target = find_drop_target(
+        pos,
+        &game,
+        &layout,
+        &KlondikePile::Tableau(Tableau::Tableau4),
+    );
+    assert_eq!(target, None);
+}
+
+#[test]
+fn pile_drop_rect_extends_for_tableau_with_cards() {
+    let game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    // Tableau 6 has 7 cards.
+    let (_, size) = pile_drop_rect(&KlondikePile::Tableau(Tableau::Tableau7), &layout, &game);
+    // Expected: card_height + 6 fan steps.
+    let expected = layout.card_size.y * (1.0 + 6.0 * layout.tableau_fan_frac);
+    assert!(
+        (size.y - expected).abs() < 1e-3,
+        "expected {expected}, got {}",
+        size.y
+    );
+}
+
+#[test]
+fn find_draggable_draw_three_waste_top_card_hit_at_fanned_position() {
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    use solitaire_core::{DrawStockConfig, game_state::GameMode};
+    let mut game = GameState::new_with_mode(1, DrawStockConfig::DrawThree, GameMode::Classic);
+    // Three waste cards; top (four_clubs) is rightmost in the fan.
+    let two_spades = Card::new(D::Deck1, Suit::Spades, Rank::Two);
+    let three_hearts = Card::new(D::Deck1, Suit::Hearts, Rank::Three);
+    let four_clubs = Card::new(D::Deck1, Suit::Clubs, Rank::Four);
+    game.set_test_waste_cards(vec![two_spades, three_hearts, four_clubs.clone()]);
+
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    let waste_base = layout.pile_positions[&KlondikePile::Stock];
+    // Top card (slot=2) is at base.x + 2 * 0.28 * card_width.
+    let top_card_x = waste_base.x + 2.0 * 0.28 * layout.card_size.x;
+    let cursor = Vec2::new(top_card_x, waste_base.y);
+
+    let result = find_draggable_at(cursor, &game, &layout);
+    assert!(
+        result.is_some(),
+        "top fanned waste card must be hittable at its visual X position"
+    );
+    let (pile, _start, ids) = result.unwrap();
+    assert_eq!(pile, KlondikePile::Stock);
+    assert_eq!(ids, vec![four_clubs], "only the top card is draggable from waste");
+}
+
+#[test]
+fn find_draggable_returns_none_for_click_on_empty_pile() {
+    let mut game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    // Clear tableau 0 so it's an empty slot.
+    game.set_test_tableau_cards(Tableau::Tableau1, Vec::new());
+    let pos = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau1)];
+    let result = find_draggable_at(pos, &game, &layout);
+    assert!(
+        result.is_none(),
+        "clicking an empty pile must not produce a draggable"
+    );
+}
+
+#[test]
+fn pile_drop_rect_is_card_sized_for_non_tableau() {
+    let game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    for pile in [
+        KlondikePile::Stock,
+        KlondikePile::Foundation(Foundation::Foundation3),
+    ] {
+        let (_, size) = pile_drop_rect(&pile, &layout, &game);
+        assert_eq!(size, layout.card_size);
+    }
+}
+
+// -----------------------------------------------------------------------
+// Task #27 — best_destination pure-function tests
+// -----------------------------------------------------------------------
+
+#[test]
+fn best_destination_returns_none_when_no_legal_move() {
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+
+    // Clear everything except one card that has nowhere to go.
+    clear_test_piles(&mut game);
+
+    // A Two of Clubs with empty foundations and empty tableau has no destination.
+    let card = Card::new(D::Deck1, Suit::Clubs, Rank::Two);
+    assert!(best_destination(&card, &game).is_none());
+}
+
+// -----------------------------------------------------------------------
+// best_tableau_destination_for_stack pure-function tests
+// -----------------------------------------------------------------------
+
+#[test]
+fn best_tableau_destination_for_stack_skips_source_pile() {
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+
+    clear_test_piles(&mut game);
+
+    // Only tableau 0 has anything; every other column is empty.
+    // A King is the only card that can go on an empty tableau column.
+    // Source is Tableau(0), so the result must NOT be Tableau(0).
+    let king = Card::new(D::Deck1, Suit::Hearts, Rank::King);
+    game.set_test_tableau_cards(Tableau::Tableau1, vec![king.clone()]);
+
+    let result = best_tableau_destination_for_stack(
+        &king,
+        &KlondikePile::Tableau(Tableau::Tableau1),
+        &game,
+        1,
+    );
+    // Result must be some other empty tableau column, never the source.
+    if let Some((dest, _)) = result {
+        assert_ne!(dest, KlondikePile::Tableau(Tableau::Tableau1));
+    }
+}
+
+#[test]
+fn best_tableau_destination_for_stack_returns_none_when_no_legal_move() {
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+
+    clear_test_piles(&mut game);
+
+    // Source: tableau 0 has a Two of Clubs (can't go on empty pile; not a King).
+    // All other piles are empty — no legal tableau target.
+    let two_clubs = Card::new(D::Deck1, Suit::Clubs, Rank::Two);
+    game.set_test_tableau_cards(Tableau::Tableau1, vec![two_clubs.clone()]);
+
+    let result = best_tableau_destination_for_stack(
+        &two_clubs,
+        &KlondikePile::Tableau(Tableau::Tableau1),
+        &game,
+        1,
+    );
+    assert!(
+        result.is_none(),
+        "Two of Clubs has no legal tableau destination on empty piles"
+    );
+}
+
+// -----------------------------------------------------------------------
+// Task #28 — find_hint pure-function tests
+// -----------------------------------------------------------------------
+
+#[test]
+fn find_hint_finds_ace_to_foundation() {
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+
+    // Place Ace of Clubs on top of tableau 0.
+    clear_test_piles(&mut game);
+    let ace_clubs = Card::new(D::Deck1, Suit::Clubs, Rank::Ace);
+    game.set_test_tableau_cards(Tableau::Tableau1, vec![ace_clubs]);
+
+    let hint = find_hint(&game);
+    assert!(hint.is_some(), "should find a hint");
+    let (from, to) = hint.unwrap();
+    assert_eq!(from, KlondikePile::Tableau(Tableau::Tableau1));
+    assert_eq!(to, KlondikePile::Foundation(Foundation::Foundation1));
+}
+
+// -----------------------------------------------------------------------
+// G key fires ForfeitRequestEvent (modal-based forfeit flow)
+// -----------------------------------------------------------------------
+
+/// `handle_keyboard_forfeit` only checks `paused` and the G keypress;
+/// the "is there actually a game?" gating lives in
+/// `pause_plugin::handle_forfeit_request` so it can surface a
+/// "No game to forfeit" toast instead of failing silently.
+#[test]
+fn g_key_paused_check_keeps_handler_silent_while_pause_modal_owns_input() {
+    // Build the system param state by hand so we don't rely on a
+    // full Bevy app: the assertion is that the function returns
+    // early on the paused branch without calling write_message.
+    // This is verified by the plain `if paused { return; }` shape;
+    // the body is small enough to inspect by reading.
+    // (Higher-level integration coverage lives in the pause-plugin
+    // tests where `forfeit_app` simulates the full flow.)
+    let _ = handle_keyboard_forfeit; // proves the symbol still compiles
+}
+
+// -----------------------------------------------------------------------
+// all_hints / new-game window — pure-function tests added during refactor
+// -----------------------------------------------------------------------
+
+/// Pass 3 of `all_hints` should suggest drawing from the stock when there
+/// are no other moves and the stock is non-empty.
+#[test]
+fn all_hints_suggests_draw_when_no_moves_and_stock_nonempty() {
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+
+    // Remove all foundation, tableau, and waste cards so no pile-to-pile
+    // move exists. Leave one card in the stock.
+    clear_test_piles(&mut game);
+    // Put one card back into the stock so "draw" is a valid suggestion.
+    game.set_test_stock_cards(vec![Card::new(D::Deck1, Suit::Clubs, Rank::Ace)]);
+
+    let hints = all_hints(&game);
+    assert_eq!(hints.len(), 1, "exactly one hint: draw from stock");
+    let (from, to) = &hints[0];
+    assert_eq!(*from, KlondikePile::Stock, "hint must come from Stock");
+    assert_eq!(*to, KlondikePile::Stock, "hint must point to Waste");
+}
+
+// `all_hints` must be empty when both stock and waste are empty and no
+// pile-to-pile move exists — the game is truly stuck.
+// -----------------------------------------------------------------------
+// Drag-rejection return tween — `CardAnimation` replaces the legacy
+// `ShakeAnim` on the dragged cards. The audio cue
+// (`card_invalid.wav` via `MoveRejectedEvent`) is unchanged; only the
+// visual response on the dragged cards swapped from a horizontal wiggle
+// to a smooth ease-out glide back to the origin pile.
+//
+// These tests build the component values exactly as `end_drag` and
+// `touch_end_drag` would, then assert the resulting `CardAnimation` is
+// shaped correctly. Driving `end_drag` end-to-end requires a real window
+// and mouse-button input, so we exercise the data path the same way the
+// legacy `ShakeAnim` tests did.
+// -----------------------------------------------------------------------
+
+/// Helper: build the `CardAnimation` the rejection paths construct for
+/// one dragged card. Mirrors the inline logic in `end_drag` and
+/// `touch_end_drag` so the tests stay in sync with the production code.
+fn build_drag_reject_animation(
+    drag_pos: Vec2,
+    drag_z: f32,
+    target_pos: Vec2,
+    stack_index: usize,
+) -> CardAnimation {
+    let end_z = 1.0 + (stack_index as f32) * STACK_FAN_FRAC;
+    CardAnimation::slide(drag_pos, drag_z, target_pos, end_z, MotionCurve::Responsive)
+        .with_duration(MOTION_DRAG_REJECT_SECS)
+}
+
+/// Every card in `drag.cards` should receive its own `CardAnimation` on
+/// rejection. With the shake → tween migration, the assertion changes
+/// from "every dragged card gets a ShakeAnim" to "every dragged card
+/// gets a CardAnimation" — same coverage, new component.
+#[test]
+fn rejected_drag_inserts_card_animation_on_each_dragged_card() {
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    // Simulate a stack drag of two cards.
+    let dragged_cards: Vec<Card> = vec![
+        Card::new(D::Deck1, Suit::Hearts, Rank::King),
+        Card::new(D::Deck1, Suit::Spades, Rank::Queen),
+    ];
+
+    let mut animated: Vec<Card> = Vec::new();
+    for card in &dragged_cards {
+        // In `end_drag` we iterate `drag.cards` and look up each card in
+        // `card_entities`. The cards we would insert a `CardAnimation` on
+        // must exactly match the dragged set.
+        animated.push(card.clone());
+    }
+
+    assert_eq!(
+        animated, dragged_cards,
+        "every card in drag.cards must receive a CardAnimation on rejection"
+    );
+}
+
+/// The `end` field of the inserted tween must equal the card's resting
+/// slot in its origin pile — the position the card belongs at after a
+/// rejected drop. Without this, the tween would glide to the wrong spot
+/// and `sync_cards` would have to fight it back.
+#[test]
+fn rejected_drag_animation_targets_origin_resting_position() {
+    let drag_pos = Vec2::new(640.0, 200.0); // somewhere mid-screen
+    let target_pos = Vec2::new(123.5, -50.0); // origin pile slot
+    let anim =
+        build_drag_reject_animation(drag_pos, DRAG_Z, target_pos, /* stack_index */ 3);
+
+    assert!(
+        (anim.end - target_pos).length() < 1e-6,
+        "CardAnimation.end must match the origin slot's resting position. \
+         Expected {target_pos:?}, got {:?}",
+        anim.end
+    );
+}
+
+/// The `start` field of the inserted tween must equal the card's
+/// drop-time transform position — i.e. wherever the cursor or finger
+/// released the card. This is what makes the glide feel like a
+/// continuous return rather than a teleport-then-shake.
+#[test]
+fn rejected_drag_animation_starts_from_drag_position() {
+    let drag_pos = Vec2::new(640.0, 200.0);
+    let target_pos = Vec2::new(80.0, -120.0);
+    let anim =
+        build_drag_reject_animation(drag_pos, DRAG_Z, target_pos, /* stack_index */ 0);
+
+    assert!(
+        (anim.start - drag_pos).length() < 1e-6,
+        "CardAnimation.start must match the drop-time transform position \
+         (where the cursor released). Expected {drag_pos:?}, got {:?}",
+        anim.start
+    );
+    // And the start must be visibly distinct from the origin slot — the
+    // whole point of the tween is that it visibly travels.
+    assert!(
+        (anim.start - anim.end).length() > 1.0,
+        "rejected drag should travel a visible distance, got start={:?} end={:?}",
+        anim.start,
+        anim.end
+    );
+}
+
+/// The tween duration is taken from the project-wide motion token so
+/// designers can retune the feel from one place. Keeps the constant and
+/// the call site honest.
+#[test]
+fn rejected_drag_animation_uses_correct_duration() {
+    let anim = build_drag_reject_animation(
+        Vec2::new(640.0, 200.0),
+        DRAG_Z,
+        Vec2::new(80.0, -120.0),
+        0,
+    );
+    assert!(
+        (anim.duration - MOTION_DRAG_REJECT_SECS).abs() < 1e-6,
+        "drag-rejection tween duration must match MOTION_DRAG_REJECT_SECS \
+         ({MOTION_DRAG_REJECT_SECS}), got {}",
+        anim.duration
+    );
+}
+
+/// The curve must be a no-overshoot ease-out so the card decelerates
+/// cleanly into its rest position — overshoot on a rejection feels
+/// jittery rather than forgiving.
+#[test]
+fn rejected_drag_animation_uses_responsive_curve() {
+    let anim = build_drag_reject_animation(
+        Vec2::new(640.0, 200.0),
+        DRAG_Z,
+        Vec2::new(80.0, -120.0),
+        0,
+    );
+    assert_eq!(
+        anim.curve,
+        MotionCurve::Responsive,
+        "drag-rejection tween must use Responsive (quintic ease-out) \
+         so the card snaps back without bouncing past the slot"
+    );
+}
+
+/// The `start_z` of the tween must equal the card's drop-time z
+/// (`DRAG_Z`) so the card stays above the rest of the table while it
+/// travels home, then settles at the correct resting z.
+#[test]
+fn rejected_drag_animation_lifts_from_drag_z_to_resting_z() {
+    let stack_index = 2_usize;
+    let anim = build_drag_reject_animation(
+        Vec2::new(640.0, 200.0),
+        DRAG_Z,
+        Vec2::new(80.0, -120.0),
+        stack_index,
+    );
+    assert!(
+        (anim.start_z - DRAG_Z).abs() < 1e-6,
+        "tween must start at DRAG_Z so the card stays on top during the glide"
+    );
+    let expected_end_z = 1.0 + (stack_index as f32) * STACK_FAN_FRAC;
+    assert!(
+        (anim.end_z - expected_end_z).abs() < 1e-6,
+        "tween must end at the slot's resting z, got {} expected {expected_end_z}",
+        anim.end_z
+    );
+}
+
+// -----------------------------------------------------------------------
+// Hint system — async port (v0.18.0+)
+//
+// `handle_keyboard_hint` no longer runs the solver inline; it
+// spawns an `AsyncComputeTaskPool` task whose result the polling
+// system in `pending_hint` turns into hint visuals one frame
+// later. The behaviour contract this section pins is "pressing H
+// populates `PendingHintTask`" — the spawn-to-emit pipeline is
+// covered end-to-end in `pending_hint::tests`.
+// -----------------------------------------------------------------------
+
+/// Pressing H on a non-paused, non-won game with a live
+/// `GameStateResource` + `LayoutResource` must populate
+/// `PendingHintTask`. The polling system, exercised in
+/// `pending_hint::tests`, drives the result to a visual event.
+#[test]
+fn pressing_h_spawns_pending_hint_task() {
+    let mut app = App::new();
+    app.add_plugins(MinimalPlugins);
+    app.add_message::<InfoToastEvent>();
+    app.add_message::<HintVisualEvent>();
+    app.init_resource::<HintCycleIndex>();
+    app.init_resource::<HintSolverConfig>();
+    app.init_resource::<crate::pending_hint::PendingHintTask>();
+    app.init_resource::<ButtonInput<KeyCode>>();
+    app.insert_resource(LayoutResource(
+        compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true),
+    ));
+    app.insert_resource(GameStateResource(GameState::new(42, DrawStockConfig::DrawOne)));
+    app.add_systems(Update, handle_keyboard_hint);
+
+    // Simulate the H key being pressed this frame.
+    {
+        let mut input = app.world_mut().resource_mut::<ButtonInput<KeyCode>>();
+        input.release(KeyCode::KeyH);
+        input.clear();
+        input.press(KeyCode::KeyH);
+    }
+    app.update();
+
+    assert!(
+        app.world()
+            .resource::<crate::pending_hint::PendingHintTask>()
+            .is_pending(),
+        "pressing H must spawn an async hint task",
+    );
+}

solitaire_engine/src/safe_area.rs

@@ -191,10 +191,12 @@ fn apply_safe_area_to_modal_scrims(
 /// whatever `SafeAreaInsets` are current at that moment.
 ///
 /// On Android the `android::rearm_on_resumed` system runs in the same frame
-/// and resets both `SafeAreaPollTries` and `SafeAreaInsets` to zero, causing
-/// `refresh_insets` to re-poll JNI over the next few frames.  When it resolves
-/// the correct values, `on_safe_area_changed` in `table_plugin` emits a second
-/// synthetic `WindowResized` and the layout converges to the right position.
+/// and resets `SafeAreaPollTries` (the cached `SafeAreaInsets` keep their
+/// last-known values), causing `refresh_insets` to re-poll JNI over the next
+/// few frames.  If the insets changed while backgrounded, `on_safe_area_changed`
+/// in `table_plugin` emits a second synthetic `WindowResized` and the layout
+/// converges to the right position; if they didn't, nothing is rewritten and
+/// the layout stays put.
 ///
 /// On non-Android targets this handler still fires — it ensures that a resume
 /// event always refreshes the layout (e.g., after a minimise/restore on
@@ -232,9 +234,14 @@ mod android {
     pub(super) struct SafeAreaPollTries(pub u32);
 
     /// Polls Android for safe-area insets until we get a non-zero
-    /// reading, then stops. `getRootWindowInsets()` returns `null` (or
-    /// all-zero `Insets`) until the decor view has been laid out, which
-    /// is typically frame 1–3 of a fresh launch.
+    /// reading, then settles until [`rearm_on_resumed`] re-arms it on the
+    /// next foreground resume — insets can change while backgrounded
+    /// (rotation, fold/unfold, gesture ↔ 3-button nav). The poll counter
+    /// (not `insets.is_populated()`) gates the loop, so a re-armed cycle
+    /// re-queries JNI even though cached values are already populated.
+    /// `getRootWindowInsets()` returns `null` (or all-zero `Insets`)
+    /// until the decor view has been laid out, which is typically frame
+    /// 1–3 of a fresh launch.
     pub(super) fn refresh_insets(
         mut insets: ResMut<SafeAreaInsets>,
         mut poll: ResMut<SafeAreaPollTries>,
@@ -243,18 +250,25 @@ mod android {
         // devices that genuinely report zero insets.
         const MAX_TRIES: u32 = 120; // ~2 seconds @ 60 fps
 
-        if poll.0 >= MAX_TRIES || insets.is_populated() {
+        if poll.0 >= MAX_TRIES {
             return;
         }
         poll.0 += 1;
 
         match query_insets() {
             Ok(v) if v.is_populated() => {
-                info!(
-                    "safe_area: insets resolved top={} bottom={} left={} right={} (after {} frames)",
-                    v.top, v.bottom, v.left, v.right, poll.0
-                );
-                *insets = v;
+                if *insets != v {
+                    info!(
+                        "safe_area: insets resolved top={} bottom={} left={} right={} (after {} frames)",
+                        v.top, v.bottom, v.left, v.right, poll.0
+                    );
+                    *insets = v;
+                }
+                // Settled for this poll cycle; `rearm_on_resumed` re-arms on
+                // the next resume. Writing `insets` only on an actual change
+                // keeps resource change detection (and the relayout it
+                // triggers) quiet on resumes where nothing moved.
+                poll.0 = MAX_TRIES;
             }
             Ok(_) => {
                 // Layout not ready yet; try again next frame.

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/mod.rs

@@ -0,0 +1,558 @@
+//! Persists `solitaire_data::Settings`, exposes hotkeys for live tuning,
+//! and renders a Bevy UI Settings panel.
+//!
+//! Hotkeys (always active, no overlay required):
+//! - `[` — decrease SFX volume by `SFX_STEP`
+//! - `]` — increase SFX volume by `SFX_STEP`
+//! - `O` — open / close the Settings panel
+//!
+//! On change, the plugin persists `settings.json` and fires
+//! `SettingsChangedEvent` so dependents (e.g. `AudioPlugin`) can react.
+
+use std::path::PathBuf;
+
+use bevy::input::mouse::MouseWheel;
+use bevy::prelude::*;
+use bevy::window::{WindowMoved, WindowResized};
+use solitaire_data::{
+    Settings, WindowGeometry, load_settings_from, save_settings_to, settings_file_path,
+};
+
+use crate::events::{
+    DeleteAccountRequestEvent, InfoToastEvent, ManualSyncRequestEvent, SyncConfigureRequestEvent,
+    SyncLogoutRequestEvent, ToggleSettingsRequestEvent,
+};
+use crate::resources::SettingsScrollPos;
+use crate::theme::ThemeThumbnailPair;
+
+mod input;
+mod ui;
+mod updates;
+
+use input::*;
+use ui::*;
+use updates::*;
+
+/// Side length of a swatch button in the card-back / background pickers.
+/// Smaller than the smallest spacing rung so it stays a literal.
+const SWATCH_PX: f32 = 40.0;
+
+/// Side length of a small toggle / cycle button (e.g. the "⇄" affordances).
+/// Sub-rung sizing — kept as a literal, see SWATCH_PX. 32 px meets the
+/// minimum desktop hit-target threshold while staying smaller than `SWATCH_PX`.
+const ICON_BUTTON_PX: f32 = 32.0;
+
+/// Volume adjustment step applied by the `[` / `]` hotkeys.
+pub const SFX_STEP: f32 = 0.1;
+
+/// Bevy resource wrapping the current `Settings`.
+#[derive(Resource, Debug, Clone)]
+pub struct SettingsResource(pub Settings);
+
+/// Persistence path for `SettingsResource`. `None` disables I/O (used in tests).
+#[derive(Resource, Debug, Clone)]
+pub struct SettingsStoragePath(pub Option<PathBuf>);
+
+/// Whether the Settings panel is currently visible. Toggle with `O`.
+#[derive(Resource, Debug, Clone, Default)]
+pub struct SettingsScreen(pub bool);
+
+/// Debounce window for persisting window-geometry changes, in seconds.
+///
+/// `WindowResized` and `WindowMoved` fire continuously during a resize/
+/// move drag, so writing to disk on every event would thrash the file
+/// system. Instead the geometry-watch system records the pending value
+/// and waits this long after the *last* event before saving.
+pub const WINDOW_GEOMETRY_DEBOUNCE_SECS: f32 = 0.5;
+
+/// Tracks a pending window-geometry change so the saver can debounce
+/// `WindowResized` / `WindowMoved` storms during a resize / move drag.
+#[derive(Resource, Debug, Default, Clone, Copy)]
+pub struct PendingWindowGeometry {
+    /// Most recent observed geometry. `None` when nothing is pending.
+    pub geometry: Option<WindowGeometry>,
+    /// `Time::elapsed_secs()` value at which `geometry` was last updated.
+    pub last_changed_secs: f32,
+}
+
+/// Fired whenever settings change so consumers (audio, UI) can react.
+#[derive(Message, Debug, Clone)]
+pub struct SettingsChangedEvent(pub Settings);
+
+/// Marker on the root Settings panel entity.
+#[derive(Component, Debug)]
+pub struct SettingsPanel;
+
+/// Marks the `Text` node showing the live SFX volume value.
+#[derive(Component, Debug)]
+struct SfxVolumeText;
+
+/// Marks the `Text` node showing the live music volume value.
+#[derive(Component, Debug)]
+struct MusicVolumeText;
+
+/// Marks the `Text` node showing the current draw mode.
+#[derive(Component, Debug)]
+struct DrawModeText;
+
+/// Marks the `Text` node showing the current theme.
+#[derive(Component, Debug)]
+struct ThemeText;
+
+/// Marks the `Text` node showing the live sync status.
+#[derive(Component, Debug)]
+struct SyncStatusText;
+
+/// Marks the `Text` node showing the active card-back index.
+#[derive(Component, Debug)]
+struct CardBackText;
+
+/// Marks the `Text` node showing the current animation speed.
+#[derive(Component, Debug)]
+struct AnimSpeedText;
+
+/// Marks the `Text` node showing the active background index.
+#[derive(Component, Debug)]
+struct BackgroundText;
+
+/// Marks the `Text` node showing the current color-blind mode state.
+#[derive(Component, Debug)]
+struct ColorBlindText;
+
+/// Marks the `Text` node showing the current high-contrast mode state.
+#[derive(Component, Debug)]
+struct HighContrastText;
+
+/// Marks the `Text` node showing the current reduce-motion mode state.
+#[derive(Component, Debug)]
+struct ReduceMotionText;
+
+/// Marks the `Text` node showing the current touch input mode state.
+#[derive(Component, Debug)]
+struct TouchInputModeText;
+
+/// Marks the `Text` node showing the live tooltip-delay value.
+#[derive(Component, Debug)]
+struct TooltipDelayText;
+
+/// Marks the `Text` node showing the live time-bonus-multiplier value.
+#[derive(Component, Debug)]
+struct TimeBonusMultiplierText;
+
+/// Marks the `Text` node showing the live replay-playback per-move
+/// interval value. The Gameplay-section row beside this label lets the
+/// player tune `Settings::replay_move_interval_secs`.
+#[derive(Component, Debug)]
+struct ReplayMoveIntervalText;
+
+/// Marks the `Text` node showing the current "Winnable deals only"
+/// state ("ON" / "OFF") in the Gameplay section.
+#[derive(Component, Debug)]
+struct WinnableDealsOnlyText;
+
+/// Marks the `Text` node showing the current "Smart window size"
+/// state ("ON" / "OFF") in the Gameplay section. The flag is stored
+/// negatively in `Settings::disable_smart_default_size`, so the
+/// label inverts: "ON" = smart sizing enabled (the default).
+#[derive(Component, Debug)]
+struct SmartDefaultSizeText;
+
+/// Marks the `Text` node showing the current "Share usage data" (analytics)
+/// state ("ON" / "OFF") in the Privacy section.
+#[derive(Component, Debug)]
+struct AnalyticsEnabledText;
+
+/// Marks the scrollable inner card so the mouse-wheel system can target it.
+#[derive(Component, Debug)]
+struct SettingsPanelScrollable;
+
+/// Marks the scrollable inner card so its `ScrollPosition` can be read before despawn.
+#[derive(Component, Debug)]
+struct SettingsScrollNode;
+
+/// Snapshot row used by [`spawn_settings_panel`] to render the card-art
+/// theme picker. Carries the `ThemeRegistry` entry's display fields plus
+/// the (optional) thumbnail pair from [`ThemeThumbnailCache`]. A `None`
+/// thumbnail means the picker should render a placeholder swatch — used
+/// when the cache hasn't generated handles yet, or when a user theme
+/// is missing one of the required preview SVGs.
+#[derive(Debug, Clone)]
+struct ThemePickerEntry {
+    /// Stable theme id (matches `ThemeMeta::id`).
+    id: String,
+    /// Player-facing label.
+    display_name: String,
+    /// Pre-generated picker preview pair, when ready. `None` collapses
+    /// the chip to its plain-text fallback.
+    thumbnails: Option<ThemeThumbnailPair>,
+}
+
+/// Tags interactive buttons inside the Settings panel.
+#[derive(Component, Debug)]
+enum SettingsButton {
+    SfxDown,
+    SfxUp,
+    MusicDown,
+    MusicUp,
+    ToggleDrawMode,
+    CycleAnimSpeed,
+    /// Decrement the tooltip-hover dwell delay by one step.
+    TooltipDelayDown,
+    /// Increment the tooltip-hover dwell delay by one step.
+    TooltipDelayUp,
+    /// Decrement the cosmetic time-bonus multiplier by one step.
+    TimeBonusDown,
+    /// Increment the cosmetic time-bonus multiplier by one step.
+    TimeBonusUp,
+    /// Decrement the replay-playback per-move interval by one step
+    /// (i.e. speed playback up).
+    ReplayMoveIntervalDown,
+    /// Increment the replay-playback per-move interval by one step
+    /// (i.e. slow playback down).
+    ReplayMoveIntervalUp,
+    ToggleTheme,
+    ToggleColorBlind,
+    /// Toggle the [`Settings::high_contrast_mode`] flag — boosts
+    /// foreground / suit-red glyphs to higher-luminance variants per
+    /// `design-system.md` §Accessibility (#2).
+    ToggleHighContrast,
+    /// Toggle the [`Settings::reduce_motion_mode`] flag — suppresses
+    /// non-essential motion (card-slide animations become instant
+    /// snaps) per `design-system.md` §Accessibility (#3).
+    ToggleReduceMotion,
+    /// Toggle [`Settings::touch_input_mode`] between `OneTap`
+    /// (auto-move on tap, default) and `TapToSelect` (first tap selects
+    /// a card/stack, second tap on a target pile moves it).
+    ToggleTouchInputMode,
+    /// Toggle the [`Settings::winnable_deals_only`] flag. When on, new
+    /// random Classic-mode deals are filtered through
+    /// [`solitaire_core::game_state::GameState::solve_fresh_deal`] until one is provably
+    /// winnable (or the retry cap is hit). Off by default.
+    ToggleWinnableDealsOnly,
+    /// Toggle the inverse of [`Settings::disable_smart_default_size`].
+    /// When the visible label reads "ON", the launch-time window
+    /// sizer scales the window to ~70 % of the primary monitor on a
+    /// fresh install; "OFF" pins the literal 1280×800 baseline. The
+    /// flag only affects launches without saved geometry — the
+    /// player's last window size always wins.
+    ToggleSmartDefaultSize,
+    /// Toggle [`Settings::analytics_enabled`]. Only rendered when a
+    /// Matomo URL is configured.
+    ToggleAnalytics,
+    /// Scan `user_theme_dir()` for new `.zip` files and import each one.
+    #[cfg(not(target_arch = "wasm32"))]
+    ScanThemes,
+    SyncNow,
+    /// Open the sync-server Connect modal (shown when backend = Local).
+    ConnectSync,
+    /// Disconnect from the sync server (shown when backend = SolitaireServer).
+    DisconnectSync,
+    /// Open the account-deletion confirmation modal.
+    DeleteAccount,
+    Done,
+    /// Select a specific card-back by index from the picker row.
+    SelectCardBack(usize),
+    /// Select a specific background by index from the picker row.
+    SelectBackground(usize),
+    /// Select a specific card-art theme by `meta.id` from the
+    /// `ThemeRegistry`. The string is owned so the click handler can
+    /// hand it directly to `Settings::selected_theme_id`.
+    SelectTheme(String),
+}
+
+impl SettingsButton {
+    /// Tab-walk priority — lower numbers visited first. Visual reading
+    /// order is top-to-bottom by section, left-to-right inside each row.
+    /// Two buttons in the same picker row receive the same `order`;
+    /// `handle_focus_keys` then breaks ties by entity index, which
+    /// matches `Children` spawn order inside each row.
+    fn focus_order(&self) -> i32 {
+        match self {
+            // Audio section
+            SettingsButton::SfxDown => 10,
+            SettingsButton::SfxUp => 11,
+            SettingsButton::MusicDown => 20,
+            SettingsButton::MusicUp => 21,
+            // Gameplay section
+            SettingsButton::ToggleDrawMode => 30,
+            SettingsButton::ToggleWinnableDealsOnly => 35,
+            SettingsButton::CycleAnimSpeed => 40,
+            SettingsButton::TooltipDelayDown => 45,
+            SettingsButton::TooltipDelayUp => 46,
+            SettingsButton::TimeBonusDown => 47,
+            SettingsButton::TimeBonusUp => 48,
+            // Replay-speed slider — last Gameplay-section row, so it
+            // sits between TimeBonusUp (48) and the Cosmetic section.
+            SettingsButton::ReplayMoveIntervalDown => 49,
+            SettingsButton::ReplayMoveIntervalUp => 49,
+            // Smart-default-size toggle — sits at the end of Gameplay.
+            SettingsButton::ToggleSmartDefaultSize => 50,
+            // Privacy section — just before Sync.
+            SettingsButton::ToggleAnalytics => 89,
+            // Cosmetic section
+            SettingsButton::ToggleTheme => 55,
+            SettingsButton::ToggleColorBlind => 60,
+            // Accessibility-section toggles sit alongside Color-blind so
+            // tab-walk visits all three a11y flags in the same vertical
+            // run before continuing to the picker rows.
+            SettingsButton::ToggleHighContrast => 61,
+            SettingsButton::ToggleReduceMotion => 62,
+            SettingsButton::ToggleTouchInputMode => 63,
+            // Picker rows — every swatch in a row shares the row's
+            // priority so entity-index tiebreaking yields left → right.
+            SettingsButton::SelectCardBack(_) => 70,
+            SettingsButton::SelectBackground(_) => 80,
+            SettingsButton::SelectTheme(_) => 85,
+            #[cfg(not(target_arch = "wasm32"))]
+            SettingsButton::ScanThemes => 86,
+            // Sync section
+            SettingsButton::SyncNow => 90,
+            SettingsButton::ConnectSync => 91,
+            SettingsButton::DisconnectSync => 92,
+            SettingsButton::DeleteAccount => 93,
+            // Done is tagged by `attach_focusable_to_modal_buttons` and
+            // never reaches `attach_focusable_to_settings_buttons`; the
+            // value here is only a fallback for completeness.
+            SettingsButton::Done => 100,
+        }
+    }
+}
+
+/// Plugin that owns the settings lifecycle.
+pub struct SettingsPlugin {
+    /// Path to `settings.json`. `None` in headless/test mode.
+    pub storage_path: Option<PathBuf>,
+    /// When `false`, panel spawn/despawn systems are not registered.
+    /// Use [`SettingsPlugin::headless`] for tests running under `MinimalPlugins`.
+    pub ui_enabled: bool,
+}
+
+impl Default for SettingsPlugin {
+    fn default() -> Self {
+        Self {
+            storage_path: settings_file_path(),
+            ui_enabled: true,
+        }
+    }
+}
+
+impl SettingsPlugin {
+    /// No persistence, no UI — safe to use under `MinimalPlugins` in tests.
+    pub fn headless() -> Self {
+        Self {
+            storage_path: None,
+            ui_enabled: false,
+        }
+    }
+}
+
+impl Plugin for SettingsPlugin {
+    fn build(&self, app: &mut App) {
+        let loaded = match &self.storage_path {
+            Some(path) => load_settings_from(path),
+            None => Settings::default(),
+        };
+        app.insert_resource(SettingsResource(loaded))
+            .insert_resource(SettingsStoragePath(self.storage_path.clone()))
+            .init_resource::<SettingsScreen>()
+            .init_resource::<SettingsScrollPos>()
+            .init_resource::<PendingWindowGeometry>()
+            .add_message::<SettingsChangedEvent>()
+            .add_message::<ManualSyncRequestEvent>()
+            .add_message::<SyncConfigureRequestEvent>()
+            .add_message::<SyncLogoutRequestEvent>()
+            .add_message::<DeleteAccountRequestEvent>()
+            .add_message::<ToggleSettingsRequestEvent>()
+            .add_message::<InfoToastEvent>()
+            .add_message::<MouseWheel>()
+            .add_message::<TouchInput>()
+            // `WindowResized` / `WindowMoved` are real Bevy window events
+            // and emitted by the windowing backend under `DefaultPlugins`,
+            // but we register them explicitly here so the geometry watcher
+            // also runs cleanly under `MinimalPlugins` (tests).
+            .add_message::<WindowResized>()
+            .add_message::<WindowMoved>()
+            .add_systems(
+                Update,
+                (
+                    handle_volume_keys,
+                    toggle_settings_screen,
+                    scroll_settings_panel,
+                    crate::ui_modal::touch_scroll_panel::<SettingsPanelScrollable>,
+                    record_window_geometry_changes,
+                    persist_window_geometry_after_debounce,
+                ),
+            );
+
+        if self.ui_enabled {
+            app.add_systems(
+                Update,
+                (
+                    sync_settings_panel_visibility,
+                    handle_settings_buttons,
+                    handle_sync_buttons,
+                    #[cfg(not(target_arch = "wasm32"))]
+                    handle_scan_themes,
+                    update_sync_status_text,
+                    update_card_back_text,
+                    update_background_text,
+                    update_anim_speed_text,
+                    update_color_blind_text,
+                    update_high_contrast_text,
+                    update_high_contrast_borders.run_if(resource_changed::<SettingsResource>),
+                    update_high_contrast_backgrounds.run_if(resource_changed::<SettingsResource>),
+                    update_reduce_motion_text,
+                    update_touch_input_mode_text,
+                    update_tooltip_delay_text,
+                    update_time_bonus_multiplier_text,
+                    update_replay_move_interval_text,
+                    update_winnable_deals_only_text,
+                    update_smart_default_size_text,
+                ),
+            );
+            app.add_systems(
+                Update,
+                (
+                    update_analytics_enabled_text,
+                    attach_focusable_to_settings_buttons,
+                ),
+            );
+            app.add_systems(Update, scroll_focus_into_view);
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+fn persist(path: &SettingsStoragePath, settings: &Settings) {
+    let Some(target) = &path.0 else { return };
+    if let Err(e) = save_settings_to(target, settings) {
+        warn!("failed to save settings: {e}");
+    }
+}
+
+/// Pure helper: returns `true` when a pending geometry change has sat
+/// quietly long enough to flush to disk.
+///
+/// Extracted so the debounce condition can be unit-tested without
+/// spinning up a Bevy app.
+fn should_persist_geometry(now_secs: f32, last_changed_secs: f32) -> bool {
+    (now_secs - last_changed_secs) >= WINDOW_GEOMETRY_DEBOUNCE_SECS
+}
+
+/// Returns the geometry implied by an event pair `(width, height, x, y)`,
+/// using each component from `existing` when the corresponding event-derived
+/// value is `None`. Returns `None` when neither side supplies width/height.
+///
+/// Pure helper so the merge logic can be unit-tested without an `App`.
+fn merge_geometry(
+    existing: Option<WindowGeometry>,
+    new_size: Option<(u32, u32)>,
+    new_pos: Option<(i32, i32)>,
+) -> Option<WindowGeometry> {
+    let (width, height) = new_size.or_else(|| existing.map(|g| (g.width, g.height)))?;
+    let (x, y) = new_pos
+        .or_else(|| existing.map(|g| (g.x, g.y)))
+        .unwrap_or((0, 0));
+    Some(WindowGeometry {
+        width,
+        height,
+        x,
+        y,
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Systems
+// ---------------------------------------------------------------------------
+
+/// Returns the next unlocked index after `current` in the sorted `unlocked` list.
+/// Wraps around. Falls back to `unlocked[0]` if `current` is not found.
+#[cfg(test)]
+fn cycle_unlocked(unlocked: &[usize], current: usize) -> usize {
+    if unlocked.is_empty() {
+        return 0;
+    }
+    let pos = unlocked.iter().position(|&i| i == current).unwrap_or(0);
+    unlocked[(pos + 1) % unlocked.len()]
+}
+
+/// Records `WindowResized` and `WindowMoved` events into
+/// [`PendingWindowGeometry`], coalescing every event arriving this frame
+/// into the latest pending geometry.
+///
+/// The actual disk write is debounced — see
+/// [`persist_window_geometry_after_debounce`] — so the file system isn't
+/// hit on every pixel of a resize / move drag.
+fn record_window_geometry_changes(
+    time: Res<Time>,
+    mut resized: MessageReader<WindowResized>,
+    mut moved: MessageReader<WindowMoved>,
+    settings: Res<SettingsResource>,
+    mut pending: ResMut<PendingWindowGeometry>,
+) {
+    // Read .last() — only the final event matters for persistence; the
+    // intermediate sizes/positions are noise during a drag.
+    let new_size = resized.read().last().map(|ev| {
+        (
+            ev.width.round().max(0.0) as u32,
+            ev.height.round().max(0.0) as u32,
+        )
+    });
+    let new_pos = moved.read().last().map(|ev| (ev.position.x, ev.position.y));
+
+    if new_size.is_none() && new_pos.is_none() {
+        return;
+    }
+
+    // Fold the new components into the existing pending value (if any),
+    // otherwise into the persisted geometry from settings.
+    let baseline = pending.geometry.or(settings.0.window_geometry);
+    let Some(geometry) = merge_geometry(baseline, new_size, new_pos) else {
+        return;
+    };
+
+    pending.geometry = Some(geometry);
+    pending.last_changed_secs = time.elapsed_secs();
+}
+
+/// After [`WINDOW_GEOMETRY_DEBOUNCE_SECS`] of quiet (no `WindowResized` or
+/// `WindowMoved` events arriving), commits the pending geometry to
+/// `SettingsResource` and writes `settings.json`. Skips the write when the
+/// pending value already matches the settings (e.g. a resize that was
+/// reverted, or a synthetic event with no geometry change).
+fn persist_window_geometry_after_debounce(
+    time: Res<Time>,
+    mut pending: ResMut<PendingWindowGeometry>,
+    mut settings: ResMut<SettingsResource>,
+    path: Res<SettingsStoragePath>,
+    mut changed: MessageWriter<SettingsChangedEvent>,
+) {
+    let Some(new_geom) = pending.geometry else {
+        return;
+    };
+    if !should_persist_geometry(time.elapsed_secs(), pending.last_changed_secs) {
+        return;
+    }
+
+    // Always clear the pending slot regardless of whether we end up
+    // writing — otherwise an idempotent change would re-trigger this
+    // system every tick.
+    pending.geometry = None;
+
+    if settings.0.window_geometry == Some(new_geom) {
+        return;
+    }
+    settings.0.window_geometry = Some(new_geom);
+    persist(&path, &settings.0);
+    changed.write(SettingsChangedEvent(settings.0.clone()));
+}
+
+// ---------------------------------------------------------------------------
+// UI construction
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests;

solitaire_engine/src/settings_plugin/tests.rs

@@ -0,0 +1,655 @@
+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();
+    app.add_plugins(MinimalPlugins)
+        .add_plugins(SettingsPlugin::headless());
+    app.init_resource::<ButtonInput<KeyCode>>();
+    app.update();
+    app
+}
+
+fn press(app: &mut App, key: KeyCode) {
+    let mut input = app.world_mut().resource_mut::<ButtonInput<KeyCode>>();
+    input.release(key);
+    input.clear();
+    input.press(key);
+}
+
+#[test]
+fn defaults_are_loaded() {
+    let app = headless_app();
+    assert_eq!(
+        app.world().resource::<SettingsResource>().0,
+        Settings::default()
+    );
+}
+
+#[test]
+fn pressing_left_bracket_decreases_volume_and_emits_event() {
+    let mut app = headless_app();
+    let before = app.world().resource::<SettingsResource>().0.sfx_volume;
+
+    press(&mut app, KeyCode::BracketLeft);
+    app.update();
+
+    let after = app.world().resource::<SettingsResource>().0.sfx_volume;
+    assert!(after < before);
+
+    let events = app.world().resource::<Messages<SettingsChangedEvent>>();
+    let mut cursor = events.get_cursor();
+    assert_eq!(cursor.read(events).count(), 1);
+}
+
+#[test]
+fn pressing_right_bracket_increases_volume() {
+    let mut app = headless_app();
+    app.world_mut()
+        .resource_mut::<SettingsResource>()
+        .0
+        .sfx_volume = 0.5;
+
+    press(&mut app, KeyCode::BracketRight);
+    app.update();
+
+    let after = app.world().resource::<SettingsResource>().0.sfx_volume;
+    assert!((after - 0.6).abs() < 1e-3);
+}
+
+#[test]
+fn clamped_change_does_not_emit_event() {
+    let mut app = headless_app();
+    app.world_mut()
+        .resource_mut::<SettingsResource>()
+        .0
+        .sfx_volume = 1.0;
+
+    press(&mut app, KeyCode::BracketRight);
+    app.update();
+
+    let events = app.world().resource::<Messages<SettingsChangedEvent>>();
+    let mut cursor = events.get_cursor();
+    assert_eq!(cursor.read(events).count(), 0);
+}
+
+#[test]
+fn volume_clamped_at_zero_does_not_emit_event() {
+    let mut app = headless_app();
+    app.world_mut()
+        .resource_mut::<SettingsResource>()
+        .0
+        .sfx_volume = 0.0;
+
+    press(&mut app, KeyCode::BracketLeft);
+    app.update();
+
+    let after = app.world().resource::<SettingsResource>().0.sfx_volume;
+    assert!(after >= 0.0, "volume must not go below zero");
+
+    let events = app.world().resource::<Messages<SettingsChangedEvent>>();
+    let mut cursor = events.get_cursor();
+    assert_eq!(
+        cursor.read(events).count(),
+        0,
+        "no event when clamped at floor"
+    );
+}
+
+#[test]
+fn pressing_o_toggles_settings_screen_flag() {
+    let mut app = headless_app();
+    assert!(
+        !app.world().resource::<SettingsScreen>().0,
+        "screen is closed initially"
+    );
+
+    press(&mut app, KeyCode::KeyO);
+    app.update();
+    assert!(
+        app.world().resource::<SettingsScreen>().0,
+        "O opens settings"
+    );
+
+    press(&mut app, KeyCode::KeyO);
+    app.update();
+    assert!(
+        !app.world().resource::<SettingsScreen>().0,
+        "second O closes settings"
+    );
+}
+
+// cycle_unlocked pure-function tests
+#[test]
+fn cycle_unlocked_wraps_at_end() {
+    // [0, 1, 2] → cycling from 2 wraps to 0
+    assert_eq!(cycle_unlocked(&[0, 1, 2], 2), 0);
+}
+
+#[test]
+fn cycle_unlocked_advances_normally() {
+    assert_eq!(cycle_unlocked(&[0, 1, 2], 0), 1);
+    assert_eq!(cycle_unlocked(&[0, 1, 2], 1), 2);
+}
+
+#[test]
+fn cycle_unlocked_single_element_stays() {
+    // Only one unlockable — cycling always returns it.
+    assert_eq!(cycle_unlocked(&[0], 0), 0);
+}
+
+#[test]
+fn cycle_unlocked_current_not_in_list_falls_back_to_second() {
+    // current=5 is not in [0,1,2]; falls back to pos=0, so next = unlocked[1] = 1
+    assert_eq!(cycle_unlocked(&[0, 1, 2], 5), 1);
+}
+
+#[test]
+fn cycle_unlocked_empty_returns_zero() {
+    assert_eq!(cycle_unlocked(&[], 0), 0);
+}
+
+#[test]
+fn scroll_is_noop_when_settings_panel_closed() {
+    use bevy::input::mouse::{MouseScrollUnit, MouseWheel};
+    let mut app = headless_app();
+    // Panel starts closed (SettingsScreen(false)); spawn a scrollable entity.
+    let entity = app
+        .world_mut()
+        .spawn((SettingsPanelScrollable, ScrollPosition::default()))
+        .id();
+    // Send a downward scroll event while the panel is closed.
+    app.world_mut().write_message(MouseWheel {
+        unit: MouseScrollUnit::Line,
+        x: 0.0,
+        y: -3.0,
+        window: Entity::PLACEHOLDER,
+    });
+    app.update();
+    // ScrollPosition must remain at 0.0 — panel was closed.
+    let offset = app
+        .world()
+        .entity(entity)
+        .get::<ScrollPosition>()
+        .unwrap()
+        .0
+        .y;
+    assert_eq!(offset, 0.0, "scroll must not move when panel is closed");
+}
+
+#[test]
+fn scroll_moves_offset_when_panel_open() {
+    use bevy::input::mouse::{MouseScrollUnit, MouseWheel};
+    let mut app = headless_app();
+    // Open the panel.
+    app.world_mut().resource_mut::<SettingsScreen>().0 = true;
+    // Spawn a scrollable entity with an existing offset so we can distinguish clamping.
+    let entity = app
+        .world_mut()
+        .spawn((
+            SettingsPanelScrollable,
+            ScrollPosition(Vec2::new(0.0, 100.0)),
+        ))
+        .id();
+    // Scroll down by 2 lines (50 px/line → +100 px added to offset_y).
+    app.world_mut().write_message(MouseWheel {
+        unit: MouseScrollUnit::Line,
+        x: 0.0,
+        y: -2.0,
+        window: Entity::PLACEHOLDER,
+    });
+    app.update();
+    let offset = app
+        .world()
+        .entity(entity)
+        .get::<ScrollPosition>()
+        .unwrap()
+        .0
+        .y;
+    assert!(
+        (offset - 200.0).abs() < 1e-3,
+        "scrolling down should increase offset_y; got {offset}"
+    );
+}
+
+// -----------------------------------------------------------------------
+// Phase 3 — keyboard focus ring, Settings buttons + FocusRow
+// -----------------------------------------------------------------------
+
+/// Headless app that runs the *real* (UI-enabled) `SettingsPlugin`
+/// alongside `UiModalPlugin` and `UiFocusPlugin`, so the spawn /
+/// auto-tag systems fire end-to-end without writing to disk.
+fn headless_app_with_focus() -> App {
+    use crate::ui_focus::UiFocusPlugin;
+    use crate::ui_modal::UiModalPlugin;
+
+    let mut app = App::new();
+    app.add_plugins(MinimalPlugins)
+        .add_plugins(UiModalPlugin)
+        .add_plugins(UiFocusPlugin)
+        .add_plugins(SettingsPlugin {
+            // No persistence — keep the test isolated.
+            storage_path: None,
+            ui_enabled: true,
+        });
+    app.init_resource::<ButtonInput<KeyCode>>();
+    app.update();
+    app
+}
+
+#[test]
+fn settings_buttons_get_focusable_marker() {
+    let mut app = headless_app_with_focus();
+
+    // Open the panel.
+    app.world_mut().resource_mut::<SettingsScreen>().0 = true;
+    app.update();
+    // Two more ticks: the first runs `sync_settings_panel_visibility`
+    // and queues the spawn commands; the second flushes them and
+    // runs `attach_focusable_to_settings_buttons`.
+    app.update();
+    app.update();
+
+    // Every bespoke `SettingsButton` (not `Done`, which is also a
+    // `ModalButton`) must carry a `Focusable`.
+    let untagged: Vec<&SettingsButton> = app
+        .world_mut()
+        .query_filtered::<&SettingsButton, (With<Button>, Without<Focusable>, Without<ModalButton>)>()
+        .iter(app.world())
+        .collect();
+
+    assert!(
+        untagged.is_empty(),
+        "every bespoke Settings button must carry Focusable; missing: {:?}",
+        untagged
+    );
+
+    // And there must be at least one tagged `SettingsButton` so the
+    // assertion above isn't vacuously true (the panel really did
+    // spawn).
+    let tagged_count = app
+        .world_mut()
+        .query_filtered::<&SettingsButton, With<Focusable>>()
+        .iter(app.world())
+        .count();
+    assert!(
+        tagged_count >= 6,
+        "expected the panel to spawn many bespoke buttons (volume up/down ×2, toggles ×4, sync, swatches…); got {tagged_count}"
+    );
+}
+
+/// Every bespoke `SettingsButton` (volume +/−, toggles, swatches,
+/// Sync Now) must spawn with a `Tooltip` so the glyph-only icons and
+/// indexed swatches carry hover-reveal context. Mirrors
+/// `settings_buttons_get_focusable_marker` (Phase 3 focus test) so
+/// the invariant — every interactive Settings element except the
+/// `Done` modal button has a tooltip — is asserted consistently.
+#[test]
+fn settings_buttons_carry_tooltip() {
+    let mut app = headless_app_with_focus();
+
+    // Open the panel and let spawn + child-flush run.
+    app.world_mut().resource_mut::<SettingsScreen>().0 = true;
+    app.update();
+    app.update();
+    app.update();
+
+    // No bespoke `SettingsButton` (i.e. excluding `Done`, which is
+    // also a `ModalButton`) may be missing a `Tooltip`.
+    let untipped: Vec<&SettingsButton> = app
+        .world_mut()
+        .query_filtered::<&SettingsButton, (With<Button>, Without<Tooltip>, Without<ModalButton>)>()
+        .iter(app.world())
+        .collect();
+    assert!(
+        untipped.is_empty(),
+        "every bespoke Settings button must carry Tooltip; missing: {:?}",
+        untipped
+    );
+
+    // And there must be at least 6 tipped buttons so the assertion
+    // above isn't vacuously true: SFX +/−, Music +/−, Draw Mode,
+    // Anim Speed, Theme, Color-blind, Sync Now, plus at least one
+    // card-back and one background swatch — well over the floor.
+    let tipped_count = app
+        .world_mut()
+        .query_filtered::<&SettingsButton, With<Tooltip>>()
+        .iter(app.world())
+        .count();
+    assert!(
+        tipped_count >= 6,
+        "expected the panel to spawn many tooltipped buttons; got {tipped_count}"
+    );
+
+    // Spot-check: with default (Local) settings the Connect button
+    // spawns. We verify its tooltip carries the canonical microcopy.
+    let connect_tip = app
+        .world_mut()
+        .query::<(&SettingsButton, &Tooltip)>()
+        .iter(app.world())
+        .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(),
+        "Connect to a self-hosted Ferrous Solitaire sync server.",
+        "ConnectSync tooltip must use the canonical microcopy"
+    );
+}
+
+#[test]
+fn settings_picker_rows_get_focus_row_marker() {
+    let mut app = headless_app_with_focus();
+
+    app.world_mut().resource_mut::<SettingsScreen>().0 = true;
+    app.update();
+    app.update();
+    app.update();
+
+    // Two picker rows are spawned (card-back + background); each
+    // must carry the FocusRow marker.
+    let row_count = app
+        .world_mut()
+        .query_filtered::<Entity, With<FocusRow>>()
+        .iter(app.world())
+        .count();
+    assert!(
+        row_count >= 2,
+        "expected at least two FocusRow containers (card-back + background); got {row_count}"
+    );
+}
+
+/// Test 3 of the thumbnail-picker spec: when [`ThemeRegistry`] has
+/// at least one theme and the [`ThemeThumbnailCache`] holds a
+/// fully-populated [`ThemeThumbnailPair`] for that theme's id, the
+/// rendered chip carries a [`ThemeThumbnailMarker`]-tagged
+/// `ImageNode` for each preview slot.
+#[test]
+fn theme_picker_chip_includes_thumbnail_sprite_when_thumbnails_loaded() {
+    use crate::theme::{ThemeEntry, ThemeRegistry, ThemeThumbnailCache, ThemeThumbnailPair};
+
+    let mut app = headless_app_with_focus();
+    // Prime an Assets<Image> resource so we can mint stable handles
+    // for the synthetic thumbnail pair.
+    app.init_resource::<Assets<Image>>();
+    let (ace_handle, back_handle) = {
+        let mut images = app.world_mut().resource_mut::<Assets<Image>>();
+        let ace = images.add(Image::default());
+        let back = images.add(Image::default());
+        (ace, back)
+    };
+    // Inject one theme entry + a matching thumbnail pair.
+    app.insert_resource(ThemeRegistry {
+        entries: vec![ThemeEntry {
+            id: "test_theme".into(),
+            display_name: "Test Theme".into(),
+            manifest_url: "themes://test_theme/theme.ron".into(),
+            meta: crate::theme::ThemeMeta {
+                id: "test_theme".into(),
+                name: "Test Theme".into(),
+                author: "x".into(),
+                version: "x".into(),
+                card_aspect: (2, 3),
+            },
+        }],
+    });
+    let mut cache = ThemeThumbnailCache::default();
+    cache.entries.insert(
+        "test_theme".into(),
+        ThemeThumbnailPair {
+            ace: ace_handle.clone(),
+            back: back_handle.clone(),
+        },
+    );
+    app.insert_resource(cache);
+
+    // Open the panel and let the spawn + child-flush systems run.
+    app.world_mut().resource_mut::<SettingsScreen>().0 = true;
+    app.update();
+    app.update();
+    app.update();
+
+    // Find every ImageNode tagged with ThemeThumbnailMarker — the
+    // theme picker chip for "test_theme" must contribute exactly
+    // two of them (ace + back).
+    let thumbnail_count = app
+        .world_mut()
+        .query_filtered::<&ImageNode, With<ThemeThumbnailMarker>>()
+        .iter(app.world())
+        .count();
+    assert!(
+        thumbnail_count >= 2,
+        "expected at least one ace + back thumbnail (2 sprites); got {thumbnail_count}"
+    );
+
+    // Spot-check: at least one thumbnail's image handle matches one
+    // of the ones we inserted into the cache. This guards against a
+    // future refactor that accidentally clones the wrong handle.
+    let any_matches = app
+        .world_mut()
+        .query_filtered::<&ImageNode, With<ThemeThumbnailMarker>>()
+        .iter(app.world())
+        .any(|node| node.image == ace_handle || node.image == back_handle);
+    assert!(
+        any_matches,
+        "at least one rendered thumbnail must reuse the cached handle"
+    );
+}
+
+// -----------------------------------------------------------------------
+// Window geometry persistence
+// -----------------------------------------------------------------------
+
+#[test]
+fn should_persist_geometry_respects_debounce_window() {
+    // Within the debounce window: not yet.
+    assert!(!should_persist_geometry(10.0, 9.7));
+    assert!(!should_persist_geometry(
+        10.0,
+        10.0 - WINDOW_GEOMETRY_DEBOUNCE_SECS + 0.01
+    ));
+    // Exactly the debounce window: allowed (>= comparison).
+    assert!(should_persist_geometry(
+        10.0,
+        10.0 - WINDOW_GEOMETRY_DEBOUNCE_SECS
+    ));
+    // Well past the debounce window: allowed.
+    assert!(should_persist_geometry(20.0, 10.0));
+}
+
+#[test]
+fn merge_geometry_uses_existing_when_event_components_missing() {
+    let existing = WindowGeometry {
+        width: 1280,
+        height: 800,
+        x: 100,
+        y: 50,
+    };
+    // Position-only event keeps existing size.
+    let merged = merge_geometry(Some(existing), None, Some((200, 75))).unwrap();
+    assert_eq!(merged.width, 1280);
+    assert_eq!(merged.height, 800);
+    assert_eq!(merged.x, 200);
+    assert_eq!(merged.y, 75);
+    // Size-only event keeps existing position.
+    let merged = merge_geometry(Some(existing), Some((1024, 768)), None).unwrap();
+    assert_eq!(merged.width, 1024);
+    assert_eq!(merged.height, 768);
+    assert_eq!(merged.x, 100);
+    assert_eq!(merged.y, 50);
+}
+
+#[test]
+fn merge_geometry_returns_none_when_size_unknown() {
+    // No existing geometry, no size in the event → can't fabricate one.
+    assert!(merge_geometry(None, None, Some((10, 20))).is_none());
+}
+
+/// Drives `app.update()` past [`WINDOW_GEOMETRY_DEBOUNCE_SECS`] using
+/// `TimeUpdateStrategy::ManualDuration`. `Time<Virtual>` clamps each
+/// frame's delta to `max_delta` (default 250 ms), so we step in 150 ms
+/// slices and run enough ticks to comfortably exceed the debounce
+/// window after the first record tick has set `last_changed_secs`.
+fn advance_past_geometry_debounce(app: &mut App) {
+    use bevy::time::TimeUpdateStrategy;
+    use std::time::Duration;
+    app.insert_resource(TimeUpdateStrategy::ManualDuration(Duration::from_secs_f32(
+        0.15,
+    )));
+    // Tick 1 sets last_changed_secs from any pending events. Each
+    // subsequent tick advances the clock by 150 ms; five ticks total
+    // buys 0.75 s of elapsed time relative to the record tick — well
+    // past the 0.5 s debounce window.
+    for _ in 0..5 {
+        app.update();
+    }
+}
+
+fn fire_resize(app: &mut App, width: f32, height: f32) {
+    app.world_mut().write_message(WindowResized {
+        window: Entity::PLACEHOLDER,
+        width,
+        height,
+    });
+}
+
+fn fire_move(app: &mut App, x: i32, y: i32) {
+    app.world_mut().write_message(WindowMoved {
+        window: Entity::PLACEHOLDER,
+        position: IVec2::new(x, y),
+    });
+}
+
+#[test]
+fn resize_event_then_quiet_persists_window_geometry() {
+    let mut app = headless_app();
+    // Sanity: geometry starts unset (default).
+    assert!(
+        app.world()
+            .resource::<SettingsResource>()
+            .0
+            .window_geometry
+            .is_none()
+    );
+
+    // Fire a resize, then go quiet for past the debounce.
+    fire_resize(&mut app, 1500.0, 950.0);
+    advance_past_geometry_debounce(&mut app);
+
+    let geom = app
+        .world()
+        .resource::<SettingsResource>()
+        .0
+        .window_geometry
+        .expect("geometry should be persisted after debounce");
+    assert_eq!(geom.width, 1500);
+    assert_eq!(geom.height, 950);
+    // Position not yet observed → defaults to 0, 0 since there was
+    // no existing geometry to fall back on.
+    assert_eq!(geom.x, 0);
+    assert_eq!(geom.y, 0);
+}
+
+#[test]
+fn move_event_after_resize_updates_position_only() {
+    let mut app = headless_app();
+
+    // First, establish a baseline geometry via a resize event.
+    fire_resize(&mut app, 1280.0, 800.0);
+    advance_past_geometry_debounce(&mut app);
+    let baseline = app
+        .world()
+        .resource::<SettingsResource>()
+        .0
+        .window_geometry
+        .unwrap();
+    assert_eq!(baseline.width, 1280);
+
+    // Now fire a move-only event — size must be preserved from the
+    // existing geometry.
+    fire_move(&mut app, 250, 175);
+    advance_past_geometry_debounce(&mut app);
+
+    let geom = app
+        .world()
+        .resource::<SettingsResource>()
+        .0
+        .window_geometry
+        .unwrap();
+    assert_eq!(
+        geom.width, 1280,
+        "size must be preserved across a move-only update"
+    );
+    assert_eq!(geom.height, 800);
+    assert_eq!(geom.x, 250);
+    assert_eq!(geom.y, 175);
+}
+
+#[test]
+fn rapid_resize_storm_only_persists_final_size() {
+    let mut app = headless_app();
+
+    // Burst of resize events on a single frame — only the last one
+    // should be the eventually-persisted size.
+    fire_resize(&mut app, 900.0, 600.0);
+    fire_resize(&mut app, 1100.0, 700.0);
+    fire_resize(&mut app, 1400.0, 850.0);
+    advance_past_geometry_debounce(&mut app);
+
+    let geom = app
+        .world()
+        .resource::<SettingsResource>()
+        .0
+        .window_geometry
+        .unwrap();
+    assert_eq!((geom.width, geom.height), (1400, 850));
+}
+
+#[test]
+fn no_window_events_no_geometry_change() {
+    let mut app = headless_app();
+    // Just advance time — without any events, settings must stay clean.
+    advance_past_geometry_debounce(&mut app);
+    assert!(
+        app.world()
+            .resource::<SettingsResource>()
+            .0
+            .window_geometry
+            .is_none()
+    );
+}
+
+#[test]
+fn scroll_clamps_offset_to_zero_at_top() {
+    use bevy::input::mouse::{MouseScrollUnit, MouseWheel};
+    let mut app = headless_app();
+    app.world_mut().resource_mut::<SettingsScreen>().0 = true;
+    // Entity starts at 10 px offset.
+    let entity = app
+        .world_mut()
+        .spawn((
+            SettingsPanelScrollable,
+            ScrollPosition(Vec2::new(0.0, 10.0)),
+        ))
+        .id();
+    // Scroll up by 5 lines → would subtract 250 px, but must clamp to 0.
+    app.world_mut().write_message(MouseWheel {
+        unit: MouseScrollUnit::Line,
+        x: 0.0,
+        y: 5.0,
+        window: Entity::PLACEHOLDER,
+    });
+    app.update();
+    let offset = app
+        .world()
+        .entity(entity)
+        .get::<ScrollPosition>()
+        .unwrap()
+        .0
+        .y;
+    assert_eq!(
+        offset, 0.0,
+        "scrolling past top must clamp to 0, got {offset}"
+    );
+}

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_server/web/pkg/canvas.js

@@ -1649,63 +1649,63 @@ 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: 114846, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__hea4b5125da4e5ded);
+            // 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`.
+            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: 9832, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 9830, 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: 9838, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h0fec466277fb30e8);
+            // 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`.
+            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: 9832, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_3);
+            // 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`.
+            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: 9832, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_4);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("Event")], shim_idx: 9830, 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: 9832, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_5);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("FocusEvent")], shim_idx: 9830, 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: 9832, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_6);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("KeyboardEvent")], shim_idx: 9830, 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: 9832, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_7);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("PageTransitionEvent")], shim_idx: 9830, 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: 9832, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_8);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("PointerEvent")], shim_idx: 9830, 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: 9832, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_9);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("WheelEvent")], shim_idx: 9830, 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: 9834, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__hf05069bc44820cc5);
+            // 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`.
+            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: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h5e26b448f43bfba9);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [], shim_idx: 9834, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h545edb23183e448a);
             return ret;
         },
         __wbindgen_cast_000000000000000d: function(arg0) {
@@ -1769,55 +1769,55 @@ function __wbg_get_imports() {
     };
 }
 
-function wasm_bindgen__convert__closures_____invoke__h5e26b448f43bfba9(arg0, arg1) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h5e26b448f43bfba9(arg0, arg1);
+function wasm_bindgen__convert__closures_____invoke__h545edb23183e448a(arg0, arg1) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h545edb23183e448a(arg0, arg1);
 }
 
-function wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e(arg0, arg1, arg2) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e(arg0, arg1, arg2);
+function wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a(arg0, arg1, arg2);
 }
 
-function wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_3(arg0, arg1, arg2) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_3(arg0, arg1, arg2);
+function wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_3(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_3(arg0, arg1, arg2);
 }
 
-function wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_4(arg0, arg1, arg2) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_4(arg0, arg1, arg2);
+function wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_4(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_4(arg0, arg1, arg2);
 }
 
-function wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_5(arg0, arg1, arg2) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_5(arg0, arg1, arg2);
+function wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_5(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_5(arg0, arg1, arg2);
 }
 
-function wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_6(arg0, arg1, arg2) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_6(arg0, arg1, arg2);
+function wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_6(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_6(arg0, arg1, arg2);
 }
 
-function wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_7(arg0, arg1, arg2) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_7(arg0, arg1, arg2);
+function wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_7(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_7(arg0, arg1, arg2);
 }
 
-function wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_8(arg0, arg1, arg2) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_8(arg0, arg1, arg2);
+function wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_8(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_8(arg0, arg1, arg2);
 }
 
-function wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_9(arg0, arg1, arg2) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h2a0b90ad2a013a3e_9(arg0, arg1, arg2);
+function wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_9(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_9(arg0, arg1, arg2);
 }
 
-function wasm_bindgen__convert__closures_____invoke__hea4b5125da4e5ded(arg0, arg1, arg2) {
-    const ret = wasm.wasm_bindgen__convert__closures_____invoke__hea4b5125da4e5ded(arg0, arg1, arg2);
+function wasm_bindgen__convert__closures_____invoke__hfb2e9a2f0bbd9ecc(arg0, arg1, arg2) {
+    const ret = wasm.wasm_bindgen__convert__closures_____invoke__hfb2e9a2f0bbd9ecc(arg0, arg1, arg2);
     if (ret[1]) {
         throw takeFromExternrefTable0(ret[0]);
     }
 }
 
-function wasm_bindgen__convert__closures_____invoke__h0fec466277fb30e8(arg0, arg1, arg2, arg3) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h0fec466277fb30e8(arg0, arg1, arg2, arg3);
+function wasm_bindgen__convert__closures_____invoke__h876550298b312ff8(arg0, arg1, arg2, arg3) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h876550298b312ff8(arg0, arg1, arg2, arg3);
 }
 
-function wasm_bindgen__convert__closures_____invoke__hf05069bc44820cc5(arg0, arg1, arg2) {
-    wasm.wasm_bindgen__convert__closures_____invoke__hf05069bc44820cc5(arg0, arg1, isLikeNone(arg2) ? 0 : addToExternrefTable0(arg2));
+function wasm_bindgen__convert__closures_____invoke__h657f46feffff6fe4(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h657f46feffff6fe4(arg0, arg1, isLikeNone(arg2) ? 0 : addToExternrefTable0(arg2));
 }