Merge pull request 'docs(changelog): cut v0.42.0 section' (#151) from docs/changelog-v0.42.0 into master

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

.gitea/workflows/test.yml

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

ARCHITECTURE.md

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

CHANGELOG.md

@@ -6,6 +6,65 @@ project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.42.0] — 2026-07-06
+
+### Added
+
+- **CI workspace gate.** New `test.yml` workflow runs clippy (deny warnings)
+  and the full test suite on every master push and PR — previously no CI ran
+  tests at all. Caught its own first bug (missing Bevy native deps) on its
+  own PR. (#135)
+- **Schedule ambiguity gate.** A headless test builds the gameplay plugin
+  cluster with Bevy ambiguity detection promoted to error. The initial
+  measurement found 302 system pairs with conflicting data access and no
+  ordering; four burn-down batches (PRs #146–#149) took it to ZERO the same
+  day, and the gate now enforces 0. Keyboard consumption, board painting,
+  and HUD updates all have deterministic order for the first time.
+
+### Changed
+
+- **Browser canvas 36% smaller.** `canvas_bg.wasm` shrank 36.2 MB → 23.2 MB
+  via a size-focused `wasm-release` profile (fat LTO, single codegen unit,
+  opt-level "s"); verified visually identical in production. (#134)
+- **Quaternions API adoption.** Canonical `FOUNDATIONS`/`TABLEAUS` consts in
+  `solitaire_core` replace five scattered enum lists; upstream
+  `Suit::SUITS`/`Rank::RANKS` replace nine hand-rolled arrays, with the
+  texture-atlas indexing re-keyed through tested canonical helpers. Net
+  −177 lines. (#137)
+
+### Fixed
+
+- **Sync push race.** The server's load→merge→store cycle now runs in one
+  transaction; concurrent pushes from two devices can no longer overwrite
+  each other's merge. (#136)
+- **Refresh-token rotation is single-use under concurrency** — rotation
+  gates on the DELETE's row count, so a stolen-then-replayed refresh token
+  loses the race and gets 401. (#136)
+- **Exit sync push actually completes.** Was a detached task killed by
+  process teardown; now a bounded 2-second blocking wait on the app's final
+  frame. (#138)
+- **Server auth hardening.** Login timing no longer reveals whether a
+  username exists; concurrent duplicate registration returns 409 instead of
+  500; avatar uploads are magic-byte checked. (#144, issues #139–#141)
+
+## [0.41.1] — 2026-07-06
+
+### Fixed
+
+- **Oversized pile-marker frames after fold/unfold.** `on_window_resized`
+  resized the marker fill sprite but never its children, so the outline frame
+  and the "A"/"K" watermark kept their spawn-time size after any resize —
+  rendering as oversized grey slabs over empty foundation slots on foldables
+  (found during Galaxy Fold 7 on-device verification of v0.41.0, fixed and
+  re-verified on the same device). Both children are now re-derived from the
+  new layout on every relayout.
+
+### Added
+
+- **Android relayout diagnostics.** Every layout recompute on Android now
+  logs its window dimensions and insets (`layout: resize to WxH …`) — the
+  evidence channel for foldable layout reports (#130).
+
 ## [0.41.0] — 2026-07-06
 
 > Consolidates everything shipped since v0.39.0, including the v0.40.0–v0.40.3

CLAUDE.md

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

Cargo.toml

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

SESSION_HANDOFF.md

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

build_wasm.sh

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

solitaire_core/src/lib.rs

@@ -19,5 +19,33 @@ pub use klondike::{DrawStockConfig, Foundation, Klondike, KlondikeInstruction, K
 // former `solitaire_data::solver` wrapper module.
 pub use game_state::{DEFAULT_SOLVE_MOVES_BUDGET, DEFAULT_SOLVE_STATES_BUDGET, SolveOutcome};
 
+/// All four foundation slots, in slot order.
+///
+/// Canonical iteration source for `Foundation` — upstream `klondike` has no
+/// `Foundation::ALL` (unlike `Suit::SUITS` / `Rank::RANKS` in `card_game`),
+/// and inherent impls cannot be added to a foreign type, so the workspace
+/// const lives here. Use this instead of hand-rolling `[Foundation; 4]`
+/// arrays; scattered copies can silently diverge.
+pub const FOUNDATIONS: [Foundation; 4] = [
+    Foundation::Foundation1,
+    Foundation::Foundation2,
+    Foundation::Foundation3,
+    Foundation::Foundation4,
+];
+
+/// All seven tableau columns, in column order (left to right on screen).
+///
+/// Canonical iteration source for `Tableau` — see [`FOUNDATIONS`] for why
+/// this lives here rather than upstream.
+pub const TABLEAUS: [Tableau; 7] = [
+    Tableau::Tableau1,
+    Tableau::Tableau2,
+    Tableau::Tableau3,
+    Tableau::Tableau4,
+    Tableau::Tableau5,
+    Tableau::Tableau6,
+    Tableau::Tableau7,
+];
+
 #[cfg(test)]
 mod proptest_tests;

solitaire_engine/src/assets/card_face_svg.rs

@@ -74,9 +74,11 @@ pub const ALL_RANKS: [Rank; 13] = [
     Rank::King,
 ];
 
-/// Every suit in `Clubs, Diamonds, Hearts, Spades` order — matches
-/// `card_plugin::load_card_images` so the suit index used here lines
-/// up with `CardImageSet.faces[suit]`.
+/// Iteration order for the SVG generator and the pin test only —
+/// output files are keyed by `suit_filename`, so no runtime index
+/// depends on this order. Kept local (not `Suit::SUITS`) because
+/// reordering would churn the pinned snapshot ordering for no
+/// benefit.
 pub const ALL_SUITS: [Suit; 4] = [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades];
 
 /// The rank component of the on-disk filename — `A`, `2`..`10`, `J`,

solitaire_engine/src/auto_complete_plugin.rs

@@ -46,6 +46,11 @@ pub struct AutoCompleteState {
 /// Plugin that drives the auto-complete sequence.
 pub struct AutoCompletePlugin;
 
+/// Set wrapping the auto-complete detect/drive chain; HUD readers of
+/// [`AutoCompleteState`] order themselves after it (#143).
+#[derive(bevy::ecs::schedule::SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
+pub struct AutoComplete;
+
 impl Plugin for AutoCompletePlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<AutoCompleteState>()
@@ -58,7 +63,9 @@ impl Plugin for AutoCompletePlugin {
                     drive_auto_complete,
                 )
                     .chain()
-                    .after(GameMutation),
+                    .in_set(AutoComplete)
+                    .after(GameMutation)
+                    .before(crate::card_plugin::BoardVisuals),
             );
     }
 }

solitaire_engine/src/card_plugin/anim.rs

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

solitaire_engine/src/card_plugin/highlights.rs

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

solitaire_engine/src/card_plugin/labels.rs

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

solitaire_engine/src/card_plugin/layout.rs

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

solitaire_engine/src/card_plugin/stock.rs

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

solitaire_engine/src/card_plugin/sync.rs

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

solitaire_engine/src/card_plugin/tests.rs

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

solitaire_engine/src/game_plugin/mod.rs

@@ -63,6 +63,29 @@ pub struct GameOverScreen;
 #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
 pub struct GameMutation;
 
+/// System set for every writer of [`crate::events::NewGameRequestEvent`].
+///
+/// Many UI entry points fire this trigger (buttons, keyboard, modals,
+/// mode pickers). Their relative append order within a frame is
+/// meaningless — consumers drain the whole queue — so members are
+/// registered `.in_set(NewGameRequestWriters).ambiguous_with(NewGameRequestWriters)`
+/// to declare writer-vs-writer order irrelevant instead of leaving it as an
+/// ambiguity (#143). Only ever combine with `.ambiguous_with` on the same
+/// set; do NOT hang ordering edges off this set.
+#[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
+pub struct NewGameRequestWriters;
+
+/// Self-ambiguous set for writers of `UndoRequestEvent` — same rationale as
+/// [`NewGameRequestWriters`]: consumers drain the queue, append order is
+/// meaningless (#143).
+#[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
+pub struct UndoRequestWriters;
+
+/// Self-ambiguous set for writers of `InfoToastEvent` — toasts queue in
+/// arrival order and any same-frame order is fine (#143).
+#[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
+pub struct InfoToastWriters;
+
 /// Persistence path for the in-progress game state file. `None` disables I/O.
 #[derive(Resource, Debug, Clone)]
 pub struct GameStatePath(pub Option<PathBuf>);
@@ -208,28 +231,66 @@ impl Plugin for GamePlugin {
             .add_message::<AppLifecycle>()
             // add_message is idempotent; SettingsPlugin also registers this.
             .add_message::<crate::settings_plugin::SettingsChangedEvent>()
-            .add_systems(Update, poll_pending_new_game_seed.before(GameMutation))
+            .add_systems(
+                Update,
+                poll_pending_new_game_seed
+                    .before(GameMutation)
+                    .in_set(NewGameRequestWriters)
+                    .ambiguous_with(NewGameRequestWriters),
+            )
             .add_systems(
                 Update,
                 (handle_new_game, handle_draw, handle_move, handle_undo)
                     .chain()
                     .in_set(GameMutation),
             )
-            .add_systems(Update, check_no_moves.after(GameMutation))
+            .add_systems(
+                Update,
+                check_no_moves
+                    .after(GameMutation)
+                    .before(crate::card_plugin::BoardVisuals)
+                    .in_set(InfoToastWriters)
+                    .ambiguous_with(InfoToastWriters),
+            )
             .add_systems(Update, record_replay_on_win.after(GameMutation))
-            .add_systems(Update, handle_confirm_input.after(GameMutation))
-            .add_systems(Update, handle_confirm_button_input.after(GameMutation))
-            .add_systems(Update, handle_game_over_input.after(GameMutation))
-            .add_systems(Update, handle_game_over_button_input.after(GameMutation))
+            .add_systems(
+                Update,
+                (
+                    handle_confirm_input,
+                    handle_confirm_button_input,
+                    handle_game_over_input,
+                    handle_game_over_button_input,
+                )
+                    .after(GameMutation)
+                    .before(crate::ui_focus::FocusKeys)
+                    .in_set(NewGameRequestWriters)
+                    .ambiguous_with(NewGameRequestWriters)
+                    .in_set(UndoRequestWriters)
+                    .ambiguous_with(UndoRequestWriters),
+            )
             // Restore prompt: spawn the modal once the splash is gone,
             // route Continue / New Game intents back into the existing
             // GameMutation flow.
-            .add_systems(Update, spawn_restore_prompt_if_pending)
-            .add_systems(Update, handle_restore_prompt.before(GameMutation))
-            .add_systems(Update, sync_settings_to_game.before(GameMutation))
+            // All pre-mutation game-state writers are chained: elapsed
+            // time ticks first, settings sync next, then the restore prompt —
+            // a deterministic spine instead of three unordered ResMut holders
+            // (ambiguity burn-down, #143).
+            .add_systems(
+                Update,
+                (
+                    tick_elapsed_time,
+                    sync_settings_to_game,
+                    spawn_restore_prompt_if_pending,
+                    handle_restore_prompt
+                        .in_set(NewGameRequestWriters)
+                        .ambiguous_with(NewGameRequestWriters),
+                )
+                    .chain()
+                    .after(crate::settings_plugin::SettingsMutation)
+                    .before(GameMutation),
+            )
             .init_resource::<AutoSaveTimer>()
-            .add_systems(Update, tick_elapsed_time)
-            .add_systems(Update, auto_save_game_state)
+            .add_systems(Update, auto_save_game_state.after(GameMutation))
             .add_systems(Last, save_game_state_on_exit);
     }
 }

solitaire_engine/src/hud_plugin/mod.rs

@@ -36,7 +36,7 @@ use crate::events::{
     UndoRequestEvent, WinStreakMilestoneEvent,
 };
 use crate::font_plugin::FontResource;
-use crate::game_plugin::GameMutation;
+use crate::game_plugin::{GameMutation, NewGameRequestWriters};
 #[cfg(target_os = "android")]
 use crate::input_plugin::TouchDragSet;
 use crate::layout::HUD_BAND_HEIGHT;
@@ -54,6 +54,7 @@ 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::UiTextFx;
 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,
@@ -153,6 +154,13 @@ pub struct HudColumn;
 #[derive(Component, Debug)]
 pub struct HudActionBar;
 
+/// Set wrapping the chained HUD button/popover interaction systems. Other
+/// keyboard consumers order themselves around it (e.g.
+/// [`crate::ui_focus::FocusKeys`] runs after) so input-consumption order is
+/// deterministic (#143).
+#[derive(bevy::ecs::schedule::SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
+pub struct HudButtons;
+
 /// 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)]
@@ -467,23 +475,56 @@ impl Plugin for HudPlugin {
             // 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))
+            // HUD text updaters run as one deterministic chain (they write
+            // disjoint Text nodes, but Bevy can't prove it); update_hud also
+            // reads AutoCompleteState, so the chain sits after the
+            // auto-complete detect/drive chain (#143).
             .add_systems(
                 Update,
-                apply_hud_visibility.before(LayoutSystem::UpdateOnResize),
+                (
+                    update_hud,
+                    update_selection_hud.run_if(
+                        resource_exists_and_changed::<SelectionState>
+                            .or(resource_exists_and_changed::<GameStateResource>),
+                    ),
+                    update_won_previously,
+                )
+                    .chain()
+                    .after(GameMutation)
+                    .after(crate::auto_complete_plugin::AutoComplete)
+                    .in_set(UiTextFx)
+                    .ambiguous_with(UiTextFx),
             )
-            .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))
+            // HUD chrome visibility: modal-restore writes HudVisibility, the
+            // applier consumes it, and the layout recompute reads it — a
+            // fixed chain instead of three racing systems (#143).
             .add_systems(
                 Update,
-                update_selection_hud.run_if(
-                    resource_exists_and_changed::<SelectionState>
-                        .or(resource_exists_and_changed::<GameStateResource>),
+                (restore_hud_on_modal, apply_hud_visibility)
+                    .chain()
+                    .before(LayoutSystem::UpdateOnResize),
+            )
+            .add_systems(
+                Update,
+                (
+                    update_hud_avatar.after(crate::settings_plugin::SettingsMutation),
+                    handle_avatar_button.ambiguous_with(HudButtons),
                 ),
             )
-            .add_systems(Update, update_hud_typography)
+            .add_systems(
+                Update,
+                announce_auto_complete
+                    .after(GameMutation)
+                    .after(crate::auto_complete_plugin::AutoComplete)
+                    .in_set(crate::game_plugin::InfoToastWriters)
+                    .ambiguous_with(crate::game_plugin::InfoToastWriters),
+            )
+            // Typography rescale touches HUD TextFont only, but orders after
+            // the board painters that resize card/label text (#143).
+            .add_systems(
+                Update,
+                update_hud_typography.after(crate::card_plugin::BoardVisuals),
+            )
             .add_systems(
                 Update,
                 (
@@ -492,24 +533,40 @@ impl Plugin for HudPlugin {
                     advance_score_floater,
                 )
                     .chain()
-                    .after(GameMutation),
+                    .after(GameMutation)
+                    .in_set(UiTextFx)
+                    .ambiguous_with(UiTextFx)
+                    .ambiguous_with(crate::card_plugin::BoardVisuals),
             )
             .add_systems(
                 Update,
                 (start_streak_flourish, advance_streak_flourish)
                     .chain()
-                    .after(GameMutation),
+                    .after(GameMutation)
+                    .in_set(UiTextFx)
+                    .ambiguous_with(UiTextFx)
+                    .ambiguous_with(crate::card_plugin::BoardVisuals),
             )
             .add_systems(
                 Update,
                 (
-                    handle_new_game_button,
-                    handle_undo_button,
+                    handle_new_game_button
+                        .in_set(NewGameRequestWriters)
+                        .ambiguous_with(NewGameRequestWriters),
+                    handle_undo_button
+                        .in_set(crate::game_plugin::UndoRequestWriters)
+                        .ambiguous_with(crate::game_plugin::UndoRequestWriters)
+                        .before(GameMutation),
                     handle_pause_button,
                     handle_help_button,
-                    handle_hint_button,
+                    handle_hint_button
+                        .after(GameMutation)
+                        .in_set(crate::game_plugin::InfoToastWriters)
+                        .ambiguous_with(crate::game_plugin::InfoToastWriters),
                     handle_modes_button,
-                    handle_mode_option_click,
+                    handle_mode_option_click
+                        .in_set(NewGameRequestWriters)
+                        .ambiguous_with(NewGameRequestWriters),
                     handle_modes_backdrop_click,
                     close_modes_popover_on_escape,
                     handle_menu_button,
@@ -517,7 +574,10 @@ impl Plugin for HudPlugin {
                     handle_menu_backdrop_click,
                     close_menu_popover_on_escape,
                     paint_action_buttons,
-                ),
+                )
+                    .chain()
+                    .in_set(HudButtons)
+                    .before(crate::ui_focus::FocusKeys),
             )
             // Fade lives in `Last` so it always overrides whatever the
             // hover/paint pass set on `BackgroundColor` this frame.

solitaire_engine/src/input_plugin/mod.rs

@@ -28,6 +28,7 @@ use bevy::window::PrimaryWindow;
 #[cfg(not(target_os = "android"))]
 use bevy::window::{MonitorSelection, WindowMode};
 use solitaire_core::{Foundation, KlondikeInstruction, KlondikePile, Tableau};
+use solitaire_core::{FOUNDATIONS, TABLEAUS};
 use solitaire_core::{Card, Suit};
 use solitaire_core::game_state::GameState;
 
@@ -1329,13 +1330,13 @@ const DOUBLE_TAP_FLASH_SECS: f32 = 0.35;
 pub fn best_destination(card: &Card, game: &GameState) -> Option<KlondikePile> {
     let source = game.pile_containing_card(card.clone())?;
 
-    for foundation in foundations() {
+    for foundation in FOUNDATIONS {
         let dest = KlondikePile::Foundation(foundation);
         if game.can_move_cards(&source, &dest, 1) {
             return Some(dest);
         }
     }
-    for tableau in tableaus() {
+    for tableau in TABLEAUS {
         let dest = KlondikePile::Tableau(tableau);
         if game.can_move_cards(&source, &dest, 1) {
             return Some(dest);
@@ -1356,7 +1357,7 @@ pub fn best_tableau_destination_for_stack(
     game: &GameState,
     stack_count: usize,
 ) -> Option<(KlondikePile, usize)> {
-    for tableau in tableaus() {
+    for tableau in TABLEAUS {
         let dest = KlondikePile::Tableau(tableau);
         if game.can_move_cards(from, &dest, stack_count) {
             return Some((dest, stack_count));
@@ -1692,7 +1693,7 @@ pub(crate) fn hint_piles(
 fn legacy_all_hints(game: &GameState) -> Vec<(KlondikePile, KlondikePile)> {
     let sources: Vec<KlondikePile> = {
         let mut s = vec![KlondikePile::Stock];
-        for tableau in tableaus() {
+        for tableau in TABLEAUS {
             s.push(KlondikePile::Tableau(tableau));
         }
         s
@@ -1706,7 +1707,7 @@ fn legacy_all_hints(game: &GameState) -> Vec<(KlondikePile, KlondikePile)> {
         let Some(_card) = from_pile.last().filter(|(_, face_up)| *face_up) else {
             continue;
         };
-        for foundation in foundations() {
+        for foundation in FOUNDATIONS {
             let dest = KlondikePile::Foundation(foundation);
             if game.can_move_cards(from, &dest, 1) {
                 hints.push((*from, dest));
@@ -1728,7 +1729,7 @@ fn legacy_all_hints(game: &GameState) -> Vec<(KlondikePile, KlondikePile)> {
         if already_has_foundation_hint {
             continue;
         }
-        for tableau in tableaus() {
+        for tableau in TABLEAUS {
             let dest = KlondikePile::Tableau(tableau);
             if game.can_move_cards(from, &dest, 1) {
                 hints.push((*from, dest));
@@ -1742,13 +1743,13 @@ fn legacy_all_hints(game: &GameState) -> Vec<(KlondikePile, KlondikePile)> {
     // should never hint Foundation→Foundation. Here we handle the return path
     // separately so the guarded `take_from_foundation` rule is respected.
     if game.take_from_foundation {
-        for foundation in foundations() {
+        for foundation in FOUNDATIONS {
             let from = KlondikePile::Foundation(foundation);
             let from_pile = pile_cards(game, &from);
             let Some(_card) = from_pile.last().filter(|(_, face_up)| *face_up) else {
                 continue;
             };
-            for tableau in tableaus() {
+            for tableau in TABLEAUS {
                 let dest = KlondikePile::Tableau(tableau);
                 if game.can_move_cards(&from, &dest, 1) {
                     hints.push((from, dest));
@@ -1782,26 +1783,7 @@ fn pile_cards(game: &GameState, pile: &KlondikePile) -> Vec<(Card, bool)> {
     }
 }
 
-const fn foundations() -> [Foundation; 4] {
-    [
-        Foundation::Foundation1,
-        Foundation::Foundation2,
-        Foundation::Foundation3,
-        Foundation::Foundation4,
-    ]
-}
 
-const fn tableaus() -> [Tableau; 7] {
-    [
-        Tableau::Tableau1,
-        Tableau::Tableau2,
-        Tableau::Tableau3,
-        Tableau::Tableau4,
-        Tableau::Tableau5,
-        Tableau::Tableau6,
-        Tableau::Tableau7,
-    ]
-}
 
 const fn tableau_number(tableau: Tableau) -> u8 {
     match tableau {

solitaire_engine/src/lib.rs

@@ -43,6 +43,7 @@ pub mod replay_overlay;
 pub mod replay_playback;
 pub mod resources;
 pub mod safe_area;
+mod schedule_checks;
 pub mod selection_plugin;
 pub mod settings_plugin;
 pub mod splash_plugin;

solitaire_engine/src/pending_hint.rs

@@ -220,32 +220,11 @@ mod tests {
         ] {
             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,
-        ] {
+        for tableau in solitaire_core::TABLEAUS {
             game.set_test_tableau_cards(tableau, Vec::new());
         }
-        let suits = [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades];
-        let ranks_below_king = [
-            Rank::Ace,
-            Rank::Two,
-            Rank::Three,
-            Rank::Four,
-            Rank::Five,
-            Rank::Six,
-            Rank::Seven,
-            Rank::Eight,
-            Rank::Nine,
-            Rank::Ten,
-            Rank::Jack,
-            Rank::Queen,
-        ];
+        let suits = Suit::SUITS;
+        let ranks_below_king = &Rank::RANKS[..12]; // everything below King
         for (foundation, suit) in [
             Foundation::Foundation1,
             Foundation::Foundation2,

solitaire_engine/src/radial_menu.rs

@@ -48,6 +48,7 @@ use bevy::math::Vec2;
 use bevy::prelude::*;
 use bevy::window::PrimaryWindow;
 use solitaire_core::{Foundation, KlondikePile, Tableau};
+use solitaire_core::{FOUNDATIONS, TABLEAUS};
 use solitaire_core::Card;
 use solitaire_core::game_state::GameState;
 
@@ -254,13 +255,13 @@ pub fn legal_destinations_for_card(
     game: &GameState,
 ) -> Vec<KlondikePile> {
     let mut out = Vec::new();
-    for foundation in foundations() {
+    for foundation in FOUNDATIONS {
         let dest = KlondikePile::Foundation(foundation);
         if game.can_move_cards(source_pile, &dest, 1) {
             out.push(dest);
         }
     }
-    for tableau in tableaus() {
+    for tableau in TABLEAUS {
         let dest = KlondikePile::Tableau(tableau);
         if game.can_move_cards(source_pile, &dest, 1) {
             out.push(dest);
@@ -360,26 +361,7 @@ fn pile_cards(game: &GameState, pile: &KlondikePile) -> Vec<(Card, bool)> {
 }
 
 
-const fn foundations() -> [Foundation; 4] {
-    [
-        Foundation::Foundation1,
-        Foundation::Foundation2,
-        Foundation::Foundation3,
-        Foundation::Foundation4,
-    ]
-}
 
-const fn tableaus() -> [Tableau; 7] {
-    [
-        Tableau::Tableau1,
-        Tableau::Tableau2,
-        Tableau::Tableau3,
-        Tableau::Tableau4,
-        Tableau::Tableau5,
-        Tableau::Tableau6,
-        Tableau::Tableau7,
-    ]
-}
 
 /// Builds the `(destination, anchor)` list for a fresh radial open.
 ///

solitaire_engine/src/schedule_checks.rs

@@ -0,0 +1,108 @@
+//! Schedule hygiene checks (issue #143).
+//!
+//! Bevy runs systems with conflicting data access in nondeterministic order
+//! unless an ordering edge exists. Nothing enforced this historically, and
+//! the headless gameplay cluster carries a large legacy backlog of such
+//! pairs — most benign (event/resource writers that never observably race),
+//! but unproven. Rather than a permanently red hard-error test or no test
+//! at all, this is a RATCHET: the count may only go down. New conflicting
+//! pairs fail CI immediately; the backlog can be triaged incrementally
+//! (add `.before`/`.after` where order matters, `.ambiguous_with` where it
+//! provably doesn't, then lower `AMBIGUITY_BASELINE`).
+//!
+//! To see the offending pair names, add the `bevy_debug` / debug feature to
+//! the bevy dev-dependency (system names are stripped otherwise) and set
+//! `ambiguity_detection: LogLevel::Error` manually.
+//!
+//! Scope note: `CoreGamePlugin` (the full composition) performs real
+//! storage/platform I/O in `build` and cannot run in a unit test; the
+//! cluster below is the same one the engine's headless behaviour tests use.
+
+#[cfg(test)]
+mod tests {
+    use bevy::ecs::schedule::{LogLevel, ScheduleBuildSettings};
+    use bevy::prelude::*;
+
+    use crate::auto_complete_plugin::AutoCompletePlugin;
+    use crate::card_plugin::CardPlugin;
+    use crate::game_plugin::GamePlugin;
+    use crate::hud_plugin::HudPlugin;
+    use crate::settings_plugin::SettingsPlugin;
+    use crate::table_plugin::TablePlugin;
+    use crate::ui_focus::UiFocusPlugin;
+    use crate::ui_modal::UiModalPlugin;
+
+    /// The backlog (302 pairs on 2026-07-06) was burned down to ZERO the
+    /// same day (#143, PRs #146–#149) — this is now a hard gate. If your
+    /// change trips this assertion you have added a pair of systems with
+    /// conflicting data access and no ordering edge: add `.before`/`.after`
+    /// where order matters, or `.ambiguous_with` the relevant domain set
+    /// (BoardVisuals, MarkerVisuals, UiTextFx, HudButtons, writer sets)
+    /// where it provably does not. Do not raise this constant.
+    const AMBIGUITY_BASELINE: usize = 0;
+
+    fn cluster_app() -> App {
+        let mut app = App::new();
+        app.add_plugins(MinimalPlugins)
+            .add_plugins(GamePlugin)
+            .add_plugins(TablePlugin)
+            .add_plugins(CardPlugin)
+            .add_plugins(HudPlugin)
+            .add_plugins(AutoCompletePlugin)
+            .add_plugins(UiModalPlugin)
+            .add_plugins(UiFocusPlugin)
+            .add_plugins(SettingsPlugin::headless());
+        app.init_resource::<ButtonInput<KeyCode>>();
+        app
+    }
+
+    #[test]
+    fn update_schedule_ambiguities_do_not_grow() {
+        let mut app = cluster_app();
+        app.edit_schedule(Update, |s| {
+            s.set_build_settings(ScheduleBuildSettings {
+                ambiguity_detection: LogLevel::Error,
+                ..Default::default()
+            });
+        });
+
+        // With LogLevel::Error the first schedule build panics when any
+        // ambiguity exists, and the panic message begins with the pair
+        // count. Catch it and ratchet on that count. (Parsing a panic
+        // message is brittle by design — if a Bevy upgrade rewords it,
+        // this test fails loudly and the parse below needs one-line
+        // maintenance, which is preferable to losing the ratchet.)
+        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            app.update();
+        }));
+
+        let count = match result {
+            Ok(()) => 0,
+            Err(payload) => {
+                let msg = payload
+                    .downcast_ref::<String>()
+                    .cloned()
+                    .or_else(|| payload.downcast_ref::<&str>().map(|s| (*s).to_string()))
+                    .unwrap_or_default();
+                let parsed = msg
+                    .split(" pairs of systems")
+                    .next()
+                    .and_then(|prefix| prefix.split_whitespace().last())
+                    .and_then(|n| n.parse::<usize>().ok());
+                parsed.unwrap_or_else(|| {
+                    panic!(
+                        "ambiguity panic message no longer parseable (Bevy upgrade?): {msg}"
+                    )
+                })
+            }
+        };
+
+        assert_eq!(
+            count, AMBIGUITY_BASELINE,
+            "system-order ambiguities changed from the enforced baseline. \
+             Add .before/.after or .ambiguous_with at the new registration site \
+             (or, if the count legitimately dropped below a nonzero baseline, \
+             lower AMBIGUITY_BASELINE).",
+        );
+    }
+}

solitaire_engine/src/settings_plugin/mod.rs

@@ -79,6 +79,14 @@ pub struct PendingWindowGeometry {
 #[derive(Message, Debug, Clone)]
 pub struct SettingsChangedEvent(pub Settings);
 
+/// System set for the systems that mutate [`SettingsResource`] every frame
+/// (hotkeys and window-geometry persistence). Ordered before
+/// [`crate::game_plugin::GameMutation`]; readers of settings should sit
+/// after this set (directly, or transitively via `.after(GameMutation)`)
+/// so they observe the current frame's settings deterministically (#143).
+#[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
+pub struct SettingsMutation;
+
 /// Marker on the root Settings panel entity.
 #[derive(Component, Debug)]
 pub struct SettingsPanel;
@@ -372,16 +380,37 @@ impl Plugin for SettingsPlugin {
             // also runs cleanly under `MinimalPlugins` (tests).
             .add_message::<WindowResized>()
             .add_message::<WindowMoved>()
+            // Settings changes land before game logic runs: the mutator
+            // chain (volume keys → geometry record → geometry persist) is a
+            // deterministic spine, and the whole set precedes GameMutation so
+            // every reader already ordered after GameMutation sees this
+            // frame's settings transitively (ambiguity burn-down, #143).
+            .configure_sets(
+                Update,
+                SettingsMutation
+                    .after(crate::layout::LayoutSystem::UpdateOnResize)
+                    .before(crate::game_plugin::GameMutation),
+            )
             .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,
-                ),
+                )
+                    .chain()
+                    .in_set(SettingsMutation),
+            )
+            .add_systems(
+                Update,
+                (
+                    toggle_settings_screen
+                        .before(crate::ui_focus::FocusKeys)
+                        .ambiguous_with(crate::hud_plugin::HudButtons),
+                    scroll_settings_panel,
+                    crate::ui_modal::touch_scroll_panel::<SettingsPanelScrollable>,
+                )
+                    .chain(),
             );
 
         if self.ui_enabled {

solitaire_engine/src/sync_plugin.rs

@@ -272,12 +272,21 @@ fn poll_pull_result(
     }
 }
 
-/// Last-schedule system: starts a best-effort push of the current local state
-/// on [`AppExit`] without blocking the Bevy main thread.
+/// Upper bound on how long [`push_on_exit`] may block the closing app.
+/// Long enough for one healthy round-trip; short enough that quitting
+/// never feels hung when the server is unreachable.
+const EXIT_PUSH_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(2);
+
+/// Last-schedule system: pushes the current local state on [`AppExit`],
+/// blocking the main thread for at most [`EXIT_PUSH_TIMEOUT`].
 ///
-/// The detached task may be cut short by process teardown, so local atomic
-/// persistence remains the durable source of truth even if the final remote
-/// push does not complete.
+/// This deliberately blocks: the previous detached-task version was almost
+/// always cut short by process teardown, so the final session's push
+/// silently never happened (2026-07-06 review, finding M3). A bounded wait
+/// during the app's final frame is invisible to the player and lets the
+/// round-trip actually complete on a healthy network. On timeout or error
+/// the push is skipped — local atomic persistence remains the durable
+/// source of truth and the next launch's pull/push converges.
 fn push_on_exit(
     mut exit_events: MessageReader<AppExit>,
     provider: Res<SyncProviderResource>,
@@ -292,16 +301,17 @@ fn push_on_exit(
     exit_events.clear();
 
     let payload = build_payload(&stats.0, &achievements.0, &progress.0);
-    let provider = provider.0.clone();
-    let rt = rt.0.clone();
-    AsyncComputeTaskPool::get()
-        .spawn(async move {
-            match rt.block_on(provider.push(&payload)) {
-                Ok(_) | Err(SyncError::UnsupportedPlatform) => {}
-                Err(e) => warn!("sync push on exit failed: {e}"),
-            }
-        })
-        .detach();
+    let result = rt
+        .0
+        .block_on(async { tokio::time::timeout(EXIT_PUSH_TIMEOUT, provider.0.push(&payload)).await });
+    match result {
+        Ok(Ok(_)) | Ok(Err(SyncError::UnsupportedPlatform)) => {}
+        Ok(Err(e)) => warn!("sync push on exit failed: {e}"),
+        Err(_) => warn!(
+            "sync push on exit timed out after {}s; will sync on next launch",
+            EXIT_PUSH_TIMEOUT.as_secs()
+        ),
+    }
 }
 
 /// Update-schedule system: on each `GameWonEvent` push the just-completed

solitaire_engine/src/table_plugin.rs

@@ -6,10 +6,12 @@
 
 use bevy::prelude::*;
 use bevy::window::WindowResized;
-use solitaire_core::{Foundation, KlondikePile, Tableau};
+use solitaire_core::KlondikePile;
+use solitaire_core::{FOUNDATIONS, TABLEAUS};
 use solitaire_core::Suit;
 
 use crate::events::{HintVisualEvent, StateChangedEvent};
+use crate::game_plugin::GameMutation;
 use crate::hud_plugin::HudVisibility;
 use crate::layout::{
     Layout, LayoutResource, LayoutSystem, TABLE_COLOUR, apply_dynamic_tableau_fan, compute_layout,
@@ -83,6 +85,13 @@ pub struct HintPileHighlight {
 /// Registers the table background and pile-marker rendering.
 pub struct TablePlugin;
 
+/// Set wrapping the pile-marker painter chain (theme, hint highlights,
+/// visibility). Runs after [`crate::card_plugin::BoardVisuals`]; chrome-fx
+/// systems that touch `Visibility` on UI entities declare themselves
+/// ambiguous with it (#143).
+#[derive(bevy::ecs::schedule::SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
+pub struct MarkerVisuals;
+
 impl Plugin for TablePlugin {
     fn build(&self, app: &mut App) {
         // Register WindowResized so the plugin works under MinimalPlugins in
@@ -99,10 +108,18 @@ impl Plugin for TablePlugin {
                 (
                     on_safe_area_changed.before(LayoutSystem::UpdateOnResize),
                     on_window_resized.in_set(LayoutSystem::UpdateOnResize),
-                    apply_theme_on_settings_change,
-                    apply_hint_pile_highlight,
-                    tick_hint_pile_highlights,
-                    sync_pile_marker_visibility,
+                    // Marker painters: deterministic chain after the card
+                    // paint pipeline — markers and cards share Sprite/
+                    // Transform access (#143).
+                    (
+                        apply_theme_on_settings_change,
+                        apply_hint_pile_highlight,
+                        tick_hint_pile_highlights,
+                        sync_pile_marker_visibility.after(GameMutation),
+                    )
+                        .chain()
+                        .in_set(MarkerVisuals)
+                        .after(crate::card_plugin::BoardVisuals),
                 ),
             );
     }
@@ -280,10 +297,10 @@ fn spawn_pile_markers(commands: &mut Commands, layout: &Layout) {
 
     let mut piles: Vec<KlondikePile> = Vec::with_capacity(12);
     piles.push(KlondikePile::Stock);
-    for foundation in foundations() {
+    for foundation in FOUNDATIONS {
         piles.push(KlondikePile::Foundation(foundation));
     }
-    for tableau in tableaus() {
+    for tableau in TABLEAUS {
         piles.push(KlondikePile::Tableau(tableau));
     }
 
@@ -362,7 +379,15 @@ fn on_window_resized(
         (&mut Sprite, &mut Transform),
         (With<TableBackground>, Without<PileMarker>),
     >,
-    mut markers: Query<(&PileMarker, &mut Sprite, &mut Transform), Without<TableBackground>>,
+    mut markers: Query<
+        (&PileMarker, &mut Sprite, &mut Transform, Option<&Children>),
+        Without<TableBackground>,
+    >,
+    mut marker_outlines: Query<
+        &mut Sprite,
+        (Without<PileMarker>, Without<TableBackground>, Without<Text2d>),
+    >,
+    mut marker_labels: Query<&mut TextFont, With<Text2d>>,
 ) {
     let Some(ev) = events.read().last() else {
         return;
@@ -373,6 +398,14 @@ fn on_window_resized(
     let safe_area_top = insets.top / scale;
     let safe_area_bottom = insets.bottom / scale;
     let hud_visible = hud_vis.as_deref().copied().unwrap_or_default() == HudVisibility::Visible;
+    // Android surface sizes after fold/unfold are unreliable (winit does not
+    // forward every content-rect change), so make each relayout observable
+    // in logcat — this is the primary evidence channel for foldable bugs.
+    #[cfg(target_os = "android")]
+    info!(
+        "layout: resize to {:.0}x{:.0} (insets top={:.0} bottom={:.0}, hud={hud_visible})",
+        window_size.x, window_size.y, insets.top, insets.bottom
+    );
     let mut new_layout = compute_layout(window_size, safe_area_top, safe_area_bottom, hud_visible);
 
     // compute_layout sizes the fan for a worst-case column; refine it to the
@@ -394,11 +427,27 @@ fn on_window_resized(
         transform.translation.y = 0.0;
     }
 
-    for (marker, mut sprite, mut transform) in &mut markers {
+    for (marker, mut sprite, mut transform, children) in &mut markers {
         if let Some(pos) = new_layout.pile_positions.get(&marker.0) {
             sprite.custom_size = Some(new_layout.card_size);
             transform.translation.x = pos.x;
             transform.translation.y = pos.y;
+            // Children carry the outline frame and the "A"/"K" watermark.
+            // They are sized at spawn from that layout's card size, so they
+            // must be re-derived here too or a resize (fold/unfold, rotation)
+            // leaves them at the stale size — visible as oversized grey
+            // frames on empty piles.
+            let outline_size =
+                new_layout.card_size + Vec2::splat(PILE_MARKER_OUTLINE_WIDTH * 2.0);
+            let font_size = new_layout.card_size.x * 0.28;
+            for child in children.into_iter().flatten() {
+                if let Ok(mut outline) = marker_outlines.get_mut(*child) {
+                    outline.custom_size = Some(outline_size);
+                }
+                if let Ok(mut label) = marker_labels.get_mut(*child) {
+                    label.font_size = font_size;
+                }
+            }
         }
     }
 
@@ -544,31 +593,13 @@ fn pile_cards(
     }
 }
 
-const fn foundations() -> [Foundation; 4] {
-    [
-        Foundation::Foundation1,
-        Foundation::Foundation2,
-        Foundation::Foundation3,
-        Foundation::Foundation4,
-    ]
-}
 
-const fn tableaus() -> [Tableau; 7] {
-    [
-        Tableau::Tableau1,
-        Tableau::Tableau2,
-        Tableau::Tableau3,
-        Tableau::Tableau4,
-        Tableau::Tableau5,
-        Tableau::Tableau6,
-        Tableau::Tableau7,
-    ]
-}
 
 #[cfg(test)]
 mod tests {
     use super::*;
     use crate::game_plugin::GamePlugin;
+    use solitaire_core::{Foundation, Tableau};
 
     /// Minimal headless app — omits windowing so pile markers are spawned with
     /// the default 1280×800 layout and no camera is created.
@@ -623,6 +654,58 @@ mod tests {
         assert_eq!(types.len(), 12);
     }
 
+    #[test]
+    fn resize_updates_marker_outline_and_watermark_children() {
+        // Regression (found on Galaxy Fold 7, v0.41.0): `on_window_resized`
+        // resized the marker fill sprite but never its children, so after a
+        // fold/unfold the outline frame and "A"/"K" watermark stayed at
+        // spawn-time size — rendering as oversized grey slabs on empty piles.
+        let mut app = headless_app();
+        // Shrink the window well below the 1280×800 spawn default.
+        app.world_mut().write_message(WindowResized {
+            window: Entity::PLACEHOLDER,
+            width: 640.0,
+            height: 480.0,
+        });
+        app.update();
+
+        let card_size = app.world().resource::<LayoutResource>().0.card_size;
+        let expected_outline = card_size + Vec2::splat(PILE_MARKER_OUTLINE_WIDTH * 2.0);
+        let expected_font = card_size.x * 0.28;
+
+        let marker_children: Vec<Entity> = {
+            let mut q = app.world_mut().query::<(&PileMarker, &Children)>();
+            q.iter(app.world())
+                .flat_map(|(_, c)| c.iter().collect::<Vec<_>>())
+                .collect()
+        };
+        assert!(
+            !marker_children.is_empty(),
+            "pile markers must have outline/watermark children"
+        );
+        let mut outlines = 0;
+        let mut labels = 0;
+        for child in marker_children {
+            if let Some(sprite) = app.world().entity(child).get::<Sprite>() {
+                assert_eq!(
+                    sprite.custom_size,
+                    Some(expected_outline),
+                    "outline child must track the resized card size",
+                );
+                outlines += 1;
+            }
+            if let Some(font) = app.world().entity(child).get::<TextFont>() {
+                assert!(
+                    (font.font_size - expected_font).abs() < 0.01,
+                    "watermark font must track the resized card size",
+                );
+                labels += 1;
+            }
+        }
+        assert_eq!(outlines, 12, "all 12 markers carry an outline child");
+        assert!(labels >= 11, "tableau + foundation markers carry watermarks");
+    }
+
     #[test]
     fn pile_markers_hide_when_pile_is_occupied() {
         // After a fresh deal: the 7 tableau piles + the stock pile are
@@ -856,7 +939,7 @@ mod tests {
 
     #[test]
     fn suit_symbol_all_four_are_distinct() {
-        let symbols: Vec<&str> = [Suit::Spades, Suit::Hearts, Suit::Diamonds, Suit::Clubs]
+        let symbols: Vec<&str> = Suit::SUITS
             .iter()
             .map(suit_symbol)
             .collect();

solitaire_engine/src/theme/mod.rs

@@ -62,22 +62,10 @@ impl CardKey {
     /// Iterator over all 52 valid keys, in suit-major / rank-ascending order.
     /// Used to enumerate the manifest's required entries.
     pub fn all() -> impl Iterator<Item = CardKey> {
-        const SUITS: [Suit; 4] = [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades];
-        const RANKS: [Rank; 13] = [
-            Rank::Ace,
-            Rank::Two,
-            Rank::Three,
-            Rank::Four,
-            Rank::Five,
-            Rank::Six,
-            Rank::Seven,
-            Rank::Eight,
-            Rank::Nine,
-            Rank::Ten,
-            Rank::Jack,
-            Rank::Queen,
-            Rank::King,
-        ];
+        // Order-independent enumeration — consumers check completeness and
+        // round-trips, never positions.
+        const SUITS: [Suit; 4] = Suit::SUITS;
+        const RANKS: [Rank; 13] = Rank::RANKS;
         SUITS
             .into_iter()
             .flat_map(|s| RANKS.into_iter().map(move |r| CardKey::new(s, r)))

solitaire_engine/src/theme/plugin.rs

@@ -17,7 +17,7 @@ use solitaire_core::{Rank, Suit};
 use crate::assets::{
     bundled_theme_url, classic_theme_svg_bytes, dark_theme_svg_bytes, rasterize_svg, user_theme_dir,
 };
-use crate::card_plugin::CardImageSet;
+use crate::card_plugin::{CardImageSet, rank_index, suit_index};
 use crate::events::StateChangedEvent;
 
 use super::loader::CardThemeLoader;
@@ -242,22 +242,8 @@ fn sync_card_image_set_with_active_theme(
 /// `theme_back` when present, so writing here is sufficient to make
 /// every face-down card pick up the theme's art on the next sync.
 fn apply_theme_to_card_image_set(theme: &CardTheme, image_set: &mut CardImageSet) {
-    for suit in [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades] {
-        for rank in [
-            Rank::Ace,
-            Rank::Two,
-            Rank::Three,
-            Rank::Four,
-            Rank::Five,
-            Rank::Six,
-            Rank::Seven,
-            Rank::Eight,
-            Rank::Nine,
-            Rank::Ten,
-            Rank::Jack,
-            Rank::Queen,
-            Rank::King,
-        ] {
+    for suit in Suit::SUITS {
+        for rank in Rank::RANKS {
             if let Some(handle) = theme.faces.get(&CardKey::new(suit, rank)) {
                 image_set.faces[suit_index(suit)][rank_index(rank)] = handle.clone();
             }
@@ -266,36 +252,7 @@ fn apply_theme_to_card_image_set(theme: &CardTheme, image_set: &mut CardImageSet
     image_set.theme_back = Some(theme.back.clone());
 }
 
-/// Index used by [`CardImageSet::faces`] for a given suit. Mirrors
-/// the `card_plugin` doc comment: Clubs=0, Diamonds=1, Hearts=2, Spades=3.
-const fn suit_index(s: Suit) -> usize {
-    match s {
-        Suit::Clubs => 0,
-        Suit::Diamonds => 1,
-        Suit::Hearts => 2,
-        Suit::Spades => 3,
-    }
-}
 
-/// Index used by [`CardImageSet::faces`] for a given rank.
-/// Ace=0, Two=1 … King=12.
-const fn rank_index(r: Rank) -> usize {
-    match r {
-        Rank::Ace => 0,
-        Rank::Two => 1,
-        Rank::Three => 2,
-        Rank::Four => 3,
-        Rank::Five => 4,
-        Rank::Six => 5,
-        Rank::Seven => 6,
-        Rank::Eight => 7,
-        Rank::Nine => 8,
-        Rank::Ten => 9,
-        Rank::Jack => 10,
-        Rank::Queen => 11,
-        Rank::King => 12,
-    }
-}
 
 /// Switches the active theme to the one served at
 /// `themes://<theme_id>/theme.ron`. Returns the new `Handle<CardTheme>`
@@ -446,21 +403,17 @@ mod tests {
     }
 
     #[test]
-    fn suit_index_ranges_match_card_plugin_layout() {
-        assert_eq!(suit_index(Suit::Clubs), 0);
-        assert_eq!(suit_index(Suit::Diamonds), 1);
-        assert_eq!(suit_index(Suit::Hearts), 2);
-        assert_eq!(suit_index(Suit::Spades), 3);
+    fn suit_index_matches_upstream_suits_order() {
+        for (i, s) in Suit::SUITS.iter().enumerate() {
+            assert_eq!(suit_index(*s), i, "faces outer layout = Suit::SUITS order");
+        }
     }
 
     #[test]
-    fn rank_index_starts_at_ace_zero_and_ends_at_king_twelve() {
-        assert_eq!(rank_index(Rank::Ace), 0);
-        assert_eq!(rank_index(Rank::Two), 1);
-        assert_eq!(rank_index(Rank::Ten), 9);
-        assert_eq!(rank_index(Rank::Jack), 10);
-        assert_eq!(rank_index(Rank::Queen), 11);
-        assert_eq!(rank_index(Rank::King), 12);
+    fn rank_index_matches_upstream_ranks_order() {
+        for (i, r) in Rank::RANKS.iter().enumerate() {
+            assert_eq!(rank_index(*r), i, "faces inner layout = Rank::RANKS order");
+        }
     }
 
     #[test]

solitaire_engine/src/ui_focus.rs

@@ -117,6 +117,13 @@ pub struct FocusedButton(pub Option<Entity>);
 /// gains keyboard navigation without per-plugin wiring.
 pub struct UiFocusPlugin;
 
+/// Set on [`handle_focus_keys`], the focus-ring keyboard navigator. It runs
+/// AFTER every app-level keyboard consumer (HUD buttons/popovers, restore
+/// prompt, settings toggle) so Esc/Tab consumption order is defined instead
+/// of scheduler-dependent (#143).
+#[derive(bevy::ecs::schedule::SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
+pub struct FocusKeys;
+
 impl Plugin for UiFocusPlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<FocusedButton>()
@@ -147,9 +154,19 @@ impl Plugin for UiFocusPlugin {
                 (
                     sync_focus_on_mouse_click,
                     clear_hud_focus_on_unhover,
-                    handle_focus_keys,
-                    update_focus_overlay,
-                    pulse_focus_overlay,
+                    handle_focus_keys
+                        .in_set(FocusKeys)
+                        .after(crate::game_plugin::GameMutation),
+                    update_focus_overlay
+                        .in_set(crate::ui_theme::UiTextFx)
+                        .ambiguous_with(crate::ui_theme::UiTextFx)
+                        .ambiguous_with(crate::card_plugin::BoardVisuals)
+                        .ambiguous_with(crate::table_plugin::MarkerVisuals),
+                    pulse_focus_overlay
+                        .after(crate::settings_plugin::SettingsMutation)
+                        .in_set(crate::ui_theme::UiTextFx)
+                        .ambiguous_with(crate::ui_theme::UiTextFx)
+                        .ambiguous_with(crate::card_plugin::BoardVisuals),
                 )
                     .chain(),
             );

solitaire_engine/src/ui_modal.rs

@@ -695,7 +695,12 @@ impl Plugin for UiModalPlugin {
                 advance_modal_enter,
                 paint_modal_buttons,
             )
-                .chain(),
+                .chain()
+                .after(crate::settings_plugin::SettingsMutation)
+                .in_set(crate::ui_theme::UiTextFx)
+                .ambiguous_with(crate::ui_theme::UiTextFx)
+                .ambiguous_with(crate::card_plugin::BoardVisuals)
+                .ambiguous_with(crate::hud_plugin::HudButtons),
         );
         // Click-outside-to-dismiss is independent of the open
         // animation chain — it reads `just_pressed(Left)` and runs

solitaire_engine/src/ui_theme.rs

@@ -698,3 +698,12 @@ mod tests {
         assert_eq!(scaled_duration(0.18, AnimSpeed::Instant), 0.0);
     }
 }
+
+/// System set for text/UI visual effects that animate `Transform`/`Sprite`
+/// on chrome entities (HUD score pulse, streak flourish, modal enter, focus
+/// ring). These never touch board entities, so members are declared
+/// `.ambiguous_with(BoardVisuals)` and `.ambiguous_with(UiTextFx)` — the
+/// entity domains are disjoint by construction and relative order within a
+/// frame is invisible (#143).
+#[derive(bevy::ecs::schedule::SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
+pub struct UiTextFx;

solitaire_server/src/auth.rs

@@ -74,6 +74,15 @@ struct UserRow {
 /// bcrypt work factor. Cost 12 ≈ 300 ms on modern hardware — balances security against registration latency.
 pub const BCRYPT_COST: u32 = 12;
 
+/// Static bcrypt hash used to equalise login timing when the username does
+/// not exist (issue #139: user-enumeration timing oracle). Both login paths
+/// must pay the same bcrypt cost; this hash is verified against when there
+/// is no real one. Computed once at first use with the same [`BCRYPT_COST`]
+/// as real hashes. `None` only if bcrypt itself fails on a constant input —
+/// in that case the dummy verify is skipped rather than panicking.
+static DUMMY_PASSWORD_HASH: std::sync::LazyLock<Option<String>> =
+    std::sync::LazyLock::new(|| hash("ferrous-dummy-timing-pad", BCRYPT_COST).ok());
+
 async fn hash_password(password: String) -> Result<String, AppError> {
     tokio::task::spawn_blocking(move || hash(password, BCRYPT_COST))
         .await
@@ -208,6 +217,10 @@ pub async fn register(
     let password_hash = hash_password(body.password).await?;
     let now = Utc::now().to_rfc3339();
 
+    // The SELECT above is a friendly fast path; the UNIQUE constraint is the
+    // real arbiter. A concurrent registration that slips between the two
+    // surfaces as a unique violation here — map it to the same 409 the
+    // fast path produces instead of a raw 500 (issue #140).
     sqlx::query!(
         "INSERT INTO users (id, username, password_hash, created_at) VALUES (?, ?, ?, ?)",
         user_id,
@@ -216,7 +229,11 @@ pub async fn register(
         now
     )
     .execute(&state.pool)
-    .await?;
+    .await
+    .map_err(|e| match &e {
+        sqlx::Error::Database(db) if db.is_unique_violation() => AppError::UsernameTaken,
+        _ => AppError::from(e),
+    })?;
 
     let access_token = make_access_token(&user_id, &state.jwt_secret)?;
     let (refresh_token, refresh_jti) = make_refresh_token(&user_id, &state.jwt_secret)?;
@@ -242,7 +259,16 @@ pub async fn login(
     .fetch_optional(&state.pool)
     .await?;
 
-    let row = row.ok_or(AppError::InvalidCredentials)?;
+    let Some(row) = row else {
+        // Unknown username: burn a bcrypt verify against a static dummy hash
+        // so this path costs the same as a wrong-password attempt. Returning
+        // immediately here would let response timing reveal which usernames
+        // exist (issue #139).
+        if let Some(dummy) = DUMMY_PASSWORD_HASH.as_ref() {
+            let _ = verify_password(body.password, dummy.clone()).await;
+        }
+        return Err(AppError::InvalidCredentials);
+    };
     let row_id = row
         .id
         .ok_or_else(|| AppError::Internal("user id missing".into()))?;
@@ -283,23 +309,20 @@ pub async fn refresh(
     // Tokens without jti predate rotation — require re-login.
     let jti = claims.jti.ok_or(AppError::Unauthorized)?;
 
-    // Verify this jti is still live (not yet consumed or from a deleted account).
-    // SQLite TEXT columns are always nullable in sqlx; flatten the double-Option.
-    let exists: Option<String> =
-        sqlx::query_scalar!("SELECT jti FROM refresh_tokens WHERE jti = ?", jti)
-            .fetch_optional(&state.pool)
-            .await?
-            .flatten();
-
-    if exists.is_none() {
-        return Err(AppError::Unauthorized);
-    }
-
-    // Consume the old token before issuing new ones. If the insert below
-    // fails, the user loses this session (must re-login) — safe by design.
-    sqlx::query!("DELETE FROM refresh_tokens WHERE jti = ?", jti)
+    // Consume the old token before issuing new ones, gating on the DELETE
+    // actually removing a row. rows_affected == 0 covers both "jti never
+    // existed / account deleted" and "a concurrent refresh already consumed
+    // it" — the previous SELECT-then-DELETE let two concurrent refreshes
+    // both pass the check and both mint fresh token pairs. The DELETE is
+    // the mutex: whoever removes the row wins; everyone else gets 401.
+    // If the insert below fails, the user loses this session (must
+    // re-login) — safe by design.
+    let deleted = sqlx::query!("DELETE FROM refresh_tokens WHERE jti = ?", jti)
         .execute(&state.pool)
         .await?;
+    if deleted.rows_affected() != 1 {
+        return Err(AppError::Unauthorized);
+    }
 
     let new_access = make_access_token(&claims.sub, &state.jwt_secret)?;
     let (new_refresh, new_jti) = make_refresh_token(&claims.sub, &state.jwt_secret)?;
@@ -365,6 +388,22 @@ const AVATAR_MAX_BYTES: usize = 1024 * 1024;
 ///
 /// The `Content-Type` header must be one of `image/jpeg`, `image/png`,
 /// `image/webp`, or `image/gif`. The previous avatar file is replaced in-place.
+/// Returns `true` when `body` begins with the magic bytes of the image type
+/// implied by `ext` (the extension derived from the declared Content-Type).
+///
+/// Avatars are re-served under the stored extension, so the extension must be
+/// derived from the content itself — a client header is not evidence of what
+/// the bytes are (issue #141).
+fn magic_bytes_match(ext: &str, body: &[u8]) -> bool {
+    match ext {
+        "png" => body.starts_with(&[0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A]),
+        "jpg" => body.starts_with(&[0xFF, 0xD8, 0xFF]),
+        "gif" => body.starts_with(b"GIF87a") || body.starts_with(b"GIF89a"),
+        "webp" => body.len() >= 12 && body.starts_with(b"RIFF") && &body[8..12] == b"WEBP",
+        _ => false,
+    }
+}
+
 pub async fn upload_avatar(
     State(state): State<AppState>,
     user: AuthenticatedUser,
@@ -390,6 +429,14 @@ pub async fn upload_avatar(
     if body.len() > AVATAR_MAX_BYTES {
         return Err(AppError::BadRequest("avatar must be ≤ 1 MB".into()));
     }
+    // The stored extension decides how the file is re-served, so it must be
+    // backed by the bytes, not just the client's Content-Type header
+    // (issue #141).
+    if !magic_bytes_match(ext, &body) {
+        return Err(AppError::BadRequest(
+            "avatar bytes do not match the declared image type".into(),
+        ));
+    }
 
     // Write to avatars/ directory, replacing any previous file for this user.
     tokio::fs::create_dir_all("avatars")
@@ -590,6 +637,46 @@ mod tests {
         assert!(username_chars_ok(""));
     }
 
+    #[test]
+    fn magic_bytes_match_accepts_real_signatures() {
+        assert!(magic_bytes_match(
+            "png",
+            &[0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A, 0x00]
+        ));
+        assert!(magic_bytes_match("jpg", &[0xFF, 0xD8, 0xFF, 0xE0, 0x00]));
+        assert!(magic_bytes_match("gif", b"GIF89a\x00\x00"));
+        assert!(magic_bytes_match("gif", b"GIF87a\x00\x00"));
+        assert!(magic_bytes_match("webp", b"RIFF\x00\x00\x00\x00WEBPVP8 "));
+    }
+
+    #[test]
+    fn magic_bytes_match_rejects_mismatched_or_bogus_content() {
+        // HTML declared as PNG — the exact spoof the check exists to stop.
+        assert!(!magic_bytes_match("png", b"<html><script>"));
+        // Real PNG bytes declared as JPEG: extension must match the bytes.
+        assert!(!magic_bytes_match(
+            "jpg",
+            &[0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A]
+        ));
+        // Truncated / empty bodies never match.
+        assert!(!magic_bytes_match("png", &[0x89, b'P']));
+        assert!(!magic_bytes_match("webp", b"RIFF1234WEB"));
+        assert!(!magic_bytes_match("gif", b""));
+        // Unknown extensions are never accepted.
+        assert!(!magic_bytes_match("svg", b"<svg xmlns="));
+    }
+
+    #[test]
+    fn dummy_password_hash_is_available_and_verifiable() {
+        // The login timing pad (issue #139) must be a real bcrypt hash so the
+        // unknown-user path pays a genuine verify at BCRYPT_COST.
+        let dummy = DUMMY_PASSWORD_HASH
+            .as_ref()
+            .expect("bcrypt of a constant input must succeed");
+        assert!(verify("ferrous-dummy-timing-pad", dummy).unwrap_or(false));
+        assert!(!verify("wrong-password", dummy).unwrap_or(true));
+    }
+
     #[test]
     fn username_chars_ok_rejects_unicode_letters() {
         // Non-ASCII characters must be rejected even if they look like letters.

solitaire_server/src/sync.rs

@@ -5,7 +5,6 @@
 
 use axum::{Json, extract::State};
 use chrono::Utc;
-use sqlx::SqlitePool;
 use uuid::Uuid;
 
 use solitaire_sync::{
@@ -26,13 +25,19 @@ struct SyncRow {
 
 /// Load the stored `SyncPayload` for `user_id` from the database.
 /// Returns `None` if this user has not pushed any data yet.
-async fn load_sync_row(pool: &SqlitePool, user_id: &str) -> Result<Option<SyncRow>, AppError> {
+///
+/// Executor-generic so `push` can run it inside its transaction while
+/// `pull` keeps passing the pool directly.
+async fn load_sync_row(
+    exec: impl sqlx::Executor<'_, Database = sqlx::Sqlite>,
+    user_id: &str,
+) -> Result<Option<SyncRow>, AppError> {
     let row = sqlx::query_as!(
         SyncRow,
         "SELECT stats_json, achievements_json, progress_json FROM sync_state WHERE user_id = ?",
         user_id
     )
-    .fetch_optional(pool)
+    .fetch_optional(exec)
     .await?;
     Ok(row)
 }
@@ -69,7 +74,7 @@ fn row_to_payload(row: &SyncRow, user_id: &str) -> Result<SyncPayload, AppError>
 
 /// Persist a `SyncPayload` for `user_id` using an upsert.
 async fn store_payload(
-    pool: &SqlitePool,
+    exec: impl sqlx::Executor<'_, Database = sqlx::Sqlite>,
     user_id: &str,
     payload: &SyncPayload,
 ) -> Result<(), AppError> {
@@ -92,7 +97,7 @@ async fn store_payload(
         progress_json,
         now
     )
-    .execute(pool)
+    .execute(exec)
     .await?;
 
     Ok(())
@@ -159,12 +164,20 @@ pub async fn push(
         return Err(AppError::BadRequest("user_id mismatch".into()));
     }
 
-    let server_payload = match load_sync_row(&state.pool, &user.user_id).await? {
+    // The whole read-merge-write cycle runs in ONE transaction. Without it,
+    // two devices pushing concurrently both read the same stored payload,
+    // merge independently, and the second store overwrites the first merge —
+    // the server visibly regresses until the losing device pushes again.
+    // SQLite serialises writers, so the second transaction simply waits.
+    let mut tx = state.pool.begin().await?;
+
+    let server_payload = match load_sync_row(&mut *tx, &user.user_id).await? {
         Some(row) => row_to_payload(&row, &user.user_id)?,
         None => {
             // First push — nothing to merge against; store directly.
-            store_payload(&state.pool, &user.user_id, &client_payload).await?;
-            update_leaderboard_if_opted_in(&state.pool, &user.user_id, &client_payload).await?;
+            store_payload(&mut *tx, &user.user_id, &client_payload).await?;
+            update_leaderboard_if_opted_in(&mut tx, &user.user_id, &client_payload).await?;
+            tx.commit().await?;
             return Ok(Json(SyncResponse {
                 merged: client_payload,
                 server_time: Utc::now(),
@@ -175,8 +188,9 @@ pub async fn push(
 
     let (merged, conflicts) = merge(&client_payload, &server_payload);
 
-    store_payload(&state.pool, &user.user_id, &merged).await?;
-    update_leaderboard_if_opted_in(&state.pool, &user.user_id, &merged).await?;
+    store_payload(&mut *tx, &user.user_id, &merged).await?;
+    update_leaderboard_if_opted_in(&mut tx, &user.user_id, &merged).await?;
+    tx.commit().await?;
 
     Ok(Json(SyncResponse {
         merged,
@@ -188,16 +202,18 @@ pub async fn push(
 /// If the user is opted in to the leaderboard, update their row with the
 /// better of the stored and incoming `best_single_score` / `fastest_win_seconds`.
 ///
-/// The opt-in check and the update are performed atomically in a single
-/// conditional UPDATE (WHERE EXISTS subquery) to avoid a TOCTOU race where
-/// the user opts out between the check and the write.
+/// Runs on the caller's transaction connection, so the opt-in check and the
+/// update are atomic with the surrounding push — an opt-out between the check
+/// and the write can no longer interleave. (An earlier doc comment claimed
+/// this was a single conditional UPDATE; it has always been two statements —
+/// the enclosing transaction is what actually provides the atomicity.)
 async fn update_leaderboard_if_opted_in(
-    pool: &SqlitePool,
+    conn: &mut sqlx::SqliteConnection,
     user_id: &str,
     payload: &SyncPayload,
 ) -> Result<(), AppError> {
     let opted_in = sqlx::query!("SELECT leaderboard_opt_in FROM users WHERE id = ?", user_id)
-        .fetch_optional(pool)
+        .fetch_optional(&mut *conn)
         .await?
         .map(|r| r.leaderboard_opt_in)
         .unwrap_or(0);
@@ -231,7 +247,7 @@ async fn update_leaderboard_if_opted_in(
         now,
         user_id
     )
-    .execute(pool)
+    .execute(&mut *conn)
     .await?;
 
     Ok(())

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: 114857, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__hfb2e9a2f0bbd9ecc);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 61868, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__hd94d76233321402f);
             return ret;
         },
         __wbindgen_cast_0000000000000002: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 7311, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h26ff63c654218354);
             return ret;
         },
         __wbindgen_cast_0000000000000003: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("Array<any>"), NamedExternref("ResizeObserver")], shim_idx: 9843, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h876550298b312ff8);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("Array<any>"), NamedExternref("ResizeObserver")], shim_idx: 7314, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__hfc779804ccb0943e);
             return ret;
         },
         __wbindgen_cast_0000000000000004: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("Array<any>")], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_3);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("Array<any>")], shim_idx: 7311, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h26ff63c654218354_3);
             return ret;
         },
         __wbindgen_cast_0000000000000005: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("Event")], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_4);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("Event")], shim_idx: 7311, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h26ff63c654218354_4);
             return ret;
         },
         __wbindgen_cast_0000000000000006: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("FocusEvent")], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_5);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("FocusEvent")], shim_idx: 7311, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h26ff63c654218354_5);
             return ret;
         },
         __wbindgen_cast_0000000000000007: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("KeyboardEvent")], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_6);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("KeyboardEvent")], shim_idx: 7311, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h26ff63c654218354_6);
             return ret;
         },
         __wbindgen_cast_0000000000000008: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("PageTransitionEvent")], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_7);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("PageTransitionEvent")], shim_idx: 7311, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h26ff63c654218354_7);
             return ret;
         },
         __wbindgen_cast_0000000000000009: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("PointerEvent")], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_8);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("PointerEvent")], shim_idx: 7311, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h26ff63c654218354_8);
             return ret;
         },
         __wbindgen_cast_000000000000000a: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("WheelEvent")], shim_idx: 9830, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h15aa57dbc666225a_9);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("WheelEvent")], shim_idx: 7311, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h26ff63c654218354_9);
             return ret;
         },
         __wbindgen_cast_000000000000000b: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Option(NamedExternref("Blob"))], shim_idx: 9840, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h657f46feffff6fe4);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Option(NamedExternref("Blob"))], shim_idx: 7312, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__hfd77696cd35180b1);
             return ret;
         },
         __wbindgen_cast_000000000000000c: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [], shim_idx: 9834, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__h545edb23183e448a);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [], shim_idx: 7313, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm_bindgen__convert__closures_____invoke__hebcd362fbbe0fc8c);
             return ret;
         },
         __wbindgen_cast_000000000000000d: function(arg0) {
@@ -1769,55 +1769,55 @@ function __wbg_get_imports() {
     };
 }
 
-function wasm_bindgen__convert__closures_____invoke__h545edb23183e448a(arg0, arg1) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h545edb23183e448a(arg0, arg1);
+function wasm_bindgen__convert__closures_____invoke__hebcd362fbbe0fc8c(arg0, arg1) {
+    wasm.wasm_bindgen__convert__closures_____invoke__hebcd362fbbe0fc8c(arg0, arg1);
 }
 
-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__h26ff63c654218354(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h26ff63c654218354(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__h26ff63c654218354_3(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h26ff63c654218354_3(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__h26ff63c654218354_4(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h26ff63c654218354_4(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__h26ff63c654218354_5(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h26ff63c654218354_5(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__h26ff63c654218354_6(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h26ff63c654218354_6(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__h26ff63c654218354_7(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h26ff63c654218354_7(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__h26ff63c654218354_8(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h26ff63c654218354_8(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__h26ff63c654218354_9(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h26ff63c654218354_9(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);
+function wasm_bindgen__convert__closures_____invoke__hd94d76233321402f(arg0, arg1, arg2) {
+    const ret = wasm.wasm_bindgen__convert__closures_____invoke__hd94d76233321402f(arg0, arg1, arg2);
     if (ret[1]) {
         throw takeFromExternrefTable0(ret[0]);
     }
 }
 
-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__hfc779804ccb0943e(arg0, arg1, arg2, arg3) {
+    wasm.wasm_bindgen__convert__closures_____invoke__hfc779804ccb0943e(arg0, arg1, arg2, arg3);
 }
 
-function wasm_bindgen__convert__closures_____invoke__h657f46feffff6fe4(arg0, arg1, arg2) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h657f46feffff6fe4(arg0, arg1, isLikeNone(arg2) ? 0 : addToExternrefTable0(arg2));
+function wasm_bindgen__convert__closures_____invoke__hfd77696cd35180b1(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__hfd77696cd35180b1(arg0, arg1, isLikeNone(arg2) ? 0 : addToExternrefTable0(arg2));
 }
 
 

solitaire_wasm/src/lib.rs

@@ -19,7 +19,7 @@
 //! is the contract.
 
 use chrono::NaiveDate;
-use solitaire_core::{Foundation, KlondikeInstruction, KlondikePile, Tableau};
+use solitaire_core::{KlondikeInstruction, KlondikePile};
 use serde::{Deserialize, Serialize};
 use solitaire_core::{Card, Deck, Rank, Suit};
 use solitaire_core::error::MoveError;
@@ -145,21 +145,10 @@ impl ReplayPlayer {
         let pile_cards = |t: KlondikePile| -> Vec<CardSnapshot> {
             self.game.pile(t).iter().map(CardSnapshot::from).collect()
         };
-        let foundations: [Vec<CardSnapshot>; 4] = [
-            pile_cards(KlondikePile::Foundation(Foundation::Foundation1)),
-            pile_cards(KlondikePile::Foundation(Foundation::Foundation2)),
-            pile_cards(KlondikePile::Foundation(Foundation::Foundation3)),
-            pile_cards(KlondikePile::Foundation(Foundation::Foundation4)),
-        ];
-        let tableaus: [Vec<CardSnapshot>; 7] = [
-            pile_cards(KlondikePile::Tableau(Tableau::Tableau1)),
-            pile_cards(KlondikePile::Tableau(Tableau::Tableau2)),
-            pile_cards(KlondikePile::Tableau(Tableau::Tableau3)),
-            pile_cards(KlondikePile::Tableau(Tableau::Tableau4)),
-            pile_cards(KlondikePile::Tableau(Tableau::Tableau5)),
-            pile_cards(KlondikePile::Tableau(Tableau::Tableau6)),
-            pile_cards(KlondikePile::Tableau(Tableau::Tableau7)),
-        ];
+        let foundations: [Vec<CardSnapshot>; 4] = solitaire_core::FOUNDATIONS
+            .map(|f| pile_cards(KlondikePile::Foundation(f)));
+        let tableaus: [Vec<CardSnapshot>; 7] =
+            solitaire_core::TABLEAUS.map(|t| pile_cards(KlondikePile::Tableau(t)));
         StateSnapshot {
             step_idx: self.step_idx,
             total_steps: self.moves.len(),
@@ -353,21 +342,9 @@ fn legal_moves_for_game(game: &GameState) -> Vec<DebugMove> {
 fn invariant_report_for_game(game: &GameState, legal_moves: &[DebugMove]) -> DebugInvariantReport {
     let stock = game.stock_cards();
     let waste = game.waste_cards();
-    let foundations = [
-        game.pile(KlondikePile::Foundation(Foundation::Foundation1)),
-        game.pile(KlondikePile::Foundation(Foundation::Foundation2)),
-        game.pile(KlondikePile::Foundation(Foundation::Foundation3)),
-        game.pile(KlondikePile::Foundation(Foundation::Foundation4)),
-    ];
-    let tableaus = [
-        game.pile(KlondikePile::Tableau(Tableau::Tableau1)),
-        game.pile(KlondikePile::Tableau(Tableau::Tableau2)),
-        game.pile(KlondikePile::Tableau(Tableau::Tableau3)),
-        game.pile(KlondikePile::Tableau(Tableau::Tableau4)),
-        game.pile(KlondikePile::Tableau(Tableau::Tableau5)),
-        game.pile(KlondikePile::Tableau(Tableau::Tableau6)),
-        game.pile(KlondikePile::Tableau(Tableau::Tableau7)),
-    ];
+    let foundations =
+        solitaire_core::FOUNDATIONS.map(|f| game.pile(KlondikePile::Foundation(f)));
+    let tableaus = solitaire_core::TABLEAUS.map(|t| game.pile(KlondikePile::Tableau(t)));
 
     let mut seen: std::collections::HashSet<Card> = std::collections::HashSet::new();
     let mut duplicate_cards = Vec::new();
@@ -488,21 +465,9 @@ impl SolitaireGame {
                 .iter()
                 .map(CardSnapshot::from)
                 .collect(),
-            foundations: [
-                cards(KlondikePile::Foundation(Foundation::Foundation1)),
-                cards(KlondikePile::Foundation(Foundation::Foundation2)),
-                cards(KlondikePile::Foundation(Foundation::Foundation3)),
-                cards(KlondikePile::Foundation(Foundation::Foundation4)),
-            ],
-            tableaus: [
-                cards(KlondikePile::Tableau(Tableau::Tableau1)),
-                cards(KlondikePile::Tableau(Tableau::Tableau2)),
-                cards(KlondikePile::Tableau(Tableau::Tableau3)),
-                cards(KlondikePile::Tableau(Tableau::Tableau4)),
-                cards(KlondikePile::Tableau(Tableau::Tableau5)),
-                cards(KlondikePile::Tableau(Tableau::Tableau6)),
-                cards(KlondikePile::Tableau(Tableau::Tableau7)),
-            ],
+            foundations: solitaire_core::FOUNDATIONS
+                .map(|f| cards(KlondikePile::Foundation(f))),
+            tableaus: solitaire_core::TABLEAUS.map(|t| cards(KlondikePile::Tableau(t))),
         }
     }
 
@@ -513,34 +478,21 @@ impl SolitaireGame {
                 let slot: u8 = s["foundation-".len()..]
                     .parse()
                     .map_err(|_| format!("bad pile: {s}"))?;
-                if slot >= 4 {
-                    return Err(format!("foundation slot out of range: {slot}"));
-                }
-                Ok(KlondikePile::Foundation(match slot {
-                    0 => Foundation::Foundation1,
-                    1 => Foundation::Foundation2,
-                    2 => Foundation::Foundation3,
-                    3 => Foundation::Foundation4,
-                    _ => return Err(format!("foundation slot out of range: {slot}")),
-                }))
+                let foundation = solitaire_core::FOUNDATIONS
+                    .get(slot as usize)
+                    .copied()
+                    .ok_or_else(|| format!("foundation slot out of range: {slot}"))?;
+                Ok(KlondikePile::Foundation(foundation))
             }
             _ if s.starts_with("tableau-") => {
                 let col: usize = s["tableau-".len()..]
                     .parse()
                     .map_err(|_| format!("bad pile: {s}"))?;
-                if col >= 7 {
-                    return Err(format!("tableau col out of range: {col}"));
-                }
-                Ok(KlondikePile::Tableau(match col {
-                    0 => Tableau::Tableau1,
-                    1 => Tableau::Tableau2,
-                    2 => Tableau::Tableau3,
-                    3 => Tableau::Tableau4,
-                    4 => Tableau::Tableau5,
-                    5 => Tableau::Tableau6,
-                    6 => Tableau::Tableau7,
-                    _ => return Err(format!("tableau col out of range: {col}")),
-                }))
+                let tableau = solitaire_core::TABLEAUS
+                    .get(col)
+                    .copied()
+                    .ok_or_else(|| format!("tableau col out of range: {col}"))?;
+                Ok(KlondikePile::Tableau(tableau))
             }
             _ => Err(format!("unknown pile: {s}")),
         }