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

docs(changelog): cut v0.41.0 section
Renames Unreleased to 0.41.0 (2026-07-06), noting it consolidates the v0.40.x patch tags that were cut without sectioning. Adds entries for today's safe-area resume re-poll fix (#116) and the plugin module test-split phase (#118). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-06 20:27:43 +00:00 · 2026-07-06 13:27:42 -07:00 · 2026-07-06 20:20:10 +00:00 · 2026-07-06 13:19:56 -07:00 · 2026-07-06 20:16:55 +00:00 · 2026-07-06 13:16:21 -07:00
153 changed files with 25830 additions and 20195 deletions
@@ -0,0 +1,5 @@
+[registries.Quaternions]
+index = "sparse+https://git.aleshym.co/api/packages/Quaternions/cargo/"
+
+[target.wasm32-unknown-unknown]
+rustflags = ['--cfg', 'getrandom_backend="wasm_js"']
@@ -6,10 +6,14 @@ on:
    branches: [master]
    paths:
      - 'solitaire_server/**'
+      - 'solitaire_wasm/**'
+      - 'solitaire_web/**'
      - 'solitaire_sync/**'
      - 'solitaire_core/**'
+      - 'solitaire_engine/**'
      - 'Cargo.toml'
      - 'Cargo.lock'
+      - 'solitaire_server/Dockerfile'
      - '.gitea/workflows/docker-build.yml'

 env:
@@ -32,6 +36,13 @@ jobs:
        id: meta
        run: echo "sha=${GITHUB_SHA::8}" >> "$GITHUB_OUTPUT"

+      # WASM artifact freshness is owned by the `web-wasm-rebuild` workflow,
+      # which rebuilds pkg/ in CI on every master change to a wasm-feeding crate
+      # and commits it back (CI is the single source of truth — the artifacts
+      # aren't byte-reproducible on contributor machines). That pkg/ commit then
+      # triggers this workflow, so the deployed image always ships fresh wasm.
+      # No drift check is needed here.
+
      - name: Log in to Gitea registry
        uses: docker/login-action@v3
        with:
@@ -0,0 +1,62 @@
+name: Web E2E
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'solitaire_server/web/**'
+      - 'solitaire_server/src/**'
+      - 'solitaire_server/e2e/**'
+      - 'solitaire_wasm/**'
+      - 'solitaire_core/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - '.gitea/workflows/web-e2e.yml'
+  workflow_dispatch:
+
+jobs:
+  web-e2e:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo build
+        uses: Swatinem/rust-cache@v2
+
+      # Prebuild the server so Playwright's `webServer` (which runs
+      # `cargo run -p solitaire_server`) starts from a compiled binary instead
+      # of cold-compiling the whole dependency graph (axum/sqlx/reqwest) inside
+      # its 120s startup window — the timeout that was failing every run.
+      # SQLX_OFFLINE uses the checked-in `.sqlx/` query cache (no live DB).
+      - name: Prebuild server
+        env:
+          SQLX_OFFLINE: 'true'
+        run: cargo build -p solitaire_server --quiet
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: solitaire_server/e2e/package-lock.json
+
+      - name: Install e2e dependencies
+        working-directory: solitaire_server/e2e
+        run: npm ci
+
+      - name: Install Playwright browser
+        working-directory: solitaire_server/e2e
+        run: npx playwright install --with-deps chromium
+
+      - name: Run web e2e tests
+        working-directory: solitaire_server/e2e
+        run: npm test
+
+      - name: Run cycle regression gate
+        working-directory: solitaire_server/e2e
+        run: npm run review:cycles:regression
@@ -0,0 +1,89 @@
+name: Web WASM Rebuild
+
+# CI is the single source of truth for solitaire_server/web/pkg/.
+#
+# The wasm artifacts cannot be reproduced byte-for-byte on an arbitrary
+# contributor machine: even with identical rustc 1.95.0 / LLVM 22.1.2, the same
+# flags, the same Cargo.lock and remapped source paths, the output still differs
+# by host environment. So rather than police freshness with a rebuild-and-diff
+# gate (which false-failed for exactly that reason), CI rebuilds the artifacts
+# itself on every master change to a wasm-feeding crate and commits them back.
+#
+# Result: the deployed pkg/ can't silently rot, and contributors never need to
+# run build_wasm.sh by hand. The commit touches only pkg/, which is not in this
+# workflow's trigger paths (so it does not re-trigger here) but does match
+# docker-build's, so the refreshed wasm deploys.
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'solitaire_core/**'
+      - 'solitaire_engine/**'
+      - 'solitaire_data/**'
+      - 'solitaire_sync/**'
+      - 'solitaire_wasm/**'
+      - 'solitaire_web/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - 'build_wasm.sh'
+      - '.gitea/workflows/web-wasm-rebuild.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: web-wasm-rebuild
+  cancel-in-progress: false
+
+jobs:
+  rebuild:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.CI_TOKEN }}
+
+      - name: Install Rust 1.95.0
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.95.0
+          targets: wasm32-unknown-unknown
+
+      - name: Cache cargo build
+        uses: Swatinem/rust-cache@v2
+
+      - name: Install wasm-bindgen-cli + wasm-pack (pinned)
+        uses: taiki-e/install-action@v2
+        with:
+          tool: wasm-bindgen-cli@0.2.120,wasm-pack@0.14.0
+
+      - name: Install binaryen 130 (wasm-opt, pinned)
+        run: |
+          set -euo pipefail
+          curl -sSL \
+            https://github.com/WebAssembly/binaryen/releases/download/version_130/binaryen-version_130-x86_64-linux.tar.gz \
+            | tar xz
+          echo "$PWD/binaryen-version_130/bin" >> "$GITHUB_PATH"
+
+      - name: Rebuild WASM artifacts
+        run: ./build_wasm.sh
+
+      - name: Commit refreshed artifacts if changed
+        run: |
+          set -euo pipefail
+          if git diff --quiet -- solitaire_server/web/pkg/; then
+            echo "pkg/ already up to date — nothing to commit."
+            exit 0
+          fi
+          git config user.email "ci@gitea.local"
+          git config user.name "Gitea CI"
+          git add solitaire_server/web/pkg/
+          git commit -m "chore(web): regenerate wasm artifacts"
+          # master is unprotected; retry once if the tip moved under us.
+          git push origin HEAD:master || {
+            git fetch origin master
+            git rebase origin/master
+            git push origin HEAD:master
+          }
@@ -15,6 +15,11 @@ agentdb.rvf.lock
 # IDE project files
 .idea/

+# Browser e2e harness artifacts
+solitaire_server/e2e/node_modules/
+solitaire_server/e2e/playwright-report/
+solitaire_server/e2e/test-results/
+
 # Android signing keystores — never commit
 *.jks
 *.jks.bak
@@ -25,3 +30,14 @@ agentdb.rvf.lock
 deploy/matomo-secret.yaml
 deploy/*-secret.yaml
 deploy/*-auth-secret.yaml
+
+# Local agent-tooling artifacts (Codex / claude-flow) — keep out of the repo
+/.agents/
+/.codex/
+/AGENTS.md
+# claude-flow scratch dirs, anywhere in the tree (e.g. solitaire_engine/src/)
+.claude-flow/
+
+# Local token-saving helper scripts (peek/cargoclip/testfail/diffclip/etc.) —
+# inspection-only Go tools, not committed. Tracked scripts/*.sh and *.md stay.
+scripts/*.go
@@ -109,6 +109,18 @@ Owns:
 - Achievement unlock condition evaluation
 - Seeded RNG for reproducible deals

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

@@ -6,6 +6,320 @@ project follows [Semantic Versioning](https://semver.org/).

 ## [Unreleased]

+## [0.41.0] — 2026-07-06
+
+> Consolidates everything shipped since v0.39.0, including the v0.40.0–v0.40.3
+> patch tags (which were cut from this section without renaming it at the time).
+
+### Added
+
+- **Rules decision record: unlimited stock recycling.** Documented in
+  `ARCHITECTURE.md` that unlimited recycling with score penalties (matching
+  mainstream digital solitaire) is intentional, and locked it in with a core
+  test — the difficulty seed catalog and winnable-deal solver are verified
+  under this rule. Resolves the last open finding from the June 500-game
+  audit (issue #117).
+- **Analytics validation runbook.** Documented native Matomo live validation,
+  expected event payloads, and the current web/WASM analytics split.
+- **Android smoke-test runbook.** Updated the Android doc with the current
+  platform status, support matrix, and a physical-device
+  launch/touch/safe-area checklist.
+- **Browser Bevy canvas route and automation support.** Added the `solitaire_web`
+  Bevy WASM build, wired `/play` to the Bevy canvas, added a
+  `window.__FERROUS_DEBUG__` bridge, and introduced Playwright coverage for the
+  web routes and interactive canvas behavior.
+- **Card-game / klondike integration.** Began replacing in-house card and pile
+  internals with upstream `card_game` / `klondike` types, including adapter
+  work, GameMode-aware scoring, upstream instruction serde, `KlondikePile`
+  migration, and documentation for the in-place rewrite phases.
+- **Android keystore integration.** Added Android Keystore JNI wiring via
+  `OnceLock` and improved Android token handling around the app directory.
+
+### Changed
+
+- **Engine plugin modules restructured.** The five oversized plugin files
+  (card, hud, settings, game, input) are now module directories with their
+  test suites in sibling `tests.rs` files — no behaviour change; first phase
+  of the module-split plan (#118).
+- **Core type ownership.** Routed all klondike/card imports through
+  `solitaire_core` and unified local `Suit` / `Rank` with upstream `card_game`
+  types.
+- **Web/WASM build reliability.** Rebuilt WASM packages, cleaned up wasm32 build
+  warnings, added a Binaryen `wasm-opt` pass, pinned upstream git dependencies,
+  and added a CI guard for canvas WASM drift.
+- **Difficulty seed catalog.** Regenerated the difficulty seed list for the
+  latest verified catalog.
+
+### Fixed
+
+- **Safe-area insets now re-polled after app resume.** The inset poller settled
+  permanently once insets first resolved, so inset changes while backgrounded
+  (fold/unfold, rotation, gesture ↔ 3-button nav switch) kept stale layout until
+  the app was killed. Each resume now re-arms a fresh poll window; the cached
+  value is rewritten only when it actually changed, so unchanged resumes still
+  cause no relayout flash. (#116)
+- **Tableau fill on foldables / tall screens.** The tableau fan now spreads from
+  each column's total depth (face-down cards included) and refills on the
+  cold-start deal, every move, and on resize (incl. the Android safe-area-inset
+  resize and fold/unfold), so a near-square viewport such as an unfolded Galaxy
+  Fold no longer leaves the bottom of the screen empty. The fan spread cap was
+  raised so very tall / narrow viewports (e.g. a foldable cover screen) fill
+  further.
+- **Card-move animation jank.** A move now rebuilds a card's child visuals only
+  when its appearance changes (flip / resize / accessibility) instead of
+  despawning and respawning every card's children each `StateChangedEvent`,
+  removing the per-move spike that stuttered the slide animation on
+  high-resolution devices.
+- **Android and modal safe-area layout.** Modal cards now center within the
+  usable area between status and gesture bars, additional modal-spawn guards were
+  added, and Android build scripts now auto-discover SDK/NDK paths and strip
+  native libraries.
+- **Core scoring and undo correctness.** Fixed recycle-count drift, undo score
+  compounding, foundation-to-tableau instruction coverage, and several
+  illegal-move paths discovered during the card-game migration.
+- **Input and rendering issues.** Fixed stock/waste hit testing, accepted waste
+  clicks, delayed first-run onboarding until splash teardown, and kept dragged
+  stacks above all piles.
+- **Draw-Three waste fan hit testing on Android.** The renderer and the click
+  hit-test now share a single `waste_fan_step` / `tableau_col_step` source. They
+  previously diverged under Android's tighter column spacing, shifting the top
+  fanned waste card's hit target onto the card beneath it, so dragging the visible
+  card played the wrong one.
+- **Web runtime stability.** Fixed wasm32 runtime panics, HiDPI canvas surface
+  sizing, WebGL2 shader compatibility, and Firefox boot/render behavior.
+- **Server and data hardening.** Moved bcrypt work to `spawn_blocking`, switched
+  file paths to async I/O where needed, and validated `JWT_SECRET` at startup.
+- **CI and deployment workflow.** Fixed deploy-branch handling, Docker registry
+  secret usage, and related release automation issues.
+
+### Tests
+
+- Ran an Android AVD `Pixel_7` launch smoke for the x86_64 debug APK,
+  including install, NativeActivity launch, safe-area log validation, screenshot
+  render check, onboarding input, and crash-log review.
+- Added direct coverage for Android/touch card corner labels using Unicode suit
+  glyphs.
+- Added schema-v3 persistence round-trip coverage, foundation-to-tableau
+  instruction coverage, expanded WASM unit tests, and Playwright E2E specs for
+  browser routes and game-canvas behavior.
+
+## [0.39.0] — 2026-05-19
+
+### Fixed
+
+- **No-legal-moves detection and banner.** Corrected no-move detection across
+  engine, WASM, and web paths, then surfaced the state to players with an
+  in-game banner instead of silently leaving the board stuck.
+- **Release/deploy automation.** Updated deployment automation so kustomization
+  changes are pushed to the deploy branch instead of the main development
+  branch.
+
+## [0.38.0] — 2026-05-19
+
+### Added
+
+- **Klondike scoring parity.** Added tableau flip bonuses and stock recycle
+  penalties to align scoring with standard Klondike expectations.
+
+### Fixed
+
+- **Core rule enforcement.** Auto-complete now requires an empty waste pile,
+  waste-origin moves reject multi-card transfers, foundation-to-foundation moves
+  are blocked, and undo restores score from the snapshot baseline.
+- **Modal lifecycle guards.** Added missing `ModalScrim` guards to New Game,
+  restore prompt, and no-moves modal spawn sites.
+- **Runtime and server robustness.** Tokio runtime setup degrades gracefully
+  instead of panicking; web replay submission casing/date formatting now matches
+  server expectations; avatar routes are publicly reachable when intended.
+- **Android token and sync merge correctness.** Android tokens are namespaced
+  under the application directory, stored per user, and migrated safely; sync
+  merges preserve draw-one / draw-three win invariants.
+
+## [0.37.0] — 2026-05-19
+
+### Fixed
+
+- **Foundation-to-tableau default.** Made `take_from_foundation` default to true
+  across clients so restored, startup, and web games use the same supported move
+  rules.
+
+## [0.36.12] — 2026-05-19
+
+### Fixed
+
+- **Foundation-to-tableau default.** Set `take_from_foundation` true by default
+  in core so every client inherits the intended house rule without special-case
+  setup.
+
+## [0.36.11] — 2026-05-19
+
+### Fixed
+
+- **Web foundation moves.** Enabled take-from-foundation moves in the web game
+  client.
+
+## [0.36.10] — 2026-05-19
+
+### Added
+
+- **Web resume flow.** Browser games now persist state across page refreshes and
+  can resume through a dialog instead of starting over.
+
+## [0.36.9] — 2026-05-19
+
+### Fixed
+
+- **Settings sync connection flow.** Clicking Connect from Settings now opens the
+  sync-setup modal.
+
+## [0.36.8] — 2026-05-19
+
+### Fixed
+
+- **Restored/startup foundation moves.** Enabled take-from-foundation behavior
+  for restored and startup games, not only newly-created sessions.
+
+## [0.36.7] — 2026-05-19
+
+### Fixed
+
+- **Remaining Android UI issues.** Resolved the final Android UI defects from
+  the review pass, including action-bar/tableau interaction and safe visual
+  spacing.
+
+## [0.36.6] — 2026-05-19
+
+### Fixed
+
+- **Action-bar layout reservation.** Reserved action-bar height in layout so
+  tableau columns do not extend behind bottom controls.
+
+## [0.36.5] — 2026-05-19
+
+### Added
+
+- **Responsive Android action-bar glyphs.** Action-bar glyph font size now scales
+  dynamically on Android to fit available space.
+
+## [0.36.4] — 2026-05-19
+
+### Fixed
+
+- **Classic card labels and HUD overlap.** Corrected classic-card corner-label
+  colors and fixed HUD-band overlap in the Android layout.
+
+## [0.36.3] — 2026-05-19
+
+### Fixed
+
+- **Core, animation, and modal review fixes.** Added the foundation-to-tableau
+  score penalty, hardened solver win validation, guarded zero-duration card
+  animations, aligned initial and dynamic tableau fan spacing, and added missing
+  modal guards for play-by-seed and win-summary paths.
+- **Pause, messages, credentials, and server validation.** Auto-complete respects
+  pause state, standalone plugins register their events, sync passwords are
+  cleared from ECS buffers after auth task spawn, and avatar MIME validation uses
+  exact matches.
+- **Foundation pile rendering.** Raised stack fan z-order above corner labels to
+  prevent bleed-through.
+- **Android release workflow.** Added a manual `workflow_dispatch` trigger to
+  the Android release workflow.
+
+## [0.36.2] — 2026-05-19
+
+### Fixed
+
+- **Comprehensive review fixes.** Addressed 26 issues across core rules, replay
+  controls, modal guards, sync payload timing, server replay casing, time-attack
+  overlays, theme refresh, auth overlays, stats ordering, animations, cursor
+  fallbacks, achievements, server temp-file cleanup, and runtime fallback paths.
+- **Animation and Android label polish.** Cancelled stale win-cascade animations
+  on new game, refreshed Android corner labels on resize, lifted animating cards
+  above lower z-layers, and froze the web timer when auto-complete starts.
+- **Web package and tooling updates.** Rebuilt the WASM package for
+  foundation-to-tableau moves, added ruflo scaffolding, and ignored ruflo runtime
+  state files.
+- **Leaderboard test stability.** Made opt-in / opt-out tests robust under
+  parallel test execution.
+
+## [0.36.1] — 2026-05-18
+
+### Fixed
+
+- **Android HUD gesture conflict.** Stock taps no longer toggle HUD visibility on
+  Android.
+
+## [0.36.0] — 2026-05-18
+
+### Changed
+
+- **Rank model cleanup.** `Rank` now uses explicit discriminants and checked
+  arithmetic, making rank conversions and sequencing more robust.
+- **Instruction generation.** Refined `possible_instructions` alongside the rank
+  arithmetic cleanup.
+- **Session handoff.** Recreated `SESSION_HANDOFF.md` to reflect the `0.35.1`
+  state.
+
+## [0.35.1] — 2026-05-17
+
+### Fixed
+
+- **Leaderboard profile sync.** Fixed three leaderboard/profile issues: wrong
+  toast type for failures, stale display-name label after update, and display
+  name not syncing to the server.
+
+## [0.35.0] — 2026-05-17
+
+### Added
+
+- **Reduced-motion support.** Decorative motion animations are now gated behind
+  `reduce_motion_mode`.
+
+### Changed
+
+- **Performance and runtime cleanup.** Shared a single Tokio runtime across
+  network tasks and gated frame-hot ECS systems on resource changes.
+- **Core/data refactors.** Consolidated the application directory name, added
+  `#[must_use]` to pure helpers, derived `Copy` for `DrawMode`, removed
+  redundant clones, added missing derives to `AchievementContext`, and used
+  saturating move-count arithmetic.
+- **HUD z-layer naming.** Replaced raw HUD popover z-index arithmetic with named
+  layer constants.
+
+### Fixed
+
+- **Android UI and font safety.** Wired FiraMono to stock-empty labels, removed
+  raw physical safe-area pixels from HUD spawns, replaced unsupported chevrons,
+  corrected the Android help hint label, and fixed touch/drop-zone behavior.
+- **Engine modal and panic hardening.** Eliminated several runtime panics, added
+  required transforms to modal scrims, constrained dismiss hit-tests, and guarded
+  home overlay respawns.
+- **Sync/data/server correctness.** Deterministic pile serialization, undo skip
+  handling, byte URL encoding, merge timestamp handling, auth-guarded avatar
+  serving, atomic server writes, and user-id assertions were corrected.
+- **Display-name and token-file boundaries.** Enforced the 32-character display
+  name limit in the sync client and aligned Android keystore temp-file cleanup
+  with the cleanup glob.
+- **WASM error reporting.** `state()` and `step()` now return `Result` so errors
+  surface as JavaScript exceptions.
+- **Sync and leaderboard toasts.** Pull failures and leaderboard opt-in /
+  opt-out failures now produce the intended warning/error feedback.
+
+### Documentation
+
+- Corrected stale focus-ring color documentation.
+
+## [0.34.0] — 2026-05-17
+
+### Fixed
+
+- **Android waste fan and resume layout.** Corrected Android waste-pile fan
+  overlap and a layout desynchronization after resume.
+- **Card-face artwork.** Fixed the wrong bottom-right suit symbol on the jack,
+  queen, and king of spades.
+- **Android corner-label font coverage.** Wired FiraMono into Android corner
+  labels and added `CardImageSet` tests to guard the asset path behavior.
+
 ## [0.33.0] — 2026-05-16

 ### Fixed
@@ -208,9 +208,14 @@ Embed via `include_bytes!()` only when ALL of the following are true:
 Currently embedded:
 * **Audio** — all `.wav` files in `audio_plugin.rs`
 * **Default card theme** — shipped via `embedded://` scheme in `ThemePlugin`
+* **Bundled UI font** — `assets/fonts/main.ttf` (FiraMono) via `include_bytes!`
+  in `font_plugin.rs` and `assets/svg_loader.rs`; it is the canonical UI face
+  and must always be present, so it is embedded rather than `AssetServer`-loaded

-Do NOT embed card face PNGs, background images, or user fonts —
-these are loaded via `AssetServer` so art can be swapped without recompile.
+Do NOT embed card face PNGs or background images — these are loaded via
+`AssetServer` so art can be swapped without recompile. User-supplied fonts
+(if ever added) likewise go through `AssetServer`; only the bundled FiraMono
+face above is embedded.

 ---

@@ -430,9 +435,11 @@ explicitly replacing the current one (despawn first, then spawn).

 ## 14.3 Safe area

-Every `ModalScrim` automatically receives `padding.bottom` equal to the
-logical gesture-bar height via `apply_safe_area_to_modal_scrims` in
-`SafeAreaInsetsPlugin`. Do not manually add bottom padding to scrim nodes.
+Every `ModalScrim` automatically receives `padding.top` equal to the logical
+status-bar height and `padding.bottom` equal to the logical gesture-bar height
+via `apply_safe_area_to_modal_scrims` in `SafeAreaInsetsPlugin`. This centres
+the modal card within the usable area between both system bars. Do not manually
+add top or bottom padding to scrim nodes.

 ## 14.4 Z-ordering

@@ -364,6 +364,12 @@ version = "0.7.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7c02d123df017efcdfbd739ef81735b36c5ba83ec3c59c80a9d7ecc718f92e50"

+[[package]]
+name = "arrayvec"
+version = "0.7.6"
+source = "sparse+https://git.aleshym.co/api/packages/Quaternions/cargo/"
+checksum = "813440870d646c57c222c1d713dc4e3ddcb2919c3801564d767d85d7bf2afee4"
+
 [[package]]
 name = "as-raw-xcb-connection"
 version = "1.0.1"
@@ -717,6 +723,28 @@ dependencies = [
 "android-activity",
 ]

+[[package]]
+name = "bevy_anti_alias"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "726cc494eb7d6a84ce6291c23636fd451fa4846604dc059fa93febca4e60a928"
+dependencies = [
+ "bevy_app",
+ "bevy_asset",
+ "bevy_camera",
+ "bevy_core_pipeline",
+ "bevy_derive",
+ "bevy_diagnostic",
+ "bevy_ecs",
+ "bevy_image",
+ "bevy_math",
+ "bevy_reflect",
+ "bevy_render",
+ "bevy_shader",
+ "bevy_utils",
+ "tracing",
+]
+
 [[package]]
 name = "bevy_app"
 version = "0.18.1"
@@ -878,6 +906,35 @@ dependencies = [
 "syn",
 ]

+[[package]]
+name = "bevy_dev_tools"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4f1464a3f5ef5c23d917987714ee89881f9f791e9ff97ecf6600ee846b9569e"
+dependencies = [
+ "bevy_app",
+ "bevy_asset",
+ "bevy_camera",
+ "bevy_color",
+ "bevy_diagnostic",
+ "bevy_ecs",
+ "bevy_image",
+ "bevy_input",
+ "bevy_math",
+ "bevy_picking",
+ "bevy_reflect",
+ "bevy_render",
+ "bevy_shader",
+ "bevy_state",
+ "bevy_text",
+ "bevy_time",
+ "bevy_transform",
+ "bevy_ui",
+ "bevy_ui_render",
+ "bevy_window",
+ "tracing",
+]
+
 [[package]]
 name = "bevy_diagnostic"
 version = "0.18.1"
@@ -901,7 +958,7 @@ version = "0.18.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c9cf7a3ee41342dd7b5a5d82e200d0e8efb933169247fce853b4ad633d51e87d"
 dependencies = [
- "arrayvec",
+ "arrayvec 0.7.6 (registry+https://github.com/rust-lang/crates.io-index)",
 "bevy_ecs_macros",
 "bevy_platform",
 "bevy_ptr",
@@ -945,6 +1002,36 @@ dependencies = [
 "encase_derive_impl",
 ]

+[[package]]
+name = "bevy_feathers"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1cb29be8f8443c5cc44e1c4710bbe02877e73703c60228ca043f20529a5496c6"
+dependencies = [
+ "accesskit",
+ "bevy_a11y",
+ "bevy_app",
+ "bevy_asset",
+ "bevy_camera",
+ "bevy_color",
+ "bevy_derive",
+ "bevy_ecs",
+ "bevy_input_focus",
+ "bevy_log",
+ "bevy_math",
+ "bevy_picking",
+ "bevy_platform",
+ "bevy_reflect",
+ "bevy_render",
+ "bevy_shader",
+ "bevy_text",
+ "bevy_ui",
+ "bevy_ui_render",
+ "bevy_ui_widgets",
+ "bevy_window",
+ "smol_str",
+]
+
 [[package]]
 name = "bevy_gizmos"
 version = "0.18.1"
@@ -1067,14 +1154,17 @@ checksum = "6a11df62e49897def470471551c02f13c6fb488e55dddb5ab7ef098132e07754"
 dependencies = [
 "bevy_a11y",
 "bevy_android",
+ "bevy_anti_alias",
 "bevy_app",
 "bevy_asset",
 "bevy_camera",
 "bevy_color",
 "bevy_core_pipeline",
 "bevy_derive",
+ "bevy_dev_tools",
 "bevy_diagnostic",
 "bevy_ecs",
+ "bevy_feathers",
 "bevy_gizmos_render",
 "bevy_image",
 "bevy_input",
@@ -1082,6 +1172,7 @@ dependencies = [
 "bevy_log",
 "bevy_math",
 "bevy_mesh",
+ "bevy_pbr",
 "bevy_platform",
 "bevy_ptr",
 "bevy_reflect",
@@ -1101,6 +1192,27 @@ dependencies = [
 "bevy_winit",
 ]

+[[package]]
+name = "bevy_light"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4d9d2ac64390a9baacb3c0fa0f5456ac1553959d5a387874c102a09aab8b92cc"
+dependencies = [
+ "bevy_app",
+ "bevy_asset",
+ "bevy_camera",
+ "bevy_color",
+ "bevy_ecs",
+ "bevy_image",
+ "bevy_math",
+ "bevy_mesh",
+ "bevy_platform",
+ "bevy_reflect",
+ "bevy_transform",
+ "bevy_utils",
+ "tracing",
+]
+
 [[package]]
 name = "bevy_log"
 version = "0.18.1"
@@ -1138,7 +1250,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e931fa969f89c83498b22c97432383afe90e90fd1a5e04fa07be8da4d3bcac84"
 dependencies = [
 "approx",
- "arrayvec",
+ "arrayvec 0.7.6 (registry+https://github.com/rust-lang/crates.io-index)",
 "bevy_reflect",
 "derive_more",
 "glam 0.30.10",
@@ -1161,7 +1273,9 @@ dependencies = [
 "bevy_asset",
 "bevy_derive",
 "bevy_ecs",
+ "bevy_image",
 "bevy_math",
+ "bevy_mikktspace",
 "bevy_platform",
 "bevy_reflect",
 "bevy_transform",
@@ -1174,6 +1288,71 @@ dependencies = [
 "wgpu-types",
 ]

+[[package]]
+name = "bevy_mikktspace"
+version = "0.17.0-dev"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ef8e4b7e61dfe7719bb03c884dc270cd46a82efb40f93e9933b990c5c190c59"
+
+[[package]]
+name = "bevy_pbr"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a5ab6944ffc6fd71604c0fbca68cc3e2a3654edfcdbfd232f9d8b88e3d20fdc0"
+dependencies = [
+ "bevy_app",
+ "bevy_asset",
+ "bevy_camera",
+ "bevy_color",
+ "bevy_core_pipeline",
+ "bevy_derive",
+ "bevy_diagnostic",
+ "bevy_ecs",
+ "bevy_image",
+ "bevy_light",
+ "bevy_log",
+ "bevy_math",
+ "bevy_mesh",
+ "bevy_platform",
+ "bevy_reflect",
+ "bevy_render",
+ "bevy_shader",
+ "bevy_transform",
+ "bevy_utils",
+ "bitflags 2.11.1",
+ "bytemuck",
+ "derive_more",
+ "fixedbitset",
+ "nonmax",
+ "offset-allocator",
+ "smallvec",
+ "static_assertions",
+ "thiserror 2.0.18",
+ "tracing",
+]
+
+[[package]]
+name = "bevy_picking"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7d524dbc8f2c9e73f7ab70c148c8f7886f3c24b8aa8c252a38ba68ed06cbf10"
+dependencies = [
+ "bevy_app",
+ "bevy_asset",
+ "bevy_camera",
+ "bevy_derive",
+ "bevy_ecs",
+ "bevy_input",
+ "bevy_math",
+ "bevy_platform",
+ "bevy_reflect",
+ "bevy_time",
+ "bevy_transform",
+ "bevy_window",
+ "tracing",
+ "uuid",
+]
+
 [[package]]
 name = "bevy_platform"
 version = "0.18.1"
@@ -1500,6 +1679,7 @@ dependencies = [
 "bevy_input",
 "bevy_input_focus",
 "bevy_math",
+ "bevy_picking",
 "bevy_platform",
 "bevy_reflect",
 "bevy_sprite",
@@ -1512,6 +1692,7 @@ dependencies = [
 "taffy",
 "thiserror 2.0.18",
 "tracing",
+ "uuid",
 ]

 [[package]]
@@ -1545,6 +1726,26 @@ dependencies = [
 "tracing",
 ]

+[[package]]
+name = "bevy_ui_widgets"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6a63cb818b0de41bdb14990e0ce1aaaa347f871750ab280f80c427e83d72712"
+dependencies = [
+ "accesskit",
+ "bevy_a11y",
+ "bevy_app",
+ "bevy_camera",
+ "bevy_ecs",
+ "bevy_input",
+ "bevy_input_focus",
+ "bevy_log",
+ "bevy_math",
+ "bevy_picking",
+ "bevy_reflect",
+ "bevy_ui",
+]
+
 [[package]]
 name = "bevy_utils"
 version = "0.18.1"
@@ -1672,6 +1873,7 @@ version = "2.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
 dependencies = [
+ "bytemuck",
 "serde_core",
 ]

@@ -1703,7 +1905,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0aa83c34e62843d924f905e0f5c866eb1dd6545fc4d719e803d9ba6030371fce"
 dependencies = [
 "arrayref",
- "arrayvec",
+ "arrayvec 0.7.6 (registry+https://github.com/rust-lang/crates.io-index)",
 "cc",
 "cfg-if",
 "constant_time_eq",
@@ -1879,6 +2081,17 @@ dependencies = [
 "wayland-client",
 ]

+[[package]]
+name = "card_game"
+version = "0.4.1"
+source = "sparse+https://git.aleshym.co/api/packages/Quaternions/cargo/"
+checksum = "983728ead19f51d96931725706e62293bd133ac3d836097dd7d745e929f7811b"
+dependencies = [
+ "arrayvec 0.7.6 (sparse+https://git.aleshym.co/api/packages/Quaternions/cargo/)",
+ "serde",
+ "serde_derive",
+]
+
 [[package]]
 name = "cbc"
 version = "0.1.2"
@@ -1939,6 +2152,17 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "18758054972164c3264f7c8386f5fc6da6114cb46b619fd365d4e3b2dc3ae487"

+[[package]]
+name = "chacha20"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6f8d983286843e49675a4b7a2d174efe136dc93a18d69130dd18198a6c167601"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.3.0",
+ "rand_core 0.10.1",
+]
+
 [[package]]
 name = "chrono"
 version = "0.4.44"
@@ -3457,6 +3681,17 @@ dependencies = [
 "weezl",
 ]

+[[package]]
+name = "gl_generator"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a95dfc23a2b4a9a2f5ab41d194f8bfda3cabec42af4e39f08c339eb2a0c124d"
+dependencies = [
+ "khronos_api",
+ "log",
+ "xml-rs",
+]
+
 [[package]]
 name = "glam"
 version = "0.30.10"
@@ -3485,6 +3720,27 @@ version = "0.3.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"

+[[package]]
+name = "glow"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c5e5ea60d70410161c8bf5da3fdfeaa1c72ed2c15f8bbb9d19fe3a4fad085f08"
+dependencies = [
+ "js-sys",
+ "slotmap",
+ "wasm-bindgen",
+ "web-sys",
+]
+
+[[package]]
+name = "glutin_wgl_sys"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2c4ee00b289aba7a9e5306d57c2d05499b2e5dc427f84ac708bd2c090212cf3e"
+dependencies = [
+ "gl_generator",
+]
+
 [[package]]
 name = "governor"
 version = "0.10.4"
@@ -4051,7 +4307,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "525e9ff3e1a4be2fbea1fdf0e98686a6d98b4d8f937e1bf7402245af1909e8c3"
 dependencies = [
 "byteorder-lite",
- "quick-error",
+ "quick-error 2.0.1",
 ]

 [[package]]
@@ -4309,6 +4565,23 @@ dependencies = [
 "uuid",
 ]

+[[package]]
+name = "khronos-egl"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6aae1df220ece3c0ada96b8153459b67eebe9ae9212258bb0134ae60416fdf76"
+dependencies = [
+ "libc",
+ "libloading",
+ "pkg-config",
+]
+
+[[package]]
+name = "khronos_api"
+version = "3.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e2db585e1d738fc771bf08a151420d3ed193d9d895a36df7f6f8a9456b911ddc"
+
 [[package]]
 name = "kira"
 version = "0.12.0"
@@ -4326,13 +4599,25 @@ dependencies = [
 "triple_buffer",
 ]

+[[package]]
+name = "klondike"
+version = "0.4.0"
+source = "sparse+https://git.aleshym.co/api/packages/Quaternions/cargo/"
+checksum = "d5c82b0c3abd7da07b4a1c4221a809e6e2ffd475ae0e67180fbfef35a9cfe769"
+dependencies = [
+ "card_game",
+ "rand 0.10.1",
+ "serde",
+ "serde_derive",
+]
+
 [[package]]
 name = "kurbo"
 version = "0.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7564e90fe3c0d5771e1f0bc95322b21baaeaa0d9213fa6a0b61c99f8b17b3bfb"
 dependencies = [
- "arrayvec",
+ "arrayvec 0.7.6 (registry+https://github.com/rust-lang/crates.io-index)",
 "euclid",
 "smallvec",
 ]
@@ -4740,7 +5025,7 @@ version = "27.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "066cf25f0e8b11ee0df221219010f213ad429855f57c494f995590c861a9a7d8"
 dependencies = [
- "arrayvec",
+ "arrayvec 0.7.6 (registry+https://github.com/rust-lang/crates.io-index)",
 "bit-set",
 "bitflags 2.11.1",
 "cfg-if",
@@ -5778,6 +6063,25 @@ version = "1.0.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3eb8486b569e12e2c32ad3e204dbaba5e4b5b216e9367044f25f1dba42341773"

+[[package]]
+name = "proptest"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b45fcc2344c680f5025fe57779faef368840d0bd1f42f216291f0dc4ace4744"
+dependencies = [
+ "bit-set",
+ "bit-vec",
+ "bitflags 2.11.1",
+ "num-traits",
+ "rand 0.9.4",
+ "rand_chacha 0.9.0",
+ "rand_xorshift",
+ "regex-syntax",
+ "rusty-fork",
+ "tempfile",
+ "unarray",
+]
+
 [[package]]
 name = "prost"
 version = "0.14.3"
@@ -5822,6 +6126,12 @@ dependencies = [
 "winapi",
 ]

+[[package]]
+name = "quick-error"
+version = "1.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0"
+
 [[package]]
 name = "quick-error"
 version = "2.0.1"
@@ -5947,6 +6257,16 @@ dependencies = [
 "rand_core 0.9.5",
 ]

+[[package]]
+name = "rand"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d2e8e8bcc7961af1fdac401278c6a831614941f6164ee3bf4ce61b7edb162207"
+dependencies = [
+ "chacha20",
+ "rand_core 0.10.1",
+]
+
 [[package]]
 name = "rand_chacha"
 version = "0.3.1"
@@ -5985,6 +6305,12 @@ dependencies = [
 "getrandom 0.3.4",
 ]

+[[package]]
+name = "rand_core"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
+
 [[package]]
 name = "rand_distr"
 version = "0.5.1"
@@ -6004,6 +6330,15 @@ dependencies = [
 "rand_core 0.6.4",
 ]

+[[package]]
+name = "rand_xorshift"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "513962919efc330f829edb2535844d1b912b0fbe2ca165d613e4e8788bb05a5a"
+dependencies = [
+ "rand_core 0.9.5",
+]
+
 [[package]]
 name = "range-alloc"
 version = "0.1.5"
@@ -6493,6 +6828,18 @@ version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"

+[[package]]
+name = "rusty-fork"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc6bf79ff24e648f6da1f8d1f011e9cac26491b619e6b9280f2b47f1774e6ee2"
+dependencies = [
+ "fnv",
+ "quick-error 1.2.3",
+ "tempfile",
+ "wait-timeout",
+]
+
 [[package]]
 name = "rustybuzz"
 version = "0.20.1"
@@ -6959,6 +7306,7 @@ name = "solitaire_app"
 version = "0.1.0"
 dependencies = [
 "bevy",
+ "jni 0.21.1",
 "keyring",
 "solitaire_data",
 "solitaire_engine",
@@ -6980,7 +7328,9 @@ dependencies = [
 name = "solitaire_core"
 version = "0.1.0"
 dependencies = [
- "rand 0.9.4",
+ "card_game",
+ "klondike",
+ "proptest",
 "serde",
 "thiserror 2.0.18",
 ]
@@ -6991,12 +7341,13 @@ version = "0.1.0"
 dependencies = [
 "async-trait",
 "axum",
- "bevy",
+ "card_game",
 "chrono",
 "dirs",
 "jni 0.21.1",
 "jsonwebtoken",
 "keyring-core",
+ "klondike",
 "reqwest",
 "serde",
 "serde_json",
@@ -7090,6 +7441,18 @@ dependencies = [
 "web-sys",
 ]

+[[package]]
+name = "solitaire_web"
+version = "0.1.0"
+dependencies = [
+ "bevy",
+ "console_error_panic_hook",
+ "getrandom 0.3.4",
+ "solitaire_data",
+ "solitaire_engine",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "spin"
 version = "0.9.8"
@@ -7502,7 +7865,7 @@ version = "0.5.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ea00cc4f79b7f6bb7ff87eddc065a1066f3a43fe1875979056672c9ef948c2af"
 dependencies = [
- "arrayvec",
+ "arrayvec 0.7.6 (registry+https://github.com/rust-lang/crates.io-index)",
 "bitflags 1.3.2",
 "bytemuck",
 "lazy_static",
@@ -7601,7 +7964,7 @@ version = "0.9.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "41ba83ebaf2954d31d05d67340fd46cebe99da2b7133b0dd68d70c65473a437b"
 dependencies = [
- "arrayvec",
+ "arrayvec 0.7.6 (registry+https://github.com/rust-lang/crates.io-index)",
 "grid",
 "serde",
 "slotmap",
@@ -7870,7 +8233,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "83d13394d44dae3207b52a326c0c85a8bf87f1541f23b0d143811088497b09ab"
 dependencies = [
 "arrayref",
- "arrayvec",
+ "arrayvec 0.7.6 (registry+https://github.com/rust-lang/crates.io-index)",
 "bytemuck",
 "cfg-if",
 "log",
@@ -7884,7 +8247,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "47ffee5eaaf5527f630fb0e356b90ebdec84d5d18d937c5e440350f88c5a91ea"
 dependencies = [
 "arrayref",
- "arrayvec",
+ "arrayvec 0.7.6 (registry+https://github.com/rust-lang/crates.io-index)",
 "bytemuck",
 "cfg-if",
 "log",
@@ -8533,6 +8896,12 @@ dependencies = [
 "windows-sys 0.61.2",
 ]

+[[package]]
+name = "unarray"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eaea85b334db583fe3274d12b4cd1880032beab409c0d774be044d4480ab9a94"
+
 [[package]]
 name = "uncased"
 version = "0.9.10"
@@ -8739,6 +9108,15 @@ version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"

+[[package]]
+name = "wait-timeout"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ac3b126d3914f9849036f826e054cbabdc8519970b8998ddaf3b5bd3c65f11"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "walkdir"
 version = "2.5.0"
@@ -9044,12 +9422,13 @@ version = "27.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bfe68bac7cde125de7a731c3400723cadaaf1703795ad3f4805f187459cd7a77"
 dependencies = [
- "arrayvec",
+ "arrayvec 0.7.6 (registry+https://github.com/rust-lang/crates.io-index)",
 "bitflags 2.11.1",
 "cfg-if",
 "cfg_aliases",
 "document-features",
 "hashbrown 0.16.1",
+ "js-sys",
 "log",
 "naga",
 "portable-atomic",
@@ -9057,6 +9436,8 @@ dependencies = [
 "raw-window-handle",
 "smallvec",
 "static_assertions",
+ "wasm-bindgen",
+ "web-sys",
 "wgpu-core",
 "wgpu-hal",
 "wgpu-types",
@@ -9068,7 +9449,7 @@ version = "27.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "27a75de515543b1897b26119f93731b385a19aea165a1ec5f0e3acecc229cae7"
 dependencies = [
- "arrayvec",
+ "arrayvec 0.7.6 (registry+https://github.com/rust-lang/crates.io-index)",
 "bit-set",
 "bit-vec",
 "bitflags 2.11.1",
@@ -9088,6 +9469,7 @@ dependencies = [
 "smallvec",
 "thiserror 2.0.18",
 "wgpu-core-deps-apple",
+ "wgpu-core-deps-wasm",
 "wgpu-core-deps-windows-linux-android",
 "wgpu-hal",
 "wgpu-types",
@@ -9102,6 +9484,15 @@ dependencies = [
 "wgpu-hal",
 ]

+[[package]]
+name = "wgpu-core-deps-wasm"
+version = "27.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b1027dcf3b027a877e44819df7ceb0e2e98578830f8cd34cd6c3c7c2a7a50b7"
+dependencies = [
+ "wgpu-hal",
+]
+
 [[package]]
 name = "wgpu-core-deps-windows-linux-android"
 version = "27.0.0"
@@ -9118,7 +9509,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5b21cb61c57ee198bc4aff71aeadff4cbb80b927beb912506af9c780d64313ce"
 dependencies = [
 "android_system_properties",
- "arrayvec",
+ "arrayvec 0.7.6 (registry+https://github.com/rust-lang/crates.io-index)",
 "ash",
 "bit-set",
 "bitflags 2.11.1",
@@ -9127,15 +9518,20 @@ dependencies = [
 "cfg-if",
 "cfg_aliases",
 "core-graphics-types 0.2.0",
+ "glow",
+ "glutin_wgl_sys",
 "gpu-alloc",
 "gpu-allocator",
 "gpu-descriptor",
 "hashbrown 0.16.1",
+ "js-sys",
+ "khronos-egl",
 "libc",
 "libloading",
 "log",
 "metal",
 "naga",
+ "ndk-sys",
 "objc",
 "once_cell",
 "ordered-float",
@@ -9148,6 +9544,8 @@ dependencies = [
 "renderdoc-sys",
 "smallvec",
 "thiserror 2.0.18",
+ "wasm-bindgen",
+ "web-sys",
 "wgpu-types",
 "windows 0.58.0",
 "windows-core 0.58.0",
@@ -10030,6 +10428,12 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b9cc00251562a284751c9973bace760d86c0276c471b4be569fe6b068ee97a56"

+[[package]]
+name = "xml-rs"
+version = "0.8.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ae8337f8a065cfc972643663ea4279e04e7256de865aa66fe25cec5fb912d3f"
+
 [[package]]
 name = "xmlwriter"
 version = "0.1.0"
@@ -8,6 +8,7 @@ members = [
    "solitaire_app",
    "solitaire_assetgen",
    "solitaire_wasm",
+    "solitaire_web",
 ]
 resolver = "2"

@@ -17,11 +18,27 @@ version = "0.1.0"
 license = "MIT"
 rust-version = "1.95"

+# Pedantic correctness lints applied across every member crate via
+# `[lints] workspace = true`.
+[workspace.lints.rust]
+# Workspace-wide ban on `unsafe`. The sole exception is `solitaire_app`,
+# which sets its own `deny`-level lints (see its Cargo.toml) because the
+# Android cdylib entry point must reconstruct raw JNI handles. Every other
+# crate reaches Android JNI through the safe `solitaire_data::android_jni`
+# bridge and stays fully unsafe-free.
+unsafe_code = "forbid"
+single_use_lifetimes = "warn"
+trivial_casts = "warn"
+unused_lifetimes = "warn"
+unused_qualifications = "warn"
+variant_size_differences = "warn"
+unexpected_cfgs = "warn"
+
 [workspace.dependencies]
 serde       = { version = "1", features = ["derive"] }
 serde_json  = "1"
 uuid        = { version = "1", features = ["v4", "serde"] }
-chrono      = { version = "0.4", features = ["serde"] }
+chrono      = { version = "0.4", features = ["serde", "wasmbind"] }
 thiserror   = "2"
 rand        = "0.9"
 async-trait = "0.1"
@@ -37,6 +54,8 @@ solitaire_core   = { path = "solitaire_core" }
 solitaire_sync   = { path = "solitaire_sync" }
 solitaire_data   = { path = "solitaire_data" }
 solitaire_engine = { path = "solitaire_engine" }
+klondike         = { version = "0.4.0", registry = "Quaternions", features = ["serde"] }
+card_game        = { version = "0.4.1", registry = "Quaternions", features = ["serde"] }

 # Bevy with `default-features = false` to avoid the unused
 # `bevy_audio → rodio + symphonia + cpal 0.15 + alsa 0.9` chain.
@@ -118,8 +118,28 @@ cargo test -p solitaire_core -p solitaire_sync -p solitaire_data -p solitaire_se

 # Lint
 cargo clippy --workspace --all-targets -- -D warnings
+
+# Browser e2e smoke (starts solitaire_server automatically)
+cd solitaire_server/e2e
+npm ci
+npx playwright install chromium
+npm test
+
+# Seed-batch cycle regression gate (thresholded)
+npm run review:cycles:regression
+
+# Loop-aware candidate benchmark (writes test-results/cycle-candidate.json)
+npm run review:cycles:candidate
 ```

+For layered engine-vs-UI automation design (Rust unit tests, wasm debug-API
+integration tests, and Playwright UI validation), see
+[docs/testing-architecture.md](docs/testing-architecture.md).
+
+For Quaternions (`klondike` / `card_game`) dependency upgrades, use
+[`scripts/update_quaternions_deps.sh`](scripts/update_quaternions_deps.sh) and
+the runbook in [docs/card-game-integration.md](docs/card-game-integration.md).
+
 ## Credits

 Built on [Bevy](https://bevyengine.org/) and the wider Rust ecosystem
@@ -1,16 +1,62 @@
 # Ferrous Solitaire — Session Handoff

-**Last updated:** 2026-05-18 — Three leaderboard bugs fixed, tagged v0.35.1. All commits on origin/master.
+**Last updated:** 2026-06-25 — v0.40.0 released (Android APK published); physical-device gate remains.

 ---

 ## Current state

- **HEAD on origin/master:** `8f86d66` (fix: three leaderboard bugs)
- **Latest tag:** `v0.35.1`
- **Working tree:** clean
- **Build:** `cargo clippy --workspace -- -D warnings` clean
- **Tests:** 1277 passing / 0 failing across the workspace
+- **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.
+
+---
+
+## v0.40.0 release (2026-06-25)
+
+Released via tag push → `.gitea/workflows/android-release.yml` built and signed the
+arm64-v8a release APK (release keystore, `versionCode 4000` / `versionName 0.40.0`,
+29.2 MB) and published it to the Gitea release. Obtainium clients tracking the repo
+pick it up automatically.
+
+- Release: https://git.aleshym.co/funman300/Ferrous-Solitaire/releases/tag/v0.40.0
+
+| PR | Summary |
+|----|---------|
+| #106 | **fix(engine):** Draw-Three waste fan hit-test now shares the renderer's fan step (`card_plugin::waste_fan_step` / `tableau_col_step`). The two had diverged under Android's tighter column spacing (`H_GAP_DIVISOR=32`), shifting the top fanned waste card's click target onto the card beneath it — so dragging the visible top card played the wrong one. Desktop/web were unaffected (the formulas already coincided there). |
+| #105 | **test(engine):** waste-card draggability regression tests (`find_draggable_at` picks the waste top with multiple cards and as a lone card). |
+| #108 | **docs(android):** NDK reference updated `26.3.11579264` → `30.0.14904198`; noted versions are not load-bearing and `build_android_apk.sh` auto-discovers the newest NDK/build-tools. |
+
+Pre-release validation performed locally this session: workspace clippy/test/build
+gates; `aarch64-linux-android` cross-compile + clippy clean (covers the
+`#[cfg(target_os = "android")]` paths that host CI never lints); release manifest
+sanity (`solitaire_app/android/AndroidManifest.xml` has no version fields so CI
+injection works; `lib_name` matches `[lib].name`); and a full signed local APK
+proving the `build_android_apk.sh` packaging pipeline end-to-end.
+
+---
+
+## What shipped since v0.39.0
+
+- Browser Bevy canvas route and `window.__FERROUS_DEBUG__` automation bridge landed, with Playwright coverage for `/play`.
+- In-place `card_game` / `klondike` rewrite phases are complete through the latest follow-up:
+  - `5e87358` integrates upstream deps cleanly.
+  - `ae1ecc8` unifies `Suit` / `Rank` with upstream `card_game` types.
+  - `d864d98` routes klondike/card imports through `solitaire_core`.
+  - `9bcf13d`, `56e3b62`, `26f1b00` finish schema-v3 migration coverage, undo/recycle score correctness, and rewrite-plan docs.
+- Android keystore wiring, Android build-script hardening, server auth/runtime hardening, and modal safe-area centering have landed.
+- `CHANGELOG.md` has been caught up from `v0.34.0` through current unreleased work and committed in `7fe6ac6`.
+- Matomo analytics was re-reviewed: `MatomoClient` and `AnalyticsPlugin` are wired through `CoreGamePlugin` on non-wasm targets, and targeted tests now cover opt-in client creation, event encoding, buffer trimming, and analytics mode labels.
+- Native analytics and Android physical-device validation now have runbooks in
+  `docs/analytics-validation.md` and `docs/ANDROID.md`.
+
+---
+
+## Historical notes before v0.39.0
+
+See git log and `CHANGELOG.md`. The changelog now includes `v0.34.0` through `v0.39.0`, plus current unreleased work.

 ---

@@ -81,32 +127,38 @@ Three bugs fixed:

 ## Open punch list

-### 1. CHANGELOG documentation debt
+### 1. Physical-device smoke test — THE ONLY REMAINING v0.40.0 ITEM

-CHANGELOG.md currently ends at v0.33.0. Entries for v0.34.0, v0.35.0, and v0.35.1
-are missing. Low priority (git log is authoritative) but worth closing before the
-next release.
+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.

-### 2. Android APK launch verification (Option A)
+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.

-Physical device test: install the latest APK on a real Android device (not AVD),
-confirm:
- App launches without crash
- Safe area insets arrive and shift HUD correctly after ~3 frames
- All modal Done buttons are above the gesture bar
- Drag-and-drop works on all pile types
- Leaderboard panel opens and the "Public name" label updates correctly after
-  using "Set Name"
+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.

-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.
+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.

-### 3. Matomo analytics wiring
+### 2. Matomo analytics live validation (independent — NOT a v0.40.0 release blocker)

-`Settings` has `analytics_enabled: bool` and `matomo_url: Option<String>` but no
-engine code consumes them — the analytics toggle in Settings is a no-op. If
-analytics are ever needed, the Matomo HTTP Tracking API client needs to be written
-and wired to `GameStateResource` events.
+Separate, ongoing task unrelated to the Android release. `Settings` has
+`analytics_enabled`, `matomo_url`, and `matomo_site_id`; the engine consumes them via
+`AnalyticsPlugin` on non-wasm targets. Remaining work is live validation against the
+deployed Matomo instance. Use `docs/analytics-validation.md` for the native
+validation checklist and the current web/WASM decision notes.

 ---

@@ -128,3 +180,18 @@ and wired to `GameStateResource` events.
 - **Test input-state pitfall:** `MinimalPlugins` has no input-tick system, so
  `ButtonInput::just_pressed` state persists across frames unless explicitly cleared
  with `input.release(key); input.clear()` between updates.
+
+- **`/play` debug bridge design:** `play.html` runs two independent WASM instances in
+  `Promise.all([bootstrap(), init()])`. `bootstrap()` sets `window.__FERROUS_DEBUG__`
+  (logic layer via `solitaire_wasm.js`); `init()` starts the Bevy canvas. The bridge
+  operates its own `SolitaireGame` — moves applied through the bridge do NOT affect
+  the Bevy visual game. This is intentional for automation/invariant checking.
+
+- **HiDPI Bevy canvas:** `WindowResolution::default().with_scale_factor_override(1.0)`
+  is set in the canvas app. Without this, physical pixels exceed WebGL2's 2048px limit
+  on HiDPI displays, causing an immediate wgpu panic on the first resize event.
+
+- **`/play-classic` vs `/play` in e2e:** `smoke.spec.js` + `gameplay_review.spec.js`
+  target `/play-classic` (DOM-heavy game.html); `play_canvas.spec.js` targets `/play`
+  using only the `__FERROUS_DEBUG__` bridge (no DOM selectors). `cycle_metrics.js`
+  supports both via `--route play-classic|play`.
@@ -1,24 +1,43 @@
 #!/usr/bin/env bash
-# Rebuild the solitaire_wasm crate and install the output into
-# solitaire_server/web/pkg/ so the server can serve the replay viewer.
+# Rebuild WASM artifacts and install them into solitaire_server/web/pkg/.
+#
+# Two artifacts are produced:
+#   solitaire_wasm.*  — thin replay-viewer + interactive JS API (wasm-pack)
+#   canvas.*          — full Bevy WASM app for play.html (cargo + wasm-bindgen)
 #
 # Prerequisites:
-#   cargo install wasm-pack
+#   cargo install wasm-pack wasm-bindgen-cli
 #   rustup target add wasm32-unknown-unknown
+#   (optional) cargo install wasm-opt   # for smaller canvas_bg.wasm
 #
 # Run from the repo root:
 #   ./build_wasm.sh
 #
-# The generated files (solitaire_wasm.js + solitaire_wasm_bg.wasm) are
-# committed to git so self-hosters who don't touch the WASM crate can
-# skip this step.  Regenerate after any change to solitaire_wasm/ or
-# solitaire_core/.
+# The generated pkg/ files are committed to git so self-hosters who don't
+# touch the WASM crates can skip this step.  Regenerate after any change to
+# solitaire_wasm/, solitaire_web/, solitaire_engine/, or solitaire_core/.

 set -euo pipefail

 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 OUT_DIR="$REPO_ROOT/solitaire_server/web/pkg"

+# Reproducible builds. The wasm artifacts otherwise bake in machine-specific
+# absolute source paths (the cargo registry, the rustup std sources, and this
+# checkout), so a rebuild on a different machine produces different bytes and
+# the CI freshness gate (rebuild-and-diff) false-positives. Remap all three
+# prefixes to fixed names so the output is byte-identical anywhere.
+#
+# We must use CARGO_ENCODED_RUSTFLAGS (not RUSTFLAGS) and re-state the
+# getrandom backend cfg here: a `*_RUSTFLAGS` env var *replaces* — does not
+# merge with — the `[target.wasm32-unknown-unknown] rustflags` in
+# .cargo/config.toml, so dropping that cfg would break the wasm getrandom build.
+# Keep this `--cfg` in sync with .cargo/config.toml.
+CARGO_HOME_DIR="${CARGO_HOME:-$HOME/.cargo}"
+RUSTUP_HOME_DIR="${RUSTUP_HOME:-$HOME/.rustup}"
+US=$'\x1f'   # unit separator: CARGO_ENCODED_RUSTFLAGS arg delimiter
+export CARGO_ENCODED_RUSTFLAGS="--cfg${US}getrandom_backend=\"wasm_js\"${US}--remap-path-prefix=${CARGO_HOME_DIR}=/cargo${US}--remap-path-prefix=${RUSTUP_HOME_DIR}=/rustup${US}--remap-path-prefix=${REPO_ROOT}=/build"
+
 if ! command -v wasm-pack &> /dev/null; then
    echo "error: wasm-pack not found." >&2
    echo "  Install with: cargo install wasm-pack" >&2
@@ -36,5 +55,43 @@ wasm-pack build \
 # Remove them — we manage the output directory ourselves.
 rm -f "$OUT_DIR/package.json" "$OUT_DIR/.gitignore"

+# ---------------------------------------------------------------------------
+# Bevy WASM app (solitaire_web → canvas.js + canvas_bg.wasm)
+# ---------------------------------------------------------------------------
+
+if ! command -v wasm-bindgen &> /dev/null; then
+    echo "error: wasm-bindgen not found." >&2
+    echo "  Install with: cargo install wasm-bindgen-cli" >&2
+    echo "  The CLI version must match the wasm-bindgen crate dep." >&2
+    exit 1
+fi
+
+echo "Building solitaire_web (Bevy WASM app)..."
+cargo build --release --target wasm32-unknown-unknown -p solitaire_web
+
+echo "Running wasm-bindgen for solitaire_web..."
+wasm-bindgen \
+    --out-dir "$OUT_DIR" \
+    --out-name canvas \
+    --target web \
+    --no-typescript \
+    "$REPO_ROOT/target/wasm32-unknown-unknown/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.
+if command -v wasm-opt &> /dev/null; then
+    echo "Running wasm-opt on canvas_bg.wasm..."
+    # Use -O2 (not -Oz): Bevy's render pipeline uses deep call stacks and
+    # complex memory patterns that wasm-opt -Oz can miscompile, resulting
+    # in a grey screen on first load. -O2 is speed-optimised and avoids
+    # the size-focused transforms that trigger the regression.
+    wasm-opt -O2 \
+        -o "$OUT_DIR/canvas_bg.wasm" \
+        "$OUT_DIR/canvas_bg.wasm"
+else
+    echo "note: wasm-opt not found; skipping size optimisation."
+    echo "  Install with: cargo install wasm-opt  (or via binaryen)"
+fi
+
 echo "Done. Output:"
 ls -lh "$OUT_DIR"
@@ -2,13 +2,13 @@

 This doc captures the toolchain install + build invocation for the
 Android target. Steps are runnable on a fresh Debian 13 (trixie) box;
-later sections document what's known to compile, what's stubbed, and
-the next milestones.
+later sections document physical-device validation, supported platform
+surfaces, and remaining Android follow-ups.

-> **Status (2026-05-07):** First working APK at `fb8b2ac`. 54 MB
-> debug-signed `ferrous-solitaire.apk` for `x86_64-linux-android`. Has
-> NOT yet been verified to launch on a device or emulator — that's
-> the next milestone.
+> **Status (2026-06-09):** Android build plumbing, app-directory storage,
+> JNI keystore wiring, and safe-area layout fixes have landed. The remaining
+> release gate is a physical-device smoke test; AVD tap injection does not
+> exercise the real touch path reliably enough for launch verification.

 ---

@@ -35,7 +35,7 @@ rm /tmp/cmdline-tools.zip
  echo ''
  echo '# Android dev'
  echo 'export ANDROID_HOME="$HOME/Android/Sdk"'
-  echo 'export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/26.3.11579264"'
+  echo 'export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/30.0.14904198"'
  echo 'export JAVA_HOME="$(dirname $(dirname $(readlink -f $(which java))))"'
  echo 'export PATH="$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator"'
 } >> ~/.bashrc
@@ -49,10 +49,15 @@ sdkmanager \
  "platform-tools" \
  "platforms;android-34" \
  "build-tools;34.0.0" \
-  "ndk;26.3.11579264" \
+  "ndk;30.0.14904198" \
  "emulator" \
  "system-images;android-34;google_apis;x86_64"

+# The exact NDK/build-tools versions above are not load-bearing — newer ones
+# work (verified on NDK 30.0.14904198 / build-tools 37.0.0). `scripts/build_android_apk.sh`
+# auto-discovers the newest installed NDK and build-tools, so set ANDROID_NDK_HOME
+# (step 3) to whatever version you actually install here.
+
 # 6. AVD for testing (one-time).
 echo no | avdmanager create avd \
  -n bevy_test \
@@ -163,8 +168,8 @@ accepted workaround.
 Physical device:

 ```bash
-adb devices                                    # confirm connection
-adb install target/debug/apk/ferrous-solitaire.apk
+adb devices                                      # confirm connection
+adb install -r target/debug/apk/ferrous-solitaire.apk
 adb shell am start -n com.ferrousapp.solitaire/android.app.NativeActivity
 adb logcat | grep -iE "RustStdoutStderr|solitaire|panic"
 ```
@@ -185,35 +190,65 @@ AVD.

 ---

-## 4. What's wired vs. what's stubbed
+## 4. Physical-device smoke test

-The first build pass (commit `fb8b2ac`) gates four desktop-only
-crates / call sites so the workspace cross-compiles. Each gate is
-documented at its call site.
+Run this on a real phone, preferably a modern 64-bit ARM device with gesture
+navigation enabled.
+
+Build and install:
+
+```bash
+cargo apk build -p solitaire_app --target aarch64-linux-android --lib
+adb install -r target/debug/apk/ferrous-solitaire.apk
+adb logcat -c
+adb shell am start -n com.ferrousapp.solitaire/android.app.NativeActivity
+adb logcat | grep -iE "RustStdoutStderr|solitaire|panic|WindowInsets"
+```
+
+Pass criteria:
+
+- App launches without panic or ANR.
+- Safe-area insets arrive after the first few frames and shift HUD/modal
+  content away from the status and gesture bars.
+- Every modal's Done button remains above the gesture bar:
+  Settings, Help, Pause, Win Summary, and Leaderboard-related dialogs.
+- Drag-and-drop works on tableau, waste, foundation, and stock/recycle paths.
+- Tap-to-select and one-tap modes both respond correctly on card stacks.
+- Leaderboard panel opens, "Set Name" saves, and the "Public name" label updates
+  while the panel remains open.
+- Rotate the device once, then repeat one modal and one drag operation.
+- Close and relaunch the app; settings/progress still load.
+
+Record the device model, Android version, APK commit, and pass/fail notes in the
+release notes or session handoff. If a failure occurs, keep the filtered logcat
+and note the exact screen/control path that reproduced it.
+
+---
+
+## 5. Platform support matrix
+
+Desktop-only crates and call sites are gated so the workspace cross-compiles.
+Each gate is documented at its call site.

 | Surface | Desktop | Android |
 |---------|---------|---------|
 | Bevy windowing | x11 + wayland | `android-native-activity` (NativeActivity glue) |
 | Clipboard ("Copy share link") | `arboard` writes URL | Toast surfaces the URL inline |
-| OS keychain (JWT tokens) | `keyring` v4 → Secret Service / Keychain / Credential Store | Stub returning `KeychainUnavailable`; sync requires fresh login each launch |
+| OS keychain (JWT tokens) | `keyring` v4 → Secret Service / Keychain / Credential Store | Android Keystore via JNI |
+| Data directory | Platform data dir | Android app files dir |
 | App entry point | `bin` target → `solitaire_app::run()` | `cdylib` target loaded by NativeActivity |

-What's NOT yet ported / not yet measured:
+Remaining Android follow-ups:

- `dirs::data_dir()` returns `None` on Android. Callers in
-  `solitaire_data/src/storage.rs`, `progress.rs`, `replay.rs`,
-  `achievements.rs`, `settings.rs` all need an Android-aware
-  helper (likely `/data/data/com.ferrousapp.solitaire/files`).
 - Touch UX pass — hit-target sizes, modal scaling on small screens,
  app lifecycle (suspend / resume), font scaling.
- Android Keystore via JNI for `auth_tokens`.
 - JNI ClipboardManager for share links.
 - Google Play Games sign-in (the `solitaire_gpgs` crate referenced
  in older docs doesn't yet exist).

 ---

-## 5. Iteration loop
+## 6. Iteration loop

 ```bash
 # Edit code…
@@ -0,0 +1,67 @@
+# Analytics Validation Runbook
+
+Ferrous Solitaire currently has two analytics paths:
+
+- Native desktop/Android gameplay events use `solitaire_engine::AnalyticsPlugin`
+  and `solitaire_data::MatomoClient`.
+- Hosted web pages include Matomo page-view snippets in
+  `solitaire_server/web/*.html`.
+
+The Bevy `/play` WASM canvas does not emit the native gameplay events because
+`AnalyticsPlugin` is intentionally gated out on `wasm32`; it depends on the
+native Tokio/reqwest stack.
+
+## Native Matomo Validation
+
+Use this when a deployed Matomo instance and a native build are available.
+
+1. Configure `settings.json` with a Matomo URL and site ID:
+
+   ```json
+   {
+     "analytics_enabled": true,
+     "matomo_url": "https://analytics.example.com",
+     "matomo_site_id": 1
+   }
+   ```
+
+2. Launch the native app and open Settings.
+3. Confirm the Privacy section appears and "Share usage data" is `ON`.
+4. Start a new confirmed game.
+5. Win or forfeit the game.
+6. Unlock an achievement if practical, or use an existing achievement path that
+   is easy to trigger in a test profile.
+7. Wait at least 60 seconds, or close after the win/forfeit path has fired its
+   immediate flush.
+8. In Matomo, confirm the following custom events arrived:
+
+   | Category | Action | Name |
+   | --- | --- | --- |
+   | `Game` | `Start` | `classic`, `zen`, `challenge`, `time_attack`, or `difficulty` |
+   | `Game` | `Won` | empty |
+   | `Game` | `Forfeit` | empty |
+   | `Achievement` | `Unlocked` | achievement id |
+
+## Web/WASM Decision
+
+Keep the current split unless the project explicitly needs in-canvas gameplay
+events for `/play`.
+
+Current behavior:
+
+- `/`, `/play-classic`, `/account`, `/leaderboard`, and `/replays` emit Matomo
+  page views through the hosted HTML snippets.
+- `/play` hosts the Bevy canvas but does not emit gameplay events from the
+  engine.
+- The browser Content-Security-Policy already allows the deployed Matomo host
+  for scripts, images, and connections.
+
+If gameplay events are needed on `/play`, add a small `wasm32`-only analytics
+bridge instead of trying to compile the native plugin:
+
+- keep the same event contract as native (`Game / Start`, `Game / Won`,
+  `Game / Forfeit`, `Achievement / Unlocked`);
+- read `Settings::analytics_enabled`, `matomo_url`, and `matomo_site_id`;
+- send through browser APIs or the existing `_paq` queue;
+- keep the Settings opt-in behavior identical to native;
+- add Playwright coverage that stubs Matomo and verifies emitted payloads.
@@ -0,0 +1,211 @@
+# Integrating `card_game` / `klondike` as the Solitaire Core
+
+**Context:** A collaborator ([Quaternions](https://git.aleshym.co/Quaternions/card_game)) is building a pure-logic Klondike library in Rust. This document maps what that library currently provides against what Ferrous Solitaire's `solitaire_core` crate requires.
+
+**Approach:** Integration is complete. Upstream `card_game` / `klondike` now owns
+authoritative Klondike rules, session history, undo snapshots, and solving.
+Ferrous keeps product-specific scoring, persistence, rendering DTOs, game modes,
+and typed UI errors in `solitaire_core`.
+
+---
+
+## What `card_game` + `klondike` Already Has
+
+### `card_game` crate (generic primitives) — v0.4.0
+| Feature | Notes |
+|---|---|
+| `Card` (Deck + Suit + Rank packed in 1 byte) | `NonZeroU8` layout — no heap allocation |
+| `Suit`, `Rank`, `Deck` enums | Full A→K, 4 suits, up to 4 deck IDs |
+| `Stack<CAP>` | Const-generic `ArrayVec` wrapper |
+| `Pile<DN, UP>` | Face-down + face-up stacks; `flip_up`, `pop_flip_up` |
+| `Game` trait | `possible_instructions`, `is_instruction_valid`, `process_instruction`, `is_win` |
+| `Session` | Wraps a `Game`; snapshot-based undo (O(1)), score including undo penalty |
+| `Session::solve()` | Built-in DFS solver with move/state budgets; returns `Solution<G>` or `SolveError` |
+| `StateSnapshot<G>` | Pre-move state + instruction; used by snapshot history and `Solution` |
+| `SessionState::score()` | = `game_score + undos × undo_penalty` (−15 by default via `SessionConfig`) |
+| `SessionConfig` | `undo_penalty`, `solve_moves_budget`, `solve_states_budget` |
+
+### `klondike` crate (Klondike rules) — v0.3.0
+| Feature | Notes |
+|---|---|
+| 7 tableau + 4 foundation + 1 stock | Fully dealt from a seeded RNG |
+| Draw-1 / Draw-3 config | `KlondikeConfig::draw_stock` (`DrawStockConfig`) |
+| `MoveFromFoundationConfig` | `Allowed` (upstream default) / `Disallowed`; controls foundation → tableau rule |
+| `ScoringConfig` | Configurable deltas: `move_to_foundation` (+10), `flip_up_bonus` (+5), `move_to_tableau` (+5), `move_from_foundation` (−15), `recycle` (0 by default) |
+| `KlondikeStats::score(&config)` | Computes score from per-event counters × `ScoringConfig` deltas |
+| `KlondikeStats` counters | `move_to_foundation_count`, `flip_up_bonus_count`, `move_to_tableau_count`, `move_from_foundation_count`, `recycle_count`, `moves` |
+| Foundation placement (Ace start, suit-matched A→K) | ✅ |
+| Tableau placement (alternating colour, K on empty) | ✅ |
+| Multi-card stack moves (via `SkipCards`) | ✅ |
+| `RotateStock` (recycle waste → stock) | ✅ |
+| `is_win_trivial` (all face-down cards cleared) | Auto-complete trigger |
+| `get_auto_move` / `get_sorted_moves` | Priority-ranked move suggestion (take `&KlondikeConfig`) |
+| Benchmark suite (`klondike-bench`) | 1 000-game throughput test |
+| CLI display (`klondike-cli`) | Terminal renderer |
+
+---
+
+## What Ferrous Solitaire's `solitaire_core` Still Owns
+
+### 1. Scoring — remaining adapter responsibilities
+Ferrous uses **Windows XP Standard** scoring. The upstream library handles the
+per-move counters and configurable deltas; Ferrous adds the product-specific
+parts in `GameState` / `KlondikeAdapter`.
+
+| Event | Delta | Handled by |
+|---|---|---|
+| Any card → foundation | +10 | `KlondikeStats` / `ScoringConfig::move_to_foundation` ✅ |
+| Waste → tableau | +5 | `KlondikeStats` / `ScoringConfig::move_to_tableau` ✅ |
+| Flip face-down tableau card | +5 | `KlondikeStats` / `ScoringConfig::flip_up_bonus` ✅ |
+| Foundation → tableau | −15 | `KlondikeStats` / `ScoringConfig::move_from_foundation` ✅ |
+| Undo | −15 | `SessionStats` / `SessionConfig::undo_penalty` ✅ |
+| Recycle (Draw-1, after 1st free) | −100 | **Our adapter** — see below |
+| Recycle (Draw-3, after 3rd free) | −20 | **Our adapter** — see below |
+| Score floor | `score.max(0)` always | **Our adapter** |
+| Time bonus on win | `700_000 / elapsed_seconds` | **Our adapter** (not wasm-portable) |
+
+Reference: <https://www.solitaireparadise.com/games_list/klondike_solitaire_scoring.html>
+
+**Undo penalty:** `SessionState::score()` = `KlondikeStats.score(&scoring) + undos × undo_penalty`. Ferrous still owns the exact user-visible score because it must restore the pre-move score when undoing recycle penalties and then apply the product's undo penalty.
+
+**Recycle penalty note:** `ScoringConfig::recycle` is a flat delta (default 0 = always free). WXP allows a fixed number of free recycles before charging a penalty, which the upstream library cannot express with a single delta. Our adapter tracks `recycle_count` from `KlondikeStats` and applies the penalty only beyond the free allowance.
+
+**In our wrapper:** `KlondikeAdapter::config_for` configures the upstream rules
+and scoring deltas. `GameState` applies recycle-with-free-allowance, score floor,
+time bonus, game-mode suppression, and undo score restoration.
+
+### 2. Game Modes
+Ferrous has three modes that alter scoring and undo behaviour:
+
+| Mode | Scoring | Undo |
+|---|---|---|
+| **Classic** | Full WXP scoring (table above) | Allowed (−15 penalty) |
+| **Zen** | All deltas suppressed — score stays 0 | Allowed (no penalty) |
+| **Challenge** | Full WXP scoring | **Disabled** — returns an error |
+
+Zen is intended for relaxed play where the score does not matter. Challenge is a timed daily puzzle where the no-undo constraint is the difficulty mechanic.
+
+**In our wrapper:** `GameMode` lives on `solitaire_core::GameState`; undo and
+scoring behavior are applied before/after delegating legal moves to the upstream
+session.
+
+### 3. Solvability Solver *(upstream merged — card_game v0.4.0)*
+`card_game v0.4.0` ships `Session::solve()` — a budget-bounded DFS that returns `Result<Option<Solution<G>>, SolveError>`. `SolveError` has two variants:
+- `MovesBudgetExceeded` — equivalent to our `SolverResult::Inconclusive`
+- `StatesBudgetExceeded` — equivalent to our `SolverResult::Inconclusive`
+
+`Solution<G>` contains the winning move sequence as `Vec<StateSnapshot<G>>`; `clean_solution()` removes cycles. `Session::solve()` uses `SessionConfig::solve_moves_budget` and `SessionConfig::solve_states_budget` (defaults: 100 000 each).
+
+The old local DFS has been replaced. `solitaire_core::solver` is now a small
+adapter around `Session::solve()` that preserves the engine-facing
+`SolverResult`, `SolverConfig`, and first-move payload contract.
+
+**In our wrapper:** `solve_game_state` calls `session.solve()` with the requested
+budgets. It maps `Ok(Some(_))` → Winnable, `Ok(None)` → Unwinnable, and budget
+errors → Inconclusive.
+
+### 4. `take_from_foundation` House Rule *(upstream merged — v0.3.0)*
+`MoveFromFoundationConfig` is now part of `KlondikeConfig`. When set to `Disallowed`, `is_instruction_valid` blocks foundation → tableau instructions.
+
+**Default behaviour:** The upstream default is `MoveFromFoundationConfig::Allowed`. Ferrous Solitaire **also defaults to Allowed** (`take_from_foundation: true` in `GameState`, `Settings`). This matches the upstream default and provides the most beginner-friendly experience. The player can disable foundation returns via a settings toggle (`take_from_foundation = false`), which maps to `Disallowed`.
+
+**In our wrapper:** `KlondikeAdapter::config_for(draw_mode, take_from_foundation)` constructs `KlondikeConfig { move_from_foundation: if take_from_foundation { Allowed } else { Disallowed }, .. }`. No custom intercept needed — `klondike` enforces the rule automatically.
+
+### 5. JSON Serialisation / Persistence
+`solitaire_core::GameState` serialises the full mid-game state to JSON via `serde` so the engine can save on exit and restore on launch.
+
+**Upstream serde status (rev 99b49e62):** At this revision, `klondike` and `card_game` both enable a `serde` feature. All nine instruction/pile types (`KlondikeInstruction`, `KlondikePile`, `KlondikePileStack`, `DstFoundation`, `DstTableau`, `TableauStack`, `Foundation`, `Tableau`, `SkipCards`) derive `serde::Serialize` + `serde::Deserialize` under that feature. The workspace `Cargo.toml` enables `features = ["serde"]`.
+
+**Schema v4 (current):** `saved_moves` serialises as `Vec<KlondikeInstruction>` using upstream named-variant serde. Example: `{"DstFoundation": {"src": "Stock", "foundation": "Foundation1"}}`.
+
+**Schema v3 (legacy, auto-migrated):** `saved_moves` used local `SavedInstruction` mirror types with u8 indices. Example: `{"DstFoundation": {"src": "Stock", "foundation": 0}}`. On load, an `AnyInstruction` untagged serde enum transparently upgrades v3 instructions to v4 and the file is written back in v4 format. The `SavedInstruction` bridge types are retained in `solitaire_core::klondike_adapter` for this migration path and for backward-compatible `solitaire_data::ReplayMove` / WASM replay formats.
+
+**Session history:** `StateSnapshot<G>` stores the pre-move game state and instruction. On load, the session is reconstructed by replaying the instruction history against a fresh deal — no full state snapshot needed.
+
+**In our wrapper:** `GameState::Serialize` emits schema v4 (upstream instruction types). `GameState::Deserialize` accepts v3 (auto-migrates) and v4 (direct). Schema version field lives on our wrapper.
+
+### 6. Typed Move Errors
+`solitaire_core::error::MoveError` returns structured errors the engine uses to trigger UI feedback (wrong-destination toast, stock-empty chime, etc.):
+
+```
+GameAlreadyWon
+UndoStackEmpty
+StockEmpty
+InvalidSource
+InvalidDestination
+RuleViolation(String)
+```
+
+`KlondikeInstruction` is always constructed by game code from valid entity layout, so invalid moves are only detectable at `solitaire_core`'s construction boundary — the error lives there, not inside `klondike`.
+
+**In our wrapper:** `MoveError` variants are generated when `solitaire_core` fails to construct a `KlondikeInstruction` from the player's requested move. No translation of `is_instruction_valid`'s bool return is required; by the time an instruction reaches `klondike`, it is already known to be structurally valid.
+
+### 7. Waste Pile as Separate Concept
+Ferrous tracks `PileType::Waste` as a distinct pile. `klondike` folds waste into `Stock` (the face-up half of the stock `Pile`). The engine's UI and scoring logic reference the waste pile directly; the mapping needs to be explicit.
+
+**In our wrapper:** Project the face-up half of `klondike`'s stock `Pile` as `PileType::Waste` when building pile snapshots for the engine.
+
+### 8. Undo Stack Approach *(resolved — not an issue)*
+`card_game v0.4.0` `Session` uses snapshot-based undo: `SessionState` stores `Vec<StateSnapshot<G>>` where each entry holds the pre-move game state and the instruction. Undo pops the last snapshot and restores state directly — O(1), matching our existing `GameState.undo_stack`.
+
+**Resolution:** `GameState` uses `Session`'s built-in snapshot history. Ferrous
+keeps parallel score/recycle metadata so undo can restore product-specific score
+state that upstream snapshots do not own.
+
+---
+
+## Integration Path (All work in `solitaire_core`)
+
+Steps in dependency order. Upstream issues #10, #11, and the solver are all merged.
+
+1. ✅ **Add `klondike = "0.3.0"` / `card_game = "0.4.0"` as dependencies** of `solitaire_core`; `KlondikeAdapter` wraps `KlondikeConfig` and exposes scoring helpers.
+2. ✅ **Map pile types** — project `klondike`'s stock face-up half as the engine's waste pile and expose renderer-facing pile snapshots.
+3. ✅ **Configure `KlondikeConfig`** — set `move_from_foundation: MoveFromFoundationConfig::Allowed` by default; wire the user's settings toggle to `Disallowed` when foundation returns are disabled (gap 4, upstream).
+4. ✅ **Port scoring** — pass WXP deltas into `ScoringConfig`; `SessionConfig::undo_penalty` handles undo; implement recycle-with-free-allowance, score floor, and time bonus in the adapter (gap 1).
+5. ✅ **Port `GameMode`** — intercept undo + scoring in the adapter based on mode (gap 2).
+6. ✅ **Replace solver** — call `session.solve()` with budgets from `SolverConfig`; map `Ok(Some)` → Winnable, `Ok(None)` → Unwinnable, `Err` → Inconclusive (gap 3, upstream).
+7. ✅ **Implement `serde`** — serialise schema v4 with upstream `KlondikeInstruction`; auto-migrate schema v3 via `SavedInstruction` compatibility types.
+
+---
+
+## Quaternions Upgrade Runbook
+
+Use this sequence whenever upgrading `klondike` / `card_game` from the
+Quaternions registry:
+
+1. Review upstream changes/releases:
+   - <https://git.aleshym.co/Quaternions/card_game>
+   - <https://git.aleshym.co/Quaternions/klondike>
+2. Run:
+   ```bash
+   scripts/update_quaternions_deps.sh <klondike_version> <card_game_version>
+   ```
+3. If the script passes, inspect the resulting `Cargo.lock` diff and land the
+   upgrade with the normal PR flow.
+
+The script enforces:
+- lockfile update to requested versions
+- `cargo test --workspace`
+- `cargo clippy --workspace -- -D warnings`
+- deterministic replay/debug-API smoke tests in `solitaire_wasm`
+
+---
+
+## What Does NOT Need to Change
+
+- The `solitaire_engine` Bevy layer — it works against `solitaire_core` types; changes are isolated to `solitaire_core`.
+- The `solitaire_sync` merge logic — operates on a `SyncPayload` DTO, independent of core card types.
+- The `solitaire_server` — speaks only `SyncPayload` JSON, unaffected.
+
+---
+
+## References
+
+- Quaternions' repo: <https://git.aleshym.co/Quaternions/card_game>
+- `card_game v0.4.0` release commit: `fa098f0d`
+- `klondike v0.3.0` release commit: `f4c4e350`
+- Upstream scoring + config PRs: #12 (closes #11), #13 (closes #10)
+- Upstream solver PR: #14
+- `solitaire_core` source: `solitaire_core/src/`
+- Scoring implementation: `solitaire_core/src/game_state.rs`, `solitaire_core/src/klondike_adapter.rs`
+- Architecture overview: `ARCHITECTURE.md`
@@ -0,0 +1,408 @@
+# In-Place card_game / klondike Rewrite Plan
+
+**Date:** 2026-06-08  
+**Upstream rev:** `99b49e62`  
+**Status:** All phases complete (0–3). recycle_count drift and score compound error on undo fixed in `56e3b62`.
+
+---
+
+## 1. What Is Already Integrated
+
+The integration is substantially complete. `solitaire_core` already delegates all
+authoritative Klondike logic to the upstream crates.
+
+| Area | Status | Location |
+|---|---|---|
+| `Session<Klondike>` ownership | ✅ complete | `GameState.session` |
+| `draw()` → `session.process_instruction(RotateStock)` | ✅ complete | `game_state.rs` |
+| `move_cards()` → `session.process_instruction(KlondikeInstruction)` | ✅ complete | `game_state.rs` |
+| `undo()` → `session.undo()` | ✅ complete | `game_state.rs` |
+| `possible_instructions()` → `session.state().state().get_sorted_moves()` | ✅ complete | `game_state.rs` |
+| `can_move_cards()` → `session.state().state().is_instruction_valid()` | ✅ complete | `game_state.rs` |
+| `solver.rs` → `session.solve()` | ✅ complete | `solver.rs` |
+| `Suit`, `Rank` → re-export from `card_game` | ✅ complete | `card.rs` |
+| `Foundation`, `Klondike`, `KlondikePile`, `Session`, `Tableau` → `solitaire_core::lib` | ✅ complete | `lib.rs` |
+| Move legality enforcement | ✅ upstream (`is_instruction_valid`) | `klondike/src/lib.rs` |
+| Foundation placement rules (Ace start, suit match) | ✅ upstream | `klondike/src/lib.rs` |
+| Tableau placement rules (alternating colour, King on empty) | ✅ upstream | `klondike/src/lib.rs` |
+| Multi-card stack moves via `SkipCards` | ✅ upstream | `klondike/src/lib.rs` |
+| Session history / snapshot undo | ✅ upstream | `card_game/src/lib.rs` |
+| DFS solver with budget limits | ✅ upstream | `card_game/src/lib.rs` |
+| Instruction history → `SavedInstruction` serde mirrors | ✅ in adapter | `klondike_adapter.rs` |
+| Schema v3 save/load (instruction replay) | ✅ complete | `game_state.rs`, `storage.rs` |
+| `take_from_foundation` house rule → `MoveFromFoundationConfig` | ✅ complete | `klondike_adapter.rs` |
+
+---
+
+## 2. Duplicated / Replaceable Logic
+
+These are local implementations that either replicate upstream or could be removed.
+
+### 2a. `SavedInstruction` mirror types (~300 lines, `klondike_adapter.rs`)
+
+**What:** A full hand-written serde mirror for every upstream klondike instruction type
+(`SavedInstruction`, `SavedDstFoundation`, `SavedDstTableau`, `SavedKlondikePile`,
+`SavedKlondikePileStack`, `SavedTableauStack`, `SavedTableau`, `SavedFoundation`,
+`SavedSkipCards`, `InvalidSavedInstruction`) plus ~20 `From`/`TryFrom` conversion impls.
+
+**Why written:** At the time, upstream klondike had no serde feature.
+
+**Current upstream status:** At rev `99b49e62`, the `serde` feature is present and active.
+`KlondikeInstruction`, `KlondikePile`, `KlondikePileStack`, `DstFoundation`, `DstTableau`,
+`TableauStack`, `Tableau`, `Foundation`, `SkipCards` all derive
+`#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]`.
+
+**Blocker — JSON format incompatibility:**
+| Field | Local `SavedInstruction` JSON | Upstream `KlondikeInstruction` JSON |
+|---|---|---|
+| Tableau index | `{ "Tableau": 0 }` (u8) | `{ "Tableau": "Tableau1" }` (named) |
+| Foundation slot | `{ "Foundation": 0 }` (u8) | `{ "Foundation": "Foundation1" }` (named) |
+| Skip count | `{ "skip_cards": 0 }` (u8) | `{ "skip_cards": "Skip0" }` (named) |
+
+Switching to direct upstream serde **changes the `saved_moves` JSON shape** stored in
+`game_state.json`. Any existing v3 save file would fail to deserialize after the switch.
+This requires either:
+- A schema bump to v4 **with a migration** (deserialize v3 manually then re-save as v4), or
+- A schema bump to v4 **with graceful fallback** (v3 files rejected → fresh game).
+
+**Recommendation:** Schema v4 with graceful fallback (v3 saves start fresh). Migration
+is feasible but adds ~100 lines of throwaway code; the in-progress game loss is modest
+since schema v3 was never shipped to users (it landed in the current dev branch, not a
+release).
+
+### 2b. `GameState::check_win()` (~15 lines)
+
+**What:** Iterates all four foundation slots checking 13-card A→K sequences.  
+**Upstream equivalent:** `session.state().state().is_win()` on `Klondike`.  
+**Status:** Local check is correct but redundant. Trivially replaceable with no format change.  
+**Risk:** None — only affects `is_won` flag update path.
+
+### 2c. `GameState::check_auto_complete()` (~15 lines)
+
+**What:** Checks stock empty, waste empty, all tableau cards face-up.  
+**Upstream equivalent:** `session.state().state().is_win_trivial()` on `Klondike`.  
+**Semantic difference:** Upstream `is_win_trivial` checks `stock.is_empty()` (both faces)
+and all `tableau.face_down().is_empty()`. Ferrous additionally checks `waste.is_empty()`.
+These are logically equivalent for a valid game state (waste = stock face-up half).  
+**Risk:** Low — validated by existing auto-complete engine tests.
+
+### 2c. `recycle_count` drift on undo (existing bug, not new)
+
+**What:** `GameState.recycle_count` is incremented in `draw()` when stock is empty.
+`undo()` does not decrement it. After undoing a recycle, `recycle_count` is stale and
+may cause incorrect future penalty application.  
+**Upstream:** `KlondikeStats.recycle_count()` has the same problem — it is cumulative
+and not restored on undo (stats are not part of the session snapshot, only game state is).  
+**Fix approach:** After each undo, recompute `recycle_count` by scanning
+`session.history()` for `RotateStock` instructions that caused recycling.  
+**Priority:** Medium — affects scoring correctness in rare paths. File as a separate bug.
+
+---
+
+## 3. What Must Remain Ferrous-Specific
+
+These responsibilities are product-layer, not Klondike-rules-layer, and must stay in `solitaire_core`.
+
+| Responsibility | Why upstream cannot own it |
+|---|---|
+| WXP recycle penalties (free allowance + -100/-20) | `ScoringConfig::recycle` is a flat delta; no free-allowance concept exists upstream |
+| Score floor (`score.max(0)`) | Not modelled upstream |
+| Time bonus (`700_000 / elapsed_seconds`) | Not modelled upstream |
+| `DrawMode` / `GameMode` enums | Product concept; not in upstream |
+| Challenge mode undo block | Product rule |
+| Zen mode scoring suppression | Product rule |
+| `MoveError` variants for UI feedback | Upstream returns `bool`; Ferrous needs typed errors |
+| `card::Card` projection (adds `id`, `face_up`) | Renderer requires stable `id` and face orientation |
+| `Pile` DTO for engine sync | Renderer-facing snapshot type |
+| `stock_cards()` / `waste_cards()` distinction | Engine models waste as a separate pile; upstream uses stock face-up half |
+| `recycle_count` tracking | Needed for free-allowance penalty calculation |
+| Persistence format + schema versioning | Product concern |
+| `SavedInstruction` (currently) or upstream serde (after migration) | Either way, Ferrous owns the save contract |
+
+---
+
+## 4. Key Audit Findings
+
+### Finding 1 — Upstream serde claim in docs is stale
+
+`docs/card-game-integration.md` (last section "JSON Serialisation") states:
+
+> Current verification (2026-06-01): klondike v0.3.0 and card_game v0.4.0 crate manifests
+> expose no serde dependency/feature.
+
+**This is wrong at rev 99b49e62.** The `serde` feature is present and active. All nine
+instruction/pile types have `#[cfg_attr(feature = "serde", derive(...))]`. The doc must
+be updated.
+
+### Finding 2 — `take_from_foundation` default: docs vs code
+
+`docs/card-game-integration.md` says:
+> Ferrous Solitaire uses the standard rule (foundation cards cannot be moved back) as the
+> default, with the house rule as an opt-in.
+
+**The code and settings say the opposite:** `Settings::take_from_foundation` defaults to
+`true` (Allowed); `GameState.take_from_foundation` also initializes to `true`. Multiple
+tests assert this is the intended behavior. The upstream default is also `Allowed`.
+
+**Resolution:** The docs are wrong. Default = Allowed (house rule on by default for
+beginner-friendliness) is intentional. Update the docs; do not change the code.
+
+### Finding 3 — `KlondikeStats` cumulative vs session-history-aware counts
+
+`KlondikeStats.moves()` and `KlondikeStats.recycle_count()` accumulate monotonically.
+They are NOT restored when `Session::undo()` is called (only `Klondike` game state is
+restored from the snapshot, not the stats). Ferrous correctly uses
+`session.history().len()` for `move_count` (history-aware). But `recycle_count` is
+stored separately in `GameState` and also not decremented on undo — making them
+equivalent in this one bug.
+
+### Finding 4 — `SkipCards as usize` cast is correct
+
+Upstream `SkipCards` has no explicit discriminants, so `Skip0 = 0 .. Skip12 = 12`.
+`skip_cards as usize` in `solver.rs` and `game_state.rs` is correct.
+
+---
+
+## 5. Staged Migration
+
+### Phase 0 — Doc fixes only (no code change)
+
+Files: `docs/card-game-integration.md`
+
+- Correct the serde claim (upstream has serde at rev 99b49e62).
+- Correct the `take_from_foundation` default description.
+- Update integration status table.
+
+### Phase 1 — Delegate `is_win` / `is_win_trivial` (safe, no format change)
+
+Files: `solitaire_core/src/game_state.rs`
+
+Replace local `check_win()` and `check_auto_complete()` with upstream delegation:
+
+```rust
+// before
+pub fn check_win(&self) -> bool { ... 40 lines ... }
+
+// after  
+pub fn check_win(&self) -> bool {
+    self.session.state().state().is_win()
+}
+```
+
+```rust
+// before
+pub fn check_auto_complete(&self) -> bool { ... 15 lines ... }
+
+// after
+pub fn check_auto_complete(&self) -> bool {
+    self.session.state().state().is_win_trivial()
+}
+```
+
+**Risk:** Very low. Both methods are tested by existing integration tests. The semantic
+difference in `check_auto_complete` (upstream vs Ferrous definition) is equivalent for
+valid game states.
+
+### Phase 2 — Replace `SavedInstruction` with upstream serde (schema v4)
+
+Files:
+- `solitaire_core/src/klondike_adapter.rs` (remove ~300 lines)
+- `solitaire_core/src/game_state.rs` (update `Serialize`/`Deserialize` impls)
+- `solitaire_core/src/proptest_tests.rs` (remove now-redundant SavedInstruction tests)
+- `solitaire_data/src/storage.rs` (add schema v4 rejection test)
+- `solitaire_data/src/replay.rs` (no change — uses `SavedKlondikePile` independently)
+- `solitaire_wasm/src/lib.rs` (uses `SavedKlondikePileStack` in its own mirror — evaluate)
+
+**Steps:**
+1. In `game_state.rs`, change `PersistedGameState.saved_moves` from
+   `Vec<SavedInstruction>` to `Vec<KlondikeInstruction>` (upstream serde now works).
+2. Update `GameState::Serialize` to emit `KlondikeInstruction` directly.
+3. Update `GameState::Deserialize` to parse `KlondikeInstruction` directly.
+4. Increment `GAME_STATE_SCHEMA_VERSION` to 4.
+5. In `GameState::Deserialize`, reject schema != 4 with graceful fallback (already
+   handled by `load_game_state_from` returning `None` on serde error or wrong version).
+6. Delete `SavedInstruction`, `SavedDstFoundation`, `SavedDstTableau`, `SavedKlondikePile`,
+   `SavedKlondikePileStack`, `SavedTableauStack`, `SavedTableau`, `SavedFoundation`,
+   `SavedSkipCards`, `InvalidSavedInstruction` from `klondike_adapter.rs`.
+7. Delete the 20 `From`/`TryFrom` impls.
+8. Remove `SavedInstruction` proptest and boundary tests (no longer needed).
+9. Add schema v4 round-trip test and v3 rejection test.
+
+**Note on `solitaire_data::replay.rs`:**
+`replay.rs` uses `SavedKlondikePile` independently (for `ReplayMove`). This is a
+separate type from the game-state save format and is NOT changed by this phase.
+`ReplayMove` has its own schema (`REPLAY_SCHEMA_VERSION`) and can keep using the local
+mirror types.
+
+**Note on `solitaire_wasm/src/lib.rs`:**
+Uses `SavedKlondikePileStack` in its own `ReplayMove` mirror. Same as above — separate
+type, not affected.
+
+### Pre-Phase 3 — Undo Field Audit (completed 2026-06-08)
+
+Full audit of every Ferrous-owned field in `GameState` for undo correctness.
+
+| Field | Correctly updated by `undo()`? | Notes |
+|---|---|---|
+| `score` | ✅ By design | −15 WXP undo penalty applied; Zen: stays 0 |
+| `move_count` | ✅ Correct | Recomputed from `session.history().len()` |
+| `is_won` | ✅ Correct | Recomputed; undo blocked on won game |
+| `is_auto_completable` | ✅ Correct | Recomputed |
+| `undo_count` | ✅ By design | Total undos ever, intentionally non-reversible |
+| `elapsed_seconds` | ✅ Intentional | Timer is independent of moves |
+| `seed` / `draw_mode` / `mode` / `take_from_foundation` | ✅ Immutable | |
+| **`recycle_count`** | ❌ **Bug** | Not decremented — see below |
+
+**`recycle_count` drift bug:**
+
+`draw()` increments `recycle_count` when `stock.face_down().is_empty()` (the rotation
+is a recycle, not just a draw). `undo()` calls `session.undo()` which restores the
+`Klondike` card state, but does NOT decrement `recycle_count`.
+
+Consequence: if the player recycles, undoes it, then recycles again, `recycle_count`
+is `2` instead of `1` — the free-recycle allowance is consumed even though the first
+recycle was undone. On Draw-1, the 2nd recycle costs −100; after the undo-and-replay
+bug the player pays −100 for what should be their still-free recycle.
+
+**Score compound effect:** When `undo()` is applied to a recycle that incurred a
+penalty, the penalty amount (`score_after_recycle - 100`) is already in `self.score`.
+`apply_undo_score` then adds `−15` on top. The recycle penalty is never reversed.
+
+**Fix approach for Phase 3:**
+- After `session.undo()`, recompute `recycle_count` by scanning the new
+  `session.history()` for `RotateStock` snapshots where
+  `snapshot.state().state().stock().face_down().is_empty()` (indicating the rotation
+  was a recycle, not a draw from a populated stock).
+- Restore `score` to `snapshot_score` **before** the undone move, then apply only
+  the −15 undo penalty. This requires reading the score stored in `StateSnapshot`
+  or keeping a pre-move score stack alongside the session history.
+
+**Simpler alternative:** Store `(score_before, recycle_count_before)` in `GameState`
+alongside each `session.process_instruction` call, mirroring the snapshot stack.
+Undo pops this alongside the session undo.
+
+### Phase 3 — Fix `recycle_count` drift on undo (optional, post-approval)
+
+Files: `solitaire_core/src/game_state.rs`
+
+After `session.undo()`, recompute `recycle_count` by scanning `session.history()` for
+`RotateStock` snapshots where the pre-instruction stock face-down was empty (indicating
+a recycle). Also correct the score: restore to the pre-undone-move score and apply only
+the −15 undo penalty.
+
+**Tests to add:**
+- `recycle_count_decrements_when_recycle_is_undone`
+- `score_recycle_penalty_is_reversed_on_undo`
+
+**Risk:** Medium — changes observable scoring behavior. The fix is strictly more
+correct, but any golden-file or regression test that recorded the old (buggy) score
+after undo-of-recycle will need updating.
+
+---
+
+## 6. Files Likely to Change Per Phase
+
+| Phase | Files |
+|---|---|
+| Phase 0 | `docs/card-game-integration.md` |
+| Phase 1 | `solitaire_core/src/game_state.rs` |
+| Phase 2 | `solitaire_core/src/klondike_adapter.rs`, `solitaire_core/src/game_state.rs`, `solitaire_core/src/proptest_tests.rs`, `solitaire_data/src/storage.rs` |
+| Phase 3 | `solitaire_core/src/game_state.rs`, new test module |
+
+---
+
+## 7. Risks
+
+### R1 — Save file format break (Phase 2, HIGH)
+Users with v3 saves lose their in-progress game. Mitigated by the fact that v3 is
+not in any shipped release (dev branch only). Graceful fallback (start fresh) is
+acceptable; a migration shim is possible but not required.
+
+### R2 — `solitaire_wasm` / `solitaire_data::replay` breakage (Phase 2, MEDIUM)
+`SavedKlondikePile` and `SavedKlondikePileStack` are also used in `replay.rs` and
+`wasm/src/lib.rs`. These are separate from the game-state save format and must be
+left in place. Plan is to keep them in `klondike_adapter.rs` (or relocate to
+`replay.rs`) after the game-state mirror types are deleted.
+
+### R3 — `check_auto_complete` semantic drift (Phase 1, LOW)
+Upstream `is_win_trivial` checks `stock.is_empty()` (no cards at all in stock)
+whereas Ferrous also checks waste. These are equivalent for a valid game state but
+could differ under test-support pile overrides. Existing auto-complete tests will
+catch any regression.
+
+### R4 — `SkipCards as usize` cast correctness
+Already verified: enums have implicit 0..12 discriminants. No risk.
+
+### R5 — Upstream changes after rev pin
+The workspace is pinned to `rev = "99b49e62"`. No upstream drift risk until explicitly
+re-pinned.
+
+---
+
+## 8. Test Plan
+
+### Phase 1 tests (all currently pass)
+- `game_state::tests::take_from_foundation_allows_legal_return_move`
+- `game_state::tests::take_from_foundation_disabled_blocks_return_move_everywhere`
+- `proptest_tests::*` (card conservation, deal determinism, undo invariant, legal moves)
+
+### Phase 2 tests to add
+- `storage::tests::game_state_v4_mid_game_round_trip` — verify upstream serde round-trip
+  after migrating to `KlondikeInstruction` directly
+- `storage::tests::save_format_v3_is_rejected` — v3 files must return `None`
+- Update `game_state::tests::*` — all existing tests must continue to pass
+
+### Phase 2 tests to remove
+- `proptest_tests::saved_instruction_round_trip` — no longer needed (no mirror types)
+- `proptest_tests::saved_instruction_boundary_tests::*` — no longer needed
+
+### Phase 3 tests to add
+- `game_state::tests::recycle_count_decrements_on_undo` — after recycling and undoing,
+  `recycle_count` must reflect the correct post-undo count
+
+---
+
+## 9. Validation Commands
+
+Run after each phase:
+
+```bash
+# Targeted (fast)
+cargo test -p solitaire_core
+cargo clippy -p solitaire_core -- -D warnings
+
+# Broader
+cargo test -p solitaire_wasm
+cargo test -p solitaire_data
+
+# Full workspace (run before declaring phase complete)
+cargo test --workspace
+cargo clippy --workspace -- -D warnings
+```
+
+---
+
+## Summary: What Would Be Removed vs Kept
+
+### Removed after all phases complete
+| Code | Lines est. | Reason |
+|---|---|---|
+| `SavedInstruction` + 8 mirror types | ~150 | Upstream serde now available |
+| 20 `From`/`TryFrom` impls | ~150 | Upstream serde now available |
+| `InvalidSavedInstruction` error type | ~10 | Upstream serde now available |
+| `check_win()` local impl | ~20 | Replaced by `is_win()` delegation |
+| `check_auto_complete()` local impl | ~15 | Replaced by `is_win_trivial()` delegation |
+| `SavedInstruction` proptest + boundary tests | ~60 | Mirror types removed |
+
+**Total: ~400 lines removed from `solitaire_core`**
+
+### Remains Ferrous-specific
+- `KlondikeAdapter` scoring helpers (recycle penalties, score floor, time bonus, Zen/mode suppression)
+- `DrawMode`, `GameMode`, `DifficultyLevel`
+- `MoveError` and all boundary-checking logic
+- `card::Card` (id + face_up projection)
+- `Pile` DTO
+- `stock_cards()` / `waste_cards()` projections
+- Persistence format (`GameState` serde, schema version, `PersistedGameState`)
+- `solitaire_data::replay` types (`ReplayMove`, `SavedKlondikePile` mirror — unchanged)
+- `solitaire_wasm` replay mirror types (unchanged)
@@ -0,0 +1,115 @@
+# Testing Architecture — Engine-first Validation
+
+Ferrous Solitaire validation is split into three layers with clear ownership:
+
+1. **Rust unit tests (`solitaire_core`)**
+   - move generation and legality
+   - deal generation determinism
+   - scoring and penalties
+   - undo semantics
+   - win detection
+
+2. **Engine integration tests (`solitaire_wasm` debug API)**
+   - autonomous game execution without UI/pointer simulation
+   - invariant checks after every move
+   - deterministic seed replay
+   - high-volume seeded runs (including long-running soak tests)
+
+3. **Playwright UI tests**
+   - verify rendering vs engine state
+   - drag/drop and keyboard UX behavior
+   - responsive layout behavior
+   - browser-compatibility checks
+
+## Source of truth
+
+The Rust engine is authoritative. Browser tests must interact with the game via
+debug API hooks, not via pixel/OCR solving or hardcoded screen coordinates.
+
+## Debug API surfaces
+
+Two automation surfaces are exposed:
+
+- `solitaire_wasm::SolitaireGame` methods:
+  - `debug_snapshot()`
+  - `debug_legal_moves()`
+  - `debug_move_history()`
+  - `debug_apply_legal_move(index)`
+  - `debug_apply_move_json(json)`
+- Browser bridge on `game.html`:
+  - `window.__FERROUS_DEBUG__.snapshot()`
+  - `window.__FERROUS_DEBUG__.legalMoves()`
+  - `window.__FERROUS_DEBUG__.moveHistory()`
+  - `window.__FERROUS_DEBUG__.applyLegalMove(index)`
+  - `window.__FERROUS_DEBUG__.applyMove(move)`
+  - `window.__FERROUS_DEBUG__.failureReport()`
+  - `window.__FERROUS_DEBUG__.runAutoplay(options)`
+
+## Required failure payload
+
+Every automation failure should capture:
+
+- seed
+- move history
+- current game state
+- screenshot
+- browser trace
+- console logs
+
+`failureReport()` provides the engine-side fields (`seed`, `moveHistory`,
+`currentState`) so UI harnesses only need to attach browser artifacts.
+
+## Execution guidance
+
+- Fast verification:
+  - `cargo test -p solitaire_core -p solitaire_wasm`
+- Full verification:
+  - `cargo test --workspace`
+  - `cargo clippy --workspace -- -D warnings`
+- Long unattended soak:
+  - `cargo test -p solitaire_wasm debug_api_autonomous_thousands_seed_soak -- --ignored`
+
+### Browser e2e harness
+
+The Playwright suite lives under `solitaire_server/e2e/` and boots
+`solitaire_server` via Playwright `webServer` config.
+
+- Install + run:
+  - `cd solitaire_server/e2e`
+  - `npm ci`
+  - `npx playwright install chromium`
+  - `npm test`
+- Cycle metrics batch run:
+  - `cd solitaire_server/e2e`
+  - `npm run review:cycles -- --games 1000 --steps 350 --policy baseline --max-visits 1 --out /tmp/cycle-baseline.json`
+  - `npm run review:cycles -- --games 1000 --steps 350 --policy loop_aware --max-visits 2 --out /tmp/cycle-loop-aware.json`
+  - `npm run review:cycles:regression` (thresholded gate, writes `test-results/cycle-regression.json`)
+  - `npm run review:cycles:candidate` (loop-aware candidate run, writes `test-results/cycle-candidate.json`)
+
+### Cycle-risk regression baseline and guardrails
+
+- Current regression gate command:
+  - `npm run review:cycles:regression`
+  - config: `games=240`, `steps=350`, `policy=baseline`, `max-visits=1`
+- Current guardrail thresholds:
+  - `all.cycle_rate_pct <= 86`
+  - `draw1.cycle_rate_pct <= 76`
+  - `draw3.cycle_rate_pct <= 95`
+  - `all.win_rate_pct >= 14`
+  - zero invariant/apply/page/console issue counts
+- Baseline sample (240 games):
+  - overall: `win_rate=15.8%`, `cycle_rate=84.2%`
+  - draw-one: `win_rate=25.8%`, `cycle_rate=74.2%`
+  - draw-three: `win_rate=5.8%`, `cycle_rate=94.2%`
+- Candidate loop-aware sample (240 games, lookahead via simulated move + restore):
+  - overall: `win_rate=20.4%`, `cycle_rate=32.5%`
+  - draw-one: `win_rate=33.3%`, `cycle_rate=16.7%`
+  - draw-three: `win_rate=7.5%`, `cycle_rate=48.3%`
+  - no invariant/apply/page/console issues in the sampled run
+- Additional 500-game candidate soak:
+  - overall: `win_rate=20.2%`, `cycle_rate=28.6%`, `step_budget=51.2%`
+  - draw-three remains the dominant risk (`cycle_rate=45.2%`)
+- Fix applied: cycle metrics regression now supports explicit
+  `max_step_budget_rate_*` thresholds. Candidate command now enforces
+  `max_step_budget_rate_all <= 60` to prevent silent drift from cycles into
+  step-budget stalls.
@@ -0,0 +1,228 @@
+# Android testing
+
+This directory contains lightweight Android test helpers for Ferrous Solitaire.
+They are intended to run against either a physical Android device or an emulator
+connected through `adb`. When no device is connected the smoke script can
+automatically launch an AVD for you.
+
+## Prerequisites
+
+- Android SDK and NDK installed.
+- `adb` available on `PATH`.
+- One device/emulator visible in `adb devices`, **or** at least one AVD created
+  (the script will launch one automatically if `LAUNCH_AVD=1`, which is the default).
+- If multiple devices are connected, set `ADB_SERIAL` to the target device serial.
+- Environment variables required by `scripts/build_android_apk.sh` when building:
+
+```sh
+export ANDROID_HOME=/path/to/android-sdk
+export ANDROID_NDK_HOME=/path/to/android-ndk
+export BUILD_TOOLS_VERSION=34.0.0
+export PLATFORM=android-34
+```
+
+## Smoke test
+
+From the workspace root (`Rusty_Solitaire/`):
+
+```sh
+scripts/android_smoke.sh
+```
+
+The smoke test first checks whether `adb` can see a ready device. If no device
+is connected and `LAUNCH_AVD=1` (default), it:
+
+1. locates the `emulator` binary under `ANDROID_HOME` or `PATH`,
+2. picks the first available AVD (or uses `AVD_NAME`),
+3. launches the emulator in the foreground (or headless with `AVD_HEADLESS=1`),
+4. waits for `sys.boot_completed=1` before proceeding,
+5. dismisses the lock screen so the screenshot shows the app.
+
+Once a device is ready (auto-launched or pre-existing) the script:
+
+1. builds the APK using `scripts/build_android_apk.sh`,
+2. installs it with `adb install -r -d` so debug smoke builds can replace newer local builds,
+3. force-stops the package by default for a clean launch,
+4. clears `logcat`,
+5. launches `com.ferrousapp.solitaire/android.app.NativeActivity`,
+6. waits for the app to settle,
+7. verifies the process is still running,
+8. captures a screenshot and `logcat`, and
+9. fails on fatal log patterns such as native crashes, JNI fatal errors, real ANRs,
+   and Rust panics.
+
+On exit the script kills any emulator it launched (`SHUTDOWN_AVD_ON_EXIT=1` by
+default). Set `SHUTDOWN_AVD_ON_EXIT=0` to keep the emulator open for inspection.
+
+Artifacts are written to `target/android-smoke/<timestamp>/` by default. A successful run includes:
+
+- `device.txt` — selected device and display metadata,
+- `df-data-before.txt` / `df-data-after.txt` — emulator/device storage snapshots,
+- `emulator.log` — stdout/stderr from the emulator process (AVD runs only),
+- `emulator.pid` — PID of the emulator process (AVD runs only),
+- `launch.png` — screenshot after the wait period,
+- `logcat.txt` — full captured log,
+- `log-summary.txt` — grep summary for warnings, errors, JNI, safe-area, and crash terms, and
+- `pid.txt` — running app process id.
+
+## Creating an AVD
+
+If no AVDs exist, create one before running the smoke test:
+
+```sh
+# Install a system image
+"$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" \
+  'system-images;android-34;google_apis;x86_64'
+
+# Create the AVD
+"$ANDROID_HOME/cmdline-tools/latest/bin/avdmanager" create avd \
+  -n Pixel_7_API_34 \
+  -k 'system-images;android-34;google_apis;x86_64' \
+  --device 'pixel_7'
+```
+
+Then run the smoke test — it will pick `Pixel_7_API_34` automatically:
+
+```sh
+scripts/android_smoke.sh
+```
+
+## Faster iteration
+
+If you already built the APK and only want to reinstall/relaunch:
+
+```sh
+BUILD_APK=0 scripts/android_smoke.sh
+```
+
+If the APK is already installed and you only want to relaunch/capture logs:
+
+```sh
+BUILD_APK=0 INSTALL_APK=0 scripts/android_smoke.sh
+```
+
+By default the script force-stops the package before launch so logcat and screenshots represent a clean app start. To test warm-launch behavior instead:
+
+```sh
+BUILD_APK=0 INSTALL_APK=0 FORCE_STOP=0 scripts/android_smoke.sh
+```
+
+This is also useful when an already-installed build is good enough for launch/log checks. On install failure, the script writes `adb-install.txt`, storage snapshots, and installed-package diagnostics to the output directory.
+
+If install fails with `INSTALL_FAILED_UPDATE_INCOMPATIBLE`, the smoke script uninstalls the package and retries once by default (`RESET_ON_SIGNATURE_MISMATCH=1`). This resets app data on the device/emulator. Disable it with:
+
+```sh
+RESET_ON_SIGNATURE_MISMATCH=0 scripts/android_smoke.sh
+```
+
+To write artifacts to a stable path:
+
+```sh
+OUT_DIR=target/android-smoke/latest scripts/android_smoke.sh
+```
+
+When reusing an output directory, previous files are removed by default so stale artifacts do not contaminate the latest result. To keep existing files:
+
+```sh
+CLEAN_OUT_DIR=0 OUT_DIR=target/android-smoke/latest scripts/android_smoke.sh
+```
+
+To target a specific device when more than one is attached:
+
+```sh
+ADB_SERIAL=emulator-5554 scripts/android_smoke.sh
+```
+
+To wait longer for safe-area inset polling or slow devices:
+
+```sh
+WAIT_SECS=8 scripts/android_smoke.sh
+```
+
+## AVD options
+
+To pick a specific AVD by name instead of auto-selecting the first one:
+
+```sh
+AVD_NAME=Pixel_7_API_34 scripts/android_smoke.sh
+```
+
+To run headless (no emulator window) — useful in CI or on a display-less machine:
+
+```sh
+AVD_HEADLESS=1 scripts/android_smoke.sh
+```
+
+To give a slow machine more time to boot the emulator (default is 120 s):
+
+```sh
+AVD_BOOT_TIMEOUT=180 scripts/android_smoke.sh
+```
+
+To keep the emulator running after the test (useful for manual inspection):
+
+```sh
+SHUTDOWN_AVD_ON_EXIT=0 scripts/android_smoke.sh
+```
+
+To pass extra flags to the emulator (e.g. disable snapshot for a completely
+cold boot, or change GPU mode):
+
+```sh
+AVD_EXTRA_ARGS="-gpu swiftshader_indirect" scripts/android_smoke.sh
+```
+
+To disable AVD auto-launch entirely and fail immediately if no device is
+connected:
+
+```sh
+LAUNCH_AVD=0 scripts/android_smoke.sh
+```
+
+For build-only validation without requiring a connected device, use the lower-level APK builder directly:
+
+```sh
+scripts/build_android_apk.sh
+```
+
+For smoke testing, `scripts/android_smoke.sh` defaults to the connected device's primary ABI when `BUILD_APK=1`, which keeps emulator APKs much smaller than the full multi-ABI default. You can still override it explicitly:
+
+```sh
+ABIS=x86_64 scripts/android_smoke.sh
+```
+
+For build-only validation, `scripts/build_android_apk.sh` still defaults to all configured ABIs unless you set `ABIS` yourself:
+
+```sh
+ABIS=x86_64 scripts/build_android_apk.sh
+```
+
+The APK builder signs debug builds with a persistent keystore at `target/android/debug.keystore` by default. This avoids signature churn across smoke-test runs.
+
+The APK builder also strips native debug symbols by default before packaging (`STRIP_NATIVE_LIBS=1`). This keeps debug APKs installable on emulators with limited `/data` storage. To preserve native debug symbols for low-level debugging:
+
+```sh
+STRIP_NATIVE_LIBS=0 ABIS=x86_64 scripts/build_android_apk.sh
+```
+
+## Device checklist
+
+The script is only a smoke test. Before shipping Android builds, also verify:
+
+- safe-area insets arrive and shift the HUD after a few seconds,
+- HUD does not overlap the top status bar,
+- modal Done buttons are above the gesture/navigation bar,
+- stock tap works,
+- drag-and-drop works on tableau, waste, and foundation piles,
+- Settings/Help/Profile modals open and close,
+- login tokens persist after app restart, and
+- `target/android-smoke/.../logcat.txt` contains no fatal JNI/native crash output.
+
+## Notes
+
+- `adb shell input tap X Y` uses physical pixels, not Bevy logical pixels.
+- The project’s common test device mapping is physical `1080×2400`, Bevy logical
+  `900×2000`, scale factor `1.20`; multiply logical coordinates by `1.20` for
+  scripted `adb shell input` commands on that device.
+- Keep generated screenshots/logs under `target/android-smoke/` so they stay out
+  of source control.
@@ -0,0 +1,362 @@
+#!/usr/bin/env bash
+# Android smoke test for Ferrous Solitaire.
+#
+# Builds (optional), installs, launches, captures logcat + screenshot, and
+# fails on fatal Android log patterns. Designed as a lightweight device/emulator
+# sanity check rather than a full UI automation suite.
+#
+# Required:
+#   adb on PATH
+#   Android SDK/NDK env required by scripts/build_android_apk.sh when BUILD_APK=1
+#
+# Optional environment:
+#   BUILD_APK=1|0          Build APK before install (default: 1)
+#   INSTALL_APK=1|0        Install APK before launch (default: 1)
+#   RESET_ON_SIGNATURE_MISMATCH=1|0
+#                           Uninstall/retry if debug signatures differ (default: 1)
+#   LAUNCH_APP=1|0         Launch app before checks (default: 1)
+#   FORCE_STOP=1|0         Force-stop package before launch for clean logs (default: 1)
+#   CAPTURE_SCREENSHOT=1|0 Capture screenshot (default: 1)
+#   ADB_SERIAL=...         Device serial to use when multiple devices are connected
+#   APK_PATH=...           APK to install (default: target/debug/apk/ferrous-solitaire.apk)
+#   PACKAGE=...            Android package (default: com.ferrousapp.solitaire)
+#   ACTIVITY=...           Activity class (default: android.app.NativeActivity)
+#   OUT_DIR=...            Artifact directory (default: target/android-smoke/<timestamp>)
+#   CLEAN_OUT_DIR=1|0      Remove prior artifacts from OUT_DIR first (default: 1)
+#   WAIT_SECS=...          Seconds to wait after launch (default: 5)
+#   ABIS=...               Passed to build script. If unset and BUILD_APK=1,
+#                           defaults to the connected device's primary ABI.
+#
+# AVD auto-launch (used when no device/emulator is already connected):
+#   LAUNCH_AVD=1|0         Auto-launch an AVD when no device is ready (default: 1)
+#   AVD_NAME=...           AVD name to launch (default: first from `emulator -list-avds`)
+#   AVD_BOOT_TIMEOUT=...   Seconds to wait for the emulator to finish booting (default: 120)
+#   AVD_HEADLESS=1|0       Run with -no-window -no-audio for CI/no-display environments (default: 0)
+#   AVD_EXTRA_ARGS=...     Extra arguments appended verbatim to the emulator command line
+#   SHUTDOWN_AVD_ON_EXIT=1|0
+#                           Kill the AVD this script launched on exit (default: 1).
+#                           Set to 0 to leave the emulator running after the test.
+#
+# Examples:
+#   scripts/android_smoke.sh
+#   BUILD_APK=0 scripts/android_smoke.sh
+#   LAUNCH_AVD=0 scripts/android_smoke.sh            # error out if no device, never auto-launch
+#   AVD_NAME=Pixel_7_API_34 scripts/android_smoke.sh
+#   AVD_HEADLESS=1 scripts/android_smoke.sh          # CI / no-display
+#   SHUTDOWN_AVD_ON_EXIT=0 scripts/android_smoke.sh  # keep emulator open after test
+#   OUT_DIR=target/android-smoke/latest WAIT_SECS=8 scripts/android_smoke.sh
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+BUILD_APK="${BUILD_APK:-1}"
+INSTALL_APK="${INSTALL_APK:-1}"
+RESET_ON_SIGNATURE_MISMATCH="${RESET_ON_SIGNATURE_MISMATCH:-1}"
+LAUNCH_APP="${LAUNCH_APP:-1}"
+FORCE_STOP="${FORCE_STOP:-1}"
+CAPTURE_SCREENSHOT="${CAPTURE_SCREENSHOT:-1}"
+APK_PATH="${APK_PATH:-target/debug/apk/ferrous-solitaire.apk}"
+PACKAGE="${PACKAGE:-com.ferrousapp.solitaire}"
+ACTIVITY="${ACTIVITY:-android.app.NativeActivity}"
+WAIT_SECS="${WAIT_SECS:-5}"
+OUT_DIR="${OUT_DIR:-target/android-smoke/$(date +%Y%m%d-%H%M%S)}"
+CLEAN_OUT_DIR="${CLEAN_OUT_DIR:-1}"
+REMOTE_SCREENSHOT="/sdcard/ferrous-solitaire-smoke.png"
+
+LAUNCH_AVD="${LAUNCH_AVD:-1}"
+AVD_NAME="${AVD_NAME:-}"
+AVD_BOOT_TIMEOUT="${AVD_BOOT_TIMEOUT:-120}"
+AVD_HEADLESS="${AVD_HEADLESS:-0}"
+AVD_EXTRA_ARGS="${AVD_EXTRA_ARGS:-}"
+SHUTDOWN_AVD_ON_EXIT="${SHUTDOWN_AVD_ON_EXIT:-1}"
+
+ADB=(adb)
+if [ -n "${ADB_SERIAL:-}" ]; then
+  ADB+=( -s "$ADB_SERIAL" )
+fi
+
+# PID of any emulator we start so the EXIT trap can clean it up.
+_LAUNCHED_EMULATOR_PID=""
+
+_cleanup_emulator() {
+  if [ -n "$_LAUNCHED_EMULATOR_PID" ] && [ "$SHUTDOWN_AVD_ON_EXIT" = "1" ]; then
+    echo ">>> shutdown emulator (PID $_LAUNCHED_EMULATOR_PID)"
+    kill "$_LAUNCHED_EMULATOR_PID" 2>/dev/null || true
+  fi
+}
+trap _cleanup_emulator EXIT
+
+require_cmd() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "missing required command: $1" >&2
+    exit 1
+  }
+}
+
+mkdir -p "$OUT_DIR"
+if [ "$CLEAN_OUT_DIR" = "1" ]; then
+  find "$OUT_DIR" -mindepth 1 -maxdepth 1 -exec rm -rf {} +
+fi
+require_cmd adb
+
+# ---------------------------------------------------------------------------
+# Device / emulator availability
+# ---------------------------------------------------------------------------
+DEVICE_STATE="$("${ADB[@]}" get-state 2>/dev/null || true)"
+if [ "$DEVICE_STATE" != "device" ]; then
+  if [ "$LAUNCH_AVD" != "1" ]; then
+    adb devices > "$OUT_DIR/adb-devices.txt" 2>&1 || true
+    if [ -n "${ADB_SERIAL:-}" ]; then
+      echo "Android device '$ADB_SERIAL' is not connected/ready (state: ${DEVICE_STATE:-unknown})." >&2
+    else
+      echo "No Android device/emulator is connected and ready." >&2
+    fi
+    echo "Run 'adb devices' or start an emulator, then retry." >&2
+    echo "Device list saved to $OUT_DIR/adb-devices.txt" >&2
+    exit 1
+  fi
+
+  # --- locate emulator binary -----------------------------------------------
+  # Priority: ANDROID_HOME env → PATH → common SDK install locations.
+  _find_sdk_root() {
+    for candidate in \
+        "$HOME/Android/Sdk" \
+        "$HOME/Library/Android/sdk" \
+        "/opt/android-sdk" \
+        "/usr/lib/android-sdk"; do
+      [ -d "$candidate" ] && echo "$candidate" && return
+    done
+  }
+
+  EMULATOR_BIN=""
+  if [ -n "${ANDROID_HOME:-}" ] && [ -x "$ANDROID_HOME/emulator/emulator" ]; then
+    EMULATOR_BIN="$ANDROID_HOME/emulator/emulator"
+  elif command -v emulator >/dev/null 2>&1; then
+    EMULATOR_BIN="$(command -v emulator)"
+  else
+    _SDK_ROOT="$(_find_sdk_root)"
+    if [ -n "$_SDK_ROOT" ] && [ -x "$_SDK_ROOT/emulator/emulator" ]; then
+      EMULATOR_BIN="$_SDK_ROOT/emulator/emulator"
+    fi
+  fi
+
+  if [ -z "$EMULATOR_BIN" ]; then
+    echo "No Android device found and 'emulator' binary is not available." >&2
+    echo "  • Install the Android SDK emulator component, or" >&2
+    echo "  • Set ANDROID_HOME to your SDK root, or" >&2
+    echo "  • Start a device/emulator manually then retry with LAUNCH_AVD=0." >&2
+    exit 1
+  fi
+  echo ">>> emulator binary: $EMULATOR_BIN"
+
+  # --- select AVD -----------------------------------------------------------
+  if [ -z "$AVD_NAME" ]; then
+    AVD_NAME="$("$EMULATOR_BIN" -list-avds 2>/dev/null | head -n 1 | tr -d '\r')"
+    if [ -z "$AVD_NAME" ]; then
+      echo "No AVDs found. Create one first, for example:" >&2
+      echo "  sdkmanager 'system-images;android-34;google_apis;x86_64'" >&2
+      echo "  avdmanager create avd -n Pixel_7_API_34 \\" >&2
+      echo "    -k 'system-images;android-34;google_apis;x86_64' --device 'pixel_7'" >&2
+      exit 1
+    fi
+    echo ">>> auto-selected AVD: $AVD_NAME"
+  fi
+
+  # --- launch emulator -------------------------------------------------------
+  EMULATOR_ARGS=( -avd "$AVD_NAME" -no-snapshot-load )
+  [ "$AVD_HEADLESS" = "1" ] && EMULATOR_ARGS+=( -no-window -no-audio )
+  # Split AVD_EXTRA_ARGS on whitespace only (disable glob expansion).
+  set -f
+  # shellcheck disable=SC2206
+  [ -n "$AVD_EXTRA_ARGS" ] && EMULATOR_ARGS+=( $AVD_EXTRA_ARGS )
+  set +f
+
+  echo ">>> launch emulator: $AVD_NAME"
+  "$EMULATOR_BIN" "${EMULATOR_ARGS[@]}" > "$OUT_DIR/emulator.log" 2>&1 &
+  _LAUNCHED_EMULATOR_PID=$!
+  echo "$_LAUNCHED_EMULATOR_PID" > "$OUT_DIR/emulator.pid"
+  echo "    emulator PID: $_LAUNCHED_EMULATOR_PID"
+  echo "    emulator log: $OUT_DIR/emulator.log"
+
+  # --- wait for adb transport -----------------------------------------------
+  # Poll adb get-state (≠ wait-for-device which blocks indefinitely) so we can
+  # honour AVD_BOOT_TIMEOUT for the whole boot sequence.
+  echo ">>> waiting for device to appear in adb (timeout: ${AVD_BOOT_TIMEOUT}s)"
+  _ELAPSED=0
+  while true; do
+    _STATE="$("${ADB[@]}" get-state 2>/dev/null || true)"
+    if [ "$_STATE" = "device" ] || [ "$_STATE" = "offline" ]; then
+      break
+    fi
+    if [ "$_ELAPSED" -ge "$AVD_BOOT_TIMEOUT" ]; then
+      echo "Device did not appear in adb within ${AVD_BOOT_TIMEOUT}s" >&2
+      echo "emulator log:" >&2
+      tail -20 "$OUT_DIR/emulator.log" >&2 || true
+      exit 1
+    fi
+    sleep 3
+    _ELAPSED=$(( _ELAPSED + 3 ))
+    echo "    ... ${_ELAPSED}s / ${AVD_BOOT_TIMEOUT}s"
+  done
+
+  # Capture emulator serial (emulator-5554 etc.) so all subsequent adb calls
+  # target the right device when ADB_SERIAL was not set by the caller.
+  if [ -z "${ADB_SERIAL:-}" ]; then
+    _EMU_SERIAL="$(adb devices 2>/dev/null | awk '/^emulator-/{print $1; exit}' | tr -d '\r')"
+    if [ -n "$_EMU_SERIAL" ]; then
+      ADB_SERIAL="$_EMU_SERIAL"
+      ADB=(adb -s "$ADB_SERIAL")
+      echo ">>> detected emulator serial: $ADB_SERIAL"
+    fi
+  fi
+
+  # --- wait for full Android boot -------------------------------------------
+  # adb get-state returning "device" means the transport is up, but the
+  # Android framework may still be initialising. Poll sys.boot_completed.
+  echo ">>> waiting for boot_completed (timeout: ${AVD_BOOT_TIMEOUT}s)"
+  _BOOT_ELAPSED=0
+  _BOOT_INTERVAL=5
+  while true; do
+    _BOOT="$("${ADB[@]}" shell getprop sys.boot_completed 2>/dev/null | tr -d '\r')"
+    if [ "$_BOOT" = "1" ]; then
+      echo ">>> emulator boot complete"
+      break
+    fi
+    if [ "$_BOOT_ELAPSED" -ge "$AVD_BOOT_TIMEOUT" ]; then
+      echo "Emulator did not finish booting within ${AVD_BOOT_TIMEOUT}s" >&2
+      echo "emulator log:" >&2
+      tail -20 "$OUT_DIR/emulator.log" >&2 || true
+      exit 1
+    fi
+    sleep "$_BOOT_INTERVAL"
+    _BOOT_ELAPSED=$(( _BOOT_ELAPSED + _BOOT_INTERVAL ))
+    echo "    ... ${_BOOT_ELAPSED}s / ${AVD_BOOT_TIMEOUT}s (boot_completed='${_BOOT}')"
+  done
+
+  # Dismiss the lock screen so later screencap shows the app, not the keyguard.
+  "${ADB[@]}" shell input keyevent 82 2>/dev/null || true
+
+  # Final sanity check — device must be fully ready before we proceed.
+  DEVICE_STATE="$("${ADB[@]}" get-state 2>/dev/null || true)"
+  if [ "$DEVICE_STATE" != "device" ]; then
+    echo "Emulator is running but adb state is '${DEVICE_STATE:-unknown}'." >&2
+    exit 1
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Device metadata
+# ---------------------------------------------------------------------------
+{
+  echo "adb_serial=${ADB_SERIAL:-default}"
+  echo "package=$PACKAGE"
+  echo "activity=$ACTIVITY"
+  echo "device_state=$DEVICE_STATE"
+  "${ADB[@]}" shell getprop ro.product.model 2>/dev/null | tr -d '\r' | sed 's/^/product_model=/'
+  "${ADB[@]}" shell getprop ro.build.version.release 2>/dev/null | tr -d '\r' | sed 's/^/android_release=/'
+  "${ADB[@]}" shell getprop ro.build.version.sdk 2>/dev/null | tr -d '\r' | sed 's/^/android_sdk=/'
+  "${ADB[@]}" shell wm size 2>/dev/null | tr -d '\r' | sed 's/^/wm_size=/'
+  "${ADB[@]}" shell wm density 2>/dev/null | tr -d '\r' | sed 's/^/wm_density=/'
+} > "$OUT_DIR/device.txt"
+"${ADB[@]}" shell df -h /data > "$OUT_DIR/df-data-before.txt" 2>&1 || true
+
+if [ "$BUILD_APK" = "1" ]; then
+  if [ -z "${ABIS:-}" ]; then
+    DEVICE_ABI="$("${ADB[@]}" shell getprop ro.product.cpu.abi 2>/dev/null | tr -d '\r')"
+    case "$DEVICE_ABI" in
+      x86_64|arm64-v8a|armeabi-v7a)
+        export ABIS="$DEVICE_ABI"
+        ;;
+      armeabi*)
+        export ABIS="armeabi-v7a"
+        ;;
+      *)
+        echo "Could not map device ABI '$DEVICE_ABI'; using build script default ABIS." >&2
+        ;;
+    esac
+  fi
+  echo ">>> build Android APK${ABIS:+ (ABIS=$ABIS)}"
+  scripts/build_android_apk.sh
+fi
+
+if [ "$INSTALL_APK" = "1" ]; then
+  [ -f "$APK_PATH" ] || {
+    echo "APK not found: $APK_PATH" >&2
+    echo "Set APK_PATH or run with BUILD_APK=1." >&2
+    exit 1
+  }
+  ls -lh "$APK_PATH" > "$OUT_DIR/apk.txt"
+  echo ">>> install $APK_PATH"
+  if ! "${ADB[@]}" install -r -d "$APK_PATH" > "$OUT_DIR/adb-install.txt" 2>&1; then
+    if [ "$RESET_ON_SIGNATURE_MISMATCH" = "1" ] && grep -q "INSTALL_FAILED_UPDATE_INCOMPATIBLE" "$OUT_DIR/adb-install.txt"; then
+      echo ">>> signature mismatch; uninstalling $PACKAGE and retrying install"
+      "${ADB[@]}" uninstall "$PACKAGE" > "$OUT_DIR/adb-uninstall-before-retry.txt" 2>&1 || true
+      if "${ADB[@]}" install -r -d "$APK_PATH" > "$OUT_DIR/adb-install-retry.txt" 2>&1; then
+        cat "$OUT_DIR/adb-install-retry.txt" >> "$OUT_DIR/adb-install.txt"
+      else
+        cat "$OUT_DIR/adb-install.txt" >&2
+        cat "$OUT_DIR/adb-install-retry.txt" >&2
+        "${ADB[@]}" shell df -h /data > "$OUT_DIR/df-data-after-install-failure.txt" 2>&1 || true
+        "${ADB[@]}" shell pm list packages | grep -F "$PACKAGE" > "$OUT_DIR/installed-package.txt" 2>&1 || true
+        echo "APK install retry failed. Diagnostics saved in $OUT_DIR" >&2
+        exit 1
+      fi
+    else
+      cat "$OUT_DIR/adb-install.txt" >&2
+      "${ADB[@]}" shell df -h /data > "$OUT_DIR/df-data-after-install-failure.txt" 2>&1 || true
+      "${ADB[@]}" shell pm list packages | grep -F "$PACKAGE" > "$OUT_DIR/installed-package.txt" 2>&1 || true
+      echo "APK install failed. Diagnostics saved in $OUT_DIR" >&2
+      echo "If the package is already installed and you only need launch/log checks, retry with INSTALL_APK=0." >&2
+      exit 1
+    fi
+  fi
+fi
+
+if [ "$FORCE_STOP" = "1" ]; then
+  echo ">>> force-stop $PACKAGE"
+  "${ADB[@]}" shell am force-stop "$PACKAGE" || true
+fi
+
+echo ">>> clear logcat"
+"${ADB[@]}" logcat -c
+
+if [ "$LAUNCH_APP" = "1" ]; then
+  echo ">>> launch $PACKAGE/$ACTIVITY"
+  "${ADB[@]}" shell am start -n "$PACKAGE/$ACTIVITY" > "$OUT_DIR/am-start.txt"
+fi
+
+echo ">>> wait ${WAIT_SECS}s"
+sleep "$WAIT_SECS"
+
+PID="$("${ADB[@]}" shell pidof "$PACKAGE" | tr -d '\r' || true)"
+if [ -z "$PID" ]; then
+  "${ADB[@]}" logcat -d > "$OUT_DIR/logcat.txt" || true
+  echo "app process is not running after launch: $PACKAGE" >&2
+  echo "logcat saved to $OUT_DIR/logcat.txt" >&2
+  exit 1
+fi
+echo "$PID" > "$OUT_DIR/pid.txt"
+
+if [ "$CAPTURE_SCREENSHOT" = "1" ]; then
+  echo ">>> capture screenshot"
+  "${ADB[@]}" shell screencap -p "$REMOTE_SCREENSHOT"
+  "${ADB[@]}" pull "$REMOTE_SCREENSHOT" "$OUT_DIR/launch.png" >/dev/null
+  "${ADB[@]}" shell rm -f "$REMOTE_SCREENSHOT" >/dev/null 2>&1 || true
+fi
+
+echo ">>> capture logcat"
+"${ADB[@]}" logcat -d > "$OUT_DIR/logcat.txt"
+grep -iE "panic|fatal|jni|native crash|\bANR\b|exception|error|warn|keystore|safe_area" "$OUT_DIR/logcat.txt" > "$OUT_DIR/log-summary.txt" || true
+"${ADB[@]}" shell df -h /data > "$OUT_DIR/df-data-after.txt" 2>&1 || true
+
+# Fatal patterns only. Avoid matching generic "error" because Android logs are
+# noisy and many non-fatal framework lines contain that word.
+if grep -iE "fatal exception|jni detected error|native crash|signal [0-9]+|ANR in|Application Not Responding|Input dispatching timed out|thread exiting with uncaught exception|panicked at" "$OUT_DIR/logcat.txt"; then
+  echo "Android smoke test found fatal log output" >&2
+  echo "Artifacts saved in $OUT_DIR" >&2
+  exit 1
+fi
+
+echo ">>> Android smoke test passed"
+echo "Artifacts saved in $OUT_DIR"
@@ -6,11 +6,15 @@
 # ndk-build crate that we couldn't isolate; running each Android toolchain
 # step explicitly gives us a debuggable pipeline.
 #
-# Required environment:
-#   ANDROID_HOME            Path to Android SDK root
-#   ANDROID_NDK_HOME        Path to the specific NDK version
-#   BUILD_TOOLS_VERSION     e.g. "34.0.0"
-#   PLATFORM                e.g. "android-34"
+# Environment:
+#   ANDROID_HOME            Path to Android SDK root. If unset, common SDK
+#                           locations such as ~/Android/Sdk are tried.
+#   ANDROID_NDK_HOME        Path to the specific NDK version. If unset, the
+#                           newest $ANDROID_HOME/ndk/* directory is used.
+#   BUILD_TOOLS_VERSION     e.g. "34.0.0". If unset, newest installed build-tools
+#                           version is used.
+#   PLATFORM                e.g. "android-34". If unset, newest installed
+#                           $ANDROID_HOME/platforms/android-* platform is used.
 #
 # Optional environment:
 #   PROFILE                 "debug" (default) | "release"
@@ -19,7 +23,8 @@
 #                           fit the runner's disk budget — a full three-ABI
 #                           debug build can exceed 25 GB of target/ output.
 #   APK_OUT                 Output APK path (default: target/$PROFILE/apk/ferrous-solitaire.apk)
-#   KEYSTORE                Path to keystore for signing (default: generates a debug keystore)
+#   STRIP_NATIVE_LIBS       1 to strip .so files before packaging (default: 1)
+#   KEYSTORE                Path to keystore for signing (default: target/android/debug.keystore)
 #   KEYSTORE_PASS           Keystore password (default: "android" for the generated debug keystore)
 #   KEY_ALIAS               Key alias (default: "androiddebugkey")
 #   KEY_PASS                Key password (default: same as KEYSTORE_PASS)
@@ -28,18 +33,63 @@
 #   $APK_OUT                Signed, zipaligned APK
 set -euo pipefail

-: "${ANDROID_HOME:?ANDROID_HOME must be set}"
-: "${ANDROID_NDK_HOME:?ANDROID_NDK_HOME must be set}"
-: "${BUILD_TOOLS_VERSION:?BUILD_TOOLS_VERSION must be set}"
-: "${PLATFORM:?PLATFORM must be set (e.g. android-34)}"
+infer_latest_dir_name() {
+  local pattern="$1"
+  local latest=""
+  shopt -s nullglob
+  local dirs=( $pattern )
+  shopt -u nullglob
+  if [ ${#dirs[@]} -gt 0 ]; then
+    latest="$(printf '%s\n' "${dirs[@]}" | sort -V | tail -n 1)"
+    basename "$latest"
+  fi
+}
+
+if [ -z "${ANDROID_HOME:-}" ]; then
+  for candidate in "$HOME/Android/Sdk" "$HOME/Library/Android/sdk" "/opt/android-sdk" "/usr/lib/android-sdk"; do
+    if [ -d "$candidate" ]; then
+      ANDROID_HOME="$candidate"
+      export ANDROID_HOME
+      break
+    fi
+  done
+fi
+: "${ANDROID_HOME:?ANDROID_HOME must be set or discoverable under a common SDK path}"
+
+if [ -z "${ANDROID_NDK_HOME:-}" ]; then
+  NDK_VERSION="$(infer_latest_dir_name "$ANDROID_HOME/ndk/*")"
+  if [ -n "$NDK_VERSION" ]; then
+    ANDROID_NDK_HOME="$ANDROID_HOME/ndk/$NDK_VERSION"
+    export ANDROID_NDK_HOME
+  fi
+fi
+: "${ANDROID_NDK_HOME:?ANDROID_NDK_HOME must be set or discoverable under ANDROID_HOME/ndk}"
+
+if [ -z "${BUILD_TOOLS_VERSION:-}" ]; then
+  BUILD_TOOLS_VERSION="$(infer_latest_dir_name "$ANDROID_HOME/build-tools/*")"
+  export BUILD_TOOLS_VERSION
+fi
+: "${BUILD_TOOLS_VERSION:?BUILD_TOOLS_VERSION must be set or discoverable under ANDROID_HOME/build-tools}"
+
+if [ -z "${PLATFORM:-}" ]; then
+  PLATFORM="$(infer_latest_dir_name "$ANDROID_HOME/platforms/android-*")"
+  export PLATFORM
+fi
+: "${PLATFORM:?PLATFORM must be set or discoverable under ANDROID_HOME/platforms}"

 PROFILE="${PROFILE:-debug}"
 ABIS="${ABIS:-arm64-v8a armeabi-v7a x86_64}"
 APK_OUT="${APK_OUT:-target/${PROFILE}/apk/ferrous-solitaire.apk}"
+STRIP_NATIVE_LIBS="${STRIP_NATIVE_LIBS:-1}"

 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$REPO_ROOT"

+echo ">>> Android SDK: $ANDROID_HOME"
+echo ">>> Android NDK: $ANDROID_NDK_HOME"
+echo ">>> Build tools: $BUILD_TOOLS_VERSION"
+echo ">>> Platform: $PLATFORM"
+
 BT="$ANDROID_HOME/build-tools/$BUILD_TOOLS_VERSION"
 PLATFORM_JAR="$ANDROID_HOME/platforms/$PLATFORM/android.jar"
 MANIFEST="solitaire_app/android/AndroidManifest.xml"
@@ -69,6 +119,24 @@ fi
 echo ">>> cargo ndk ${CARGO_NDK_ARGS[*]}"
 cargo ndk "${CARGO_NDK_ARGS[@]}"

+if [ "$STRIP_NATIVE_LIBS" = "1" ]; then
+  LLVM_STRIP=""
+  shopt -s nullglob
+  STRIP_CANDIDATES=( "$ANDROID_NDK_HOME"/toolchains/llvm/prebuilt/*/bin/llvm-strip )
+  shopt -u nullglob
+  if [ ${#STRIP_CANDIDATES[@]} -gt 0 ]; then
+    LLVM_STRIP="${STRIP_CANDIDATES[0]}"
+  fi
+  if [ -z "$LLVM_STRIP" ]; then
+    echo "llvm-strip not found under ANDROID_NDK_HOME; native libraries will remain unstripped" >&2
+  else
+    echo ">>> strip native libraries with $LLVM_STRIP"
+    find "$STAGING/lib" -name '*.so' -print0 | while IFS= read -r -d '' so; do
+      "$LLVM_STRIP" --strip-debug "$so"
+    done
+  fi
+fi
+
 # --- 2. compile + link resources and manifest ------------------------------
 if [ -d "$RES_DIR" ]; then
  echo ">>> aapt2 compile resources"
@@ -120,11 +188,15 @@ rm -f "$STAGING/app-unsigned.apk"

 # --- 5. sign ---------------------------------------------------------------
 if [ -z "${KEYSTORE:-}" ]; then
-  # Generate a deterministic debug keystore on the fly.
-  KEYSTORE="$STAGING/debug.keystore"
-  KEYSTORE_PASS="${KEYSTORE_PASS:-android}"
-  KEY_ALIAS="${KEY_ALIAS:-androiddebugkey}"
-  KEY_PASS="${KEY_PASS:-$KEYSTORE_PASS}"
+  KEYSTORE="target/android/debug.keystore"
+fi
+
+KEYSTORE_PASS="${KEYSTORE_PASS:-android}"
+KEY_ALIAS="${KEY_ALIAS:-androiddebugkey}"
+KEY_PASS="${KEY_PASS:-$KEYSTORE_PASS}"
+
+if [ ! -f "$KEYSTORE" ]; then
+  mkdir -p "$(dirname "$KEYSTORE")"
  echo ">>> generating debug keystore at $KEYSTORE"
  keytool -genkeypair -v \
    -keystore "$KEYSTORE" \
@@ -141,15 +213,35 @@ KEY_PASS="${KEY_PASS:-$KEYSTORE_PASS}"

 mkdir -p "$(dirname "$APK_OUT")"
 echo ">>> apksigner sign -> $APK_OUT"
+# Sign the schemes explicitly instead of relying on apksigner's auto behaviour.
+# Left to "auto", this pipeline produced an APK carrying invalid v1 (JAR)
+# signature files (META-INF/*.SF/.RSA present but failing v1 verification).
+# Android installs it fine via v2/v3, but Obtainium parses the APK's legacy v1
+# certificate at install time, gets an empty cert list, and crashes with
+# "RangeError (length): Invalid value: valid value range is empty: 0".
+# minSdk is 26 (solitaire_app/android/AndroidManifest.xml), so v1/JAR signing is
+# not needed at all — disable it and ship a clean v2+v3 signature, matching what
+# modern Android tooling produces for minSdk >= 24.
 "$BT/apksigner" sign \
  --ks "$KEYSTORE" \
  --ks-pass "pass:$KEYSTORE_PASS" \
  --ks-key-alias "$KEY_ALIAS" \
  --key-pass "pass:$KEY_PASS" \
+  --min-sdk-version 26 \
+  --v1-signing-enabled false \
+  --v2-signing-enabled true \
+  --v3-signing-enabled true \
  --out "$APK_OUT" \
  "$STAGING/app-aligned.apk"

 echo ">>> verify"
-"$BT/apksigner" verify --verbose "$APK_OUT"
+"$BT/apksigner" verify --min-sdk-version 26 --verbose "$APK_OUT"
+
+# Guard: no leftover v1/JAR signature files may remain — their presence (valid or
+# not) is what tripped Obtainium. Fail the build if any slipped through.
+if unzip -l "$APK_OUT" 2>/dev/null | grep -qiE 'META-INF/.*\.(SF|RSA|DSA|EC)$'; then
+  echo "ERROR: APK still contains v1/JAR signature files; expected v2+v3 only" >&2
+  exit 1
+fi

 echo ">>> done: $APK_OUT"
@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Update Quaternions registry dependencies and run the full safety gate.
+#
+# Usage:
+#   scripts/update_quaternions_deps.sh <klondike_version> <card_game_version>
+#
+# Example:
+#   scripts/update_quaternions_deps.sh 0.3.1 0.4.1
+#
+# This script updates Cargo.lock to the requested versions (within the semver
+# ranges already declared in Cargo.toml), then runs the project's required
+# verification steps plus deterministic replay checks.
+set -euo pipefail
+
+if [ "$#" -ne 2 ]; then
+  echo "usage: $0 <klondike_version> <card_game_version>"
+  exit 2
+fi
+
+KLONDIKE_VERSION="$1"
+CARD_GAME_VERSION="$2"
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+cd "$REPO_ROOT"
+
+echo ">>> Quaternions registry:"
+echo "    https://git.aleshym.co/api/packages/Quaternions/cargo/"
+echo
+echo ">>> Review upstream release notes / changelogs before proceeding:"
+echo "    - https://git.aleshym.co/Quaternions/card_game"
+echo "    - https://git.aleshym.co/Quaternions/klondike"
+echo
+
+echo ">>> Updating lockfile to klondike=$KLONDIKE_VERSION card_game=$CARD_GAME_VERSION"
+cargo update -p klondike --precise "$KLONDIKE_VERSION"
+cargo update -p card_game --precise "$CARD_GAME_VERSION"
+
+echo ">>> Verifying dependency graph"
+cargo tree -p solitaire_core --depth 2 | cat
+
+echo ">>> Running workspace tests"
+cargo test --workspace
+
+echo ">>> Running workspace clippy"
+cargo clippy --workspace -- -D warnings
+
+echo ">>> Running deterministic replay / debug-api smoke checks"
+cargo test -p solitaire_wasm debug_snapshot_exposes_replayable_seed_and_history -- --exact
+cargo test -p solitaire_wasm debug_api_autonomous_seed_batch_smoke -- --exact
+
+echo ">>> Quaternions dependency upgrade gate passed"
@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Live-watch the Gitea Actions deploy pipeline for Ferrous Solitaire.
+#
+# Polls recent workflow runs and prints a compact status block each cycle.
+# Stops when the newest docker-build (the deploy) has completed and no
+# web-wasm-rebuild is still pending — i.e. the full fix is live.
+#
+# Usage:  ./scripts/watch_deploy.sh [interval_seconds]
+#   token is read from ~/.config/tea/config.yml (never printed).
+set -uo pipefail
+
+REPO="funman300/Ferrous-Solitaire"
+BASE="https://git.aleshym.co/api/v1/repos/${REPO}"
+INTERVAL="${1:-20}"
+CFG="${HOME}/.config/tea/config.yml"
+
+TOKEN="$(grep -E '^[[:space:]]*token:' "$CFG" | head -1 | sed -E 's/.*token:[[:space:]]*//' | tr -d '"'\'' ')"
+[ -z "$TOKEN" ] && { echo "error: no token in $CFG" >&2; exit 1; }
+
+echo "── watching ${REPO} deploy (poll ${INTERVAL}s, Ctrl-C to stop) ──"
+
+while :; do
+  json="$(curl -s --max-time 20 -H "Authorization: token ${TOKEN}" "${BASE}/actions/runs?limit=6")"
+  # Print rows + emit the deploy state on the last line (parsed below).
+  # JSON is passed via env var because `python3 -` reads its program from the
+  # heredoc on stdin, so stdin can't also carry the data.
+  out="$(JSON_DATA="$json" python3 - <<'PY'
+import os, sys, json, datetime
+now = datetime.datetime.now().strftime("%H:%M:%S")
+raw = os.environ.get("JSON_DATA", "").strip()
+try:
+    d = json.loads(raw)
+except Exception:
+    print("[%s] (api unavailable, retrying)" % now)
+    print("STATE=DEPLOYING")
+    sys.exit(0)
+runs = d.get("workflow_runs", [])[:6]
+icons = {("completed","success"):"OK  ", ("completed","failure"):"FAIL",
+         ("completed","cancelled"):"CXL "}
+def ic(s, c):
+    if s == "queued": return "queue"
+    if s == "in_progress": return "run.."
+    return icons.get((s, c), s or "?")
+print("[%s]" % datetime.datetime.now().strftime("%H:%M:%S"))
+for r in runs:
+    wf = str(r.get("path","")).split("@")[0].split("/")[-1].replace(".yml","")
+    print("   %-5s %-5s %-7s %-18s %s/%s" % (
+        ic(r.get("status"), r.get("conclusion")),
+        r.get("id"), str(r.get("head_sha"))[:7], wf[:18],
+        r.get("status"), r.get("conclusion")))
+db = [r for r in runs if "docker-build" in str(r.get("path"))]
+wr_pending = any(r.get("status") != "completed" for r in runs if "web-wasm-rebuild" in str(r.get("path")))
+top = db[0] if db else None
+live = bool(top and top.get("status")=="completed" and top.get("conclusion")=="success" and not wr_pending)
+print("STATE=%s" % ("LIVE" if live else ("WAIT_WASM" if wr_pending else "DEPLOYING")))
+PY
+)"
+  echo "$out" | grep -v '^STATE='
+  if echo "$out" | grep -q '^STATE=LIVE'; then
+    echo ""
+    echo "DEPLOY LIVE — newest docker-build succeeded, no wasm rebuild pending."
+    echo "   Test: https://klondike.aleshym.co/play?v=${RANDOM}"
+    break
+  fi
+  sleep "$INTERVAL"
+done
@@ -22,6 +22,13 @@ bevy             = { workspace = true }
 solitaire_engine = { workspace = true }
 solitaire_data   = { workspace = true }

+# Android-only: the entry point reconstructs the raw `JavaVM` / activity
+# handles and registers the safe `solitaire_data::android_jni` bridge. This
+# is the one crate in the workspace that performs `unsafe` FFI, so it is also
+# the only one that depends on `jni` directly at the app layer.
+[target.'cfg(target_os = "android")'.dependencies]
+jni = { workspace = true }
+
 # Desktop-only deps. `keyring`'s default-store init only matters on
 # platforms with a real keychain backend (Linux Secret Service,
 # macOS Keychain, Windows Credential Store), and its transitive
@@ -99,3 +106,18 @@ icon = "@mipmap/ic_launcher"
 # in portrait orientation. Remove (or add a landscape layout) before
 # enabling auto-rotate.
 orientation = "portrait"
+
+# `solitaire_app` is the one crate that cannot inherit the workspace
+# `forbid(unsafe_code)`: as the Android cdylib it must export the
+# `#[unsafe(no_mangle)]` entry point and reconstruct the raw JNI handles
+# there (a `no_mangle` symbol cannot live in a dependency rlib). It mirrors
+# the workspace lints but at `deny`, so the two `#[allow(unsafe_code)]`
+# scopes in the Android entry point are the only unsafe in the whole tree.
+[lints.rust]
+unsafe_code = "deny"
+single_use_lifetimes = "warn"
+trivial_casts = "warn"
+unused_lifetimes = "warn"
+unused_qualifications = "warn"
+variant_size_differences = "warn"
+unexpected_cfgs = "warn"
@@ -25,7 +25,10 @@ use bevy::window::{MonitorSelection, PresentMode, WindowPosition};
 use bevy::winit::WinitWindows;
 #[cfg(target_os = "android")]
 use bevy::winit::{UpdateMode, WinitSettings};
-use solitaire_data::{Settings, load_settings_from, provider_for_backend, settings_file_path};
+use solitaire_data::{
+    Settings, cleanup_orphaned_tmp_files, load_settings_from, provider_for_backend,
+    settings_file_path,
+};
 use solitaire_engine::{CoreGamePlugin, SyncProvider, register_theme_asset_sources};

 fn load_settings() -> Settings {
@@ -49,6 +52,12 @@ pub fn run() {
    // and any debugger attached still sees the panic).
    install_crash_log_hook();

+    // Remove any *.tmp files left behind by a crash between an atomic write
+    // and its rename.  Safe to call unconditionally — missing data dir is a
+    // no-op.  Must run before GamePlugin loads saved state so orphaned files
+    // don't accumulate across launches.
+    let _ = cleanup_orphaned_tmp_files();
+
    // Initialise the platform keyring store before any token operations.
    // On Linux this uses the Secret Service (GNOME Keyring / KWallet); on
    // macOS it uses the Keychain; on Windows it uses the Credential store.
@@ -56,10 +65,9 @@ pub fn run() {
    // operations will fail gracefully with TokenError::KeychainUnavailable.
    //
    // Android: `keyring` isn't compiled in (its `rpassword` transitive
-    // pulls a libc symbol Android's bionic doesn't expose). `auth_tokens`
-    // ships an Android stub that returns KeychainUnavailable for every
-    // call — the runtime behaviour is "session login required each launch"
-    // until we wire Android Keystore via JNI in the Phase-Android round.
+    // pulls a libc symbol Android's bionic doesn't expose). The Android
+    // auth-token path uses Android Keystore via JNI; `android_main` passes
+    // the process JavaVM pointer into `solitaire_data` before `run()`.
    #[cfg(not(target_os = "android"))]
    if let Err(e) = keyring::use_native_store(true) {
        eprintln!(
@@ -136,7 +144,7 @@ fn build_app_with_settings(
                    // Android windows always fill the screen; max_width/max_height
                    // default to 0.0, which panics Bevy's clamp when min > max.
                    #[cfg(not(target_os = "android"))]
-                    resize_constraints: bevy::window::WindowResizeConstraints {
+                    resize_constraints: WindowResizeConstraints {
                        min_width: 800.0,
                        min_height: 600.0,
                        ..default()
@@ -158,7 +166,7 @@ fn build_app_with_settings(
            // default makes it walk *out* of the APK's assets root and
            // all loads fail silently — which is what produced the
            // solid-red card-back fallback in the v0.22.3 screenshot.
-            .set(bevy::asset::AssetPlugin {
+            .set(AssetPlugin {
                #[cfg(not(target_os = "android"))]
                file_path: "../assets".to_string(),
                ..default()
@@ -172,13 +180,16 @@ fn build_app_with_settings(
    // a 1-second ceiling when the app is backgrounded cuts wake-up frequency
    // from ~60 Hz to ≤1 Hz, dramatically reducing background battery drain.
    //
-    // The focused mode stays Continuous so that card-slide animations remain
-    // smooth. PresentMode::AutoVsync (set above) keeps the GPU capped at the
-    // display refresh rate (~60 Hz) when foregrounded, which already prevents
-    // the GPU from spinning at 200+ fps between vsync intervals.
+    // focused_mode uses reactive_low_power(100 ms) so the CPU only wakes when
+    // an event arrives (touch, resize, etc.) or an animation system writes
+    // RequestRedraw. The 100 ms ceiling is a fallback that ensures the game
+    // timer ticks at least 10×/s even with no input, while keeping the GPU
+    // completely idle between frames when the board is static.
+    // PresentMode::AutoVsync (set above) still caps the GPU at the display
+    // refresh rate when frames do render.
    #[cfg(target_os = "android")]
    app.insert_resource(WinitSettings {
-        focused_mode: UpdateMode::Continuous,
+        focused_mode: UpdateMode::reactive_low_power(std::time::Duration::from_millis(100)),
        unfocused_mode: UpdateMode::reactive_low_power(std::time::Duration::from_secs(1)),
    });

@@ -352,12 +363,57 @@ fn set_window_icon(
 /// works on a function named `main`; our shared entry point is `run`, so
 /// we emit the equivalent expansion manually.
 #[cfg(target_os = "android")]
+#[allow(unsafe_code)]
 #[unsafe(no_mangle)]
 fn android_main(android_app: bevy::android::android_activity::AndroidApp) {
+    if let Err(e) = init_android_jni(&android_app) {
+        eprintln!("warn: could not initialise Android JNI bridge ({e})");
+    }
    let _ = bevy::android::ANDROID_APP.set(android_app);
    run();
 }

+/// Reconstructs the raw `JavaVM` / `NativeActivity` handles handed over by the
+/// Android runtime and registers safe wrappers with `solitaire_data`.
+///
+/// This is the *only* place in the workspace that performs `unsafe` FFI handle
+/// reconstruction. Every other crate consumes the safe
+/// [`solitaire_data::android_jni`] bridge and stays `forbid(unsafe_code)`;
+/// `solitaire_app` opts down to `deny` with a narrowly scoped allow on this
+/// function and the `#[unsafe(no_mangle)]` entry point above.
+#[cfg(target_os = "android")]
+#[allow(unsafe_code)]
+fn init_android_jni(
+    android_app: &bevy::android::android_activity::AndroidApp,
+) -> Result<(), String> {
+    use jni::JavaVM;
+    use jni::objects::JObject;
+
+    let vm_ptr = android_app.vm_as_ptr();
+    if vm_ptr.is_null() {
+        return Err("JavaVM pointer is null".into());
+    }
+    // SAFETY: `vm_as_ptr()` returns the process-wide JavaVM* established by the
+    // Android runtime; it is valid for the lifetime of the process.
+    let vm = unsafe { JavaVM::from_raw(vm_ptr.cast()) }.map_err(|e| format!("JavaVM: {e}"))?;
+
+    let env = vm
+        .attach_current_thread_permanently()
+        .map_err(|e| format!("attach_current_thread: {e}"))?;
+
+    // SAFETY: `activity_as_ptr()` returns the NativeActivity jobject pointer,
+    // valid for the lifetime of the process. Promote it to a global reference
+    // so the safe bridge can hand it to any thread.
+    let activity = unsafe { JObject::from_raw(android_app.activity_as_ptr().cast()) };
+    let activity_ref = env
+        .new_global_ref(&activity)
+        .map_err(|e| format!("activity global ref: {e}"))?;
+
+    solitaire_data::android_jni::set_jvm(vm);
+    solitaire_data::android_jni::set_activity(activity_ref);
+    Ok(())
+}
+
 /// Wraps the default panic hook with one that also appends a crash log
 /// to `<data_dir>/crash.log` (next to `settings.json`). The default hook
 /// still runs afterwards, so stderr output and debugger integration are
@@ -30,3 +30,6 @@ path = "src/bin/gen_seeds.rs"
 [[bin]]
 name = "gen_difficulty_seeds"
 path = "src/bin/gen_difficulty_seeds.rs"
+
+[lints]
+workspace = true
@@ -2,10 +2,10 @@
 //! `HARD_SEEDS`, `EXPERT_SEEDS`, and `GRANDMASTER_SEEDS` in
 //! `solitaire_data/src/difficulty_seeds.rs`.
 //!
-//! A seed's tier is determined by the **smallest** `SolverConfig` budget that
-//! returns `SolverResult::Winnable`. Seeds that are `Unwinnable` at any budget
-//! are discarded; `Inconclusive` at all budgets are also discarded (we only emit
-//! provably-winnable seeds).
+//! A seed's tier is determined by the **smallest** solve budget at which it is
+//! proven winnable (`Ok(Some(_))`). Seeds proven dead (`Ok(None)`) at any budget
+//! are discarded; seeds inconclusive (`Err`) at all budgets are also discarded
+//! (we only emit provably-winnable seeds).
 //!
 //! # Usage
 //!
@@ -19,12 +19,12 @@
 //!   --per-tier  Seeds to emit per tier (default 40)
 //!   --help      Print this message

-use solitaire_core::game_state::DrawMode;
-use solitaire_core::solver::{SolverConfig, SolverResult, try_solve};
+use solitaire_core::DrawStockConfig;
+use solitaire_core::game_state::GameState;

 // Budget boundaries defining each tier. A seed belongs to the lowest tier
 // whose budget proves it Winnable.
-const BUDGETS: &[(&str, u64, usize)] = &[
+const BUDGETS: &[(&str, u64, u64)] = &[
    ("Easy", 1_000, 1_000),
    ("Medium", 5_000, 5_000),
    ("Hard", 25_000, 25_000),
@@ -74,7 +74,7 @@ fn main() {
        std::process::exit(1);
    }

-    let draw_mode = DrawMode::DrawOne;
+    let draw_mode = DrawStockConfig::DrawOne;
    let num_tiers = BUDGETS.len();
    let mut buckets: Vec<Vec<u64>> = vec![Vec::with_capacity(per_tier); num_tiers];
    let mut tried: u64 = 0;
@@ -99,12 +99,8 @@ fn main() {
            if buckets[i].len() >= per_tier {
                continue;
            }
-            let cfg = SolverConfig {
-                move_budget,
-                state_budget,
-            };
-            match try_solve(seed, draw_mode, &cfg) {
-                SolverResult::Winnable => {
+            match GameState::solve_fresh_deal(seed, draw_mode, move_budget, state_budget) {
+                Ok(Some(_)) => {
                    buckets[i].push(seed);
                    eprintln!(
                        "  [{name}  {:>3}/{}]  0x{seed:016X}  (tried {tried})",
@@ -113,13 +109,13 @@ fn main() {
                    );
                    break 'tier; // assign to the cheapest tier that proves it winnable
                }
-                SolverResult::Unwinnable => {
+                Ok(None) => {
                    // Definitely unsolvable — skip all remaining tiers.
                    break 'tier;
                }
-                SolverResult::Inconclusive => {
+                Err(_) => {
                    // Budget exhausted without proof — try the next larger tier.
-                    // If this is the last tier, the seed is discarded (Inconclusive
+                    // If this is the last tier, the seed is discarded (inconclusive
                    // at max budget means "probably but not provably winnable").
                    if i == num_tiers - 1 {
                        break 'tier;
@@ -1,7 +1,7 @@
 //! Generate provably-winnable Klondike seeds for `CHALLENGE_SEEDS`.
 //!
 //! Walks seeds incrementally from `--start`, calls the solver on each, and
-//! collects only those that return `SolverResult::Winnable` (Inconclusive is
+//! collects only those proven winnable (`Ok(Some(_))`; inconclusive is
 //! rejected — the curated list wants proof). Prints Rust source suitable for
 //! pasting into `solitaire_data/src/challenge.rs`.
 //!
@@ -17,8 +17,9 @@
 //!   --count  Number of Winnable seeds to emit (default 75)
 //!   --help   Print this message

-use solitaire_core::game_state::DrawMode;
-use solitaire_core::solver::{SolverConfig, SolverResult, try_solve};
+use solitaire_core::DrawStockConfig;
+use solitaire_core::game_state::GameState;
+use solitaire_core::{DEFAULT_SOLVE_MOVES_BUDGET, DEFAULT_SOLVE_STATES_BUDGET};

 fn main() {
    let mut args = std::env::args().skip(1).peekable();
@@ -67,8 +68,7 @@ fn main() {
        std::process::exit(1);
    }

-    let cfg = SolverConfig::default();
-    let draw_mode = DrawMode::DrawOne;
+    let draw_mode = DrawStockConfig::DrawOne;
    let mut found: Vec<u64> = Vec::with_capacity(count);
    let mut tried: u64 = 0;
    let mut seed = start;
@@ -77,7 +77,15 @@ fn main() {

    while found.len() < count {
        tried += 1;
-        if matches!(try_solve(seed, draw_mode, &cfg), SolverResult::Winnable) {
+        if matches!(
+            GameState::solve_fresh_deal(
+                seed,
+                draw_mode,
+                DEFAULT_SOLVE_MOVES_BUDGET,
+                DEFAULT_SOLVE_STATES_BUDGET
+            ),
+            Ok(Some(_))
+        ) {
            found.push(seed);
            eprintln!(
                "  [{:>3}/{}]  0x{:016X}  ({} tried so far)",
@@ -4,7 +4,18 @@ version.workspace = true
 license.workspace = true
 edition.workspace = true

+[features]
+default = []
+test-support = []
+
+[dev-dependencies]
+proptest = "1"
+
 [dependencies]
 serde     = { workspace = true }
 thiserror = { workspace = true }
-rand      = { workspace = true }
+klondike  = { workspace = true }
+card_game = { workspace = true }
+
+[lints]
+workspace = true
@@ -1,169 +0,0 @@
-use serde::{Deserialize, Serialize};
-
-/// Card suit.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
-pub enum Suit {
-    Clubs,
-    Diamonds,
-    Hearts,
-    Spades,
-}
-
-impl Suit {
-    /// All four suits in declaration order.
-    pub const SUITS: [Self; 4] = [Self::Clubs, Self::Diamonds, Self::Hearts, Self::Spades];
-
-    /// Returns `true` for red suits (Diamonds, Hearts).
-    pub fn is_red(self) -> bool {
-        matches!(self, Suit::Diamonds | Suit::Hearts)
-    }
-
-    /// Returns `true` for black suits (Clubs, Spades).
-    pub fn is_black(self) -> bool {
-        !self.is_red()
-    }
-}
-
-/// Card rank, Ace through King.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
-pub enum Rank {
-    Ace = 1,
-    Two = 2,
-    Three = 3,
-    Four = 4,
-    Five = 5,
-    Six = 6,
-    Seven = 7,
-    Eight = 8,
-    Nine = 9,
-    Ten = 10,
-    Jack = 11,
-    Queen = 12,
-    King = 13,
-}
-
-impl Rank {
-    /// All thirteen ranks in ascending order.
-    pub const RANKS: [Self; 13] = [
-        Self::Ace,
-        Self::Two,
-        Self::Three,
-        Self::Four,
-        Self::Five,
-        Self::Six,
-        Self::Seven,
-        Self::Eight,
-        Self::Nine,
-        Self::Ten,
-        Self::Jack,
-        Self::Queen,
-        Self::King,
-    ];
-
-    /// Numeric value: Ace = 1, King = 13.
-    pub fn value(self) -> u8 {
-        self as u8
-    }
-
-    const fn new(n: u8) -> Option<Self> {
-        match n {
-            1 => Some(Self::Ace),
-            2 => Some(Self::Two),
-            3 => Some(Self::Three),
-            4 => Some(Self::Four),
-            5 => Some(Self::Five),
-            6 => Some(Self::Six),
-            7 => Some(Self::Seven),
-            8 => Some(Self::Eight),
-            9 => Some(Self::Nine),
-            10 => Some(Self::Ten),
-            11 => Some(Self::Jack),
-            12 => Some(Self::Queen),
-            13 => Some(Self::King),
-            _ => None,
-        }
-    }
-
-    /// Returns the rank `n` steps above `self`, or `None` if it would exceed King.
-    pub const fn checked_add(self, n: u8) -> Option<Self> {
-        Self::new((self as u8).saturating_add(n))
-    }
-
-    /// Returns the rank `n` steps below `self`, or `None` if it would go below Ace.
-    pub const fn checked_sub(self, n: u8) -> Option<Self> {
-        match (self as u8).checked_sub(n) {
-            Some(v) => Self::new(v),
-            None => None,
-        }
-    }
-}
-
-/// A single playing card.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct Card {
-    /// Unique identifier for this card within the deal. Stable across moves and undo.
-    pub id: u32,
-    /// The card's suit (Clubs, Diamonds, Hearts, Spades).
-    pub suit: Suit,
-    /// The card's rank (Ace through King).
-    pub rank: Rank,
-    /// Whether the card is visible to the player. Face-down cards may not be moved.
-    pub face_up: bool,
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn rank_values_are_sequential() {
-        for (i, r) in Rank::RANKS.iter().enumerate() {
-            assert_eq!(r.value(), (i + 1) as u8);
-        }
-    }
-
-    #[test]
-    fn rank_as_u8_matches_value() {
-        for r in Rank::RANKS {
-            assert_eq!(r as u8, r.value());
-        }
-    }
-
-    #[test]
-    fn rank_checked_add_boundary() {
-        assert_eq!(Rank::King.checked_add(1), None);
-        assert_eq!(Rank::Queen.checked_add(1), Some(Rank::King));
-        assert_eq!(Rank::Ace.checked_add(1), Some(Rank::Two));
-        assert_eq!(Rank::Five.checked_add(3), Some(Rank::Eight));
-    }
-
-    #[test]
-    fn rank_checked_sub_boundary() {
-        assert_eq!(Rank::Ace.checked_sub(1), None);
-        assert_eq!(Rank::Two.checked_sub(1), Some(Rank::Ace));
-        assert_eq!(Rank::King.checked_sub(1), Some(Rank::Queen));
-        assert_eq!(Rank::Five.checked_sub(3), Some(Rank::Two));
-    }
-
-    #[test]
-    fn suit_suits_contains_all_four() {
-        assert_eq!(Suit::SUITS.len(), 4);
-        assert!(Suit::SUITS.contains(&Suit::Clubs));
-        assert!(Suit::SUITS.contains(&Suit::Diamonds));
-        assert!(Suit::SUITS.contains(&Suit::Hearts));
-        assert!(Suit::SUITS.contains(&Suit::Spades));
-    }
-
-    #[test]
-    fn suit_red_and_black_are_complementary() {
-        for suit in [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades] {
-            assert_ne!(
-                suit.is_red(),
-                suit.is_black(),
-                "{suit:?} must be exactly one of red/black"
-            );
-        }
-        assert!(Suit::Diamonds.is_red() && Suit::Hearts.is_red());
-        assert!(Suit::Clubs.is_black() && Suit::Spades.is_black());
-    }
-}
@@ -1,193 +0,0 @@
-use crate::card::{Card, Rank, Suit};
-use crate::pile::{Pile, PileType};
-use rand::rngs::StdRng;
-use rand::{SeedableRng, seq::SliceRandom};
-
-const ALL_SUITS: [Suit; 4] = [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades];
-const ALL_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,
-];
-
-/// A standard 52-card deck.
-pub struct Deck {
-    /// All 52 cards in the deck, in deal order.
-    pub cards: Vec<Card>,
-}
-
-impl Deck {
-    /// Creates an unshuffled deck with all 52 unique cards (id 0–51).
-    pub fn new() -> Self {
-        let mut cards = Vec::with_capacity(52);
-        let mut id = 0u32;
-        for &suit in &ALL_SUITS {
-            for &rank in &ALL_RANKS {
-                cards.push(Card {
-                    id,
-                    suit,
-                    rank,
-                    face_up: false,
-                });
-                id += 1;
-            }
-        }
-        Self { cards }
-    }
-
-    /// Shuffles the deck in-place using Fisher-Yates with a seeded `StdRng`.
-    /// The same seed always produces the same order on any platform.
-    pub fn shuffle(&mut self, seed: u64) {
-        let mut rng = StdRng::seed_from_u64(seed);
-        self.cards.shuffle(&mut rng);
-    }
-}
-
-impl Default for Deck {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-/// Deals a standard Klondike layout from a pre-shuffled deck.
-///
-/// Returns 7 tableau piles and the remaining stock pile.
-/// Column `i` contains `i + 1` cards; only the top card is face-up.
-/// Stock receives the remaining 24 cards, all face-down.
-pub fn deal_klondike(deck: Deck) -> ([Pile; 7], Pile) {
-    debug_assert_eq!(
-        deck.cards.len(),
-        52,
-        "deal_klondike requires a full 52-card deck"
-    );
-    let mut tableau: [Pile; 7] = core::array::from_fn(|i| Pile::new(PileType::Tableau(i)));
-    // Safety: the debug_assert above documents the 52-card contract; index arithmetic is bounded.
-    let mut idx = 0usize;
-
-    for (col, pile) in tableau.iter_mut().enumerate() {
-        for row in 0..=col {
-            let mut card = deck.cards[idx].clone();
-            card.face_up = row == col;
-            pile.cards.push(card);
-            idx += 1;
-        }
-    }
-
-    let mut stock = Pile::new(PileType::Stock);
-    stock.cards.extend(deck.cards.into_iter().skip(idx));
-    (tableau, stock)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn deck_new_has_52_cards() {
-        assert_eq!(Deck::new().cards.len(), 52);
-    }
-
-    #[test]
-    fn deck_new_has_unique_ids() {
-        let deck = Deck::new();
-        let mut ids: Vec<u32> = deck.cards.iter().map(|c| c.id).collect();
-        ids.sort_unstable();
-        ids.dedup();
-        assert_eq!(ids.len(), 52);
-    }
-
-    #[test]
-    fn deck_new_has_all_suits_and_ranks() {
-        let deck = Deck::new();
-        for suit in ALL_SUITS {
-            for rank in ALL_RANKS {
-                assert!(
-                    deck.cards.iter().any(|c| c.suit == suit && c.rank == rank),
-                    "missing {rank:?} {suit:?}"
-                );
-            }
-        }
-    }
-
-    #[test]
-    fn same_seed_produces_same_order() {
-        let mut d1 = Deck::new();
-        d1.shuffle(42);
-        let mut d2 = Deck::new();
-        d2.shuffle(42);
-        assert_eq!(d1.cards, d2.cards);
-    }
-
-    #[test]
-    fn different_seeds_produce_different_orders() {
-        let mut d1 = Deck::new();
-        d1.shuffle(1);
-        let mut d2 = Deck::new();
-        d2.shuffle(2);
-        assert_ne!(d1.cards, d2.cards);
-    }
-
-    #[test]
-    fn deal_klondike_correct_tableau_sizes() {
-        let mut deck = Deck::new();
-        deck.shuffle(0);
-        let (tableau, stock) = deal_klondike(deck);
-        for (i, pile) in tableau.iter().enumerate() {
-            assert_eq!(pile.cards.len(), i + 1, "col {i} wrong size");
-        }
-        assert_eq!(stock.cards.len(), 24);
-    }
-
-    #[test]
-    fn deal_klondike_top_cards_are_face_up() {
-        let mut deck = Deck::new();
-        deck.shuffle(0);
-        let (tableau, _) = deal_klondike(deck);
-        for pile in &tableau {
-            assert!(pile.cards.last().unwrap().face_up);
-        }
-    }
-
-    #[test]
-    fn deal_klondike_non_top_cards_are_face_down() {
-        let mut deck = Deck::new();
-        deck.shuffle(0);
-        let (tableau, _) = deal_klondike(deck);
-        for pile in &tableau {
-            for card in &pile.cards[..pile.cards.len().saturating_sub(1)] {
-                assert!(!card.face_up);
-            }
-        }
-    }
-
-    #[test]
-    fn deal_klondike_stock_is_face_down() {
-        let mut deck = Deck::new();
-        deck.shuffle(0);
-        let (_, stock) = deal_klondike(deck);
-        assert!(stock.cards.iter().all(|c| !c.face_up));
-    }
-
-    #[test]
-    fn deal_klondike_all_52_cards_present() {
-        let mut deck = Deck::new();
-        deck.shuffle(99);
-        let (tableau, stock) = deal_klondike(deck);
-        let mut ids: Vec<u32> = stock.cards.iter().map(|c| c.id).collect();
-        for pile in &tableau {
-            ids.extend(pile.cards.iter().map(|c| c.id));
-        }
-        ids.sort_unstable();
-        assert_eq!(ids, (0u32..52).collect::<Vec<_>>());
-    }
-}
@@ -0,0 +1,85 @@
+//! Adapter bridging `solitaire_core` types to the upstream `klondike` crate.
+//!
+//! [`KlondikeAdapter`] is a pure helper namespace for:
+//! - building [`KlondikeConfig`] from Ferrous settings
+//! - translating between local and upstream types
+//!
+//! Ferrous-specific scoring policy (the win-time bonus) lives in
+//! [`crate::scoring`], not here.
+//!
+//! All `From` / `TryFrom` conversions between `solitaire_core` product types and
+//! upstream `card_game` / `klondike` types live here so that the product modules
+//! (`card`, `pile`, etc.) remain free of upstream dependencies.
+
+use klondike::{
+    DrawStockConfig, Foundation, KlondikeConfig, MoveFromFoundationConfig, ScoringConfig,
+    SkipCards, Tableau,
+};
+
+/// Bridges `solitaire_core` game config to the upstream `klondike` crate.
+///
+/// This type is intentionally zero-sized: it does not carry mutable runtime
+/// state, and exists only as a namespace for configuration and conversion
+/// helpers.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct KlondikeAdapter;
+
+impl KlondikeAdapter {
+    /// Build a [`KlondikeConfig`] from draw mode and foundation house-rule setting.
+    pub fn config_for(draw_mode: DrawStockConfig, take_from_foundation: bool) -> KlondikeConfig {
+        KlondikeConfig {
+            draw_stock: draw_mode,
+            move_from_foundation: if take_from_foundation {
+                MoveFromFoundationConfig::Allowed
+            } else {
+                MoveFromFoundationConfig::Disallowed
+            },
+            scoring: ScoringConfig::DEFAULT,
+        }
+    }
+}
+
+/// Convert a zero-based tableau index (0..=6) into [`Tableau`].
+pub fn tableau_from_index(index: usize) -> Option<Tableau> {
+    match index {
+        0 => Some(Tableau::Tableau1),
+        1 => Some(Tableau::Tableau2),
+        2 => Some(Tableau::Tableau3),
+        3 => Some(Tableau::Tableau4),
+        4 => Some(Tableau::Tableau5),
+        5 => Some(Tableau::Tableau6),
+        6 => Some(Tableau::Tableau7),
+        _ => None,
+    }
+}
+
+/// Convert a zero-based foundation slot (0..=3) into [`Foundation`].
+pub fn foundation_from_slot(slot: u8) -> Option<Foundation> {
+    match slot {
+        0 => Some(Foundation::Foundation1),
+        1 => Some(Foundation::Foundation2),
+        2 => Some(Foundation::Foundation3),
+        3 => Some(Foundation::Foundation4),
+        _ => None,
+    }
+}
+
+/// Convert a tableau skip count (0..=12) into [`SkipCards`].
+pub fn skip_cards_from_count(skip: usize) -> Option<SkipCards> {
+    match skip {
+        0 => Some(SkipCards::Skip0),
+        1 => Some(SkipCards::Skip1),
+        2 => Some(SkipCards::Skip2),
+        3 => Some(SkipCards::Skip3),
+        4 => Some(SkipCards::Skip4),
+        5 => Some(SkipCards::Skip5),
+        6 => Some(SkipCards::Skip6),
+        7 => Some(SkipCards::Skip7),
+        8 => Some(SkipCards::Skip8),
+        9 => Some(SkipCards::Skip9),
+        10 => Some(SkipCards::Skip10),
+        11 => Some(SkipCards::Skip11),
+        12 => Some(SkipCards::Skip12),
+        _ => None,
+    }
+}
@@ -1,9 +1,23 @@
 pub mod achievement;
-pub mod card;
-pub mod deck;
 pub mod error;
 pub mod game_state;
-pub mod pile;
-pub mod rules;
+pub mod klondike_adapter;
 pub mod scoring;
-pub mod solver;
+
+// Re-export the upstream types that cross the solitaire_core API boundary so
+// downstream crates (engine, wasm) can import from one place without a direct
+// `klondike` / `card_game` dep.
+//
+// `KlondikePileStack`, `SkipCards` and `TableauStack` are intentionally NOT
+// re-exported — they are only used internally (in `klondike_adapter.rs` and
+// when decoding instructions to piles in `instruction_to_piles`) and do not
+// appear in any public method signature.
+pub use card_game::{Card, Deck, Rank, Session, SolveError, Suit};
+pub use klondike::{DrawStockConfig, Foundation, Klondike, KlondikeInstruction, KlondikePile, Tableau};
+
+// Solvability check API (delegates to `card_game::Session::solve`); replaces the
+// former `solitaire_data::solver` wrapper module.
+pub use game_state::{DEFAULT_SOLVE_MOVES_BUDGET, DEFAULT_SOLVE_STATES_BUDGET, SolveOutcome};
+
+#[cfg(test)]
+mod proptest_tests;
@@ -1,133 +0,0 @@
-use crate::card::{Card, Suit};
-use serde::{Deserialize, Serialize};
-
-/// Identifies which pile on the board a set of cards belongs to.
-#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
-pub enum PileType {
-    /// The face-down draw pile.
-    Stock,
-    /// The face-up discard pile drawn to.
-    Waste,
-    /// One of the four foundation slots (0..=3). The claimed suit, if any,
-    /// is derived from the bottom card of the pile (always an Ace by
-    /// construction).
-    Foundation(u8),
-    /// One of the seven tableau columns (0–6).
-    Tableau(usize),
-}
-
-/// A named collection of cards in a specific board position.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct Pile {
-    /// Which pile this is (Stock, Waste, Foundation slot, or Tableau column).
-    pub pile_type: PileType,
-    /// Cards in the pile, bottom-to-top stacking order. Last element is the top card.
-    pub cards: Vec<Card>,
-}
-
-impl Pile {
-    /// Creates a new empty pile of the given type.
-    pub fn new(pile_type: PileType) -> Self {
-        Self {
-            pile_type,
-            cards: Vec::new(),
-        }
-    }
-
-    /// Returns a reference to the top (last) card, or `None` if empty.
-    pub fn top(&self) -> Option<&Card> {
-        self.cards.last()
-    }
-
-    /// For foundation piles: returns `Some(suit)` once at least one card has
-    /// landed (the bottom card is always an Ace of the claimed suit).
-    /// Returns `None` for empty foundations or non-foundation piles.
-    pub fn claimed_suit(&self) -> Option<Suit> {
-        match self.pile_type {
-            PileType::Foundation(_) => self.cards.first().map(|c| c.suit),
-            _ => None,
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::card::{Card, Rank, Suit};
-
-    #[test]
-    fn new_pile_is_empty() {
-        let pile = Pile::new(PileType::Stock);
-        assert!(pile.cards.is_empty());
-    }
-
-    #[test]
-    fn pile_top_returns_last_card() {
-        let mut pile = Pile::new(PileType::Waste);
-        pile.cards.push(Card {
-            id: 0,
-            suit: Suit::Hearts,
-            rank: Rank::Ace,
-            face_up: true,
-        });
-        pile.cards.push(Card {
-            id: 1,
-            suit: Suit::Clubs,
-            rank: Rank::Two,
-            face_up: true,
-        });
-        assert_eq!(pile.top().unwrap().id, 1);
-    }
-
-    #[test]
-    fn pile_top_on_empty_is_none() {
-        let pile = Pile::new(PileType::Waste);
-        assert!(pile.top().is_none());
-    }
-
-    #[test]
-    fn pile_type_foundation_uses_slot_index() {
-        assert_ne!(PileType::Foundation(0), PileType::Foundation(3));
-    }
-
-    #[test]
-    fn pile_type_tableau_uses_index() {
-        assert_ne!(PileType::Tableau(0), PileType::Tableau(6));
-    }
-
-    #[test]
-    fn claimed_suit_is_none_for_empty_foundation() {
-        let pile = Pile::new(PileType::Foundation(0));
-        assert!(pile.claimed_suit().is_none());
-    }
-
-    #[test]
-    fn claimed_suit_is_none_for_non_foundation() {
-        let mut pile = Pile::new(PileType::Tableau(0));
-        pile.cards.push(Card {
-            id: 0,
-            suit: Suit::Hearts,
-            rank: Rank::Ace,
-            face_up: true,
-        });
-        assert!(pile.claimed_suit().is_none());
-    }
-
-    #[test]
-    fn claimed_suit_returns_bottom_card_suit() {
-        let mut pile = Pile::new(PileType::Foundation(2));
-        pile.cards.push(Card {
-            id: 0,
-            suit: Suit::Hearts,
-            rank: Rank::Ace,
-            face_up: true,
-        });
-        pile.cards.push(Card {
-            id: 1,
-            suit: Suit::Hearts,
-            rank: Rank::Two,
-            face_up: true,
-        });
-        assert_eq!(pile.claimed_suit(), Some(Suit::Hearts));
-    }
-}
@@ -0,0 +1,259 @@
+use card_game::{Card, Game};
+use klondike::{DrawStockConfig, Foundation, KlondikePile, Tableau};
+use proptest::prelude::*;
+
+use crate::game_state::GameState;
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+/// Collect all cards across every pile in a fixed traversal order:
+/// stock → waste → foundations 1–4 → tableaux 1–7.
+///
+/// The order is deterministic for a given game state, so two calls on
+/// equivalent states produce identical Vec outputs — the right fingerprint
+/// for undo-reversibility checks.
+fn all_cards(game: &GameState) -> Vec<Card> {
+    let foundations = [
+        Foundation::Foundation1,
+        Foundation::Foundation2,
+        Foundation::Foundation3,
+        Foundation::Foundation4,
+    ];
+    let tableaux = [
+        Tableau::Tableau1,
+        Tableau::Tableau2,
+        Tableau::Tableau3,
+        Tableau::Tableau4,
+        Tableau::Tableau5,
+        Tableau::Tableau6,
+        Tableau::Tableau7,
+    ];
+
+    let mut cards: Vec<Card> = game.stock_cards().iter().map(|(c, _)| c.clone()).collect();
+    cards.extend(game.waste_cards().iter().map(|(c, _)| c.clone()));
+    for f in &foundations {
+        cards.extend(
+            game.pile(KlondikePile::Foundation(*f))
+                .iter()
+                .map(|(c, _)| c.clone()),
+        );
+    }
+    for t in &tableaux {
+        cards.extend(game.pile(KlondikePile::Tableau(*t)).iter().map(|(c, _)| c.clone()));
+    }
+    cards
+}
+
+fn draw_mode_strategy() -> impl Strategy<Value = DrawStockConfig> {
+    prop_oneof![Just(DrawStockConfig::DrawOne), Just(DrawStockConfig::DrawThree)]
+}
+
+/// Apply a sequence of random actions to a game, silently ignoring errors.
+///
+/// Each action is `(draw_flag, move_index)`:
+/// - `draw_flag = true`  → call `game.draw()`
+/// - `draw_flag = false` → pick the `move_index % len`th legal instruction
+///   from `possible_instructions()` and apply it via `apply_instruction()`.
+///
+/// `possible_instructions()` may return `RotateStock`, which
+/// `apply_instruction()` dispatches to `game.draw()`; ordinary instructions
+/// are equivalent to `move_cards(from, to, count)`.
+fn apply_random_actions(game: &mut GameState, actions: &[(bool, usize)]) {
+    for &(do_draw, idx) in actions {
+        if do_draw {
+            let _ = game.draw();
+        } else {
+            let moves = game.possible_instructions();
+            if moves.is_empty() {
+                continue;
+            }
+            let instruction = moves[idx % moves.len()];
+            let _ = game.apply_instruction(instruction);
+        }
+    }
+}
+
+/// Apply one move from `possible_instructions()` (or a draw if no move is
+/// available), using `move_idx` to select among the legal options.
+/// Returns `true` when a move was successfully applied.
+fn apply_one_move(game: &mut GameState, move_idx: usize) -> bool {
+    if game.is_won() {
+        return false;
+    }
+    let moves = game.possible_instructions();
+    if moves.is_empty() {
+        return game.draw().is_ok();
+    }
+    let instruction = moves[move_idx % moves.len()];
+    game.apply_instruction(instruction).is_ok()
+}
+
+// ---------------------------------------------------------------------------
+// Properties
+// ---------------------------------------------------------------------------
+
+proptest! {
+    /// `check_auto_complete()` and `is_win_trivial()` must agree on every
+    /// reachable game state.
+    ///
+    /// The upstream `Klondike::is_win_trivial()` checks that the stock pile
+    /// (both face-down and face-up halves) is completely empty AND that all
+    /// tableau columns have no face-down cards.  Ferrous `check_auto_complete()`
+    /// checks the same three conditions individually (stock empty, waste empty,
+    /// all tableau cards face-up).  This property guards against any semantic
+    /// drift between the two implementations so that delegating to upstream is
+    /// safe.
+    ///
+    /// If this property ever fails, `check_auto_complete()` must NOT be fully
+    /// replaced — the Ferrous conditions must be preserved and `is_win_trivial()`
+    /// used only as a supplementary guard.
+    #[test]
+    fn check_auto_complete_agrees_with_is_win_trivial(
+        seed in any::<u64>(),
+        draw_mode in draw_mode_strategy(),
+        actions in prop::collection::vec((any::<bool>(), 0usize..200), 0..30),
+    ) {
+        let mut game = GameState::new(seed, draw_mode);
+        apply_random_actions(&mut game, &actions);
+        prop_assert_eq!(
+            game.check_auto_complete(),
+            game.session().state().state().is_win_trivial(),
+            "check_auto_complete() disagreed with is_win_trivial() after {:?} actions",
+            actions.len(),
+        );
+    }
+
+    /// `check_win()` and `is_win()` must agree on every reachable game state.
+    #[test]
+    fn check_win_agrees_with_is_win(
+        seed in any::<u64>(),
+        draw_mode in draw_mode_strategy(),
+        actions in prop::collection::vec((any::<bool>(), 0usize..200), 0..30),
+    ) {
+        let mut game = GameState::new(seed, draw_mode);
+        apply_random_actions(&mut game, &actions);
+        prop_assert_eq!(
+            game.check_win(),
+            game.session().state().state().is_win(),
+            "check_win() disagreed with is_win()",
+        );
+    }
+
+    /// All 52 card IDs must be present exactly once across every pile after
+    /// any reachable sequence of draw + move_cards actions.
+    ///
+    /// Catches two bug classes at once:
+    /// - Card loss (fewer than 52 unique IDs after the sequence).
+    /// - Card duplication (52 total but deduplication reduces the set).
+    #[test]
+    fn all_52_cards_always_present(
+        seed in any::<u64>(),
+        draw_mode in draw_mode_strategy(),
+        actions in prop::collection::vec((any::<bool>(), 0usize..200), 0..30),
+    ) {
+        let mut game = GameState::new(seed, draw_mode);
+        apply_random_actions(&mut game, &actions);
+
+        let cards = all_cards(&game);
+        prop_assert_eq!(cards.len(), 52, "card count ≠ 52 (got {})", cards.len());
+        let unique: std::collections::HashSet<Card> = cards.iter().cloned().collect();
+        prop_assert_eq!(
+            unique.len(), 52,
+            "duplicate cards found after dedup — a card was cloned"
+        );
+    }
+
+    /// `GameState::new(seed, draw_mode)` must be deterministic: two calls
+    /// with the same arguments must produce identical initial pile layouts.
+    ///
+    /// Pins that the deal is seeded from `seed` alone and not from any
+    /// implicit source like wall-clock time or global state.
+    #[test]
+    fn deal_is_deterministic(
+        seed in any::<u64>(),
+        draw_mode in draw_mode_strategy(),
+    ) {
+        let a = GameState::new(seed, draw_mode);
+        let b = GameState::new(seed, draw_mode);
+        prop_assert_eq!(
+            all_cards(&a),
+            all_cards(&b),
+            "same seed + draw_mode produced different deals",
+        );
+    }
+
+    /// After applying any single legal move and immediately undoing it, the
+    /// pile layout and move_count must be identical to their pre-move values.
+    ///
+    /// `setup_actions` drives the game to an arbitrary mid-game position;
+    /// `move_idx` selects which legal move to apply and then undo.
+    ///
+    /// The score is intentionally excluded: `undo()` applies a −15 penalty
+    /// that is by design, not a regression.
+    #[test]
+    fn undo_restores_pile_layout_and_move_count(
+        seed in any::<u64>(),
+        draw_mode in draw_mode_strategy(),
+        setup_actions in prop::collection::vec((any::<bool>(), 0usize..200), 0..20),
+        move_idx in 0usize..200,
+    ) {
+        let mut game = GameState::new(seed, draw_mode);
+        apply_random_actions(&mut game, &setup_actions);
+
+        // Snapshot the state before the move.
+        let before_ids = all_cards(&game);
+        let before_move_count = game.move_count();
+
+        // Apply one move.
+        if !apply_one_move(&mut game, move_idx) || game.is_won() {
+            return Ok(()); // nothing to undo
+        }
+
+        // Undo and verify.
+        prop_assert!(
+            game.undo().is_ok(),
+            "undo must succeed immediately after a successful move",
+        );
+        prop_assert_eq!(
+            all_cards(&game),
+            before_ids,
+            "pile layout after undo differs from the pre-move snapshot",
+        );
+        prop_assert_eq!(
+            game.move_count(),
+            before_move_count,
+            "move_count after undo must equal the pre-move value",
+        );
+    }
+
+    /// Every move returned by `possible_instructions()` must succeed when
+    /// applied via `move_cards()`.
+    ///
+    /// `possible_instructions()` and `move_cards()` both validate moves
+    /// through the same upstream rule engine. This property ensures no
+    /// drift has opened up between what the engine reports as legal and
+    /// what it actually accepts.
+    #[test]
+    fn legal_moves_always_succeed(
+        seed in any::<u64>(),
+        draw_mode in draw_mode_strategy(),
+        setup_actions in prop::collection::vec((any::<bool>(), 0usize..200), 0..20),
+    ) {
+        let mut game = GameState::new(seed, draw_mode);
+        apply_random_actions(&mut game, &setup_actions);
+
+        for instruction in game.possible_instructions() {
+            // Clone so each move is tried from the same starting state.
+            let mut trial = game.clone();
+            let result = trial.apply_instruction(instruction);
+            prop_assert!(
+                result.is_ok(),
+                "possible_instructions() reported {instruction:?} \
+                 as legal but the call returned Err: {result:?}",
+            );
+        }
+    }
+
+}
@@ -1,228 +0,0 @@
-use crate::card::{Card, Rank};
-use crate::pile::Pile;
-
-/// Returns `true` if `card` can be placed on the foundation `pile`.
-///
-/// Foundation rules:
-/// - When the pile is empty, any Ace is accepted; the placed Ace's suit
-///   becomes the pile's claimed suit (derived from the bottom card via
-///   [`Pile::claimed_suit`](crate::pile::Pile::claimed_suit)).
-/// - When the pile is non-empty, the next card must match the top card's
-///   suit and be exactly one rank higher.
-#[must_use]
-pub fn can_place_on_foundation(card: &Card, pile: &Pile) -> bool {
-    match pile.cards.last() {
-        None => card.rank == Rank::Ace,
-        Some(top) => card.suit == top.suit && card.rank.checked_sub(1) == Some(top.rank),
-    }
-}
-
-/// Returns `true` if `card` (or the bottom card of a sequence) can be placed on `pile` in the tableau.
-///
-/// Tableau rules: Kings go on empty piles; otherwise alternating colour, one rank lower.
-#[must_use]
-pub fn can_place_on_tableau(card: &Card, pile: &Pile) -> bool {
-    match pile.cards.last() {
-        None => card.rank == Rank::King,
-        Some(top) => {
-            top.face_up
-                && card.rank.checked_add(1) == Some(top.rank)
-                && card.suit.is_red() != top.suit.is_red()
-        }
-    }
-}
-
-/// Returns `true` if `cards` is a legal tableau run on its own — every
-/// adjacent pair descends by one rank and alternates colour. A single
-/// card is trivially valid. The destination check is separate; this
-/// only validates the sequence's *internal* structure, which the tableau
-/// move path must enforce so a player can't smuggle an arbitrary stack
-/// onto another column when the bottom card happens to land legally.
-#[must_use]
-pub fn is_valid_tableau_sequence(cards: &[Card]) -> bool {
-    cards.windows(2).all(|w| {
-        w[0].rank.checked_sub(1) == Some(w[1].rank) && w[0].suit.is_red() != w[1].suit.is_red()
-    })
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::card::{Card, Rank, Suit};
-    use crate::pile::{Pile, PileType};
-
-    fn card(suit: Suit, rank: Rank) -> Card {
-        Card {
-            id: 0,
-            suit,
-            rank,
-            face_up: true,
-        }
-    }
-
-    fn pile_with(pile_type: PileType, cards: Vec<Card>) -> Pile {
-        Pile { pile_type, cards }
-    }
-
-    // Foundation tests
-    #[test]
-    fn foundation_ace_on_empty_is_valid() {
-        // Every suit's Ace must land on an empty foundation slot regardless of
-        // its slot index; the slot claims the suit only after the Ace lands.
-        for suit in [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades] {
-            let c = card(suit, Rank::Ace);
-            let p = Pile::new(PileType::Foundation(0));
-            assert!(
-                can_place_on_foundation(&c, &p),
-                "Ace of {suit:?} must land on empty slot 0",
-            );
-        }
-    }
-
-    #[test]
-    fn foundation_non_ace_on_empty_is_invalid() {
-        let c = card(Suit::Hearts, Rank::Two);
-        let p = Pile::new(PileType::Foundation(0));
-        assert!(!can_place_on_foundation(&c, &p));
-    }
-
-    #[test]
-    fn foundation_two_on_ace_same_suit_is_valid() {
-        let c = card(Suit::Clubs, Rank::Two);
-        let p = pile_with(PileType::Foundation(0), vec![card(Suit::Clubs, Rank::Ace)]);
-        assert!(can_place_on_foundation(&c, &p));
-    }
-
-    #[test]
-    fn foundation_second_card_must_match_claimed_suit() {
-        // Place Ace of Hearts on slot 0, then attempt 2 of Spades — rejected
-        // because the slot's claimed suit is Hearts after the Ace lands.
-        let p = pile_with(PileType::Foundation(0), vec![card(Suit::Hearts, Rank::Ace)]);
-        let c = card(Suit::Spades, Rank::Two);
-        assert!(!can_place_on_foundation(&c, &p));
-    }
-
-    #[test]
-    fn foundation_skipping_rank_is_invalid() {
-        let c = card(Suit::Diamonds, Rank::Three);
-        let p = pile_with(
-            PileType::Foundation(0),
-            vec![card(Suit::Diamonds, Rank::Ace)],
-        );
-        assert!(!can_place_on_foundation(&c, &p));
-    }
-
-    // Tableau tests
-    #[test]
-    fn tableau_king_on_empty_is_valid() {
-        let c = card(Suit::Hearts, Rank::King);
-        let p = Pile::new(PileType::Tableau(0));
-        assert!(can_place_on_tableau(&c, &p));
-    }
-
-    #[test]
-    fn tableau_non_king_on_empty_is_invalid() {
-        let c = card(Suit::Hearts, Rank::Queen);
-        let p = Pile::new(PileType::Tableau(0));
-        assert!(!can_place_on_tableau(&c, &p));
-    }
-
-    #[test]
-    fn tableau_red_on_black_one_lower_is_valid() {
-        let c = card(Suit::Hearts, Rank::Nine);
-        let p = pile_with(PileType::Tableau(0), vec![card(Suit::Spades, Rank::Ten)]);
-        assert!(can_place_on_tableau(&c, &p));
-    }
-
-    #[test]
-    fn tableau_same_color_is_invalid() {
-        let c = card(Suit::Clubs, Rank::Nine);
-        let p = pile_with(PileType::Tableau(0), vec![card(Suit::Spades, Rank::Ten)]);
-        assert!(!can_place_on_tableau(&c, &p));
-    }
-
-    #[test]
-    fn tableau_wrong_rank_difference_is_invalid() {
-        let c = card(Suit::Hearts, Rank::Eight);
-        let p = pile_with(PileType::Tableau(0), vec![card(Suit::Spades, Rank::Ten)]);
-        assert!(!can_place_on_tableau(&c, &p));
-    }
-
-    #[test]
-    fn tableau_black_on_red_one_lower_is_valid() {
-        let c = card(Suit::Clubs, Rank::Six);
-        let p = pile_with(PileType::Tableau(0), vec![card(Suit::Hearts, Rank::Seven)]);
-        assert!(can_place_on_tableau(&c, &p));
-    }
-
-    #[test]
-    fn foundation_king_on_queen_completes_suit() {
-        // The last card placed to complete a foundation is always King on Queen.
-        let c = card(Suit::Spades, Rank::King);
-        let p = pile_with(
-            PileType::Foundation(0),
-            vec![card(Suit::Spades, Rank::Queen)],
-        );
-        assert!(can_place_on_foundation(&c, &p));
-    }
-
-    #[test]
-    fn foundation_king_wrong_suit_is_invalid() {
-        // King of Hearts cannot go on a Spades-claimed foundation even if rank matches.
-        let c = card(Suit::Hearts, Rank::King);
-        let p = pile_with(
-            PileType::Foundation(0),
-            vec![card(Suit::Spades, Rank::Queen)],
-        );
-        assert!(!can_place_on_foundation(&c, &p));
-    }
-
-    #[test]
-    fn tableau_ace_on_two_different_color_is_valid() {
-        // Ace (rank 1) can be placed on a Two of the opposite colour in the tableau.
-        // rank check: Ace.value() + 1 = 2 == Two.value() — passes.
-        let c = card(Suit::Hearts, Rank::Ace);
-        let p = pile_with(PileType::Tableau(0), vec![card(Suit::Spades, Rank::Two)]);
-        assert!(can_place_on_tableau(&c, &p));
-    }
-
-    #[test]
-    fn tableau_same_rank_different_color_is_invalid() {
-        // Two cards of the same rank cannot be stacked regardless of colour.
-        let c = card(Suit::Hearts, Rank::Nine);
-        let p = pile_with(PileType::Tableau(0), vec![card(Suit::Spades, Rank::Nine)]);
-        assert!(!can_place_on_tableau(&c, &p));
-    }
-
-    #[test]
-    fn tableau_face_down_destination_top_is_invalid() {
-        // A face-down top card must never be a valid placement target.
-        let c = card(Suit::Hearts, Rank::Nine);
-        let mut top = card(Suit::Spades, Rank::Ten);
-        top.face_up = false;
-        let p = pile_with(PileType::Tableau(0), vec![top]);
-        assert!(!can_place_on_tableau(&c, &p));
-    }
-
-    #[test]
-    fn tableau_sequence_validation() {
-        // Single card is trivially a valid sequence.
-        assert!(is_valid_tableau_sequence(&[card(Suit::Hearts, Rank::Five)]));
-        // Valid descending alternating-colour run K♠ Q♥ J♣.
-        assert!(is_valid_tableau_sequence(&[
-            card(Suit::Spades, Rank::King),
-            card(Suit::Hearts, Rank::Queen),
-            card(Suit::Clubs, Rank::Jack),
-        ]));
-        // Same colour twice (Q♠ on K♠) — invalid.
-        assert!(!is_valid_tableau_sequence(&[
-            card(Suit::Spades, Rank::King),
-            card(Suit::Spades, Rank::Queen),
-        ]));
-        // Rank gap (K♠ → J♥) — invalid.
-        assert!(!is_valid_tableau_sequence(&[
-            card(Suit::Spades, Rank::King),
-            card(Suit::Hearts, Rank::Jack),
-        ]));
-    }
-}
@@ -1,50 +1,9 @@
-use crate::pile::PileType;
-
-/// Score delta for moving cards from `from` to `to`.
-///
-/// Windows XP Standard scoring:
-/// - +10 for any card reaching a foundation pile
-/// - +5 for a waste → tableau move
-/// - -15 for a foundation → tableau (take-from-foundation) move
-/// - 0 for all other moves
-///
-/// Note: the +5 flip bonus for exposing a face-down tableau card is applied
-/// separately in `game_state::move_cards` because it depends on post-move state.
-pub fn score_move(from: &PileType, to: &PileType) -> i32 {
-    match to {
-        PileType::Foundation(_) => 10,
-        PileType::Tableau(_) => match from {
-            PileType::Waste => 5,
-            PileType::Foundation(_) => -15,
-            _ => 0,
-        },
-        _ => 0,
-    }
-}
-
-/// Score penalty applied when the player uses undo: -15.
-pub fn score_undo() -> i32 {
-    -15
-}
-
-/// Score bonus awarded when a face-down tableau card is flipped face-up: +5.
-pub fn score_flip() -> i32 {
-    5
-}
-
-/// Score penalty for recycling the waste pile back to stock.
-///
-/// Windows standard: the first N recycles are free (N=1 for Draw-1, N=3 for Draw-3).
-/// Subsequent recycles cost -100 (Draw-1) or -20 (Draw-3).
-/// `recycle_count` is the new total count **after** this recycle.
-pub fn score_recycle(recycle_count: u32, is_draw_three: bool) -> i32 {
-    let (free, penalty) = if is_draw_three {
-        (3_u32, -20_i32)
-    } else {
-        (1_u32, -100_i32)
-    };
-    if recycle_count > free { penalty } else { 0 }
-}
+//! Ferrous-specific scoring policy layered on top of upstream `klondike`.
+//!
+//! Upstream [`klondike::KlondikeStats::score`] owns the per-move point values
+//! (move-to-foundation, flip-up bonus, recycle penalty, etc.). The functions
+//! here are the Ferrous Solitaire house rules that upstream has no opinion on —
+//! currently just the win-time bonus shown in the win modal.

 /// Time bonus added to the score on a win: `700_000 / elapsed_seconds`.
 /// Returns 0 when `elapsed_seconds` is 0 to avoid division by zero.
@@ -54,99 +13,3 @@ pub fn compute_time_bonus(elapsed_seconds: u64) -> i32 {
    }
    (700_000u64 / elapsed_seconds).min(i32::MAX as u64) as i32
 }
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn move_to_foundation_scores_ten() {
-        assert_eq!(score_move(&PileType::Waste, &PileType::Foundation(2)), 10);
-        assert_eq!(
-            score_move(&PileType::Tableau(0), &PileType::Foundation(0)),
-            10
-        );
-    }
-
-    #[test]
-    fn waste_to_tableau_scores_five() {
-        assert_eq!(score_move(&PileType::Waste, &PileType::Tableau(3)), 5);
-    }
-
-    #[test]
-    fn tableau_to_tableau_scores_zero() {
-        assert_eq!(score_move(&PileType::Tableau(0), &PileType::Tableau(1)), 0);
-    }
-
-    #[test]
-    fn undo_penalty_is_negative_fifteen() {
-        assert_eq!(score_undo(), -15);
-    }
-
-    #[test]
-    fn time_bonus_at_100_seconds() {
-        assert_eq!(compute_time_bonus(100), 7000);
-    }
-
-    #[test]
-    fn time_bonus_at_zero_is_zero() {
-        assert_eq!(compute_time_bonus(0), 0);
-    }
-
-    #[test]
-    fn time_bonus_at_one_second() {
-        assert_eq!(compute_time_bonus(1), 700_000);
-    }
-
-    #[test]
-    fn foundation_to_tableau_penalises_fifteen() {
-        // Moving a card back off a foundation (take_from_foundation rule) costs -15.
-        assert_eq!(
-            score_move(&PileType::Foundation(0), &PileType::Tableau(0)),
-            -15
-        );
-    }
-
-    #[test]
-    fn move_to_stock_or_waste_scores_zero() {
-        // These destinations are illegal moves in practice, but the function
-        // must not panic and should return 0.
-        assert_eq!(score_move(&PileType::Waste, &PileType::Stock), 0);
-        assert_eq!(score_move(&PileType::Waste, &PileType::Waste), 0);
-    }
-
-    #[test]
-    fn time_bonus_is_capped_at_i32_max_for_huge_values() {
-        // Very short elapsed time would overflow without the .min() guard.
-        let bonus = compute_time_bonus(1);
-        assert!(
-            bonus >= 0,
-            "time bonus must be non-negative after u64→i32 cast"
-        );
-    }
-
-    #[test]
-    fn flip_bonus_is_five() {
-        assert_eq!(score_flip(), 5);
-    }
-
-    #[test]
-    fn recycle_draw1_first_pass_free() {
-        assert_eq!(score_recycle(1, false), 0);
-    }
-
-    #[test]
-    fn recycle_draw1_second_pass_penalised() {
-        assert_eq!(score_recycle(2, false), -100);
-    }
-
-    #[test]
-    fn recycle_draw3_third_pass_free() {
-        assert_eq!(score_recycle(3, true), 0);
-    }
-
-    #[test]
-    fn recycle_draw3_fourth_pass_penalised() {
-        assert_eq!(score_recycle(4, true), -20);
-    }
-}
@@ -7,15 +7,23 @@ edition.workspace = true
 [dependencies]
 solitaire_core = { workspace = true }
 solitaire_sync = { workspace = true }
+klondike  = { workspace = true }
+card_game = { workspace = true }
 serde          = { workspace = true }
 serde_json     = { workspace = true }
 chrono         = { workspace = true }
 thiserror      = { workspace = true }
 async-trait    = { workspace = true }
+uuid           = { workspace = true }
+
+# These deps are not available / not needed on wasm32:
+#   dirs     — platform data directories (no filesystem on browser)
+#   reqwest  — native HTTP client (sync/analytics gated out on wasm32)
+#   tokio    — OS-threaded async runtime (mio doesn't compile on wasm32)
+[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
 dirs           = { workspace = true }
 reqwest        = { workspace = true }
 tokio          = { workspace = true }
-uuid           = { workspace = true }

 # `keyring-core` is the typed Entry/Error API used by
 # `auth_tokens`. The crate's own dependency tree pulls in
@@ -24,17 +32,14 @@ uuid           = { workspace = true }
 # on bionic). On Android `auth_tokens` falls back to a stub
 # implementation that always returns `KeychainUnavailable`; the
 # real backend lands when we wire Android Keystore via JNI.
-[target.'cfg(not(target_os = "android"))'.dependencies]
+[target.'cfg(all(not(target_os = "android"), not(target_arch = "wasm32")))'.dependencies]
 keyring-core   = { workspace = true }

 [target.'cfg(target_os = "android")'.dependencies]
 jni            = { workspace = true }
-# android_keystore.rs uses bevy::android::ANDROID_APP to obtain the
-# process-wide JavaVM handle for JNI. Must be listed here so the
-# symbol resolves when cross-compiling for Android targets.
-bevy           = { workspace = true }

 [dev-dependencies]
+solitaire_core   = { workspace = true, features = ["test-support"] }
 solitaire_server = { path = "../solitaire_server" }
 solitaire_sync   = { workspace = true }
 axum             = { workspace = true }
@@ -42,3 +47,6 @@ sqlx             = { workspace = true }
 jsonwebtoken     = { workspace = true }
 uuid             = { workspace = true }
 chrono           = { workspace = true }
+
+[lints]
+workspace = true
@@ -0,0 +1,65 @@
+//! Safe JNI bridge for Android platform integration.
+//!
+//! Reconstructing the raw `JavaVM` / `NativeActivity` handles handed over by
+//! the Android runtime requires `unsafe` FFI. That single reconstruction lives
+//! in `solitaire_app`'s entry point ([`solitaire_app::android_main`]); this
+//! module only ever stores the resulting *safe* [`JavaVM`] and activity
+//! [`GlobalRef`] and hands callers an attached [`JNIEnv`].
+//!
+//! As a result every consumer of Android JNI — the keystore, clipboard, and
+//! safe-area subsystems — goes through the safe functions here and stays
+//! `forbid(unsafe_code)`. The only crate carrying `unsafe` is `solitaire_app`.
+//!
+//! Only compiled and linked on `target_os = "android"`.
+
+use jni::objects::{GlobalRef, JObject};
+use jni::{JNIEnv, JavaVM};
+use std::sync::OnceLock;
+
+static ANDROID_JVM: OnceLock<JavaVM> = OnceLock::new();
+static ANDROID_ACTIVITY: OnceLock<GlobalRef> = OnceLock::new();
+
+/// Store the process-wide [`JavaVM`]. Called once from Android startup
+/// (`solitaire_app::android_main`); subsequent calls are ignored.
+pub fn set_jvm(vm: JavaVM) {
+    let _ = ANDROID_JVM.set(vm);
+}
+
+/// Store a global reference to the `NativeActivity`. Called once from Android
+/// startup; subsequent calls are ignored.
+pub fn set_activity(activity: GlobalRef) {
+    let _ = ANDROID_ACTIVITY.set(activity);
+}
+
+/// Run `f` with a [`JNIEnv`] attached to the current thread.
+///
+/// Returns an error string if the bridge has not been initialised yet or the
+/// thread cannot be attached. The closure's JNI errors are surfaced through the
+/// same `String` channel so callers have a single error type to map.
+pub fn with_env<F, R>(f: F) -> Result<R, String>
+where
+    F: for<'local> FnOnce(&mut JNIEnv<'local>) -> jni::errors::Result<R>,
+{
+    let vm = ANDROID_JVM
+        .get()
+        .ok_or_else(|| "Android JavaVM not initialised".to_string())?;
+    let mut env = vm
+        .attach_current_thread_permanently()
+        .map_err(|e| format!("attach_current_thread: {e}"))?;
+    f(&mut env).map_err(|e| format!("JNI: {e}"))
+}
+
+/// Run `f` with an attached [`JNIEnv`] and the `NativeActivity` object.
+///
+/// Like [`with_env`] but also resolves the cached activity global reference, so
+/// callers that need to invoke instance methods on the activity (clipboard,
+/// window insets) never touch a raw handle.
+pub fn with_activity_env<F, R>(f: F) -> Result<R, String>
+where
+    F: for<'local> FnOnce(&mut JNIEnv<'local>, &JObject<'local>) -> jni::errors::Result<R>,
+{
+    let activity = ANDROID_ACTIVITY
+        .get()
+        .ok_or_else(|| "Android activity not initialised".to_string())?;
+    with_env(|env| f(env, activity.as_obj()))
+}
@@ -14,7 +14,7 @@
 ///
 /// Only compiled and linked on `target_os = "android"`.
 use jni::{
-    JNIEnv, JavaVM,
+    JNIEnv,
    objects::{JByteArray, JObject, JObjectArray, JValue, JValueOwned},
 };
 use serde::{Deserialize, Serialize};
@@ -36,23 +36,15 @@ struct TokenBlob {
 // JVM helper
 // ---------------------------------------------------------------------------

+/// Run `f` with an attached `JNIEnv`, delegating thread attach and the
+/// `JavaVM` handle to the safe [`crate::android_jni`] bridge. The bridge is
+/// initialised once from Android startup, so the keystore never touches a raw
+/// pointer and this module stays `forbid(unsafe_code)`.
 fn with_jvm<F, R>(f: F) -> Result<R, TokenError>
 where
    F: for<'env> FnOnce(&mut JNIEnv<'env>) -> Result<R, jni::errors::Error>,
 {
-    let app = bevy::android::ANDROID_APP
-        .get()
-        .ok_or_else(|| TokenError::KeychainUnavailable("ANDROID_APP not initialised".into()))?;
-
-    // SAFETY: vm_as_ptr() is the process-wide JavaVM* set by the Android runtime.
-    let vm = unsafe { JavaVM::from_raw(app.vm_as_ptr().cast()) }
-        .map_err(|e| TokenError::Keyring(format!("JavaVM: {e}")))?;
-
-    let mut env = vm
-        .attach_current_thread_permanently()
-        .map_err(|e| TokenError::Keyring(format!("attach: {e}")))?;
-
-    f(&mut env).map_err(|e| TokenError::Keyring(format!("JNI: {e}")))
+    crate::android_jni::with_env(f).map_err(TokenError::Keyring)
 }

 // ---------------------------------------------------------------------------
@@ -207,9 +199,10 @@ fn encrypt_gcm(
    .v()?;

    // IV is generated by Android's provider; read it back after init.
+    // `getIV()` returns `[B`; the safe `From<JObject>` reinterprets the
+    // returned object reference as a typed byte array.
    let iv_jobj = env.call_method(&cipher, "getIV", "()[B", &[])?.l()?;
-    // SAFETY: the method signature guarantees a byte array return.
-    let iv_arr = unsafe { JByteArray::from_raw(iv_jobj.into_raw()) };
+    let iv_arr = JByteArray::from(iv_jobj);
    let iv = env.convert_byte_array(&iv_arr)?;

    let pt_arr = env.byte_array_from_slice(plaintext)?;
@@ -217,8 +210,7 @@ fn encrypt_gcm(
    let ct_jobj = env
        .call_method(&cipher, "doFinal", "([B)[B", &[pt_val.borrow()])?
        .l()?;
-    // SAFETY: doFinal([B) returns [B.
-    let ct_arr = unsafe { JByteArray::from_raw(ct_jobj.into_raw()) };
+    let ct_arr = JByteArray::from(ct_jobj);
    let ciphertext = env.convert_byte_array(&ct_arr)?;

    let mut out = Vec::with_capacity(iv.len() + ciphertext.len());
@@ -269,8 +261,7 @@ fn decrypt_gcm(
    let pt_jobj = env
        .call_method(&cipher, "doFinal", "([B)[B", &[ct_val.borrow()])?
        .l()?;
-    // SAFETY: doFinal([B) returns [B.
-    let pt_arr = unsafe { JByteArray::from_raw(pt_jobj.into_raw()) };
+    let pt_arr = JByteArray::from(pt_jobj);
    env.convert_byte_array(&pt_arr)
 }

@@ -357,29 +348,29 @@ fn read_map() -> Result<HashMap<String, TokenBlob>, TokenError> {
    }

    // --- 2. Legacy path migration ---
-    if let Some(ref lpath) = legacy_path {
-        if lpath.exists() {
-            let data = read_file_bytes_from(lpath).map_err(|e| match e {
-                TokenError::NotFound(_) => TokenError::NotFound(String::new()),
-                other => other,
+    if let Some(ref lpath) = legacy_path
+        && lpath.exists()
+    {
+        let data = read_file_bytes_from(lpath).map_err(|e| match e {
+            TokenError::NotFound(_) => TokenError::NotFound(String::new()),
+            other => other,
+        })?;
+        if data.len() >= 12 {
+            let plaintext = with_jvm(|env| {
+                let key = load_or_create_key(env)?;
+                decrypt_gcm(env, &key, &data)
            })?;
-            if data.len() >= 12 {
-                let plaintext = with_jvm(|env| {
-                    let key = load_or_create_key(env)?;
-                    decrypt_gcm(env, &key, &data)
-                })?;
-                if let Ok(blob) = serde_json::from_slice::<TokenBlob>(&plaintext) {
-                    let mut map = HashMap::new();
-                    map.insert(blob.username.clone(), blob);
-                    // Write to the new location, then remove the legacy file.
-                    if write_map_inner(&map).is_ok() {
-                        let _ = std::fs::remove_file(lpath);
-                    }
-                    return Ok(map);
+            if let Ok(blob) = serde_json::from_slice::<TokenBlob>(&plaintext) {
+                let mut map = HashMap::new();
+                map.insert(blob.username.clone(), blob);
+                // Write to the new location, then remove the legacy file.
+                if write_map_inner(&map).is_ok() {
+                    let _ = std::fs::remove_file(lpath);
                }
+                return Ok(map);
            }
-            // Legacy file corrupt or unrecognised — treat as empty.
        }
+        // Legacy file corrupt or unrecognised — treat as empty.
    }

    // --- 3. No file found ---
@@ -468,11 +459,11 @@ pub fn delete_tokens(username: &str) -> Result<(), TokenError> {

    if map.is_empty() {
        // No more users — remove the file and the Keystore key.
-        if let Some(path) = token_file_path() {
-            if path.exists() {
-                std::fs::remove_file(&path)
-                    .map_err(|e| TokenError::Keyring(format!("delete auth_tokens.bin: {e}")))?;
-            }
+        if let Some(path) = token_file_path()
+            && path.exists()
+        {
+            std::fs::remove_file(&path)
+                .map_err(|e| TokenError::Keyring(format!("delete auth_tokens.bin: {e}")))?;
        }

        // Remove the Keystore key so a future re-login generates a fresh key.
@@ -14,15 +14,14 @@
 //! the Bevy `App`). If no default store is set, all operations in this module
 //! will return [`TokenError::KeychainUnavailable`].
 //!
-//! # Android stub
+//! # Android
 //!
 //! `keyring-core` cannot compile for the android target (its `rpassword`
 //! transitive dep uses `libc::__errno_location`, which Android's bionic
-//! doesn't expose). On Android every function in this module returns
-//! [`TokenError::KeychainUnavailable`] so callers can detect the fallback
-//! the same way they handle a Linux box without Secret Service. The
-//! real Android backend will arrive in the Phase-Android round when we
-//! wire Android Keystore via JNI.
+//! doesn't expose). On Android this module delegates to an Android Keystore
+//! JNI backend. `solitaire_app` must initialise the safe
+//! [`crate::android_jni`] bridge (via `set_jvm` / `set_activity`) from Android
+//! startup before token operations can succeed.
 //!
 //! # Note: no unit tests — requires live OS keychain.

@@ -26,227 +26,227 @@ use solitaire_core::game_state::DifficultyLevel;

 /// 40 seeds proven winnable within the Easy budget (≤ 1 000 states).
 pub const EASY_SEEDS: &[u64] = &[
-    // Generated by solitaire_assetgen::gen_difficulty_seeds (tier=Easy, date=2026-05-09)
-    0xD1FF_0000_0000_0001,
-    0xD1FF_0000_0000_0002,
-    0xD1FF_0000_0000_0007,
-    0xD1FF_0000_0000_0008,
+    // Generated by solitaire_assetgen::gen_difficulty_seeds (tier=Easy, date=2026-06-04)
    0xD1FF_0000_0000_0009,
-    0xD1FF_0000_0000_000E,
-    0xD1FF_0000_0000_0013,
-    0xD1FF_0000_0000_0015,
-    0xD1FF_0000_0000_0018,
-    0xD1FF_0000_0000_001D,
-    0xD1FF_0000_0000_0021,
-    0xD1FF_0000_0000_0022,
-    0xD1FF_0000_0000_0026,
-    0xD1FF_0000_0000_002C,
-    0xD1FF_0000_0000_002E,
-    0xD1FF_0000_0000_002F,
-    0xD1FF_0000_0000_0035,
-    0xD1FF_0000_0000_0036,
-    0xD1FF_0000_0000_003C,
-    0xD1FF_0000_0000_0045,
-    0xD1FF_0000_0000_0046,
-    0xD1FF_0000_0000_0048,
-    0xD1FF_0000_0000_0049,
-    0xD1FF_0000_0000_004D,
-    0xD1FF_0000_0000_004F,
-    0xD1FF_0000_0000_0050,
-    0xD1FF_0000_0000_0051,
-    0xD1FF_0000_0000_0053,
-    0xD1FF_0000_0000_0054,
-    0xD1FF_0000_0000_0057,
-    0xD1FF_0000_0000_0058,
-    0xD1FF_0000_0000_005A,
-    0xD1FF_0000_0000_005B,
-    0xD1FF_0000_0000_005C,
-    0xD1FF_0000_0000_005D,
-    0xD1FF_0000_0000_005F,
-    0xD1FF_0000_0000_0061,
-    0xD1FF_0000_0000_0062,
-    0xD1FF_0000_0000_0063,
-    0xD1FF_0000_0000_0069,
+    0xD1FF_0000_0000_0087,
+    0xD1FF_0000_0000_00EB,
+    0xD1FF_0000_0000_017F,
+    0xD1FF_0000_0000_01CE,
+    0xD1FF_0000_0000_020F,
+    0xD1FF_0000_0000_0251,
+    0xD1FF_0000_0000_0275,
+    0xD1FF_0000_0000_029C,
+    0xD1FF_0000_0000_02BD,
+    0xD1FF_0000_0000_02ED,
+    0xD1FF_0000_0000_038F,
+    0xD1FF_0000_0000_03C9,
+    0xD1FF_0000_0000_0415,
+    0xD1FF_0000_0000_045F,
+    0xD1FF_0000_0000_04C4,
+    0xD1FF_0000_0000_04CC,
+    0xD1FF_0000_0000_04EE,
+    0xD1FF_0000_0000_0631,
+    0xD1FF_0000_0000_0651,
+    0xD1FF_0000_0000_0689,
+    0xD1FF_0000_0000_0735,
+    0xD1FF_0000_0000_0748,
+    0xD1FF_0000_0000_0801,
+    0xD1FF_0000_0000_0820,
+    0xD1FF_0000_0000_08F9,
+    0xD1FF_0000_0000_091C,
+    0xD1FF_0000_0000_0937,
+    0xD1FF_0000_0000_09A6,
+    0xD1FF_0000_0000_09C3,
+    0xD1FF_0000_0000_09DD,
+    0xD1FF_0000_0000_0BD9,
+    0xD1FF_0000_0000_0BEC,
+    0xD1FF_0000_0000_0BF2,
+    0xD1FF_0000_0000_0C1B,
+    0xD1FF_0000_0000_0C26,
+    0xD1FF_0000_0000_0C36,
+    0xD1FF_0000_0000_0C4B,
+    0xD1FF_0000_0000_0C78,
+    0xD1FF_0000_0000_0CBC,
 ];

 /// 40 seeds proven winnable within the Medium budget (≤ 5 000 states).
 pub const MEDIUM_SEEDS: &[u64] = &[
-    // Generated by solitaire_assetgen::gen_difficulty_seeds (tier=Medium, date=2026-05-09)
-    0xD1FF_0000_0000_0000,
+    // Generated by solitaire_assetgen::gen_difficulty_seeds (tier=Medium, date=2026-06-04)
    0xD1FF_0000_0000_0012,
-    0xD1FF_0000_0000_0016,
-    0xD1FF_0000_0000_001B,
-    0xD1FF_0000_0000_001C,
-    0xD1FF_0000_0000_0020,
-    0xD1FF_0000_0000_002A,
-    0xD1FF_0000_0000_0034,
-    0xD1FF_0000_0000_003A,
-    0xD1FF_0000_0000_0041,
-    0xD1FF_0000_0000_0043,
-    0xD1FF_0000_0000_0060,
-    0xD1FF_0000_0000_006A,
-    0xD1FF_0000_0000_006C,
-    0xD1FF_0000_0000_006E,
-    0xD1FF_0000_0000_006F,
-    0xD1FF_0000_0000_0071,
-    0xD1FF_0000_0000_0072,
-    0xD1FF_0000_0000_0075,
-    0xD1FF_0000_0000_0076,
-    0xD1FF_0000_0000_007B,
-    0xD1FF_0000_0000_007E,
-    0xD1FF_0000_0000_0081,
-    0xD1FF_0000_0000_0083,
-    0xD1FF_0000_0000_0084,
-    0xD1FF_0000_0000_0087,
-    0xD1FF_0000_0000_0090,
-    0xD1FF_0000_0000_0092,
-    0xD1FF_0000_0000_0093,
-    0xD1FF_0000_0000_0098,
+    0xD1FF_0000_0000_002C,
+    0xD1FF_0000_0000_004B,
+    0xD1FF_0000_0000_0052,
+    0xD1FF_0000_0000_0058,
+    0xD1FF_0000_0000_005E,
+    0xD1FF_0000_0000_0063,
    0xD1FF_0000_0000_0099,
-    0xD1FF_0000_0000_009A,
-    0xD1FF_0000_0000_009E,
-    0xD1FF_0000_0000_00A5,
-    0xD1FF_0000_0000_00A8,
-    0xD1FF_0000_0000_00AA,
-    0xD1FF_0000_0000_00AB,
-    0xD1FF_0000_0000_00AE,
+    0xD1FF_0000_0000_00A9,
    0xD1FF_0000_0000_00AF,
-    0xD1FF_0000_0000_00B0,
+    0xD1FF_0000_0000_00BB,
+    0xD1FF_0000_0000_00D1,
+    0xD1FF_0000_0000_00E3,
+    0xD1FF_0000_0000_0108,
+    0xD1FF_0000_0000_010D,
+    0xD1FF_0000_0000_0110,
+    0xD1FF_0000_0000_012F,
+    0xD1FF_0000_0000_0139,
+    0xD1FF_0000_0000_013C,
+    0xD1FF_0000_0000_0148,
+    0xD1FF_0000_0000_015E,
+    0xD1FF_0000_0000_016A,
+    0xD1FF_0000_0000_016F,
+    0xD1FF_0000_0000_0179,
+    0xD1FF_0000_0000_019E,
+    0xD1FF_0000_0000_01A8,
+    0xD1FF_0000_0000_01AB,
+    0xD1FF_0000_0000_01B5,
+    0xD1FF_0000_0000_01B8,
+    0xD1FF_0000_0000_01D3,
+    0xD1FF_0000_0000_01EE,
+    0xD1FF_0000_0000_01F3,
+    0xD1FF_0000_0000_0202,
+    0xD1FF_0000_0000_0203,
+    0xD1FF_0000_0000_021E,
+    0xD1FF_0000_0000_022C,
+    0xD1FF_0000_0000_022D,
+    0xD1FF_0000_0000_0233,
+    0xD1FF_0000_0000_0245,
+    0xD1FF_0000_0000_024E,
 ];

 /// 40 seeds proven winnable within the Hard budget (≤ 25 000 states).
 pub const HARD_SEEDS: &[u64] = &[
-    // Generated by solitaire_assetgen::gen_difficulty_seeds (tier=Hard, date=2026-05-09)
-    0xD1FF_0000_0000_001F,
-    0xD1FF_0000_0000_0024,
-    0xD1FF_0000_0000_0025,
-    0xD1FF_0000_0000_0031,
-    0xD1FF_0000_0000_0032,
-    0xD1FF_0000_0000_003E,
-    0xD1FF_0000_0000_004A,
-    0xD1FF_0000_0000_006D,
+    // Generated by solitaire_assetgen::gen_difficulty_seeds (tier=Hard, date=2026-06-04)
+    0xD1FF_0000_0000_0006,
+    0xD1FF_0000_0000_0008,
+    0xD1FF_0000_0000_000F,
+    0xD1FF_0000_0000_0011,
+    0xD1FF_0000_0000_0022,
+    0xD1FF_0000_0000_0023,
+    0xD1FF_0000_0000_002A,
+    0xD1FF_0000_0000_002D,
+    0xD1FF_0000_0000_0040,
+    0xD1FF_0000_0000_0042,
+    0xD1FF_0000_0000_0050,
+    0xD1FF_0000_0000_005B,
+    0xD1FF_0000_0000_005D,
+    0xD1FF_0000_0000_0067,
+    0xD1FF_0000_0000_0069,
+    0xD1FF_0000_0000_006E,
+    0xD1FF_0000_0000_0072,
    0xD1FF_0000_0000_0079,
    0xD1FF_0000_0000_007C,
    0xD1FF_0000_0000_0080,
-    0xD1FF_0000_0000_008A,
-    0xD1FF_0000_0000_0097,
+    0xD1FF_0000_0000_0081,
+    0xD1FF_0000_0000_0083,
+    0xD1FF_0000_0000_0091,
+    0xD1FF_0000_0000_009B,
+    0xD1FF_0000_0000_00A1,
    0xD1FF_0000_0000_00B1,
-    0xD1FF_0000_0000_00B2,
-    0xD1FF_0000_0000_00B3,
-    0xD1FF_0000_0000_00B5,
-    0xD1FF_0000_0000_00B7,
-    0xD1FF_0000_0000_00B8,
-    0xD1FF_0000_0000_00B9,
-    0xD1FF_0000_0000_00BA,
-    0xD1FF_0000_0000_00BB,
-    0xD1FF_0000_0000_00BC,
-    0xD1FF_0000_0000_00BD,
-    0xD1FF_0000_0000_00C2,
    0xD1FF_0000_0000_00C3,
-    0xD1FF_0000_0000_00C5,
-    0xD1FF_0000_0000_00CC,
-    0xD1FF_0000_0000_00CE,
-    0xD1FF_0000_0000_00D1,
-    0xD1FF_0000_0000_00D2,
    0xD1FF_0000_0000_00D6,
-    0xD1FF_0000_0000_00D7,
-    0xD1FF_0000_0000_00DC,
-    0xD1FF_0000_0000_00DF,
-    0xD1FF_0000_0000_00E0,
-    0xD1FF_0000_0000_00E1,
-    0xD1FF_0000_0000_00E4,
-    0xD1FF_0000_0000_00E6,
-    0xD1FF_0000_0000_00E7,
+    0xD1FF_0000_0000_00DD,
+    0xD1FF_0000_0000_00E8,
+    0xD1FF_0000_0000_00F2,
+    0xD1FF_0000_0000_0101,
+    0xD1FF_0000_0000_010F,
+    0xD1FF_0000_0000_0113,
+    0xD1FF_0000_0000_0118,
+    0xD1FF_0000_0000_0119,
+    0xD1FF_0000_0000_012D,
+    0xD1FF_0000_0000_0133,
+    0xD1FF_0000_0000_0144,
+    0xD1FF_0000_0000_0147,
 ];

 /// 40 seeds proven winnable within the Expert budget (≤ 100 000 states).
 pub const EXPERT_SEEDS: &[u64] = &[
-    // Generated by solitaire_assetgen::gen_difficulty_seeds (tier=Expert, date=2026-05-09)
-    0xD1FF_0000_0000_0006,
-    0xD1FF_0000_0000_000B,
-    0xD1FF_0000_0000_0019,
+    // Generated by solitaire_assetgen::gen_difficulty_seeds (tier=Expert, date=2026-06-04)
+    0xD1FF_0000_0000_0000,
+    0xD1FF_0000_0000_0002,
+    0xD1FF_0000_0000_000A,
+    0xD1FF_0000_0000_0013,
+    0xD1FF_0000_0000_0017,
+    0xD1FF_0000_0000_001C,
+    0xD1FF_0000_0000_001F,
+    0xD1FF_0000_0000_0021,
+    0xD1FF_0000_0000_0024,
+    0xD1FF_0000_0000_0029,
+    0xD1FF_0000_0000_002E,
+    0xD1FF_0000_0000_0035,
+    0xD1FF_0000_0000_0045,
+    0xD1FF_0000_0000_0048,
+    0xD1FF_0000_0000_0049,
+    0xD1FF_0000_0000_004F,
+    0xD1FF_0000_0000_0062,
+    0xD1FF_0000_0000_006D,
+    0xD1FF_0000_0000_0074,
+    0xD1FF_0000_0000_0076,
    0xD1FF_0000_0000_0082,
-    0xD1FF_0000_0000_00CB,
-    0xD1FF_0000_0000_00D5,
-    0xD1FF_0000_0000_00D8,
-    0xD1FF_0000_0000_00E8,
-    0xD1FF_0000_0000_00EA,
-    0xD1FF_0000_0000_00EB,
-    0xD1FF_0000_0000_00EC,
+    0xD1FF_0000_0000_008F,
+    0xD1FF_0000_0000_0090,
+    0xD1FF_0000_0000_0097,
+    0xD1FF_0000_0000_009A,
+    0xD1FF_0000_0000_009F,
+    0xD1FF_0000_0000_00A5,
+    0xD1FF_0000_0000_00A8,
+    0xD1FF_0000_0000_00AD,
+    0xD1FF_0000_0000_00AE,
+    0xD1FF_0000_0000_00B8,
+    0xD1FF_0000_0000_00B9,
+    0xD1FF_0000_0000_00BC,
+    0xD1FF_0000_0000_00C5,
+    0xD1FF_0000_0000_00CA,
+    0xD1FF_0000_0000_00CE,
+    0xD1FF_0000_0000_00DE,
    0xD1FF_0000_0000_00ED,
-    0xD1FF_0000_0000_00F2,
-    0xD1FF_0000_0000_00F3,
-    0xD1FF_0000_0000_00F4,
-    0xD1FF_0000_0000_00FE,
-    0xD1FF_0000_0000_00FF,
-    0xD1FF_0000_0000_0102,
-    0xD1FF_0000_0000_0103,
-    0xD1FF_0000_0000_0104,
-    0xD1FF_0000_0000_0105,
-    0xD1FF_0000_0000_0106,
-    0xD1FF_0000_0000_0109,
-    0xD1FF_0000_0000_010B,
-    0xD1FF_0000_0000_010C,
-    0xD1FF_0000_0000_0110,
-    0xD1FF_0000_0000_0113,
-    0xD1FF_0000_0000_0114,
-    0xD1FF_0000_0000_011B,
-    0xD1FF_0000_0000_011C,
-    0xD1FF_0000_0000_011E,
-    0xD1FF_0000_0000_0120,
-    0xD1FF_0000_0000_0121,
-    0xD1FF_0000_0000_0122,
-    0xD1FF_0000_0000_0123,
-    0xD1FF_0000_0000_0124,
-    0xD1FF_0000_0000_0126,
-    0xD1FF_0000_0000_012B,
-    0xD1FF_0000_0000_012C,
-    0xD1FF_0000_0000_012E,
+    0xD1FF_0000_0000_00EE,
+    0xD1FF_0000_0000_00EF,
 ];

 /// 40 seeds proven winnable only within the Grandmaster budget (≤ 200 000 states).
 pub const GRANDMASTER_SEEDS: &[u64] = &[
-    // Generated by solitaire_assetgen::gen_difficulty_seeds (tier=Grandmaster, date=2026-05-09)
-    0xD1FF_0000_0000_0027,
-    0xD1FF_0000_0000_00A0,
-    0xD1FF_0000_0000_00C4,
-    0xD1FF_0000_0000_00D4,
-    0xD1FF_0000_0000_00DE,
-    0xD1FF_0000_0000_00F9,
-    0xD1FF_0000_0000_0107,
-    0xD1FF_0000_0000_0108,
-    0xD1FF_0000_0000_0130,
-    0xD1FF_0000_0000_0132,
-    0xD1FF_0000_0000_0133,
-    0xD1FF_0000_0000_0134,
+    // Generated by solitaire_assetgen::gen_difficulty_seeds (tier=Grandmaster, date=2026-06-04)
+    0xD1FF_0000_0000_003C,
+    0xD1FF_0000_0000_0047,
+    0xD1FF_0000_0000_005A,
+    0xD1FF_0000_0000_009C,
+    0xD1FF_0000_0000_00D2,
+    0xD1FF_0000_0000_00F4,
+    0xD1FF_0000_0000_00F6,
+    0xD1FF_0000_0000_0104,
+    0xD1FF_0000_0000_0106,
+    0xD1FF_0000_0000_0111,
+    0xD1FF_0000_0000_0112,
+    0xD1FF_0000_0000_0116,
+    0xD1FF_0000_0000_0117,
+    0xD1FF_0000_0000_011A,
+    0xD1FF_0000_0000_0123,
+    0xD1FF_0000_0000_012B,
+    0xD1FF_0000_0000_012E,
    0xD1FF_0000_0000_0135,
-    0xD1FF_0000_0000_0137,
-    0xD1FF_0000_0000_0139,
    0xD1FF_0000_0000_013A,
-    0xD1FF_0000_0000_013D,
-    0xD1FF_0000_0000_013F,
-    0xD1FF_0000_0000_0140,
+    0xD1FF_0000_0000_013B,
    0xD1FF_0000_0000_0141,
-    0xD1FF_0000_0000_0142,
-    0xD1FF_0000_0000_0143,
-    0xD1FF_0000_0000_0145,
-    0xD1FF_0000_0000_0146,
    0xD1FF_0000_0000_014A,
    0xD1FF_0000_0000_014B,
-    0xD1FF_0000_0000_014C,
-    0xD1FF_0000_0000_014D,
-    0xD1FF_0000_0000_014F,
+    0xD1FF_0000_0000_014E,
    0xD1FF_0000_0000_0150,
-    0xD1FF_0000_0000_0151,
-    0xD1FF_0000_0000_0152,
-    0xD1FF_0000_0000_0153,
+    0xD1FF_0000_0000_0155,
    0xD1FF_0000_0000_0157,
    0xD1FF_0000_0000_0158,
-    0xD1FF_0000_0000_015B,
+    0xD1FF_0000_0000_0159,
+    0xD1FF_0000_0000_015A,
    0xD1FF_0000_0000_015C,
-    0xD1FF_0000_0000_015E,
-    0xD1FF_0000_0000_0162,
-    0xD1FF_0000_0000_0164,
+    0xD1FF_0000_0000_015D,
+    0xD1FF_0000_0000_015F,
+    0xD1FF_0000_0000_0166,
+    0xD1FF_0000_0000_0173,
+    0xD1FF_0000_0000_0174,
+    0xD1FF_0000_0000_0178,
+    0xD1FF_0000_0000_017D,
+    0xD1FF_0000_0000_0182,
+    0xD1FF_0000_0000_0187,
 ];

 // ---------------------------------------------------------------------------
@@ -58,7 +58,7 @@ pub trait SyncProvider: Send + Sync {
    /// so backends without a server (e.g. `LocalOnlyProvider`) are
    /// silently no-op'd by the engine's push-on-win system, matching
    /// the same pattern `pull` / `push` follow.
-    async fn push_replay(&self, _replay: &crate::replay::Replay) -> Result<String, SyncError> {
+    async fn push_replay(&self, _replay: &Replay) -> Result<String, SyncError> {
        Err(SyncError::UnsupportedPlatform)
    }
 }
@@ -94,7 +94,7 @@ impl SyncProvider for Box<dyn SyncProvider + Send + Sync> {
    async fn delete_account(&self) -> Result<(), SyncError> {
        (**self).delete_account().await
    }
-    async fn push_replay(&self, replay: &crate::replay::Replay) -> Result<String, SyncError> {
+    async fn push_replay(&self, replay: &Replay) -> Result<String, SyncError> {
        (**self).push_replay(replay).await
    }
 }
@@ -118,8 +118,8 @@ pub use achievements::{

 pub mod progress;
 pub use progress::{
-    PlayerProgress, daily_seed_for, level_for_xp, load_progress_from, progress_file_path,
-    save_progress_to, xp_for_win,
+    PlayerProgress, XpBreakdown, daily_seed_for, level_for_xp, load_progress_from,
+    progress_file_path, save_progress_to, xp_breakdown, xp_for_win,
 };

 pub mod weekly;
@@ -143,27 +143,39 @@ pub use settings::{
    load_settings_from, save_settings_to, settings_file_path,
 };

+#[cfg(target_os = "android")]
+pub mod android_jni;
+
 #[cfg(target_os = "android")]
 mod android_keystore;

+#[cfg(not(target_arch = "wasm32"))]
 pub mod auth_tokens;
+#[cfg(not(target_arch = "wasm32"))]
 pub use auth_tokens::{
    TokenError, delete_tokens, load_access_token, load_refresh_token, store_tokens,
 };

 pub mod sync_client;
-pub use sync_client::{LocalOnlyProvider, SolitaireServerClient, provider_for_backend};
+pub use sync_client::LocalOnlyProvider;
+#[cfg(not(target_arch = "wasm32"))]
+pub use sync_client::{SolitaireServerClient, provider_for_backend};

 pub mod replay;
 pub use replay::{
    REPLAY_HISTORY_CAP, REPLAY_HISTORY_SCHEMA_VERSION, REPLAY_SCHEMA_VERSION, Replay,
-    ReplayHistory, ReplayMove, append_replay_to_history, load_replay_history_from,
+    ReplayHistory, append_replay_to_history, load_replay_history_from,
    migrate_legacy_latest_replay, replay_history_path, save_replay_history_to,
 };
+// `latest_replay_path` is still consumed by the engine's one-shot legacy
+// migration; `load_latest_replay_from`/`save_latest_replay_to` had no callers
+// outside `replay.rs` and were dropped from the public surface.
 #[allow(deprecated)]
-pub use replay::{latest_replay_path, load_latest_replay_from, save_latest_replay_to};
+pub use replay::latest_replay_path;

+#[cfg(not(target_arch = "wasm32"))]
 pub mod matomo_client;
+#[cfg(not(target_arch = "wasm32"))]
 pub use matomo_client::MatomoClient;

 pub mod platform;
@@ -114,3 +114,62 @@ fn url_encode(s: &str) -> String {
        })
        .collect()
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn pending(client: &MatomoClient) -> Vec<String> {
+        client.pending.lock().expect("pending lock").clone()
+    }
+
+    #[test]
+    fn event_buffers_encoded_matomo_query() {
+        let client = MatomoClient::new(
+            "https://analytics.example.com/",
+            7,
+            Some("alice bob".into()),
+        );
+
+        client.event("Game Flow", "Won+Fast", Some("draw three"), Some(42.5));
+
+        let pending = pending(&client);
+        assert_eq!(pending.len(), 1);
+        let query = &pending[0];
+        assert!(query.contains("idsite=7"));
+        assert!(query.contains("rec=1"));
+        assert!(query.contains("e_c=Game%20Flow"));
+        assert!(query.contains("e_a=Won%2BFast"));
+        assert!(query.contains("e_n=draw%20three"));
+        assert!(query.contains("e_v=42.5"));
+        assert!(query.contains("uid=alice%20bob"));
+    }
+
+    #[test]
+    fn event_buffer_drops_oldest_entries_when_capacity_exceeded() {
+        let client = MatomoClient::new("https://analytics.example.com", 1, None);
+
+        for idx in 0..101 {
+            client.event("Game", "Start", Some(&format!("event-{idx}")), None);
+        }
+
+        let pending = pending(&client);
+        assert_eq!(pending.len(), 51);
+        assert!(
+            pending[0].contains("event-50"),
+            "oldest retained event should be event-50, got {}",
+            pending[0]
+        );
+        assert!(
+            pending[50].contains("event-100"),
+            "newest retained event should be event-100, got {}",
+            pending[50]
+        );
+    }
+
+    #[test]
+    fn url_encode_leaves_unreserved_bytes_and_escapes_everything_else() {
+        assert_eq!(url_encode("AZaz09-_.~"), "AZaz09-_.~");
+        assert_eq!(url_encode("a b+c/d?"), "a%20b%2Bc%2Fd%3F");
+    }
+}
@@ -55,7 +55,15 @@ pub fn data_dir() -> Option<PathBuf> {
    {
        Some(PathBuf::from(ANDROID_APP_FILES_DIR))
    }
-    #[cfg(not(target_os = "android"))]
+    #[cfg(target_arch = "wasm32")]
+    {
+        // No filesystem on the browser; all persistence goes through
+        // WasmStorage (localStorage-backed). Return None so every caller
+        // degrades gracefully (the same path they take on a
+        // misconfigured desktop environment).
+        None
+    }
+    #[cfg(all(not(target_os = "android"), not(target_arch = "wasm32")))]
    {
        dirs::data_dir()
    }
@@ -25,12 +25,34 @@ pub fn daily_seed_for(date: NaiveDate) -> u64 {
    y * 10_000 + m * 100 + d
 }

-/// XP awarded for winning a game.
+/// Component breakdown of the XP awarded for a win.
+///
+/// This is the single source of truth for win-XP scoring: [`xp_for_win`] sums
+/// it for the total, and UI that displays the individual lines (the win-summary
+/// modal) reads the parts from here so the breakdown can never drift from the
+/// total.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct XpBreakdown {
+    /// Flat base XP granted for any win.
+    pub base: u64,
+    /// Scaled fast-win bonus (10..=50 for sub-2-minute wins, else 0).
+    pub speed_bonus: u64,
+    /// Bonus for winning without using undo (25, else 0).
+    pub no_undo_bonus: u64,
+}
+
+impl XpBreakdown {
+    /// Total XP awarded: `base + speed_bonus + no_undo_bonus`.
+    pub fn total(self) -> u64 {
+        self.base + self.speed_bonus + self.no_undo_bonus
+    }
+}
+
+/// Component breakdown of the XP awarded for a win.
 ///
 /// Base 50 + scaled fast-win bonus (10..=50 for sub-2-minute wins) + 25 if
 /// the player did not use undo.
-pub fn xp_for_win(time_seconds: u64, used_undo: bool) -> u64 {
-    let base: u64 = 50;
+pub fn xp_breakdown(time_seconds: u64, used_undo: bool) -> XpBreakdown {
    let speed_bonus: u64 = if time_seconds >= 120 {
        0
    } else {
@@ -39,8 +61,16 @@ pub fn xp_for_win(time_seconds: u64, used_undo: bool) -> u64 {
        let scaled = 50_u64.saturating_sub(time_seconds.saturating_mul(40) / 120);
        scaled.max(10)
    };
-    let no_undo_bonus: u64 = if used_undo { 0 } else { 25 };
-    base + speed_bonus + no_undo_bonus
+    XpBreakdown {
+        base: 50,
+        speed_bonus,
+        no_undo_bonus: if used_undo { 0 } else { 25 },
+    }
+}
+
+/// XP awarded for winning a game. See [`xp_breakdown`] for the components.
+pub fn xp_for_win(time_seconds: u64, used_undo: bool) -> u64 {
+    xp_breakdown(time_seconds, used_undo).total()
 }

 /// Platform-specific default path for `progress.json`.
@@ -12,13 +12,22 @@
 //! carries any other version so older replays are silently dropped instead
 //! of crashing the loader.
 //!
-//! The recording is intentionally minimal — only [`ReplayMove`] entries
-//! that successfully advanced the game. `Undo` is **not** recorded: a
-//! replay represents the canonical path the player ultimately took to win,
-//! so backed-out missteps simply do not appear in the move list. The
-//! starting deal is not stored either — the [`seed`](Replay::seed) +
+//! The recording is intentionally minimal — only the
+//! [`KlondikeInstruction`](solitaire_core::KlondikeInstruction) inputs that
+//! successfully advanced the game. `Undo` is **not** recorded: a replay
+//! represents the canonical path the player ultimately took to win, so
+//! backed-out missteps simply do not appear in the move list. The starting
+//! deal is not stored either — the [`seed`](Replay::seed) +
 //! [`draw_mode`](Replay::draw_mode) + [`mode`](Replay::mode) are sufficient
 //! for `GameState::new_with_mode` to rebuild the identical layout.
+//!
+//! Each recorded move is the player's atomic *input*, not its outcome.
+//! `KlondikeInstruction::RotateStock` covers every click on the stock pile;
+//! the engine resolves draw-vs-recycle deterministically from the current
+//! stock state during playback, so the same input always produces the same
+//! effect on the same starting deal. Runtime-only pile-position types are
+//! never serialised — the instruction itself serialises via its compact
+//! upstream serde representation.

 use std::fs;
 use std::io;
@@ -26,8 +35,7 @@ use std::path::{Path, PathBuf};

 use chrono::NaiveDate;
 use serde::{Deserialize, Serialize};
-use solitaire_core::game_state::{DrawMode, GameMode};
-use solitaire_core::pile::PileType;
+use solitaire_core::{DrawStockConfig, KlondikeInstruction, game_state::GameMode};

 const LATEST_REPLAY_FILE_NAME: &str = "latest_replay.json";
 const REPLAY_HISTORY_FILE_NAME: &str = "replays.json";
@@ -65,14 +73,17 @@ fn history_schema_v0() -> u32 {
 /// seeing a broken one.
 ///
 /// History:
-/// - v1: initial release. `ReplayMove` had separate `Draw` and `Recycle`
+/// - v1: initial release. The move type had separate `Draw` and `Recycle`
 ///   variants which carried the *outcome* of a stock interaction rather
 ///   than the player's atomic input.
-/// - v2 (current): `Draw` + `Recycle` collapsed into a single `StockClick`
-///   variant. The engine resolves draw-vs-recycle deterministically from
-///   the current stock state, so the input alone is sufficient and the
-///   replay model now stores atomic player inputs end-to-end.
-pub const REPLAY_SCHEMA_VERSION: u32 = 2;
+/// - v2: `Draw` + `Recycle` collapsed into a single `StockClick` variant.
+/// - v3 (current): the bespoke `ReplayMove` serde mirror was dropped. Moves
+///   are now stored directly as upstream
+///   [`KlondikeInstruction`](solitaire_core::KlondikeInstruction) (compact
+///   int serde); `StockClick` is now `RotateStock`. Pile-position types are
+///   runtime-only and are never serialised. v1/v2 files fail to deserialise
+///   and are discarded by the loader.
+pub const REPLAY_SCHEMA_VERSION: u32 = 3;

 /// Default value for [`Replay::schema_version`] when deserialising files
 /// that pre-date the field. Any value other than [`REPLAY_SCHEMA_VERSION`]
@@ -81,32 +92,6 @@ fn schema_v0() -> u32 {
    0
 }

-/// One atomic player input recorded during a winning game, in the order
-/// it was applied to the live `GameState`.
-///
-/// `Undo` is intentionally absent — see the module-level docs.
-///
-/// The variants represent *inputs*, not outcomes. `StockClick` covers
-/// every player click on the stock pile; the engine then resolves
-/// draw-vs-recycle deterministically from the current state during both
-/// recording and playback, so the same input always produces the same
-/// effect on the same starting deal.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub enum ReplayMove {
-    /// A successful `move_cards(from, to, count)` call.
-    Move {
-        /// Source pile.
-        from: PileType,
-        /// Destination pile.
-        to: PileType,
-        /// Number of cards moved.
-        count: usize,
-    },
-    /// A click on the stock pile. Resolves to a draw when stock is
-    /// non-empty and to a waste→stock recycle when stock is empty.
-    StockClick,
-}
-
 /// A complete recording of a single winning game.
 ///
 /// Replays are reconstructed by rebuilding a fresh
@@ -124,7 +109,7 @@ pub struct Replay {
    /// `GameState::new_with_mode(seed, draw_mode, mode)`.
    pub seed: u64,
    /// Draw mode the recorded game was played in.
-    pub draw_mode: DrawMode,
+    pub draw_mode: DrawStockConfig,
    /// Game mode the recorded game was played in.
    pub mode: GameMode,
    /// Total wall-clock seconds the win took. Used for the Stats UI
@@ -134,9 +119,11 @@ pub struct Replay {
    pub final_score: i32,
    /// ISO-8601 date the win was recorded.
    pub recorded_at: NaiveDate,
-    /// Ordered move list. Each entry is what the player did, replayable
-    /// against a fresh `GameState` constructed from the seed.
-    pub moves: Vec<ReplayMove>,
+    /// Ordered move list. Each entry is the atomic
+    /// [`KlondikeInstruction`](solitaire_core::KlondikeInstruction) the player
+    /// issued, replayable against a fresh `GameState` constructed from the
+    /// seed via `GameState::apply_instruction`.
+    pub moves: Vec<KlondikeInstruction>,
    /// Public share URL for this replay on the active sync backend, set
    /// by `sync_plugin::poll_replay_upload_result` when the upload
    /// task resolves. `None` when the player won on a local-only
@@ -180,12 +167,12 @@ impl Replay {
    /// latter directly when the upload task resolves.
    pub fn new(
        seed: u64,
-        draw_mode: DrawMode,
+        draw_mode: DrawStockConfig,
        mode: GameMode,
        time_seconds: u64,
        final_score: i32,
        recorded_at: NaiveDate,
-        moves: Vec<ReplayMove>,
+        moves: Vec<KlondikeInstruction>,
    ) -> Self {
        Self {
            schema_version: REPLAY_SCHEMA_VERSION,
@@ -442,6 +429,9 @@ pub fn migrate_legacy_latest_replay(latest_path: &Path, history_path: &Path) {
 #[allow(deprecated)]
 mod tests {
    use super::*;
+    use klondike::{
+        DstFoundation, DstTableau, Foundation, KlondikePile, KlondikePileStack, Tableau,
+    };
    use std::env;

    fn tmp_path(name: &str) -> PathBuf {
@@ -452,24 +442,22 @@ mod tests {
        let date = NaiveDate::from_ymd_opt(2026, 5, 2).expect("valid date");
        Replay::new(
            12345,
-            DrawMode::DrawThree,
+            DrawStockConfig::DrawThree,
            GameMode::Classic,
            134,
            5_120,
            date,
            vec![
-                ReplayMove::StockClick,
-                ReplayMove::Move {
-                    from: PileType::Waste,
-                    to: PileType::Tableau(3),
-                    count: 1,
-                },
-                ReplayMove::StockClick,
-                ReplayMove::Move {
-                    from: PileType::Tableau(3),
-                    to: PileType::Foundation(0),
-                    count: 1,
-                },
+                KlondikeInstruction::RotateStock,
+                KlondikeInstruction::DstTableau(DstTableau {
+                    src: KlondikePileStack::Stock,
+                    tableau: Tableau::Tableau4,
+                }),
+                KlondikeInstruction::RotateStock,
+                KlondikeInstruction::DstFoundation(DstFoundation {
+                    src: KlondikePile::Tableau(Tableau::Tableau4),
+                    foundation: Foundation::Foundation1,
+                }),
            ],
        )
    }
@@ -595,12 +583,12 @@ mod tests {
        let date = NaiveDate::from_ymd_opt(2026, 5, 2).expect("valid date");
        Replay::new(
            id as u64,
-            DrawMode::DrawOne,
+            DrawStockConfig::DrawOne,
            GameMode::Classic,
            60,
            id,
            date,
-            vec![ReplayMove::StockClick],
+            vec![KlondikeInstruction::RotateStock],
        )
    }

@@ -836,9 +824,11 @@ mod tests {
        let path = tmp_path("legacy_no_win_move_index");
        let _ = fs::remove_file(&path);

-        // Hand-rolled minimal v2 replay JSON with no win_move_index field.
-        let v2_no_field = r#"{
-            "schema_version": 2,
+        // Hand-rolled minimal current-schema replay JSON with no
+        // win_move_index field — the additive field must still default to None.
+        let no_field = format!(
+            r#"{{
+            "schema_version": {schema},
            "seed": 1,
            "draw_mode": "DrawOne",
            "mode": "Classic",
@@ -846,8 +836,10 @@ mod tests {
            "final_score": 100,
            "recorded_at": "2026-05-02",
            "moves": []
-        }"#;
-        fs::write(&path, v2_no_field).expect("write fixture");
+        }}"#,
+            schema = REPLAY_SCHEMA_VERSION,
+        );
+        fs::write(&path, no_field).expect("write fixture");

        let loaded = load_latest_replay_from(&path).expect("load");
        assert_eq!(loaded.win_move_index, None);
@@ -9,7 +9,7 @@ use std::io;
 use std::path::{Path, PathBuf};

 use serde::{Deserialize, Serialize};
-use solitaire_core::game_state::{DifficultyLevel, DrawMode};
+use solitaire_core::{DrawStockConfig, game_state::DifficultyLevel};

 const SETTINGS_FILE_NAME: &str = "settings.json";

@@ -101,7 +101,7 @@ pub struct WindowGeometry {
 pub struct Settings {
    /// Draw mode selected for new games.
    #[serde(default = "default_draw_mode")]
-    pub draw_mode: DrawMode,
+    pub draw_mode: DrawStockConfig,
    /// Linear SFX volume in `[0.0, 1.0]`. Applied to kira's SFX channel gain.
    #[serde(default = "default_sfx_volume")]
    pub sfx_volume: f32,
@@ -200,7 +200,7 @@ pub struct Settings {
    #[serde(default = "default_time_bonus_multiplier")]
    pub time_bonus_multiplier: f32,
    /// When `true`, the engine rejects new-game deals the
-    /// [`solitaire_core::solver`] cannot prove winnable, retrying
+    /// the solver cannot prove winnable, retrying
    /// fresh seeds up to [`SOLVER_DEAL_RETRY_CAP`] attempts before
    /// giving up and using the last tried seed. Off by default —
    /// the solver adds a few hundred milliseconds of latency on the
@@ -288,8 +288,8 @@ pub struct Settings {
    pub touch_input_mode: TouchInputMode,
 }

-fn default_draw_mode() -> DrawMode {
-    DrawMode::DrawOne
+fn default_draw_mode() -> DrawStockConfig {
+    DrawStockConfig::DrawOne
 }

 fn default_sfx_volume() -> f32 {
@@ -381,9 +381,9 @@ pub const REPLAY_MOVE_INTERVAL_STEP_SECS: f32 = 0.05;
 /// Maximum number of seed retries [`solitaire_engine::handle_new_game`]
 /// is willing to attempt before giving up and accepting the latest
 /// candidate seed when [`Settings::winnable_deals_only`] is on. If
-/// every retry comes back [`SolverResult::Unwinnable`] (which would
-/// be very unusual) we'd rather hand the player a possibly-unwinnable
-/// deal than spin forever on the main thread.
+/// every retry comes back provably unwinnable (`Ok(None)` from the
+/// solver, which would be very unusual) we'd rather hand the player a
+/// possibly-unwinnable deal than spin forever on the main thread.
 ///
 /// 50 attempts × ~50 ms median per solve = ~2.5 s worst-case stall —
 /// the upper bound on UI freeze when the toggle is on.
@@ -392,7 +392,7 @@ pub const SOLVER_DEAL_RETRY_CAP: u32 = 50;
 impl Default for Settings {
    fn default() -> Self {
        Self {
-            draw_mode: DrawMode::DrawOne,
+            draw_mode: DrawStockConfig::DrawOne,
            sfx_volume: default_sfx_volume(),
            music_volume: default_music_volume(),
            animation_speed: AnimSpeed::Normal,
@@ -2,10 +2,10 @@
 //!
 //! [`StatsSnapshot`] is defined in `solitaire_sync` and re-exported here.
 //! This module adds the [`StatsExt`] extension trait, which supplies the
-//! `update_on_win` method that depends on [`DrawMode`] from `solitaire_core`.
+//! `update_on_win` method that depends on [`DrawStockConfig`] from `solitaire_core`.

 use chrono::Utc;
-use solitaire_core::game_state::{DrawMode, GameMode};
+use solitaire_core::{DrawStockConfig, game_state::GameMode};

 pub use solitaire_sync::StatsSnapshot;

@@ -18,9 +18,9 @@ pub trait StatsExt {
    ///
    /// Tracks lifetime totals only — per-mode best scores and times are
    /// updated separately via [`StatsExt::update_per_mode_bests`] so the
-    /// long-standing call sites that only know about [`DrawMode`] keep
+    /// long-standing call sites that only know about [`DrawStockConfig`] keep
    /// compiling.
-    fn update_on_win(&mut self, score: i32, time_seconds: u64, draw_mode: &DrawMode);
+    fn update_on_win(&mut self, score: i32, time_seconds: u64, draw_mode: &DrawStockConfig);

    /// Updates the per-mode best score and fastest-win-time fields for the
    /// given [`GameMode`]. Call alongside [`StatsExt::update_on_win`] from
@@ -37,7 +37,7 @@ pub trait StatsExt {
 }

 impl StatsExt for StatsSnapshot {
-    fn update_on_win(&mut self, score: i32, time_seconds: u64, draw_mode: &DrawMode) {
+    fn update_on_win(&mut self, score: i32, time_seconds: u64, draw_mode: &DrawStockConfig) {
        let prev_wins = self.games_won;
        self.games_played += 1;
        self.games_won += 1;
@@ -64,8 +64,8 @@ impl StatsExt for StatsSnapshot {
        };

        match draw_mode {
-            DrawMode::DrawOne => self.draw_one_wins += 1,
-            DrawMode::DrawThree => self.draw_three_wins += 1,
+            DrawStockConfig::DrawOne => self.draw_one_wins += 1,
+            DrawStockConfig::DrawThree => self.draw_three_wins += 1,
        }

        self.last_modified = Utc::now();
@@ -135,7 +135,7 @@ mod tests {
    #[test]
    fn first_win_sets_all_fields() {
        let mut s = StatsSnapshot::default();
-        s.update_on_win(1500, 120, &DrawMode::DrawOne);
+        s.update_on_win(1500, 120, &DrawStockConfig::DrawOne);
        assert_eq!(s.games_played, 1);
        assert_eq!(s.games_won, 1);
        assert_eq!(s.win_streak_current, 1);
@@ -152,7 +152,7 @@ mod tests {
    fn streak_tracks_across_wins() {
        let mut s = StatsSnapshot::default();
        for _ in 0..3 {
-            s.update_on_win(100, 60, &DrawMode::DrawOne);
+            s.update_on_win(100, 60, &DrawStockConfig::DrawOne);
        }
        assert_eq!(s.win_streak_current, 3);
        assert_eq!(s.win_streak_best, 3);
@@ -161,8 +161,8 @@ mod tests {
    #[test]
    fn record_abandoned_resets_streak_and_increments_played() {
        let mut s = StatsSnapshot::default();
-        s.update_on_win(100, 60, &DrawMode::DrawOne);
-        s.update_on_win(100, 60, &DrawMode::DrawOne);
+        s.update_on_win(100, 60, &DrawStockConfig::DrawOne);
+        s.update_on_win(100, 60, &DrawStockConfig::DrawOne);
        assert_eq!(s.win_streak_current, 2);
        s.record_abandoned();
        assert_eq!(s.games_played, 3);
@@ -174,35 +174,35 @@ mod tests {
    #[test]
    fn fastest_win_takes_minimum() {
        let mut s = StatsSnapshot::default();
-        s.update_on_win(100, 300, &DrawMode::DrawOne);
-        s.update_on_win(100, 120, &DrawMode::DrawOne);
-        s.update_on_win(100, 500, &DrawMode::DrawOne);
+        s.update_on_win(100, 300, &DrawStockConfig::DrawOne);
+        s.update_on_win(100, 120, &DrawStockConfig::DrawOne);
+        s.update_on_win(100, 500, &DrawStockConfig::DrawOne);
        assert_eq!(s.fastest_win_seconds, 120);
    }

    #[test]
    fn avg_time_is_correct_rolling_average() {
        let mut s = StatsSnapshot::default();
-        s.update_on_win(100, 100, &DrawMode::DrawOne);
-        s.update_on_win(100, 200, &DrawMode::DrawOne);
-        s.update_on_win(100, 300, &DrawMode::DrawOne);
+        s.update_on_win(100, 100, &DrawStockConfig::DrawOne);
+        s.update_on_win(100, 200, &DrawStockConfig::DrawOne);
+        s.update_on_win(100, 300, &DrawStockConfig::DrawOne);
        assert_eq!(s.avg_time_seconds, 200);
    }

    #[test]
    fn best_score_updates_only_on_higher_score() {
        let mut s = StatsSnapshot::default();
-        s.update_on_win(500, 60, &DrawMode::DrawOne);
-        s.update_on_win(300, 60, &DrawMode::DrawOne);
+        s.update_on_win(500, 60, &DrawStockConfig::DrawOne);
+        s.update_on_win(300, 60, &DrawStockConfig::DrawOne);
        assert_eq!(s.best_single_score, 500);
-        s.update_on_win(800, 60, &DrawMode::DrawOne);
+        s.update_on_win(800, 60, &DrawStockConfig::DrawOne);
        assert_eq!(s.best_single_score, 800);
    }

    #[test]
    fn negative_score_treated_as_zero() {
        let mut s = StatsSnapshot::default();
-        s.update_on_win(-50, 60, &DrawMode::DrawOne);
+        s.update_on_win(-50, 60, &DrawStockConfig::DrawOne);
        assert_eq!(s.best_single_score, 0);
        assert_eq!(s.lifetime_score, 0);
    }
@@ -210,8 +210,8 @@ mod tests {
    #[test]
    fn draw_three_wins_tracked_separately() {
        let mut s = StatsSnapshot::default();
-        s.update_on_win(100, 60, &DrawMode::DrawOne);
-        s.update_on_win(100, 60, &DrawMode::DrawThree);
+        s.update_on_win(100, 60, &DrawStockConfig::DrawOne);
+        s.update_on_win(100, 60, &DrawStockConfig::DrawThree);
        assert_eq!(s.draw_one_wins, 1);
        assert_eq!(s.draw_three_wins, 1);
    }
@@ -221,7 +221,7 @@ mod tests {
        let mut s = StatsSnapshot::default();
        // Build a streak of 5.
        for _ in 0..5 {
-            s.update_on_win(100, 60, &DrawMode::DrawOne);
+            s.update_on_win(100, 60, &DrawStockConfig::DrawOne);
        }
        assert_eq!(s.win_streak_best, 5);
        // Lose (abandon), resetting current.
@@ -229,7 +229,7 @@ mod tests {
        assert_eq!(s.win_streak_current, 0);
        assert_eq!(s.win_streak_best, 5, "best must survive the loss");
        // Win once — current becomes 1, best must remain 5.
-        s.update_on_win(100, 60, &DrawMode::DrawOne);
+        s.update_on_win(100, 60, &DrawStockConfig::DrawOne);
        assert_eq!(s.win_streak_current, 1);
        assert_eq!(
            s.win_streak_best, 5,
@@ -243,7 +243,7 @@ mod tests {
            lifetime_score: u64::MAX - 100,
            ..Default::default()
        };
-        s.update_on_win(200, 60, &DrawMode::DrawOne);
+        s.update_on_win(200, 60, &DrawStockConfig::DrawOne);
        assert_eq!(
            s.lifetime_score,
            u64::MAX,
@@ -3,13 +3,13 @@
 //! All saves go through `filename.json.tmp` → `rename()` so a crash or power
 //! loss during a write never corrupts the saved data.

+use chrono::Utc;
 use std::fs;
 use std::io;
 use std::path::{Path, PathBuf};
-use std::time::{SystemTime, UNIX_EPOCH};

 use serde::{Deserialize, Serialize};
-use solitaire_core::game_state::{GAME_STATE_SCHEMA_VERSION, GameState};
+use solitaire_core::game_state::GameState;

 use crate::stats::StatsSnapshot;

@@ -85,16 +85,13 @@ pub fn game_state_file_path() -> Option<PathBuf> {
 pub fn load_game_state_from(path: &Path) -> Option<GameState> {
    let data = fs::read(path).ok()?;
    let gs: GameState = serde_json::from_slice(&data).ok()?;
-    if gs.schema_version != GAME_STATE_SCHEMA_VERSION {
-        return None;
-    }
-    if gs.is_won { None } else { Some(gs) }
+    if gs.is_won() { None } else { Some(gs) }
 }

 /// Save an in-progress `GameState` atomically. Skips the write if `gs.is_won`
 /// because a completed game should not be resumed.
 pub fn save_game_state_to(path: &Path, gs: &GameState) -> io::Result<()> {
-    if gs.is_won {
+    if gs.is_won() {
        return Ok(());
    }
    if let Some(parent) = path.parent() {
@@ -234,9 +231,7 @@ pub fn load_time_attack_session_from_at(
 /// See [`load_time_attack_session_from_at`] for the rules under which
 /// the call returns `None` (missing file, corrupt JSON, expired window).
 pub fn load_time_attack_session_from(path: &Path) -> Option<TimeAttackSession> {
-    let now = SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .map_or(0, |d| d.as_secs());
+    let now = Utc::now().timestamp().max(0) as u64;
    load_time_attack_session_from_at(path, now)
 }

@@ -254,9 +249,7 @@ pub fn delete_time_attack_session_at(path: &Path) -> io::Result<()> {
 /// current wall-clock time. Equivalent to constructing the struct
 /// manually and setting `saved_at_unix_secs` to `SystemTime::now()`.
 pub fn time_attack_session_with_now(remaining_secs: f32, wins: u32) -> TimeAttackSession {
-    let now = SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .map_or(0, |d| d.as_secs());
+    let now = Utc::now().timestamp().max(0) as u64;
    TimeAttackSession {
        remaining_secs,
        wins,
@@ -286,7 +279,7 @@ fn cleanup_tmp_files_in(dir: &Path) {
 mod tests {
    use super::*;
    use crate::stats::{StatsExt, StatsSnapshot};
-    use solitaire_core::game_state::DrawMode;
+    use solitaire_core::DrawStockConfig;
    use std::env;

    fn tmp_path(name: &str) -> PathBuf {
@@ -299,7 +292,7 @@ mod tests {
        let _ = fs::remove_file(&path);

        let mut stats = StatsSnapshot::default();
-        stats.update_on_win(1000, 180, &DrawMode::DrawOne);
+        stats.update_on_win(1000, 180, &DrawStockConfig::DrawOne);
        save_stats_to(&path, &stats).expect("save");

        let loaded = load_stats_from(&path);
@@ -384,17 +377,17 @@ mod tests {

    #[test]
    fn game_state_round_trip() {
-        use solitaire_core::game_state::{DrawMode, GameState};
+        use solitaire_core::game_state::GameState;
        let path = gs_path("round_trip");
        let _ = fs::remove_file(&path);

-        let gs = GameState::new(12345, DrawMode::DrawOne);
+        let gs = GameState::new(12345, DrawStockConfig::DrawOne);
        save_game_state_to(&path, &gs).expect("save");

        let loaded = load_game_state_from(&path).expect("load");
        assert_eq!(loaded.seed, gs.seed);
-        assert_eq!(loaded.draw_mode, gs.draw_mode);
-        assert!(!loaded.is_won);
+        assert_eq!(loaded.draw_mode(), gs.draw_mode());
+        assert!(!loaded.is_won());
    }

    #[test]
@@ -413,12 +406,12 @@ mod tests {

    #[test]
    fn save_game_state_skips_won_games() {
-        use solitaire_core::game_state::{DrawMode, GameState};
+        use solitaire_core::game_state::GameState;
        let path = gs_path("won_skip");
        let _ = fs::remove_file(&path);

-        let mut gs = GameState::new(99, DrawMode::DrawOne);
-        gs.is_won = true;
+        let mut gs = GameState::new(99, DrawStockConfig::DrawOne);
+        gs.set_test_won(true);
        save_game_state_to(&path, &gs).expect("save should be no-op, not error");
        assert!(
            !path.exists(),
@@ -426,28 +419,11 @@ mod tests {
        );
    }

-    #[test]
-    fn load_game_state_ignores_won_games() {
-        use solitaire_core::game_state::{DrawMode, GameState};
-        let path = gs_path("won_load");
-        let _ = fs::remove_file(&path);
-
-        // Write a won game directly (bypassing save_game_state_to's guard).
-        let mut gs = GameState::new(77, DrawMode::DrawOne);
-        gs.is_won = true;
-        let json = serde_json::to_string_pretty(&gs).unwrap();
-        let tmp = path.with_extension("json.tmp");
-        fs::write(&tmp, json.as_bytes()).unwrap();
-        fs::rename(&tmp, &path).unwrap();
-
-        assert!(load_game_state_from(&path).is_none());
-    }
-
    #[test]
    fn delete_game_state_removes_file() {
-        use solitaire_core::game_state::{DrawMode, GameState};
+        use solitaire_core::game_state::GameState;
        let path = gs_path("delete");
-        let gs = GameState::new(1, DrawMode::DrawOne);
+        let gs = GameState::new(1, DrawStockConfig::DrawOne);
        save_game_state_to(&path, &gs).expect("save");
        assert!(path.exists());
        delete_game_state_at(&path).expect("delete");
@@ -463,9 +439,9 @@ mod tests {

    #[test]
    fn save_game_state_is_atomic() {
-        use solitaire_core::game_state::{DrawMode, GameState};
+        use solitaire_core::game_state::GameState;
        let path = gs_path("atomic");
-        let gs = GameState::new(55, DrawMode::DrawThree);
+        let gs = GameState::new(55, DrawStockConfig::DrawThree);
        save_game_state_to(&path, &gs).expect("save");
        let tmp = path.with_extension("json.tmp");
        assert!(!tmp.exists(), ".tmp must be cleaned up after rename");
@@ -516,6 +492,161 @@ mod tests {
        assert_eq!(loaded, StatsSnapshot::default());
    }

+    /// Schema v4 serialises the instruction history using upstream
+    /// `KlondikeInstruction` serde (named enum variants). The deserialiser
+    /// replays all `saved_moves` to reconstruct every pile.
+    ///
+    /// A fresh-game test (zero moves) never exercises that replay path, so this
+    /// test plays several real moves — including an undo — before saving.
+    ///
+    /// Since schema v5 no longer persists `score`/`undo_count`/`recycle_count`
+    /// (they are derived from the replayed session stats), round-trip fidelity is
+    /// verified by **re-save idempotency**: reloading the save and serialising it
+    /// again must reproduce byte-identical JSON. `undo_count` deliberately resets
+    /// to 0 on load because only the forward instruction history is persisted.
+    #[test]
+    fn game_state_v5_mid_game_round_trip() {
+        use solitaire_core::KlondikeInstruction;
+        use solitaire_core::game_state::GameState;
+
+        let path = gs_path("v4_mid_game");
+        let _ = fs::remove_file(&path);
+
+        let mut gs = GameState::new(42, DrawStockConfig::DrawOne);
+
+        // Draw several times to populate the instruction history with
+        // RotateStock entries and expose waste cards for further moves.
+        for _ in 0..6 {
+            if gs.draw().is_err() {
+                break;
+            }
+        }
+
+        // Execute the first available DstTableau or DstFoundation move so the
+        // instruction history contains a type other than RotateStock.
+        if let Some(instruction) = gs.possible_instructions().into_iter().find(|i| {
+            matches!(
+                i,
+                KlondikeInstruction::DstTableau(_) | KlondikeInstruction::DstFoundation(_)
+            )
+        }) {
+            let _ = gs.apply_instruction(instruction);
+        }
+
+        // Undo once: verifies that `undo_count` is persisted and that the
+        // truncated history (post-undo) replays back to the correct state.
+        if gs.undo_stack_len() > 0 {
+            let _ = gs.undo();
+        }
+
+        assert!(
+            gs.undo_stack_len() > 0,
+            "instruction history must be non-empty (seed 42 always produces draws)",
+        );
+
+        save_game_state_to(&path, &gs).expect("save");
+
+        // Verify the file carries the v5 schema marker.
+        let json = fs::read_to_string(&path).expect("read json");
+        assert!(
+            json.contains("\"schema_version\"") && json.contains('5'),
+            "saved file must use schema version 5",
+        );
+
+        let loaded = load_game_state_from(&path)
+            .expect("a valid in-progress game must load without error");
+
+        // The forward instruction history round-trips, so the reconstructed board
+        // re-serialises to byte-identical JSON.
+        let path_reload = gs_path("v5_mid_game_reload");
+        let _ = fs::remove_file(&path_reload);
+        save_game_state_to(&path_reload, &loaded).expect("re-save loaded");
+        assert_eq!(
+            fs::read_to_string(&path).expect("read original save"),
+            fs::read_to_string(&path_reload).expect("read re-saved"),
+            "re-saving the loaded game must reproduce the original save exactly",
+        );
+
+        // Derived board reads match the live game (move count + recycle count are
+        // both rebuilt from the replayed forward history).
+        assert_eq!(loaded.move_count(), gs.move_count(), "move_count round-trips");
+        assert_eq!(
+            loaded.recycle_count(),
+            gs.recycle_count(),
+            "recycle_count round-trips",
+        );
+        // undo_count is intentionally not persisted: it resets to 0 on load.
+        assert_eq!(
+            loaded.undo_count(),
+            0,
+            "undo_count resets across save/load under schema v5",
+        );
+    }
+
+    /// A schema v3 save (instruction history using the old u8-index mirror
+    /// types) is no longer loadable. The legacy migration path was dropped,
+    /// so any file claiming `schema_version: 3` must be rejected and the
+    /// player started on a fresh game.
+    #[test]
+    fn game_state_v3_is_rejected() {
+        let path = gs_path("v3_reject");
+        let _ = fs::remove_file(&path);
+
+        // Hand-crafted schema v3 JSON: one RotateStock (draw) instruction.
+        let v3_json = r#"{
+            "draw_mode": "DrawOne",
+            "mode": "Classic",
+            "score": 0,
+            "elapsed_seconds": 0,
+            "seed": 42,
+            "undo_count": 0,
+            "recycle_count": 0,
+            "take_from_foundation": true,
+            "schema_version": 3,
+            "saved_moves": ["RotateStock"]
+        }"#;
+        fs::write(&path, v3_json).expect("write v3 fixture");
+
+        assert!(
+            load_game_state_from(&path).is_none(),
+            "schema v3 must be rejected (no migration path)",
+        );
+
+        let _ = fs::remove_file(&path);
+    }
+
+    /// Schema v2 stored raw pile arrays and undo snapshots (no instruction
+    /// history). Any file claiming `schema_version: 2` must be rejected so
+    /// players upgrading from an older build start with a fresh game rather
+    /// than a half-reconstructed state.
+    #[test]
+    fn save_format_v2_is_rejected() {
+        let path = gs_path("schema_v2");
+        let _ = fs::remove_file(&path);
+
+        // Structurally valid JSON for `PersistedGameState` but with
+        // `schema_version: 2`. The schema-version gate in
+        // `GameState::deserialize` must reject this before replay starts.
+        let v2_json = r#"{
+            "draw_mode": "DrawOne",
+            "mode": "Classic",
+            "score": 0,
+            "elapsed_seconds": 0,
+            "seed": 42,
+            "undo_count": 0,
+            "recycle_count": 0,
+            "take_from_foundation": true,
+            "schema_version": 2,
+            "saved_moves": []
+        }"#;
+        fs::write(&path, v2_json).expect("write v2 fixture");
+
+        assert!(
+            load_game_state_from(&path).is_none(),
+            "schema v2 game_state.json must be rejected — player must start a fresh game",
+        );
+    }
+
    // -----------------------------------------------------------------------
    // Time Attack session persistence
    //
@@ -12,10 +12,14 @@
 //! without matching on [`SyncBackend`] anywhere else in the codebase.

 use async_trait::async_trait;
-use solitaire_sync::{ChallengeGoal, LeaderboardEntry, SyncPayload, SyncResponse};
+#[cfg(not(target_arch = "wasm32"))]
+use solitaire_sync::{ChallengeGoal, LeaderboardEntry};
+use solitaire_sync::{SyncPayload, SyncResponse};

+use crate::{SyncError, SyncProvider};
+
+#[cfg(not(target_arch = "wasm32"))]
 use crate::{
-    SyncError, SyncProvider,
    auth_tokens::{load_access_token, load_refresh_token, store_tokens},
    replay::Replay,
    settings::SyncBackend,
@@ -54,12 +58,17 @@ impl SyncProvider for LocalOnlyProvider {
 // ---------------------------------------------------------------------------
 // SolitaireServerClient
 // ---------------------------------------------------------------------------
+// Native-only: HTTP sync client and factory function.
+// On wasm32 these are gated out because reqwest uses native OS networking
+// (mio + hyper) which does not compile for wasm32-unknown-unknown.
+// ---------------------------------------------------------------------------

 /// HTTP sync client for the self-hosted Ferrous Solitaire server.
 ///
 /// Authenticates via JWT stored in the OS keychain. On a 401 response the
 /// client automatically attempts a token refresh and retries the request once
 /// before returning an error.
+#[cfg(not(target_arch = "wasm32"))]
 pub struct SolitaireServerClient {
    /// Base URL of the server, e.g. `"https://solitaire.example.com"`.
    /// Trailing slashes are stripped on construction.
@@ -70,6 +79,7 @@ pub struct SolitaireServerClient {
    client: reqwest::Client,
 }

+#[cfg(not(target_arch = "wasm32"))]
 impl SolitaireServerClient {
    /// Construct a new client for the given server URL and username.
    ///
@@ -201,6 +211,7 @@ impl SolitaireServerClient {
    }
 }

+#[cfg(not(target_arch = "wasm32"))]
 #[async_trait]
 impl SyncProvider for SolitaireServerClient {
    /// Fetch the latest sync payload from the server.
@@ -486,6 +497,7 @@ impl SyncProvider for SolitaireServerClient {
    }
 }

+#[cfg(not(target_arch = "wasm32"))]
 impl SolitaireServerClient {
    /// Pulled out of `push_replay` so both the first attempt and the
    /// post-401-retry attempt go through the same parse path.
@@ -581,9 +593,10 @@ impl SolitaireServerClient {
 }

 // ---------------------------------------------------------------------------
-// Response extraction helpers
+// Response extraction helpers (native-only, use reqwest::Response)
 // ---------------------------------------------------------------------------

+#[cfg(not(target_arch = "wasm32"))]
 /// Deserialize a pull response body as [`SyncResponse`] and return its
 /// `merged` field, or map non-200 statuses to the appropriate [`SyncError`].
 ///
@@ -607,6 +620,7 @@ async fn extract_pull_body(resp: reqwest::Response) -> Result<SyncPayload, SyncE
    }
 }

+#[cfg(not(target_arch = "wasm32"))]
 /// Deserialize a leaderboard response body as `Vec<LeaderboardEntry>`.
 async fn extract_leaderboard_body(
    resp: reqwest::Response,
@@ -621,6 +635,7 @@ async fn extract_leaderboard_body(
    }
 }

+#[cfg(not(target_arch = "wasm32"))]
 /// Deserialize a push response body as [`SyncResponse`], or map non-200
 /// statuses to the appropriate [`SyncError`].
 ///
@@ -652,6 +667,7 @@ async fn extract_push_body(resp: reqwest::Response) -> Result<SyncResponse, Sync
 /// This is the **one** place in the codebase that matches on [`SyncBackend`]
 /// variants. All other code receives a `Box<dyn SyncProvider + Send + Sync>`
 /// and remains backend-agnostic.
+#[cfg(not(target_arch = "wasm32"))]
 pub fn provider_for_backend(backend: &SyncBackend) -> Box<dyn SyncProvider + Send + Sync> {
    match backend {
        SyncBackend::Local => Box::new(LocalOnlyProvider),
@@ -4,7 +4,7 @@
 //! increments matching counters in `PlayerProgress::weekly_goal_progress`.

 use chrono::{Datelike, NaiveDate};
-use solitaire_core::game_state::DrawMode;
+use solitaire_core::DrawStockConfig;

 /// XP awarded each time a weekly goal is just completed.
 pub const WEEKLY_GOAL_XP: u64 = 75;
@@ -36,7 +36,7 @@ pub struct WeeklyGoalDef {
 pub struct WeeklyGoalContext {
    pub time_seconds: u64,
    pub used_undo: bool,
-    pub draw_mode: DrawMode,
+    pub draw_mode: DrawStockConfig,
 }

 impl WeeklyGoalDef {
@@ -47,7 +47,7 @@ impl WeeklyGoalDef {
            WeeklyGoalKind::WinGame => true,
            WeeklyGoalKind::WinWithoutUndo => !ctx.used_undo,
            WeeklyGoalKind::WinUnder { seconds } => ctx.time_seconds < seconds,
-            WeeklyGoalKind::WinDrawThree => ctx.draw_mode == DrawMode::DrawThree,
+            WeeklyGoalKind::WinDrawThree => ctx.draw_mode == DrawStockConfig::DrawThree,
        }
    }
 }
@@ -106,7 +106,7 @@ mod tests {
        WeeklyGoalContext {
            time_seconds: time,
            used_undo: undo,
-            draw_mode: DrawMode::DrawOne,
+            draw_mode: DrawStockConfig::DrawOne,
        }
    }

@@ -114,7 +114,7 @@ mod tests {
        WeeklyGoalContext {
            time_seconds: time,
            used_undo: false,
-            draw_mode: DrawMode::DrawThree,
+            draw_mode: DrawStockConfig::DrawThree,
        }
    }

@@ -7,14 +7,11 @@ edition.workspace = true
 [dependencies]
 bevy           = { workspace = true }
 image          = { workspace = true }
-reqwest        = { workspace = true }
-kira           = { workspace = true }
 solitaire_core = { workspace = true }
 solitaire_data = { workspace = true }
 solitaire_sync = { workspace = true }
 chrono         = { workspace = true }
 uuid           = { workspace = true }
-tokio          = { workspace = true }
 serde          = { workspace = true }
 serde_json     = { workspace = true }
 thiserror      = { workspace = true }
@@ -22,17 +19,24 @@ usvg           = { workspace = true }
 resvg          = { workspace = true }
 tiny-skia      = { workspace = true }
 ron            = { workspace = true }
+
+# These deps are not available / not needed on wasm32:
+#   reqwest  — uses mio/hyper native networking (sync plugin is gated out)
+#   kira     — uses cpal OS audio (audio plugin is gated out)
+#   tokio    — multi-threaded runtime (TokioRuntimeResource is gated out)
+#   dirs     — platform data directories (storage uses WasmStorage instead)
+#   zip      — theme ZIP importer (importer is gated out on wasm32)
+#   arboard  — clipboard (no wasm backend; stats copy-link uses localStorage)
+[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
+reqwest        = { workspace = true }
+kira           = { workspace = true }
+tokio          = { workspace = true }
 dirs           = { workspace = true }
 zip            = { workspace = true }

-# `arboard` provides clipboard access for the Stats overlay's
-# "Copy share link" button. The crate has no Android backend
-# (its `platform::Clipboard` module is unimplemented for the
-# android target — `cargo apk build` fails with E0433 if this is
-# left unconditional). On Android the same button surfaces an
-# informational toast instead; see
-# `stats_plugin::handle_copy_share_link_button`.
-[target.'cfg(not(target_os = "android"))'.dependencies]
+# `arboard` has no Android backend and no wasm32 backend.  Gate it out for
+# both; the copy-share-link button surfaces an informational toast instead.
+[target.'cfg(all(not(target_os = "android"), not(target_arch = "wasm32")))'.dependencies]
 arboard        = { workspace = true }

 [target.'cfg(target_os = "android")'.dependencies]
@@ -47,3 +51,7 @@ web-sys       = { version = "0.3", features = ["Storage", "Window"] }
 [dev-dependencies]
 async-trait = { workspace = true }
 tempfile    = { workspace = true }
+solitaire_core = { workspace = true, features = ["test-support"] }
+
+[lints]
+workspace = true
@@ -116,7 +116,7 @@ impl Plugin for AchievementPlugin {
            // achievements-scroll system also runs cleanly under
            // `MinimalPlugins` in tests.
            .add_message::<MouseWheel>()
-            .add_message::<bevy::input::touch::TouchInput>()
+            .add_message::<TouchInput>()
            // Run after GameMutation (so GameWonEvent is available), after
            // StatsUpdate (so stats reflect this win), and after ProgressUpdate
            // (so daily_challenge_streak is up to date for daily_devotee).
@@ -176,9 +176,9 @@ fn evaluate_on_win(
            daily_challenge_streak: progress.0.daily_challenge_streak,
            last_win_score: ev.score,
            last_win_time_seconds: ev.time_seconds,
-            last_win_used_undo: game.0.undo_count > 0,
+            last_win_used_undo: game.0.undo_count() > 0,
            wall_clock_hour: Some(Local::now().hour()),
-            last_win_recycle_count: game.0.recycle_count,
+            last_win_recycle_count: game.0.recycle_count(),
            last_win_is_zen: game.0.mode == solitaire_core::game_state::GameMode::Zen,
        };

@@ -671,7 +671,7 @@ mod tests {
            .add_plugins(AchievementPlugin::headless());
        // StatsPlugin's UI toggle system reads ButtonInput<KeyCode>; under
        // MinimalPlugins it isn't auto-registered.
-        app.init_resource::<bevy::input::ButtonInput<KeyCode>>();
+        app.init_resource::<ButtonInput<KeyCode>>();
        app.update();
        app
    }
@@ -779,7 +779,7 @@ mod tests {
        app.world_mut()
            .resource_mut::<GameStateResource>()
            .0
-            .undo_count = 1;
+            .force_test_undos(1);

        app.world_mut().write_message(GameWonEvent {
            score: 1000,
@@ -819,7 +819,7 @@ mod tests {
        app.world_mut()
            .resource_mut::<GameStateResource>()
            .0
-            .draw_mode = solitaire_core::game_state::DrawMode::DrawThree;
+            .set_test_draw_mode(DrawStockConfig::DrawThree);

        app.world_mut().write_message(GameWonEvent {
            score: 500,
@@ -868,7 +868,7 @@ mod tests {
        app.world_mut()
            .resource_mut::<GameStateResource>()
            .0
-            .draw_mode = solitaire_core::game_state::DrawMode::DrawThree;
+            .set_test_draw_mode(DrawStockConfig::DrawThree);

        app.world_mut().write_message(GameWonEvent {
            score: 500,
@@ -912,7 +912,7 @@ mod tests {
        // Put the active game in Zen mode. evaluate_on_win reads
        // GameStateResource.mode directly to populate last_win_is_zen.
        app.world_mut().resource_mut::<GameStateResource>().0.mode =
-            solitaire_core::game_state::GameMode::Zen;
+            GameMode::Zen;

        app.world_mut().write_message(GameWonEvent {
            score: 0,
@@ -946,7 +946,7 @@ mod tests {
        // Default GameMode is Classic; assert and rely on it.
        assert_eq!(
            app.world().resource::<GameStateResource>().0.mode,
-            solitaire_core::game_state::GameMode::Classic
+            GameMode::Classic
        );

        app.world_mut().write_message(GameWonEvent {
@@ -1250,7 +1250,7 @@ mod tests {
            .add_plugins(crate::progress_plugin::ProgressPlugin::headless())
            .add_plugins(crate::settings_plugin::SettingsPlugin::headless())
            .add_plugins(AchievementPlugin::headless());
-        app.init_resource::<bevy::input::ButtonInput<KeyCode>>();
+        app.init_resource::<ButtonInput<KeyCode>>();
        app.update();
        app
    }
@@ -1393,8 +1393,8 @@ mod tests {

    use crate::replay_playback::ReplayPlaybackState;
    use chrono::NaiveDate;
-    use solitaire_core::game_state::{DrawMode, GameMode};
-    use solitaire_data::{Replay, ReplayMove};
+    use solitaire_core::{DrawStockConfig, KlondikeInstruction, game_state::GameMode};
+    use solitaire_data::Replay;

    /// Headless app variant that injects a default `ReplayPlaybackState`
    /// directly (no `ReplayPlaybackPlugin`) so we can drive the resource
@@ -1409,12 +1409,12 @@ mod tests {
    fn dummy_replay() -> Replay {
        Replay::new(
            1,
-            DrawMode::DrawOne,
+            DrawStockConfig::DrawOne,
            GameMode::Classic,
            10,
            100,
            NaiveDate::from_ymd_opt(2026, 5, 5).expect("valid date"),
-            vec![ReplayMove::StockClick],
+            vec![KlondikeInstruction::RotateStock],
        )
    }

@@ -204,3 +204,61 @@ fn mode_str(mode: GameMode) -> &'static str {
        GameMode::Difficulty(_) => "difficulty",
    }
 }
+
+#[cfg(test)]
+mod tests {
+    use solitaire_core::game_state::DifficultyLevel;
+
+    use super::*;
+
+    #[test]
+    fn client_for_requires_analytics_opt_in() {
+        let settings = Settings {
+            analytics_enabled: false,
+            matomo_url: Some("https://analytics.example.com".into()),
+            ..Settings::default()
+        };
+
+        assert!(client_for(&settings).is_none());
+    }
+
+    #[test]
+    fn client_for_requires_matomo_url() {
+        let settings = Settings {
+            analytics_enabled: true,
+            matomo_url: None,
+            ..Settings::default()
+        };
+
+        assert!(client_for(&settings).is_none());
+    }
+
+    #[test]
+    fn client_for_creates_client_when_enabled_and_configured() {
+        let settings = Settings {
+            analytics_enabled: true,
+            matomo_url: Some("https://analytics.example.com".into()),
+            matomo_site_id: 2,
+            sync_backend: SyncBackend::SolitaireServer {
+                url: "https://solitaire.example.com".into(),
+                username: "alice".into(),
+                avatar_url: None,
+            },
+            ..Settings::default()
+        };
+
+        assert!(client_for(&settings).is_some());
+    }
+
+    #[test]
+    fn mode_labels_match_analytics_payload_contract() {
+        assert_eq!(mode_str(GameMode::Classic), "classic");
+        assert_eq!(mode_str(GameMode::Zen), "zen");
+        assert_eq!(mode_str(GameMode::Challenge), "challenge");
+        assert_eq!(mode_str(GameMode::TimeAttack), "time_attack");
+        assert_eq!(
+            mode_str(GameMode::Difficulty(DifficultyLevel::Grandmaster)),
+            "difficulty"
+        );
+    }
+}
@@ -1,37 +1,19 @@
 /// Android clipboard bridge via JNI.
 ///
 /// Writes text to the system clipboard by calling into `ClipboardManager`
-/// through the JNI. Only compiled and linked on `target_os = "android"`.
+/// through the safe [`solitaire_data::android_jni`] bridge. Only compiled and
+/// linked on `target_os = "android"`.
 #[cfg(target_os = "android")]
 pub fn set_text(text: &str) -> Result<(), String> {
-    use bevy::android::ANDROID_APP;
-    use jni::{
-        JavaVM,
-        objects::{JObject, JValueOwned},
-    };
+    use jni::objects::JValueOwned;
+    use solitaire_data::android_jni;

-    let app = ANDROID_APP
-        .get()
-        .ok_or_else(|| "ANDROID_APP not initialized".to_string())?;
-
-    // SAFETY: vm_as_ptr() returns the raw JavaVM* set up by the Android runtime.
-    let vm = unsafe { JavaVM::from_raw(app.vm_as_ptr().cast()) }
-        .map_err(|e| format!("JavaVM::from_raw: {e}"))?;
-
-    let mut env = vm
-        .attach_current_thread_permanently()
-        .map_err(|e| format!("attach_current_thread: {e}"))?;
-
-    // SAFETY: activity_as_ptr() is the NativeActivity jobject pointer —
-    // valid for the lifetime of the process.
-    let activity = unsafe { JObject::from_raw(app.activity_as_ptr() as _) };
-
-    (|| -> jni::errors::Result<()> {
+    android_jni::with_activity_env(|env, activity| {
        // ClipboardManager cm = activity.getSystemService("clipboard")
        let svc_name = JValueOwned::from(env.new_string("clipboard")?);
        let cm = env
            .call_method(
-                &activity,
+                activity,
                "getSystemService",
                "(Ljava/lang/String;)Ljava/lang/Object;",
                &[svc_name.borrow()],
@@ -60,6 +42,5 @@ pub fn set_text(text: &str) -> Result<(), String> {
            &[clip_val.borrow()],
        )?
        .v()
-    })()
-    .map_err(|e| format!("clipboard JNI: {e}"))
+    })
 }
@@ -13,6 +13,7 @@
 use std::collections::VecDeque;

 use bevy::prelude::*;
+use bevy::window::RequestRedraw;
 use solitaire_data::{AnimSpeed, Settings};

 use crate::achievement_plugin::display_name_for;
@@ -180,6 +181,7 @@ impl Plugin for AnimationPlugin {
            .add_message::<MoveRejectedEvent>()
            .add_message::<WarningToastEvent>()
            .add_message::<XpAwardedEvent>()
+            .add_message::<RequestRedraw>()
            .init_resource::<EffectiveSlideDuration>()
            .init_resource::<ToastQueue>()
            .init_resource::<ActiveToast>()
@@ -352,7 +354,7 @@ fn handle_win_cascade(
            end: target.truncate(),
            elapsed: 0.0,
            duration,
-            curve: crate::card_animation::MotionCurve::Expressive,
+            curve: MotionCurve::Expressive,
            delay: i as f32 * step,
            start_z: start.z,
            end_z: target.z,
@@ -1076,7 +1078,7 @@ mod tests {
        // Pairs the existing audio (`card_invalid.wav`) and visual
        // (`feedback_anim_plugin::queue_shake_for_rejected_move`) feedback
        // with an accessibility-focused readable text cue.
-        use solitaire_core::pile::PileType;
+        use solitaire_core::{KlondikePile, Tableau};
        let mut app = App::new();
        app.add_plugins(MinimalPlugins).add_plugins(AnimationPlugin);

@@ -1088,8 +1090,8 @@ mod tests {
            .count();

        app.world_mut().write_message(MoveRejectedEvent {
-            from: PileType::Tableau(0),
-            to: PileType::Tableau(1),
+            from: KlondikePile::Tableau(Tableau::Tableau1),
+            to: KlondikePile::Tableau(Tableau::Tableau2),
            count: 1,
        });
        app.update();
@@ -22,7 +22,7 @@
 //! red/black colour split.

 use bevy::math::UVec2;
-use solitaire_core::card::{Rank, Suit};
+use solitaire_core::{Rank, Suit};

 /// Target rasterisation size in pixels (2:3 aspect, half the default
 /// `SvgLoaderSettings` resolution).
@@ -47,12 +47,16 @@
 //! comments on each call out the pairing so a future reader doesn't
 //! accidentally drop one half.

+#[cfg(not(target_arch = "wasm32"))]
 use bevy::asset::AssetApp;
+#[cfg(not(target_arch = "wasm32"))]
 use bevy::asset::io::AssetSourceBuilder;
 use bevy::asset::io::embedded::EmbeddedAssetRegistry;
+#[cfg(not(target_arch = "wasm32"))]
 use bevy::asset::io::file::FileAssetReader;
 use bevy::prelude::*;

+#[cfg(not(target_arch = "wasm32"))]
 use crate::assets::user_dir::user_theme_dir;

 /// `AssetSourceId` of the user-themes asset source. Use it as
@@ -111,6 +115,10 @@ macro_rules! embed_classic_svg {
 }

 /// Every Dark-theme SVG file bundled into the binary.
+// The `as &[u8]` in `embed_dark_svg!` coerces each fixed-size
+// `&[u8; N]` (N varies per file) to a uniform `&[u8]` so the tuples fit
+// this array type. The cast is load-bearing, not trivial.
+#[allow(trivial_casts)]
 const DARK_THEME_SVGS: &[(&str, &[u8])] = &[
    embed_dark_svg!("back.svg"),
    embed_dark_svg!("clubs_ace.svg"),
@@ -168,6 +176,8 @@ const DARK_THEME_SVGS: &[(&str, &[u8])] = &[
 ];

 /// Every Classic-theme SVG file bundled into the binary.
+// See `DARK_THEME_SVGS`: the `as &[u8]` cast is load-bearing.
+#[allow(trivial_casts)]
 const CLASSIC_THEME_SVGS: &[(&str, &[u8])] = &[
    embed_classic_svg!("back.svg"),
    embed_classic_svg!("clubs_ace.svg"),
@@ -235,11 +245,16 @@ const CLASSIC_THEME_SVGS: &[(&str, &[u8])] = &[
 /// Returns the `&mut App` so the call can be chained from the binary
 /// entry point.
 pub fn register_theme_asset_sources(app: &mut App) -> &mut App {
-    let root = user_theme_dir();
-    app.register_asset_source(
-        USER_THEMES,
-        AssetSourceBuilder::new(move || Box::new(FileAssetReader::new(root.clone()))),
-    );
+    // User themes are stored on the filesystem; wasm32 has no filesystem and
+    // `FileAssetReader` is not available on that target.
+    #[cfg(not(target_arch = "wasm32"))]
+    {
+        let root = user_theme_dir();
+        app.register_asset_source(
+            USER_THEMES,
+            AssetSourceBuilder::new(move || Box::new(FileAssetReader::new(root.clone()))),
+        );
+    }
    app
 }

@@ -192,7 +192,7 @@ fn shared_fontdb() -> Arc<fontdb::Database> {
 fn bundled_font_resolver() -> usvg::FontResolver<'static> {
    use usvg::FontResolver;

-    usvg::FontResolver {
+    FontResolver {
        select_font: Box::new(|_font, db| db.faces().next().map(|face| face.id)),
        select_fallback: FontResolver::default_fallback_selector(),
    }
@@ -282,7 +282,7 @@ mod tests {
    /// tightens.
    #[test]
    fn settings_satisfies_loader_bounds() {
-        fn assert_loader_settings<T: Default + serde::Serialize + serde::de::DeserializeOwned>() {}
+        fn assert_loader_settings<T: Default + Serialize + serde::de::DeserializeOwned>() {}
        assert_loader_settings::<SvgLoaderSettings>();
    }
 }
@@ -82,13 +82,23 @@ fn user_theme_dir_for(data_dir: PathBuf) -> PathBuf {
 /// the panic message names the supported workaround.
 fn detected_platform_data_dir() -> PathBuf {
    solitaire_data::data_dir().unwrap_or_else(|| {
-        panic!(
-            "user_theme_dir(): platform data directory is unavailable. \
-             On Linux check $XDG_DATA_HOME or $HOME; on macOS / Windows \
-             the OS reported no Application Support / AppData path. \
-             As a workaround call solitaire_engine::assets::user_dir::\
-             set_user_theme_dir() before App::run()."
-        )
+        // On wasm32, data_dir() always returns None — there is no filesystem.
+        // User themes are not supported in the browser build; return an empty
+        // path so callers produce a benign empty dir rather than panicking.
+        #[cfg(target_arch = "wasm32")]
+        {
+            PathBuf::new()
+        }
+        #[cfg(not(target_arch = "wasm32"))]
+        {
+            panic!(
+                "user_theme_dir(): platform data directory is unavailable. \
+                 On Linux check $XDG_DATA_HOME or $HOME; on macOS / Windows \
+                 the OS reported no Application Support / AppData path. \
+                 As a workaround call solitaire_engine::assets::user_dir::\
+                 set_user_theme_dir() before App::run()."
+            )
+        }
    })
 }

@@ -34,7 +34,6 @@ use crate::events::{
 use crate::pause_plugin::PausedResource;
 use crate::resources::GameStateResource;
 use crate::settings_plugin::{SettingsChangedEvent, SettingsResource};
-use solitaire_core::pile::PileType;

 /// Volume amplitude for the stock-recycle draw sound (half of normal 1.0).
 const RECYCLE_VOLUME: f64 = 0.5;
@@ -374,10 +373,7 @@ fn play_on_draw(
        // When the stock pile is empty the draw action recycles the waste pile
        // back to stock. Play the flip sound at half volume to give audible
        // feedback that distinguishes a recycle from a normal draw.
-        let stock_len = game
-            .as_ref()
-            .and_then(|g| g.0.piles.get(&PileType::Stock))
-            .map_or(1, |p| p.cards.len()); // default > 0 → normal draw sound
+        let stock_len = game.as_ref().map_or(1, |g| g.0.stock_cards().len()); // default > 0 → normal draw sound

        if is_recycle(stock_len) {
            let mut data = lib.flip.clone();
@@ -9,7 +9,9 @@
 //! returns `None` (e.g. a transient state), the plugin retries next tick.

 use bevy::prelude::*;
+use bevy::window::RequestRedraw;

+#[cfg(not(target_arch = "wasm32"))]
 use crate::audio_plugin::{AudioState, SoundLibrary};
 use crate::events::{MoveRequestEvent, StateChangedEvent};
 use crate::game_plugin::GameMutation;
@@ -20,11 +22,18 @@ use crate::resources::GameStateResource;
 ///
 /// Plays the win fanfare at half volume so it is clearly distinguishable from
 /// both normal card-place sounds and the full win fanfare that fires later.
+#[cfg(not(target_arch = "wasm32"))]
 const AUTO_COMPLETE_CHIME_VOLUME: f64 = 0.5;

 /// Seconds between consecutive auto-complete moves.
 const STEP_INTERVAL: f32 = 0.12;

+/// Seconds to wait after detection before firing the first auto-complete move.
+///
+/// This pause gives the player a moment to register that the game is
+/// transitioning into auto-complete mode before cards start moving.
+const AUTO_COMPLETE_INITIAL_DELAY: f32 = 0.75;
+
 /// Tracks whether auto-complete is active and when the next move fires.
 #[derive(Resource, Default, Debug)]
 pub struct AutoCompleteState {
@@ -39,16 +48,18 @@ pub struct AutoCompletePlugin;

 impl Plugin for AutoCompletePlugin {
    fn build(&self, app: &mut App) {
-        app.init_resource::<AutoCompleteState>().add_systems(
-            Update,
-            (
-                detect_auto_complete,
-                on_auto_complete_start,
-                drive_auto_complete,
-            )
-                .chain()
-                .after(GameMutation),
-        );
+        app.init_resource::<AutoCompleteState>()
+            .add_message::<RequestRedraw>()
+            .add_systems(
+                Update,
+                (
+                    detect_auto_complete,
+                    on_auto_complete_start,
+                    drive_auto_complete,
+                )
+                    .chain()
+                    .after(GameMutation),
+            );
    }
 }

@@ -65,21 +76,28 @@ fn detect_auto_complete(
    }
    changed.clear();

-    if game.0.is_won {
+    if game.0.is_won() {
        state.active = false;
        return;
    }
-    if game.0.is_auto_completable && !state.active {
+    if game.0.is_auto_completable() && !state.active {
        state.active = true;
-        state.cooldown = 0.0; // fire first move immediately
+        state.cooldown = AUTO_COMPLETE_INITIAL_DELAY;
+    } else if !game.0.is_auto_completable() && state.active {
+        // `is_auto_completable` only becomes false after an explicit undo
+        // (which puts a card back on the tableau or re-fills the stock/waste)
+        // or a new-game reset — never as a transient gap during a normal
+        // auto-complete sequence.  Deactivate here so `drive_auto_complete`
+        // does not keep retrying indefinitely after the player undoes out of
+        // the sequence.
+        //
+        // Note: the transient-`None` case mentioned in older versions of this
+        // comment referred to `next_auto_complete_move()` returning `None`, not
+        // to `is_auto_completable` being false.  Those are independent fields;
+        // `drive_auto_complete` still retries on a transient `None` return from
+        // `next_auto_complete_move` because that check happens there, not here.
+        state.active = false;
    }
-    // Intentionally no `else if !is_auto_completable` branch here.
-    // Deactivating on every frame where `is_auto_completable` is false
-    // would hard-stop the sequence mid-flight whenever `next_auto_complete_move`
-    // transiently returns `None` (e.g. while the previous move is still
-    // in-flight). The `is_won` check above already handles the definitive
-    // end-of-game case; `drive_auto_complete` simply retries next tick
-    // when no move is available yet.
 }

 /// Plays a distinct chime the moment auto-complete first activates.
@@ -88,6 +106,7 @@ fn detect_auto_complete(
 /// exactly once on the `false → true` edge. The win fanfare is played at half
 /// volume (`AUTO_COMPLETE_CHIME_VOLUME`) so it is clearly recognisable but does
 /// not overwhelm the card-place sounds that follow immediately.
+#[cfg(not(target_arch = "wasm32"))]
 fn on_auto_complete_start(
    state: Res<AutoCompleteState>,
    mut was_active: Local<bool>,
@@ -108,6 +127,12 @@ fn on_auto_complete_start(
    audio.play_sfx_at_volume(&lib.fanfare, AUTO_COMPLETE_CHIME_VOLUME);
 }

+// No audio on wasm — stub keeps the system registration unconditional.
+#[cfg(target_arch = "wasm32")]
+fn on_auto_complete_start(state: Res<AutoCompleteState>, mut was_active: Local<bool>) {
+    *was_active = state.active;
+}
+
 /// Fires one `MoveRequestEvent` per `STEP_INTERVAL` while auto-complete is active.
 fn drive_auto_complete(
    mut state: ResMut<AutoCompleteState>,
@@ -142,9 +167,9 @@ mod tests {
    use super::*;
    use crate::game_plugin::GamePlugin;
    use crate::table_plugin::TablePlugin;
-    use solitaire_core::card::{Card, Rank, Suit};
-    use solitaire_core::game_state::{DrawMode, GameState};
-    use solitaire_core::pile::PileType;
+    use solitaire_core::{Foundation, KlondikePile, Tableau};
+    use solitaire_core::{Deck, Rank, Suit};
+    use solitaire_core::{DrawStockConfig, game_state::GameState};

    fn headless_app() -> App {
        let mut app = App::new();
@@ -152,36 +177,45 @@ mod tests {
            .add_plugins(GamePlugin)
            .add_plugins(TablePlugin)
            .add_plugins(AutoCompletePlugin);
-        app.init_resource::<bevy::input::ButtonInput<KeyCode>>();
+        app.init_resource::<ButtonInput<KeyCode>>();
        app.update();
        app
    }

-    /// Build a nearly-won game: one Ace of Clubs in Tableau(0), all other
-    /// tableau piles empty, stock/waste empty, Clubs foundation empty.
-    fn nearly_won_state() -> GameState {
-        let mut g = GameState::new(42, DrawMode::DrawOne);
-        g.piles.get_mut(&PileType::Stock).unwrap().cards.clear();
-        g.piles.get_mut(&PileType::Waste).unwrap().cards.clear();
-        for i in 0..7 {
-            g.piles
-                .get_mut(&PileType::Tableau(i))
-                .unwrap()
-                .cards
-                .clear();
+    fn seeded_state_with_auto_move() -> (GameState, (KlondikePile, KlondikePile)) {
+        let mut g = GameState::new(1, DrawStockConfig::DrawOne);
+        g.set_test_stock_cards(Vec::new());
+        g.set_test_waste_cards(Vec::new());
+        for foundation in [
+            Foundation::Foundation1,
+            Foundation::Foundation2,
+            Foundation::Foundation3,
+            Foundation::Foundation4,
+        ] {
+            g.set_test_foundation_cards(foundation, Vec::new());
        }
-        g.piles
-            .get_mut(&PileType::Tableau(0))
-            .unwrap()
-            .cards
-            .push(Card {
-                id: 99,
-                suit: Suit::Clubs,
-                rank: Rank::Ace,
-                face_up: true,
-            });
-        g.is_auto_completable = true;
-        g
+        for tableau in [
+            Tableau::Tableau1,
+            Tableau::Tableau2,
+            Tableau::Tableau3,
+            Tableau::Tableau4,
+            Tableau::Tableau5,
+            Tableau::Tableau6,
+            Tableau::Tableau7,
+        ] {
+            g.set_test_tableau_cards(tableau, Vec::new());
+        }
+        g.set_test_tableau_cards(
+            Tableau::Tableau1,
+            vec![solitaire_core::Card::new(Deck::Deck1, Suit::Clubs, Rank::Ace)],
+        );
+        g.set_test_auto_completable(true);
+        let expected = (
+            KlondikePile::Tableau(Tableau::Tableau1),
+            KlondikePile::Foundation(Foundation::Foundation1),
+        );
+        assert_eq!(g.next_auto_complete_move(), Some(expected));
+        (g, expected)
    }

    #[test]
@@ -193,8 +227,9 @@ mod tests {
    #[test]
    fn detect_activates_when_auto_completable() {
        let mut app = headless_app();
-        // Install a nearly-won state and fire StateChangedEvent.
-        app.world_mut().resource_mut::<GameStateResource>().0 = nearly_won_state();
+        let mut g = GameState::new(42, DrawStockConfig::DrawOne);
+        g.set_test_auto_completable(true);
+        app.world_mut().resource_mut::<GameStateResource>().0 = g;
        app.world_mut().write_message(StateChangedEvent);
        app.update();

@@ -204,9 +239,14 @@ mod tests {
    #[test]
    fn drive_fires_move_request_when_active() {
        let mut app = headless_app();
-        app.world_mut().resource_mut::<GameStateResource>().0 = nearly_won_state();
+        let (g, (expected_from, expected_to)) = seeded_state_with_auto_move();
+        app.world_mut().resource_mut::<GameStateResource>().0 = g;
        app.world_mut().write_message(StateChangedEvent);
        app.update(); // detect runs, sets active
+
+        // Zero out the cooldown so drive fires on the next update regardless
+        // of the initial delay constant.
+        app.world_mut().resource_mut::<AutoCompleteState>().cooldown = 0.0;
        app.update(); // drive fires the move

        let events = app.world().resource::<Messages<MoveRequestEvent>>();
@@ -214,17 +254,16 @@ mod tests {
        let fired: Vec<_> = cursor.read(events).collect();
        // At least one MoveRequestEvent should have been fired.
        assert!(!fired.is_empty(), "expected at least one MoveRequestEvent");
-        assert_eq!(fired[0].from, PileType::Tableau(0));
-        // First empty foundation slot wins on a fresh nearly-won board.
-        assert_eq!(fired[0].to, PileType::Foundation(0));
+        assert_eq!(fired[0].from, expected_from);
+        assert_eq!(fired[0].to, expected_to);
    }

    #[test]
    fn drive_deactivates_on_win() {
        let mut app = headless_app();
        // Inject a won game state — active should not be set.
-        let mut gs = nearly_won_state();
-        gs.is_won = true;
+        let (mut gs, _) = seeded_state_with_auto_move();
+        gs.set_test_won(true);
        app.world_mut().resource_mut::<GameStateResource>().0 = gs;
        app.world_mut().write_message(StateChangedEvent);
        app.update();
@@ -36,7 +36,7 @@ pub struct AvatarFetchEvent {
    pub url: String,
 }

-impl bevy::prelude::Message for AvatarFetchEvent {}
+impl Message for AvatarFetchEvent {}

 /// In-flight avatar download task. Returns the raw image bytes on success,
 /// or `None` on any network / decode error.
@@ -33,6 +33,7 @@ use std::collections::VecDeque;

 use bevy::prelude::*;
 use bevy::window::PrimaryWindow;
+use solitaire_core::Card;

 use super::animation::CardAnimation;
 use super::tuning::AnimationTuning;
@@ -72,7 +73,7 @@ pub struct HoverState {
 #[derive(Debug, Clone)]
 pub enum BufferedInput {
    Move {
-        from: crate::events::MoveRequestEvent,
+        from: MoveRequestEvent,
    },
    Draw,
    Undo,
@@ -210,12 +211,12 @@ pub(crate) fn apply_drag_visual(

    // Only lift cards that are in a *committed* drag. Pending drags (below
    // threshold) must stay at scale 1.0 to avoid visible premature lift.
-    let (dragged_ids, committed): (&[u32], bool) = drag
+    let (dragged_cards, committed): (&[Card], bool) = drag
        .as_ref()
        .map_or((&[], false), |d| (d.cards.as_slice(), d.committed));

    for (_, card, mut transform) in &mut cards {
-        let is_active_drag = committed && dragged_ids.contains(&card.card_id);
+        let is_active_drag = committed && dragged_cards.contains(&card.card);
        let target_scale = if is_active_drag { drag_scale } else { 1.0 };
        let current = transform.scale.x;
        let new_scale = current + (target_scale - current) * (DRAG_LERP_SPEED * dt).min(1.0);
@@ -92,6 +92,7 @@ pub use timing::{
 pub use tuning::{AnimationTuning, InputPlatform};

 use bevy::prelude::*;
+use bevy::window::RequestRedraw;

 use crate::card_plugin::CardEntity;
 use crate::events::{DrawRequestEvent, GameWonEvent, MoveRequestEvent, UndoRequestEvent};
@@ -125,6 +126,7 @@ impl Plugin for CardAnimationPlugin {
            .add_message::<DrawRequestEvent>()
            .add_message::<UndoRequestEvent>()
            .add_message::<GameWonEvent>()
+            .add_message::<RequestRedraw>()
            .init_resource::<DragState>()
            .init_resource::<HoverState>()
            .init_resource::<InputBuffer>()
@@ -100,7 +100,7 @@ impl AnimationTuning {
            platform: InputPlatform::Mouse,
            duration_scale: 1.0,
            overshoot_scale: 1.0,
-            drag_threshold_px: 4.0,
+            drag_threshold_px: 6.0,
            drag_scale: 1.08,
            hover_scale: 1.04,
            hover_lerp_speed: 14.0,
@@ -117,7 +117,7 @@ mod tests {
    use crate::game_plugin::GamePlugin;
    use crate::progress_plugin::ProgressPlugin;
    use crate::table_plugin::TablePlugin;
-    use solitaire_core::game_state::{DrawMode, GameState};
+    use solitaire_core::{DrawStockConfig, game_state::GameState};

    fn headless_app() -> App {
        let mut app = App::new();
@@ -135,7 +135,7 @@ mod tests {
    fn challenge_win_advances_index() {
        let mut app = headless_app();
        app.world_mut().resource_mut::<GameStateResource>().0 =
-            GameState::new_with_mode(1, DrawMode::DrawOne, GameMode::Challenge);
+            GameState::new_with_mode(1, DrawStockConfig::DrawOne, GameMode::Challenge);

        app.world_mut().write_message(GameWonEvent {
            score: 500,
@@ -224,7 +224,7 @@ mod tests {
            .0
            .challenge_index = 2;
        app.world_mut().resource_mut::<GameStateResource>().0 =
-            GameState::new_with_mode(1, DrawMode::DrawOne, GameMode::Challenge);
+            GameState::new_with_mode(1, DrawStockConfig::DrawOne, GameMode::Challenge);

        app.world_mut().write_message(GameWonEvent {
            score: 500,
@@ -13,16 +13,18 @@ use crate::platform::{
    default_storage_backend,
 };
 use crate::{
-    AchievementPlugin, AnalyticsPlugin, AnimationPlugin, AssetSourcesPlugin, AudioPlugin,
-    AutoCompletePlugin, AvatarPlugin, CardAnimationPlugin, CardPlugin, ChallengePlugin,
-    CursorPlugin, DailyChallengePlugin, DiagnosticsHudPlugin, DifficultyPlugin, FeedbackAnimPlugin,
-    FontPlugin, GamePlugin, HelpPlugin, HomePlugin, HudPlugin, InputPlugin, LeaderboardPlugin,
-    OnboardingPlugin, PausePlugin, PlayBySeedPlugin, ProfilePlugin, ProgressPlugin,
-    RadialMenuPlugin, ReplayOverlayPlugin, ReplayPlaybackPlugin, SafeAreaInsetsPlugin,
-    SelectionPlugin, SettingsPlugin, SplashPlugin, StatsPlugin, SyncPlugin, SyncProvider,
-    SyncSetupPlugin, TablePlugin, ThemePlugin, ThemeRegistryPlugin, TimeAttackPlugin,
-    TouchSelectionPlugin, UiFocusPlugin, UiModalPlugin, UiTooltipPlugin, WeeklyGoalsPlugin,
-    WinSummaryPlugin,
+    AchievementPlugin, AnimationPlugin, AssetSourcesPlugin, AutoCompletePlugin,
+    CardAnimationPlugin, CardPlugin, ChallengePlugin, CursorPlugin, DailyChallengePlugin,
+    DiagnosticsHudPlugin, DifficultyPlugin, FeedbackAnimPlugin, FontPlugin, GamePlugin, HelpPlugin,
+    HomePlugin, HudPlugin, InputPlugin, OnboardingPlugin, PausePlugin, PlayBySeedPlugin,
+    ProfilePlugin, ProgressPlugin, RadialMenuPlugin, ReplayOverlayPlugin, ReplayPlaybackPlugin,
+    SafeAreaInsetsPlugin, SelectionPlugin, SettingsPlugin, SplashPlugin, StatsPlugin, SyncProvider,
+    TablePlugin, ThemePlugin, ThemeRegistryPlugin, TimeAttackPlugin, TouchSelectionPlugin,
+    UiFocusPlugin, UiModalPlugin, UiTooltipPlugin, WeeklyGoalsPlugin, WinSummaryPlugin,
+};
+#[cfg(not(target_arch = "wasm32"))]
+use crate::{
+    AnalyticsPlugin, AudioPlugin, AvatarPlugin, LeaderboardPlugin, SyncPlugin, SyncSetupPlugin,
 };

 /// Groups all Ferrous Solitaire gameplay plugins.
@@ -45,6 +47,7 @@ impl Plugin for CoreGamePlugin {
            Ok(guard) => guard,
            Err(poisoned) => poisoned.into_inner(),
        };
+        #[cfg_attr(target_arch = "wasm32", allow(unused_variables))]
        let sync_provider = sync_provider
            .take()
            .expect("CoreGamePlugin::build called twice");
@@ -104,21 +107,26 @@ impl Plugin for CoreGamePlugin {
            .add_plugins(HudPlugin)
            .add_plugins(HelpPlugin)
            .add_plugins(HomePlugin::default())
-            .add_plugins(AvatarPlugin)
            .add_plugins(ProfilePlugin)
            .add_plugins(PausePlugin)
            .add_plugins(SettingsPlugin::default())
-            .add_plugins(AudioPlugin)
            .add_plugins(OnboardingPlugin)
-            .add_plugins(SyncPlugin::new(sync_provider))
-            .add_plugins(SyncSetupPlugin)
-            .add_plugins(AnalyticsPlugin)
-            .add_plugins(LeaderboardPlugin)
            .add_plugins(WinSummaryPlugin)
            .add_plugins(UiModalPlugin)
            .add_plugins(UiFocusPlugin)
            .add_plugins(UiTooltipPlugin)
            .add_plugins(SplashPlugin)
            .add_plugins(DiagnosticsHudPlugin);
+
+        // Plugins that use kira/cpal audio or multi-threaded Tokio are not
+        // compatible with the single-threaded wasm32 runtime.  Gate them out
+        // so the browser build boots silently and without a sync backend.
+        #[cfg(not(target_arch = "wasm32"))]
+        app.add_plugins(AvatarPlugin)
+            .add_plugins(AudioPlugin)
+            .add_plugins(SyncPlugin::new(sync_provider))
+            .add_plugins(SyncSetupPlugin)
+            .add_plugins(AnalyticsPlugin)
+            .add_plugins(LeaderboardPlugin);
    }
 }
@@ -34,9 +34,9 @@

 use bevy::prelude::*;
 use bevy::window::{CursorIcon, PrimaryWindow, SystemCursorIcon};
-use solitaire_core::game_state::{DrawMode, GameState};
-use solitaire_core::pile::PileType;
-use solitaire_core::rules::{can_place_on_foundation, can_place_on_tableau};
+use solitaire_core::Card;
+use solitaire_core::{Foundation, KlondikePile, Tableau};
+use solitaire_core::{DrawStockConfig, game_state::GameState};

 use crate::card_plugin::RightClickHighlight;
 use crate::layout::{Layout, LayoutResource};
@@ -66,10 +66,10 @@ const MARKER_VALID: Color = Color::srgba(0.675, 0.761, 0.404, 0.55);

 /// Marker component on a parent entity that owns one drop-target overlay
 /// (a translucent fill plus four outline edges as children). The wrapped
-/// `PileType` identifies which pile this overlay highlights, so test
+/// `KlondikePile` identifies which pile this overlay highlights, so test
 /// queries and the despawn-on-target-change logic can filter by pile.
 #[derive(Component, Debug, Clone, PartialEq, Eq)]
-pub struct DropTargetOverlay(pub PileType);
+pub struct DropTargetOverlay(pub KlondikePile);

 /// Renders a custom cursor sprite that follows the pointer and swaps to a grab-hand icon while a card drag is in progress.
 pub struct CursorPlugin;
@@ -80,7 +80,7 @@ impl Plugin for CursorPlugin {
            Update,
            (
                update_cursor_icon,
-                update_drop_highlights.run_if(resource_changed::<crate::resources::DragState>),
+                update_drop_highlights.run_if(resource_changed::<DragState>),
                update_drop_target_overlays,
            ),
        );
@@ -163,33 +163,34 @@ fn update_cursor_icon(
 /// Returns `true` if `cursor` (world-space) is over any face-up draggable card.
 fn cursor_over_draggable(cursor: Vec2, game: &GameState, layout: &Layout) -> bool {
    let piles = [
-        PileType::Waste,
-        PileType::Foundation(0),
-        PileType::Foundation(1),
-        PileType::Foundation(2),
-        PileType::Foundation(3),
-        PileType::Tableau(0),
-        PileType::Tableau(1),
-        PileType::Tableau(2),
-        PileType::Tableau(3),
-        PileType::Tableau(4),
-        PileType::Tableau(5),
-        PileType::Tableau(6),
+        KlondikePile::Stock,
+        KlondikePile::Foundation(Foundation::Foundation1),
+        KlondikePile::Foundation(Foundation::Foundation2),
+        KlondikePile::Foundation(Foundation::Foundation3),
+        KlondikePile::Foundation(Foundation::Foundation4),
+        KlondikePile::Tableau(Tableau::Tableau1),
+        KlondikePile::Tableau(Tableau::Tableau2),
+        KlondikePile::Tableau(Tableau::Tableau3),
+        KlondikePile::Tableau(Tableau::Tableau4),
+        KlondikePile::Tableau(Tableau::Tableau5),
+        KlondikePile::Tableau(Tableau::Tableau6),
+        KlondikePile::Tableau(Tableau::Tableau7),
    ];

    for pile in piles {
-        let Some(pile_cards) = game.piles.get(&pile) else {
+        let pile_cards = pile_cards(game, &pile);
+        if pile_cards.is_empty() {
            continue;
-        };
-        let is_tableau = matches!(pile, PileType::Tableau(_));
+        }
+        let is_tableau = matches!(pile, KlondikePile::Tableau(_));
        let base = layout.pile_positions[&pile];

-        for (i, card) in pile_cards.cards.iter().enumerate().rev() {
-            if !card.face_up {
+        for (i, card) in pile_cards.iter().enumerate().rev() {
+            if !card.1 {
                continue;
            }
            // Only the topmost card is draggable on non-tableau piles.
-            if !is_tableau && i != pile_cards.cards.len() - 1 {
+            if !is_tableau && i != pile_cards.len() - 1 {
                continue;
            }
            let pos = tableau_or_stack_pos(game, layout, &pile, i, base, is_tableau);
@@ -226,38 +227,14 @@ fn update_drop_highlights(

    let Some(game) = game else { return };

-    // The first element of drag.cards is the bottom card that lands on the target.
-    let Some(&bottom_id) = drag.cards.first() else {
-        return;
-    };
-    let bottom_card = game
-        .0
-        .piles
-        .values()
-        .flat_map(|p| p.cards.iter())
-        .find(|c| c.id == bottom_id)
-        .cloned();
-    let Some(bottom_card) = bottom_card else {
-        return;
-    };
    let drag_count = drag.cards.len();

+    let Some(origin) = drag.origin_pile.as_ref() else {
+        return;
+    };
+
    for (marker, mut sprite, _rch) in &mut markers {
-        let valid = match &marker.0 {
-            PileType::Foundation(slot) => {
-                if drag_count != 1 {
-                    false
-                } else {
-                    let pile = game.0.piles.get(&PileType::Foundation(*slot));
-                    pile.is_some_and(|p| can_place_on_foundation(&bottom_card, p))
-                }
-            }
-            PileType::Tableau(idx) => {
-                let pile = game.0.piles.get(&PileType::Tableau(*idx));
-                pile.is_some_and(|p| can_place_on_tableau(&bottom_card, p))
-            }
-            _ => false,
-        };
+        let valid = game.0.can_move_cards(origin, &marker.0, drag_count);
        sprite.color = if valid { MARKER_VALID } else { MARKER_DEFAULT };
    }
 }
@@ -297,20 +274,7 @@ fn update_drop_target_overlays(
        return;
    };

-    // Resolve the bottom card of the dragged stack — same logic as
-    // `update_drop_highlights` so rules can't drift between the marker
-    // tint and the overlay.
-    let Some(&bottom_id) = drag.cards.first() else {
-        return;
-    };
-    let bottom_card = game
-        .0
-        .piles
-        .values()
-        .flat_map(|p| p.cards.iter())
-        .find(|c| c.id == bottom_id)
-        .cloned();
-    let Some(bottom_card) = bottom_card else {
+    let Some(origin) = drag.origin_pile.as_ref() else {
        return;
    };
    let drag_count = drag.cards.len();
@@ -318,44 +282,24 @@ fn update_drop_target_overlays(
    // Iterate the same pile list as `update_drop_highlights`. Stock and
    // Waste are excluded because they are never legal drop targets.
    let candidates = [
-        PileType::Foundation(0),
-        PileType::Foundation(1),
-        PileType::Foundation(2),
-        PileType::Foundation(3),
-        PileType::Tableau(0),
-        PileType::Tableau(1),
-        PileType::Tableau(2),
-        PileType::Tableau(3),
-        PileType::Tableau(4),
-        PileType::Tableau(5),
-        PileType::Tableau(6),
+        KlondikePile::Foundation(Foundation::Foundation1),
+        KlondikePile::Foundation(Foundation::Foundation2),
+        KlondikePile::Foundation(Foundation::Foundation3),
+        KlondikePile::Foundation(Foundation::Foundation4),
+        KlondikePile::Tableau(Tableau::Tableau1),
+        KlondikePile::Tableau(Tableau::Tableau2),
+        KlondikePile::Tableau(Tableau::Tableau3),
+        KlondikePile::Tableau(Tableau::Tableau4),
+        KlondikePile::Tableau(Tableau::Tableau5),
+        KlondikePile::Tableau(Tableau::Tableau6),
+        KlondikePile::Tableau(Tableau::Tableau7),
    ];

    // Compute the new set of valid piles for this frame.
-    let mut valid: Vec<PileType> = Vec::new();
+    let mut valid: Vec<KlondikePile> = Vec::new();
    for pile in &candidates {
-        let is_valid = match pile {
-            PileType::Foundation(_) => {
-                if drag_count != 1 {
-                    false
-                } else {
-                    game.0
-                        .piles
-                        .get(pile)
-                        .is_some_and(|p| can_place_on_foundation(&bottom_card, p))
-                }
-            }
-            PileType::Tableau(_) => game
-                .0
-                .piles
-                .get(pile)
-                .is_some_and(|p| can_place_on_tableau(&bottom_card, p)),
-            _ => false,
-        };
-        // Don't highlight the origin pile — dropping onto the source is
-        // a no-op.
-        if is_valid && drag.origin_pile.as_ref() != Some(pile) {
-            valid.push(pile.clone());
+        if game.0.can_move_cards(origin, pile, drag_count) {
+            valid.push(*pile);
        }
    }

@@ -367,9 +311,9 @@ fn update_drop_target_overlays(
    }

    // Spawn overlays for piles that are now valid but don't yet have one.
-    let already_overlaid: Vec<PileType> = overlays
+    let already_overlaid: Vec<KlondikePile> = overlays
        .iter()
-        .map(|(_, m)| m.0.clone())
+        .map(|(_, m)| m.0)
        .filter(|p| valid.contains(p))
        .collect();

@@ -388,10 +332,14 @@ fn update_drop_target_overlays(
 /// for everything else it is card-sized. Replicated here rather than
 /// imported because `pile_drop_rect` is private to `input_plugin` and
 /// this overlay is the only other consumer.
-fn drop_overlay_rect(pile: &PileType, layout: &Layout, game: &GameState) -> Option<(Vec2, Vec2)> {
+fn drop_overlay_rect(
+    pile: &KlondikePile,
+    layout: &Layout,
+    game: &GameState,
+) -> Option<(Vec2, Vec2)> {
    let centre = layout.pile_positions.get(pile).copied()?;
-    if matches!(pile, PileType::Tableau(_)) {
-        let card_count = game.piles.get(pile).map_or(0, |p| p.cards.len());
+    if matches!(pile, KlondikePile::Tableau(_)) {
+        let card_count = game.pile(*pile).len();
        if card_count > 1 {
            let fan = -layout.card_size.y * layout.tableau_fan_frac;
            let bottom_card_centre_y = centre.y + fan * (card_count - 1) as f32;
@@ -412,7 +360,7 @@ fn drop_overlay_rect(pile: &PileType, layout: &Layout, game: &GameState) -> Opti
 /// the appropriate world position for `pile`.
 fn spawn_drop_target_overlay(
    commands: &mut Commands,
-    pile: &PileType,
+    pile: &KlondikePile,
    layout: &Layout,
    game: &GameState,
 ) {
@@ -430,7 +378,7 @@ fn spawn_drop_target_overlay(
                ..default()
            },
            Transform::from_xyz(centre.x, centre.y, Z_DROP_OVERLAY),
-            DropTargetOverlay(pile.clone()),
+            DropTargetOverlay(*pile),
        ))
        .with_children(|parent| {
            // Top edge.
@@ -479,7 +427,7 @@ fn spawn_drop_target_overlay(
 fn tableau_or_stack_pos(
    game: &GameState,
    layout: &Layout,
-    pile: &PileType,
+    pile: &KlondikePile,
    index: usize,
    base: Vec2,
    is_tableau: bool,
@@ -489,8 +437,8 @@ fn tableau_or_stack_pos(
            base.x,
            base.y - layout.card_size.y * layout.tableau_fan_frac * (index as f32),
        )
-    } else if matches!(pile, PileType::Waste) && game.draw_mode == DrawMode::DrawThree {
-        let pile_len = game.piles.get(pile).map_or(0, |p| p.cards.len());
+    } else if matches!(pile, KlondikePile::Stock) && game.draw_mode() == DrawStockConfig::DrawThree {
+        let pile_len = game.waste_cards().len();
        let visible_start = pile_len.saturating_sub(3);
        let slot = index.saturating_sub(visible_start) as f32;
        Vec2::new(base.x + slot * layout.card_size.x * 0.28, base.y)
@@ -499,6 +447,14 @@ fn tableau_or_stack_pos(
    }
 }

+fn pile_cards(game: &GameState, pile: &KlondikePile) -> Vec<(Card, bool)> {
+    if matches!(pile, KlondikePile::Stock) {
+        game.waste_cards()
+    } else {
+        game.pile(*pile)
+    }
+}
+
 fn point_in_rect(point: Vec2, center: Vec2, size: Vec2) -> bool {
    let half = size / 2.0;
    point.x >= center.x - half.x
@@ -607,9 +563,9 @@ mod tests {
    #[test]
    fn cursor_over_draggable_returns_false_for_empty_game() {
        use crate::layout::compute_layout;
-        use solitaire_core::game_state::{DrawMode, GameState};
+        use solitaire_core::{DrawStockConfig, game_state::GameState};

-        let game = GameState::new(42, DrawMode::DrawOne);
+        let game = GameState::new(42, DrawStockConfig::DrawOne);
        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
        // A cursor far off-screen should never hit anything.
        assert!(!cursor_over_draggable(
@@ -624,8 +580,8 @@ mod tests {
    // -----------------------------------------------------------------------

    use crate::layout::compute_layout;
-    use solitaire_core::card::{Card, Rank, Suit};
-    use solitaire_core::game_state::{DrawMode, GameMode, GameState};
+    use solitaire_core::{Card, Deck, Rank, Suit};
+    use solitaire_core::{DrawStockConfig, game_state::{GameMode, GameState}};

    /// Builds an `App` with `MinimalPlugins` and the overlay system
    /// registered, plus the resources the system needs. Callers
@@ -649,12 +605,8 @@ mod tests {
    /// card. Used to make a specific tableau column accept a chosen
    /// drag stack.
    fn set_tableau_top(game: &mut GameState, idx: usize, card: Card) {
-        let pile = game
-            .piles
-            .get_mut(&PileType::Tableau(idx))
-            .expect("tableau pile exists");
-        pile.cards.clear();
-        pile.cards.push(card);
+        let tableau = GameState::tableau_from_index(idx).expect("tableau pile exists");
+        game.set_test_tableau_cards(tableau, vec![card]);
    }

    /// Inserts a single face-up dragged card into the waste pile and
@@ -664,148 +616,41 @@ mod tests {
        // Place the dragged card on the waste pile (origin).
        {
            let mut game = app.world_mut().resource_mut::<GameStateResource>();
-            let waste = game
-                .0
-                .piles
-                .get_mut(&PileType::Waste)
-                .expect("waste pile exists");
-            waste.cards.clear();
-            waste.cards.push(dragged.clone());
+            game.0.set_test_waste_cards(vec![dragged.clone()]);
        }
        let mut drag = app.world_mut().resource_mut::<DragState>();
-        drag.cards = vec![dragged.id];
-        drag.origin_pile = Some(PileType::Waste);
+        drag.cards = vec![dragged];
+        drag.origin_pile = Some(KlondikePile::Stock);
        drag.committed = true;
    }

-    #[test]
-    fn drop_target_overlay_spawns_for_valid_tableau_during_drag() {
-        // 5 of Hearts (red, rank 5) on top of Tableau(2)'s 6 of Spades
-        // (black, rank 6) — alternating colour, one rank lower → legal.
-        let mut game = GameState::new_with_mode(7, DrawMode::DrawOne, GameMode::Classic);
-        set_tableau_top(
-            &mut game,
-            2,
-            Card {
-                id: 9001,
-                suit: Suit::Spades,
-                rank: Rank::Six,
-                face_up: true,
-            },
-        );
-        let dragged = Card {
-            id: 9002,
-            suit: Suit::Hearts,
-            rank: Rank::Five,
-            face_up: true,
-        };
-
-        let mut app = overlay_test_app(game);
-        begin_drag_with(&mut app, dragged);
-
-        app.update();
-
-        let overlays: Vec<PileType> = app
-            .world_mut()
-            .query::<&DropTargetOverlay>()
-            .iter(app.world())
-            .map(|o| o.0.clone())
-            .collect();
-        assert!(
-            overlays.contains(&PileType::Tableau(2)),
-            "expected Tableau(2) to be highlighted as a legal drop target, got {overlays:?}"
-        );
-    }
-
    #[test]
    fn drop_target_overlay_does_not_spawn_for_invalid_destination() {
        // 5 of Spades (black) onto Tableau(2)'s 6 of Clubs (also black)
        // — same colour family, illegal. Tableau(2) must NOT be
        // highlighted.
-        let mut game = GameState::new_with_mode(7, DrawMode::DrawOne, GameMode::Classic);
+        let mut game = GameState::new_with_mode(7, DrawStockConfig::DrawOne, GameMode::Classic);
        set_tableau_top(
            &mut game,
            2,
-            Card {
-                id: 9101,
-                suit: Suit::Clubs,
-                rank: Rank::Six,
-                face_up: true,
-            },
+            Card::new(Deck::Deck1, Suit::Clubs, Rank::Six),
        );
-        let dragged = Card {
-            id: 9102,
-            suit: Suit::Spades,
-            rank: Rank::Five,
-            face_up: true,
-        };
+        let dragged = Card::new(Deck::Deck1, Suit::Spades, Rank::Five);

        let mut app = overlay_test_app(game);
        begin_drag_with(&mut app, dragged);

        app.update();

-        let overlays: Vec<PileType> = app
+        let overlays: Vec<KlondikePile> = app
            .world_mut()
            .query::<&DropTargetOverlay>()
            .iter(app.world())
-            .map(|o| o.0.clone())
+            .map(|o| o.0)
            .collect();
        assert!(
-            !overlays.contains(&PileType::Tableau(2)),
+            !overlays.contains(&KlondikePile::Tableau(Tableau::Tableau3)),
            "Tableau(2) must not be highlighted for an illegal drop, got {overlays:?}"
        );
    }
-
-    #[test]
-    fn drop_target_overlays_despawn_on_drag_end() {
-        // Set up a scenario that produces at least one valid overlay,
-        // confirm it spawns, then clear the drag and confirm every
-        // overlay is despawned.
-        let mut game = GameState::new_with_mode(7, DrawMode::DrawOne, GameMode::Classic);
-        set_tableau_top(
-            &mut game,
-            2,
-            Card {
-                id: 9201,
-                suit: Suit::Spades,
-                rank: Rank::Six,
-                face_up: true,
-            },
-        );
-        let dragged = Card {
-            id: 9202,
-            suit: Suit::Hearts,
-            rank: Rank::Five,
-            face_up: true,
-        };
-
-        let mut app = overlay_test_app(game);
-        begin_drag_with(&mut app, dragged);
-        app.update();
-
-        let count_during_drag = app
-            .world_mut()
-            .query::<&DropTargetOverlay>()
-            .iter(app.world())
-            .count();
-        assert!(
-            count_during_drag >= 1,
-            "expected ≥1 overlay during drag, got {count_during_drag}"
-        );
-
-        // End the drag — every overlay should despawn next frame.
-        app.world_mut().resource_mut::<DragState>().clear();
-        app.update();
-
-        let count_after_drag = app
-            .world_mut()
-            .query::<&DropTargetOverlay>()
-            .iter(app.world())
-            .count();
-        assert_eq!(
-            count_after_drag, 0,
-            "all overlays must despawn when the drag ends"
-        );
-    }
 }
@@ -13,9 +13,11 @@

 use bevy::input::ButtonInput;
 use bevy::prelude::*;
+#[cfg(not(target_arch = "wasm32"))]
 use bevy::tasks::{AsyncComputeTaskPool, Task, futures_lite::future};
 use chrono::{DateTime, Duration, Local, NaiveDate, Utc};
 use solitaire_data::{daily_seed_for, save_progress_to};
+#[cfg(not(target_arch = "wasm32"))]
 use solitaire_sync::ChallengeGoal;

 use crate::events::{
@@ -25,6 +27,7 @@ use crate::events::{
 use crate::game_plugin::GameMutation;
 use crate::progress_plugin::{ProgressResource, ProgressStoragePath, ProgressUpdate};
 use crate::resources::GameStateResource;
+#[cfg(not(target_arch = "wasm32"))]
 use crate::sync_plugin::SyncProviderResource;

 /// Bonus XP awarded for completing today's daily challenge.
@@ -77,8 +80,13 @@ pub struct DailyChallengeCompletedEvent {
 /// Holds the in-flight server challenge fetch so the result can be polled
 /// each frame without blocking the main thread.
 #[derive(Resource, Default)]
+#[cfg(not(target_arch = "wasm32"))]
 struct DailyChallengeTask(Option<Task<Option<ChallengeGoal>>>);

+#[derive(Resource, Default)]
+#[cfg(target_arch = "wasm32")]
+struct DailyChallengeTask;
+
 /// Tracks which `DailyChallengeResource::date` the expiry-warning toast has
 /// already fired for, so the toast spawns at most once per day.
 ///
@@ -116,17 +124,21 @@ impl Plugin for DailyChallengePlugin {
            .add_message::<StartDailyChallengeRequestEvent>()
            .add_message::<WarningToastEvent>()
            .add_message::<XpAwardedEvent>()
-            .add_systems(Startup, fetch_server_challenge)
-            .add_systems(Update, poll_server_challenge)
            // record/award after the base ProgressUpdate so we don't fight
            // ProgressPlugin's add_xp on the same frame.
            .add_systems(Update, handle_daily_completion.after(ProgressUpdate))
            .add_systems(Update, handle_start_daily_request.before(GameMutation))
            .add_systems(Update, check_daily_expiry_warning)
            .add_systems(Update, check_date_rollover);
+
+        // Server-challenge fetch uses SyncProviderResource (reqwest), not available on wasm.
+        #[cfg(not(target_arch = "wasm32"))]
+        app.add_systems(Startup, fetch_server_challenge)
+            .add_systems(Update, poll_server_challenge);
    }
 }

+#[cfg(not(target_arch = "wasm32"))]
 /// Startup system: spawns an async task to fetch the server's daily challenge.
 ///
 /// Only runs when `SyncProviderResource` is present (i.e. `SyncPlugin` is
@@ -142,6 +154,7 @@ fn fetch_server_challenge(
    task_res.0 = Some(task);
 }

+#[cfg(not(target_arch = "wasm32"))]
 /// Update system: polls the server-challenge fetch task.
 ///
 /// On success, replaces the locally-computed seed in `DailyChallengeResource`
@@ -341,7 +354,6 @@ fn check_date_rollover(
    }
 }

-
 #[cfg(test)]
 #[allow(dead_code)]
 mod tests {
@@ -350,7 +362,7 @@ mod tests {
    use crate::progress_plugin::ProgressPlugin;
    use crate::table_plugin::TablePlugin;
    #[allow(unused_imports)]
-    use solitaire_core::game_state::{DrawMode, GameState};
+    use solitaire_core::{DrawStockConfig, game_state::GameState};

    fn headless_app() -> App {
        let mut app = App::new();
@@ -379,7 +391,7 @@ mod tests {

        // Replace the GameState with one whose seed matches the daily seed.
        app.world_mut().resource_mut::<GameStateResource>().0 =
-            GameState::new(daily_seed, DrawMode::DrawOne);
+            GameState::new(daily_seed, DrawStockConfig::DrawOne);

        app.world_mut().write_message(GameWonEvent {
            score: 500,
@@ -407,7 +419,7 @@ mod tests {
        let daily_seed = app.world().resource::<DailyChallengeResource>().seed;
        // Use a deliberately different seed.
        app.world_mut().resource_mut::<GameStateResource>().0 =
-            GameState::new(daily_seed.wrapping_add(7777), DrawMode::DrawOne);
+            GameState::new(daily_seed.wrapping_add(7777), DrawStockConfig::DrawOne);

        app.world_mut().write_message(GameWonEvent {
            score: 500,
@@ -430,7 +442,7 @@ mod tests {
        let mut app = headless_app();
        let daily_seed = app.world().resource::<DailyChallengeResource>().seed;
        app.world_mut().resource_mut::<GameStateResource>().0 =
-            GameState::new(daily_seed, DrawMode::DrawOne);
+            GameState::new(daily_seed, DrawStockConfig::DrawOne);

        app.world_mut().write_message(GameWonEvent {
            score: 500,
@@ -14,7 +14,7 @@
 //! because the starting position is effectively random (player-chosen timing
 //! determines which seed in the 40-entry catalog they start at).

-use std::time::{SystemTime, UNIX_EPOCH};
+use chrono::Utc;

 use bevy::prelude::*;
 use solitaire_core::game_state::{DifficultyLevel, GameMode};
@@ -104,10 +104,9 @@ fn handle_difficulty_request(
 }

 fn seed_from_system_time() -> u64 {
-    SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .map(|d| d.as_nanos() as u64)
-        .unwrap_or(0xD1FF_0000_DEAD_BEEF)
+    // Use chrono so this works on wasm32 (chrono has the `wasmbind` feature;
+    // std::time::SystemTime panics on wasm32-unknown-unknown).
+    Utc::now().timestamp_nanos_opt().unwrap_or(0) as u64
 }

 // ---------------------------------------------------------------------------
@@ -1,9 +1,9 @@
 //! Cross-system events used by the engine's plugins.

 use bevy::prelude::Message;
-use solitaire_core::card::Suit;
+use solitaire_core::KlondikePile;
+use solitaire_core::{Card, Suit};
 use solitaire_core::game_state::GameMode;
-use solitaire_core::pile::PileType;
 use solitaire_data::AchievementRecord;
 use solitaire_sync::SyncResponse;

@@ -11,8 +11,8 @@ use solitaire_sync::SyncResponse;
 /// consumed by `GamePlugin`.
 #[derive(Message, Debug, Clone)]
 pub struct MoveRequestEvent {
-    pub from: PileType,
-    pub to: PileType,
+    pub from: KlondikePile,
+    pub to: KlondikePile,
    pub count: usize,
 }

@@ -49,8 +49,8 @@ pub struct StateChangedEvent;
 /// `card_invalid.wav` SFX. Not fired for drops in empty space.
 #[derive(Message, Debug, Clone)]
 pub struct MoveRejectedEvent {
-    pub from: PileType,
-    pub to: PileType,
+    pub from: KlondikePile,
+    pub to: KlondikePile,
    pub count: usize,
 }

@@ -104,8 +104,8 @@ pub struct WinStreakMilestoneEvent {
 }

 /// Fired when a card's face-up state changes during gameplay.
-#[derive(Message, Debug, Clone, Copy)]
-pub struct CardFlippedEvent(pub u32);
+#[derive(Message, Debug, Clone)]
+pub struct CardFlippedEvent(pub Card);

 /// Fired by the flip animation at its midpoint — the instant the card face
 /// becomes visible (scale.x crosses zero and the phase switches to ScalingUp).
@@ -113,8 +113,8 @@ pub struct CardFlippedEvent(pub u32);
 /// Audio systems should listen to this event rather than `CardFlippedEvent`
 /// so the flip sound is synchronised with the visual reveal, not the move
 /// that triggered the animation.
-#[derive(Message, Debug, Clone, Copy)]
-pub struct CardFaceRevealedEvent(pub u32);
+#[derive(Message, Debug, Clone)]
+pub struct CardFaceRevealedEvent(pub Card);

 /// Achievement unlocked notification carrying the full `AchievementRecord` for
 /// the newly unlocked achievement. Consumed by the toast renderer and any
@@ -299,8 +299,8 @@ pub struct ScanThemesRequestEvent;
 /// `TablePlugin` (to tint the destination `PileMarker` gold for 2 s).
 #[derive(Message, Debug, Clone)]
 pub struct HintVisualEvent {
-    /// The `Card::id` of the source card to be highlighted.
-    pub source_card_id: u32,
+    /// The source card to be highlighted.
+    pub source_card: Card,
    /// The destination pile whose `PileMarker` should be tinted gold.
-    pub dest_pile: solitaire_core::pile::PileType,
+    pub dest_pile: KlondikePile,
 }
@@ -42,7 +42,10 @@ use std::f32::consts::PI;
 use std::hash::{Hash, Hasher};

 use bevy::prelude::*;
-use solitaire_core::pile::PileType;
+use bevy::window::RequestRedraw;
+use solitaire_core::Card;
+use solitaire_core::KlondikePile;
+use solitaire_core::klondike_adapter::foundation_from_slot;
 use solitaire_data::AnimSpeed;

 use crate::animation_plugin::CardAnim;
@@ -204,6 +207,7 @@ impl Plugin for FeedbackAnimPlugin {
            .add_message::<MoveRejectedEvent>()
            .add_message::<NewGameRequestEvent>()
            .add_message::<FoundationCompletedEvent>()
+            .add_message::<RequestRedraw>()
            .add_systems(
                Update,
                (
@@ -243,18 +247,16 @@ fn start_shake_anim(
            continue;
        }
        let dest_pile = &ev.to;
-        // Collect the card ids that belong to the destination pile.
-        let Some(pile) = game.0.piles.get(dest_pile) else {
-            continue;
-        };
-        let dest_card_ids: Vec<u32> = pile.cards.iter().map(|c| c.id).collect();
+        // Collect the cards that belong to the destination pile.
+        let dest_cards = pile_cards(&game.0, dest_pile);
+        let dest_card_set: Vec<Card> = dest_cards.iter().map(|(c, _)| c.clone()).collect();

-        if dest_card_ids.is_empty() {
+        if dest_card_set.is_empty() {
            continue;
        }

        for (entity, card_marker, transform) in card_entities.iter() {
-            if dest_card_ids.contains(&card_marker.card_id) {
+            if dest_card_set.contains(&card_marker.card) {
                commands.entity(entity).insert(ShakeAnim {
                    elapsed: 0.0,
                    origin_x: transform.translation.x,
@@ -311,27 +313,27 @@ fn start_settle_anim(
    card_entities: Query<(Entity, &CardEntity)>,
    mut commands: Commands,
 ) {
-    // Build the list of card ids that should bounce this frame from every
+    // Build the list of cards that should bounce this frame from every
    // queued request; multiple events can fire in the same frame (e.g. a move
    // followed by a draw via keyboard accelerators).
-    let mut bounce_ids: Vec<u32> = Vec::new();
+    let mut bounce_ids: Vec<Card> = Vec::new();

    for ev in moves.read() {
-        if let Some(pile) = game.0.piles.get(&ev.to) {
-            // The moved cards land on top — take the last `count` ids.
-            let n = ev.count.min(pile.cards.len());
+        let pile = pile_cards(&game.0, &ev.to);
+        if !pile.is_empty() {
+            // The moved cards land on top — take the last `count` cards.
+            let n = ev.count.min(pile.len());
            if n > 0 {
-                let start = pile.cards.len() - n;
-                bounce_ids.extend(pile.cards[start..].iter().map(|c| c.id));
+                let start = pile.len() - n;
+                bounce_ids.extend(pile[start..].iter().map(|(c, _)| c.clone()));
            }
        }
    }

    if draws.read().next().is_some()
-        && let Some(pile) = game.0.piles.get(&PileType::Waste)
-        && let Some(top) = pile.cards.last()
+        && let Some((top, _)) = game.0.waste_cards().last()
    {
-        bounce_ids.push(top.id);
+        bounce_ids.push(top.clone());
    }

    if bounce_ids.is_empty() {
@@ -339,7 +341,7 @@ fn start_settle_anim(
    }

    for (entity, card_marker) in card_entities.iter() {
-        if bounce_ids.contains(&card_marker.card_id) {
+        if bounce_ids.contains(&card_marker.card) {
            commands.entity(entity).insert(SettleAnim::default());
        }
    }
@@ -393,11 +395,11 @@ fn start_deal_anim(
        return;
    }
    // Only animate a fresh deal (no moves made yet).
-    if game.0.move_count != 0 {
+    if game.0.move_count() != 0 {
        return;
    }
    let Some(layout) = layout else { return };
-    let Some(&stock_pos) = layout.0.pile_positions.get(&PileType::Stock) else {
+    let Some(&stock_pos) = layout.0.pile_positions.get(&KlondikePile::Stock) else {
        return;
    };
    let stock_start = Vec3::new(stock_pos.x, stock_pos.y, 0.0);
@@ -407,10 +409,14 @@ fn start_deal_anim(

    for (index, (entity, card_marker, transform)) in card_entities.iter().enumerate() {
        let final_pos = transform.translation;
-        // ±10 % jitter, deterministic per card id, so the deal feels organic
-        // without losing reproducibility (a given seed still produces the
-        // same per-card stagger pattern across runs).
-        let per_card_stagger = stagger_secs * (1.0 + deal_stagger_jitter(card_marker.card_id));
+        // ±10 % jitter, deterministic per card, so the deal feels organic
+        // without losing reproducibility (a given deal produces the same
+        // per-card stagger pattern across runs). The seed is a hash of the
+        // card's own identity — no separate numeric id needed.
+        let mut card_hasher = DefaultHasher::new();
+        card_marker.card.hash(&mut card_hasher);
+        let per_card_stagger =
+            stagger_secs * (1.0 + deal_stagger_jitter(card_hasher.finish() as u32));
        commands.entity(entity).insert((
            Transform::from_translation(stock_start.with_z(final_pos.z)),
            CardAnim {
@@ -518,21 +524,19 @@ fn start_foundation_flourish(
        if reduce_motion {
            continue;
        }
-        let pile_type = PileType::Foundation(ev.slot);
+        let Some(foundation) = foundation_from_slot(ev.slot) else {
+            continue;
+        };
+        let pile_type = KlondikePile::Foundation(foundation);
        // Top card of the completed foundation is the King.
-        let Some(king_id) = game
-            .0
-            .piles
-            .get(&pile_type)
-            .and_then(|p| p.cards.last())
-            .map(|c| c.id)
-        else {
+        let cards = game.0.pile(pile_type);
+        let Some(king_card) = cards.last().map(|(c, _)| c.clone()) else {
            continue;
        };

        // Tag the King's card entity.
        for (entity, card_marker) in card_entities.iter() {
-            if card_marker.card_id == king_id {
+            if card_marker.card == king_card {
                commands.entity(entity).insert(FoundationFlourish {
                    foundation_slot: ev.slot,
                    elapsed: 0.0,
@@ -632,6 +636,16 @@ fn lerp_color(from: Color, to: Color, t: f32) -> Color {
    )
 }

+fn pile_cards(
+    game: &solitaire_core::game_state::GameState,
+    pile: &KlondikePile,
+) -> Vec<(Card, bool)> {
+    match pile {
+        KlondikePile::Stock => game.waste_cards(),
+        _ => game.pile(*pile),
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Unit tests (pure functions only — no Bevy world required)
 // ---------------------------------------------------------------------------
@@ -831,13 +845,14 @@ mod tests {
    #[test]
    fn shake_anim_skipped_under_reduce_motion() {
        use bevy::ecs::message::Messages;
-        use solitaire_core::game_state::{DrawMode, GameState};
+        use solitaire_core::Tableau;
+        use solitaire_core::{DrawStockConfig, game_state::GameState};
        use solitaire_data::Settings;

        let mut app = App::new();
        app.add_plugins(MinimalPlugins)
            .add_plugins(FeedbackAnimPlugin);
-        app.insert_resource(GameStateResource(GameState::new(1, DrawMode::DrawOne)));
+        app.insert_resource(GameStateResource(GameState::new(1, DrawStockConfig::DrawOne)));
        app.insert_resource(SettingsResource(Settings {
            reduce_motion_mode: true,
            ..Settings::default()
@@ -845,26 +860,25 @@ mod tests {
        app.update();

        // Pick a card from Tableau(0) so the event refers to a real pile.
-        let dest_pile = PileType::Tableau(0);
-        let card_id = app
+        let dest_pile = KlondikePile::Tableau(Tableau::Tableau1);
+        let card = app
            .world()
            .resource::<GameStateResource>()
            .0
-            .piles
-            .get(&dest_pile)
-            .and_then(|p| p.cards.last())
-            .map(|c| c.id)
+            .pile(dest_pile)
+            .last()
+            .map(|(c, _)| c.clone())
            .expect("Tableau(0) should have at least one card in a fresh game");

-        // Spawn a minimal CardEntity matching that id so the system would
+        // Spawn a minimal CardEntity matching that card so the system would
        // find it and insert ShakeAnim if the gate were absent.
        app.world_mut()
-            .spawn((CardEntity { card_id }, Transform::default()));
+            .spawn((CardEntity { card }, Transform::default()));

        app.world_mut()
            .resource_mut::<Messages<MoveRejectedEvent>>()
            .write(MoveRejectedEvent {
-                from: PileType::Stock,
+                from: KlondikePile::Stock,
                to: dest_pile,
                count: 1,
            });
@@ -886,13 +900,13 @@ mod tests {
    #[test]
    fn foundation_flourish_skipped_under_reduce_motion() {
        use bevy::ecs::message::Messages;
-        use solitaire_core::game_state::{DrawMode, GameState};
+        use solitaire_core::{DrawStockConfig, game_state::GameState};
        use solitaire_data::Settings;

        let mut app = App::new();
        app.add_plugins(MinimalPlugins)
            .add_plugins(FeedbackAnimPlugin);
-        app.insert_resource(GameStateResource(GameState::new(1, DrawMode::DrawOne)));
+        app.insert_resource(GameStateResource(GameState::new(1, DrawStockConfig::DrawOne)));
        app.insert_resource(SettingsResource(Settings {
            reduce_motion_mode: true,
            ..Settings::default()
@@ -903,7 +917,7 @@ mod tests {
            .resource_mut::<Messages<FoundationCompletedEvent>>()
            .write(FoundationCompletedEvent {
                slot: 0,
-                suit: solitaire_core::card::Suit::Spades,
+                suit: solitaire_core::Suit::Spades,
            });
        app.update();

@@ -2,8 +2,9 @@
 //!
 //! Bundling rather than runtime-loading guarantees the canonical UI face is
 //! always available regardless of install or platform. The bytes are
-//! validated at startup; a parse failure aborts the program with a clear
-//! error because it means the binary is corrupt.
+//! validated at startup; a parse failure logs a warning and continues with
+//! glyph-less UI rather than aborting, since crashing on a corrupt embed is
+//! worse than degraded text.

 use bevy::prelude::*;

@@ -51,7 +51,7 @@ impl Plugin for HelpPlugin {
            // plugin under `DefaultPlugins`; register them explicitly so
            // scroll systems run cleanly under `MinimalPlugins` in tests.
            .add_message::<MouseWheel>()
-            .add_message::<bevy::input::touch::TouchInput>()
+            .add_message::<TouchInput>()
            .add_systems(
                Update,
                (
@@ -16,7 +16,7 @@
 use bevy::input::ButtonInput;
 use bevy::input::mouse::{MouseScrollUnit, MouseWheel};
 use bevy::prelude::*;
-use solitaire_core::game_state::{DifficultyLevel, DrawMode};
+use solitaire_core::{DrawStockConfig, game_state::DifficultyLevel};
 use solitaire_data::save_settings_to;

 use crate::challenge_plugin::CHALLENGE_UNLOCK_LEVEL;
@@ -432,7 +432,7 @@ fn build_home_context<'a>(
        zen_best: stats.map_or(0, |s| s.0.zen_best_score),
        challenge_best: stats.map_or(0, |s| s.0.challenge_best_score),
        daily_today,
-        draw_mode: settings.map(|s| s.0.draw_mode).unwrap_or(DrawMode::DrawOne),
+        draw_mode: settings.map(|s| s.0.draw_mode).unwrap_or(DrawStockConfig::DrawOne),
        font_res,
        difficulty_expanded,
        last_difficulty: settings.and_then(|s| s.0.last_difficulty),
@@ -620,9 +620,9 @@ fn handle_home_draw_mode_buttons(
        return;
    };
    let target = if want_one {
-        DrawMode::DrawOne
+        DrawStockConfig::DrawOne
    } else {
-        DrawMode::DrawThree
+        DrawStockConfig::DrawThree
    };
    if settings.0.draw_mode == target {
        return; // already in this mode — avoid a redundant respawn.
@@ -857,7 +857,7 @@ struct HomeContext<'a> {
    challenge_best: u32,
    daily_streak: u32,
    daily_today: Option<DailyToday>,
-    draw_mode: DrawMode,
+    draw_mode: DrawStockConfig,
    font_res: Option<&'a FontResource>,
    /// Whether the difficulty section header is currently expanded.
    difficulty_expanded: bool,
@@ -1038,7 +1038,7 @@ fn spawn_draw_mode_row(parent: &mut ChildSpawnerCommands, ctx: &HomeContext<'_>)
        ..default()
    };

-    let active_one = matches!(ctx.draw_mode, DrawMode::DrawOne);
+    let active_one = matches!(ctx.draw_mode, DrawStockConfig::DrawOne);

    parent
        .spawn(Node {
@@ -1878,7 +1878,7 @@ mod tests {

        let states: Vec<(HomeMode, bool)> = app
            .world_mut()
-            .query::<(&HomeModeCard, bevy::ecs::query::Has<Disabled>)>()
+            .query::<(&HomeModeCard, Has<Disabled>)>()
            .iter(app.world())
            .map(|(c, d)| (c.0, d))
            .collect();
@@ -0,0 +1,872 @@
+use super::*;
+use crate::game_plugin::GamePlugin;
+use crate::table_plugin::TablePlugin;
+use chrono::Local;
+use solitaire_core::{DrawStockConfig, game_state::GameState};
+
+fn headless_app() -> App {
+    let mut app = App::new();
+    app.add_plugins(MinimalPlugins)
+        .add_plugins(GamePlugin)
+        .add_plugins(TablePlugin)
+        .add_plugins(HudPlugin);
+    app.update();
+    app
+}
+
+#[test]
+fn hud_plugin_registers_without_panic() {
+    let _app = headless_app();
+}
+
+#[test]
+fn update_hud_runs_after_game_mutation_without_panic() {
+    let mut app = headless_app();
+    app.world_mut().resource_mut::<GameStateResource>().0 =
+        GameState::new(42, DrawStockConfig::DrawOne);
+    app.update();
+}
+
+fn read_hud_text<M: Component>(app: &mut App) -> String {
+    app.world_mut()
+        .query_filtered::<&Text, With<M>>()
+        .iter(app.world())
+        .next()
+        .map(|t| t.0.clone())
+        .unwrap_or_default()
+}
+
+#[test]
+fn score_reflects_game_state() {
+    let mut app = headless_app();
+    let score = app.world_mut().resource_mut::<GameStateResource>().0.force_test_score(20);
+    app.update();
+    assert_eq!(read_hud_text::<HudScore>(&mut app), format!("Score: {score}"));
+}
+
+#[test]
+fn moves_reflects_game_state() {
+    let mut app = headless_app();
+    app.world_mut()
+        .resource_mut::<GameStateResource>()
+        .0
+        .set_test_move_count(42);
+    app.update();
+    assert_eq!(read_hud_text::<HudMoves>(&mut app), "Moves: 42");
+}
+
+#[test]
+fn draw_three_mode_shows_draw_3_badge() {
+    use solitaire_core::game_state::GameMode;
+    let mut app = headless_app();
+    app.world_mut().resource_mut::<GameStateResource>().0 =
+        GameState::new_with_mode(42, DrawStockConfig::DrawThree, GameMode::Classic);
+    app.update();
+    assert_eq!(read_hud_text::<HudMode>(&mut app), "Draw 3");
+}
+
+#[test]
+fn zen_mode_hides_score() {
+    use solitaire_core::game_state::GameMode;
+    let mut app = headless_app();
+    app.world_mut().resource_mut::<GameStateResource>().0 =
+        GameState::new_with_mode(42, DrawStockConfig::DrawOne, GameMode::Zen);
+    app.update();
+    // Zen mode spec: "No score display" → text must be empty.
+    assert_eq!(read_hud_text::<HudScore>(&mut app), "");
+}
+
+#[test]
+fn time_display_uses_mm_ss_format() {
+    let mut app = headless_app();
+    app.world_mut()
+        .resource_mut::<GameStateResource>()
+        .0
+        .elapsed_seconds = 125;
+    app.update();
+    // 125 seconds = 2 minutes 5 seconds → "2:05"
+    assert_eq!(read_hud_text::<HudTime>(&mut app), "2:05");
+}
+
+// -----------------------------------------------------------------------
+// format_time_limit (pure function)
+// -----------------------------------------------------------------------
+
+#[test]
+fn format_time_limit_300_is_5_00() {
+    assert_eq!(format_time_limit(300), "5:00");
+}
+
+#[test]
+fn format_time_limit_zero() {
+    assert_eq!(format_time_limit(0), "0:00");
+}
+
+#[test]
+fn format_time_limit_pads_seconds() {
+    assert_eq!(format_time_limit(65), "1:05");
+}
+
+// -----------------------------------------------------------------------
+// challenge_hud_text (pure function)
+// -----------------------------------------------------------------------
+
+#[test]
+fn challenge_hud_text_shows_time_limit() {
+    let dc = DailyChallengeResource {
+        date: Local::now().date_naive(),
+        seed: 1,
+        goal_description: None,
+        target_score: None,
+        max_time_secs: Some(300),
+    };
+    assert_eq!(challenge_hud_text(&dc), "Limit: 5:00");
+}
+
+#[test]
+fn challenge_hud_text_shows_score_goal() {
+    let dc = DailyChallengeResource {
+        date: Local::now().date_naive(),
+        seed: 1,
+        goal_description: None,
+        target_score: Some(4000),
+        max_time_secs: None,
+    };
+    assert_eq!(challenge_hud_text(&dc), "Goal: 4000 pts");
+}
+
+#[test]
+fn challenge_hud_text_empty_when_no_constraints() {
+    let dc = DailyChallengeResource {
+        date: Local::now().date_naive(),
+        seed: 1,
+        goal_description: None,
+        target_score: None,
+        max_time_secs: None,
+    };
+    assert_eq!(challenge_hud_text(&dc), "");
+}
+
+#[test]
+fn challenge_time_color_above_60_is_info() {
+    let c = challenge_time_color(61);
+    assert_eq!(c, STATE_INFO);
+}
+
+#[test]
+fn challenge_time_color_exactly_60_is_info() {
+    let c = challenge_time_color(60);
+    assert_eq!(c, STATE_INFO);
+}
+
+#[test]
+fn challenge_time_color_59_is_warning() {
+    let c = challenge_time_color(59);
+    assert_eq!(c, STATE_WARNING);
+}
+
+#[test]
+fn challenge_time_color_30_is_warning() {
+    let c = challenge_time_color(30);
+    assert_eq!(c, STATE_WARNING);
+}
+
+#[test]
+fn challenge_time_color_29_is_danger() {
+    let c = challenge_time_color(29);
+    assert_eq!(c, STATE_DANGER);
+}
+
+#[test]
+fn challenge_time_color_zero_is_danger() {
+    let c = challenge_time_color(0);
+    assert_eq!(c, STATE_DANGER);
+}
+
+// -----------------------------------------------------------------------
+// HudChallenge in-app tests
+// -----------------------------------------------------------------------
+
+#[test]
+fn challenge_hud_empty_when_no_daily_resource() {
+    // No DailyChallengeResource inserted → HudChallenge must be empty.
+    let mut app = headless_app();
+    app.world_mut().resource_mut::<GameStateResource>().set_changed();
+    app.update();
+    assert_eq!(read_hud_text::<HudChallenge>(&mut app), "");
+}
+
+#[test]
+fn challenge_hud_shows_time_limit_when_resource_present() {
+    let mut app = headless_app();
+    app.world_mut().insert_resource(DailyChallengeResource {
+        date: Local::now().date_naive(),
+        seed: 42,
+        goal_description: Some("Win fast".to_string()),
+        target_score: None,
+        max_time_secs: Some(300),
+    });
+    app.world_mut().resource_mut::<GameStateResource>().set_changed();
+    app.update();
+    assert_eq!(read_hud_text::<HudChallenge>(&mut app), "Limit: 5:00");
+}
+
+#[test]
+fn challenge_hud_shows_score_goal_when_resource_present() {
+    let mut app = headless_app();
+    app.world_mut().insert_resource(DailyChallengeResource {
+        date: Local::now().date_naive(),
+        seed: 42,
+        goal_description: None,
+        target_score: Some(4000),
+        max_time_secs: None,
+    });
+    app.world_mut().resource_mut::<GameStateResource>().set_changed();
+    app.update();
+    assert_eq!(read_hud_text::<HudChallenge>(&mut app), "Goal: 4000 pts");
+}
+
+#[test]
+fn challenge_hud_clears_on_win() {
+    let mut app = headless_app();
+    app.world_mut().insert_resource(DailyChallengeResource {
+        date: Local::now().date_naive(),
+        seed: 42,
+        goal_description: None,
+        target_score: None,
+        max_time_secs: Some(300),
+    });
+    // Mark the game as won — HudChallenge should be empty.
+    app.world_mut().resource_mut::<GameStateResource>().0.set_test_won(true);
+    app.update();
+    assert_eq!(read_hud_text::<HudChallenge>(&mut app), "");
+}
+
+// -----------------------------------------------------------------------
+// HudUndos in-app tests
+// -----------------------------------------------------------------------
+
+#[test]
+fn undos_hud_empty_at_game_start() {
+    let mut app = headless_app();
+    app.update();
+    assert_eq!(read_hud_text::<HudUndos>(&mut app), "");
+}
+
+#[test]
+fn undos_hud_shows_count_after_undo() {
+    let mut app = headless_app();
+    app.world_mut()
+        .resource_mut::<GameStateResource>()
+        .0
+        .force_test_undos(3);
+    app.update();
+    assert_eq!(read_hud_text::<HudUndos>(&mut app), "Undos: 3");
+}
+
+// -----------------------------------------------------------------------
+// HudAutoComplete in-app tests (Task #56)
+// -----------------------------------------------------------------------
+
+fn headless_app_with_auto_complete() -> App {
+    let mut app = App::new();
+    app.add_plugins(MinimalPlugins)
+        .add_plugins(GamePlugin)
+        .add_plugins(TablePlugin)
+        .add_plugins(HudPlugin);
+    app.init_resource::<AutoCompleteState>();
+    app.update();
+    app
+}
+
+#[test]
+fn auto_complete_badge_shows_auto_when_active() {
+    let mut app = headless_app_with_auto_complete();
+    app.world_mut().resource_mut::<AutoCompleteState>().active = true;
+    // Also trigger game state change so the update fires.
+    app.world_mut()
+        .resource_mut::<GameStateResource>()
+        .0
+        .set_test_move_count(1);
+    app.update();
+    assert_eq!(read_hud_text::<HudAutoComplete>(&mut app), "AUTO");
+}
+
+#[test]
+fn auto_complete_badge_empty_when_inactive() {
+    let mut app = headless_app_with_auto_complete();
+    // active is false by default.
+    app.world_mut()
+        .resource_mut::<GameStateResource>()
+        .0
+        .set_test_move_count(1);
+    app.update();
+    assert_eq!(read_hud_text::<HudAutoComplete>(&mut app), "");
+}
+
+// -----------------------------------------------------------------------
+// HudRecycles in-app tests
+// -----------------------------------------------------------------------
+
+#[test]
+fn recycles_hud_hidden_when_zero_in_draw_one_mode() {
+    let mut app = headless_app();
+    // Draw-One, no recycles yet — text must be empty.
+    app.world_mut().resource_mut::<GameStateResource>().0 =
+        GameState::new(42, DrawStockConfig::DrawOne);
+    app.update();
+    assert_eq!(read_hud_text::<HudRecycles>(&mut app), "");
+}
+
+#[test]
+fn recycles_hud_hidden_when_zero_in_draw_three_mode() {
+    let mut app = headless_app();
+    // Draw-Three, no recycles yet — text must also be empty.
+    app.world_mut().resource_mut::<GameStateResource>().0 =
+        GameState::new(42, DrawStockConfig::DrawThree);
+    app.update();
+    assert_eq!(read_hud_text::<HudRecycles>(&mut app), "");
+}
+
+#[test]
+fn recycles_hud_shows_count_draw_three() {
+    let mut app = headless_app();
+    let mut gs = GameState::new(42, DrawStockConfig::DrawThree);
+    gs.force_test_recycles(3);
+    app.world_mut().resource_mut::<GameStateResource>().0 = gs;
+    app.update();
+    assert_eq!(read_hud_text::<HudRecycles>(&mut app), "Recycles: 3");
+}
+
+#[test]
+fn recycles_hud_shows_count_draw_one() {
+    let mut app = headless_app();
+    // Draw-One with recycle_count > 0 must now show the counter too.
+    let mut gs = GameState::new(42, DrawStockConfig::DrawOne);
+    gs.force_test_recycles(2);
+    app.world_mut().resource_mut::<GameStateResource>().0 = gs;
+    app.update();
+    assert_eq!(read_hud_text::<HudRecycles>(&mut app), "Recycles: 2");
+}
+
+// -----------------------------------------------------------------------
+// Score-change feedback (G2)
+// -----------------------------------------------------------------------
+
+/// Tells `TimePlugin` to advance by `secs` on every subsequent
+/// `app.update()`. Mirrors the helper in `ui_modal::tests`; kept
+/// local to avoid coupling the two test modules.
+fn set_manual_time_step(app: &mut App, secs: f32) {
+    use bevy::time::TimeUpdateStrategy;
+    use std::time::Duration;
+    app.insert_resource(TimeUpdateStrategy::ManualDuration(Duration::from_secs_f32(
+        secs,
+    )));
+}
+
+/// Counts entities matching component `M` currently in the world.
+fn count_with<M: Component>(app: &mut App) -> usize {
+    app.world_mut().query::<&M>().iter(app.world()).count()
+}
+
+/// A score jump ≥ `SCORE_FLOATER_THRESHOLD` spawns a floating
+/// `ScoreFloater` entity coloured `ACCENT_PRIMARY`. The pulse
+/// component is also inserted on the score readout — both signals
+/// fire from the same delta detection.
+#[test]
+fn score_increase_above_threshold_spawns_floater_in_accent_primary() {
+    let mut app = headless_app();
+    // Pin `Time::delta_secs()` to 0 so the floater's RGB and alpha
+    // can be asserted exactly: with Automatic strategy a few ms
+    // of wall-clock time leaks in between updates and the alpha
+    // drifts below 1.0 by `dt / lifetime`.
+    set_manual_time_step(&mut app, 0.0);
+    // Initial state has score=0; bumping by 50 (the threshold)
+    // is the smallest jump that triggers the floater.
+    app.world_mut().resource_mut::<GameStateResource>().0.force_test_score(50);
+    app.update();
+
+    // One floater should now exist.
+    let count = count_with::<ScoreFloater>(&mut app);
+    assert_eq!(count, 1, "expected a single ScoreFloater for a +50 jump");
+
+    // Its TextColor must be ACCENT_PRIMARY at full alpha. The
+    // detect system spawns the floater coloured ACCENT_PRIMARY
+    // and at dt=0 the first advance tick leaves alpha = 1.0.
+    let world = app.world_mut();
+    let mut q = world.query::<(&ScoreFloater, &TextColor)>();
+    let (_floater, color) = q.iter(world).next().expect("floater missing TextColor");
+    assert_eq!(color.0, ACCENT_PRIMARY);
+}
+
+/// After enough time for `MOTION_SCORE_PULSE_SECS * 2` to elapse
+/// the floater has reached the end of its lifetime and despawned.
+#[test]
+fn score_floater_despawns_after_full_lifetime() {
+    let mut app = headless_app();
+    app.world_mut().resource_mut::<GameStateResource>().0.force_test_score(50);
+    app.update();
+    assert_eq!(count_with::<ScoreFloater>(&mut app), 1);
+
+    // Advance by a delta well past the floater's lifetime — the
+    // single oversized tick clamps t at 1.0 and the entity is
+    // despawned in the same `Update`.
+    set_manual_time_step(&mut app, MOTION_SCORE_PULSE_SECS * 2.0 * 2.0 + 0.1);
+    app.update();
+    app.update(); // first update propagates the new strategy; second runs the system with non-zero dt.
+
+    assert_eq!(
+        count_with::<ScoreFloater>(&mut app),
+        0,
+        "floater should have despawned after its full lifetime"
+    );
+}
+
+/// A small score change (below the threshold) inserts a pulse on
+/// the readout but never spawns a floater — keeping the floating
+/// "+N" reserved for meaningful score jumps.
+#[test]
+fn score_increase_below_threshold_does_not_spawn_floater() {
+    let mut app = headless_app();
+    // +5 mirrors a single tableau-to-foundation move; well below
+    // the 50-point threshold so the floater path stays dormant.
+    app.world_mut().resource_mut::<GameStateResource>().0.force_test_score(5);
+    app.update();
+    assert_eq!(
+        count_with::<ScoreFloater>(&mut app),
+        0,
+        "delta of +5 must not spawn a floater"
+    );
+}
+
+/// The triangular pulse curve hits its peak (1.1) at t=0.5 and
+/// returns to 1.0 at the endpoints. Pure-function check that
+/// guards the curve shape against future tweaks.
+#[test]
+fn score_pulse_scale_is_triangular() {
+    assert!((score_pulse_scale(0.0) - 1.0).abs() < 1e-6);
+    assert!((score_pulse_scale(0.5) - 1.1).abs() < 1e-6);
+    assert!((score_pulse_scale(1.0) - 1.0).abs() < 1e-6);
+    // Values outside [0,1] are clamped before the curve runs.
+    assert!((score_pulse_scale(-0.2) - 1.0).abs() < 1e-6);
+    assert!((score_pulse_scale(2.0) - 1.0).abs() < 1e-6);
+}
+
+/// Streak flourish curve must be 1.0 at t=0, peak at t=0.5, and
+/// return to 1.0 at t=duration. Mirrors the `foundation_flourish_scale`
+/// curve test — the two animations share a triangular shape so a
+/// future tweak that desyncs them shows up here.
+#[test]
+fn streak_flourish_scale_curves_through_one_one_one() {
+    let dur = MOTION_STREAK_FLOURISH_SECS;
+    assert!(
+        (streak_flourish_scale(0.0, dur) - 1.0).abs() < 1e-5,
+        "streak flourish scale at t=0 must be 1.0",
+    );
+    assert!(
+        (streak_flourish_scale(dur / 2.0, dur) - STREAK_FLOURISH_PEAK_SCALE).abs() < 1e-5,
+        "streak flourish scale at midpoint must be STREAK_FLOURISH_PEAK_SCALE",
+    );
+    assert!(
+        (streak_flourish_scale(dur, dur) - 1.0).abs() < 1e-5,
+        "streak flourish scale at t=duration must return to 1.0",
+    );
+}
+
+/// Out-of-range values are clamped, not extrapolated. Matches the
+/// foundation flourish's clamp behaviour so the score readout never
+/// freezes at a non-1.0 scale on the frame after the flourish ends.
+#[test]
+fn streak_flourish_scale_clamps_out_of_range() {
+    let dur = MOTION_STREAK_FLOURISH_SECS;
+    assert!((streak_flourish_scale(-1.0, dur) - 1.0).abs() < 1e-5);
+    assert!((streak_flourish_scale(dur * 5.0, dur) - 1.0).abs() < 1e-5);
+}
+
+/// Zero duration (e.g. `AnimSpeed::Instant`) returns identity, never
+/// divides by zero.
+#[test]
+fn streak_flourish_scale_zero_duration_is_one() {
+    assert!((streak_flourish_scale(0.0, 0.0) - 1.0).abs() < 1e-5);
+    assert!((streak_flourish_scale(0.5, 0.0) - 1.0).abs() < 1e-5);
+}
+
+// -----------------------------------------------------------------------
+// Reduce-motion gates — ScorePulse, ScoreFloater, StreakFlourish
+// -----------------------------------------------------------------------
+
+/// Under `Settings::reduce_motion_mode`, a score bump must NOT spawn
+/// a `ScorePulse` on the readout or a `ScoreFloater` on the stage.
+#[test]
+fn score_change_skips_pulse_and_floater_under_reduce_motion() {
+    use solitaire_data::Settings;
+    let mut app = headless_app();
+    app.insert_resource(SettingsResource(Settings {
+        reduce_motion_mode: true,
+        ..Settings::default()
+    }));
+    // +100 would normally create both a ScorePulse and a ScoreFloater.
+    app.world_mut().resource_mut::<GameStateResource>().0.force_test_score(50);
+    app.update();
+    assert_eq!(
+        count_with::<ScorePulse>(&mut app),
+        0,
+        "ScorePulse must not spawn under reduce-motion"
+    );
+    assert_eq!(
+        count_with::<ScoreFloater>(&mut app),
+        0,
+        "ScoreFloater must not spawn under reduce-motion"
+    );
+}
+
+// -----------------------------------------------------------------------
+// Phase 2: keyboard focus ring — HUD action bar
+// -----------------------------------------------------------------------
+
+/// Returns the `Focusable` carried by the unique entity matching
+/// marker `M`. Helper for the HUD focus tests.
+fn focusable_for<M: Component>(app: &mut App) -> Focusable {
+    app.world_mut()
+        .query_filtered::<&Focusable, With<M>>()
+        .iter(app.world())
+        .next()
+        .copied()
+        .unwrap_or_else(|| panic!("no Focusable on the {} button", std::any::type_name::<M>()))
+}
+
+#[test]
+fn hud_buttons_get_focusable_marker() {
+    let mut app = headless_app();
+    // Every action-bar button is in `FocusGroup::Hud`.
+    for f in [
+        focusable_for::<MenuButton>(&mut app),
+        focusable_for::<UndoButton>(&mut app),
+        focusable_for::<PauseButton>(&mut app),
+        focusable_for::<HelpButton>(&mut app),
+        focusable_for::<HintButton>(&mut app),
+        focusable_for::<ModesButton>(&mut app),
+        focusable_for::<NewGameButton>(&mut app),
+    ] {
+        assert_eq!(
+            f.group,
+            FocusGroup::Hud,
+            "every HUD action button must be in FocusGroup::Hud"
+        );
+    }
+}
+
+/// Returns the tooltip string carried by the unique entity matching
+/// marker `M`. Panics if zero or more than one such entity exists,
+/// which is the invariant we want to enforce for HUD readouts and
+/// action buttons (each marker is spawned exactly once).
+fn tooltip_for<M: Component>(app: &mut App) -> String {
+    let mut q = app.world_mut().query_filtered::<&Tooltip, With<M>>();
+    let world = app.world();
+    let mut iter = q.iter(world);
+    let first = iter
+        .next()
+        .unwrap_or_else(|| {
+            panic!(
+                "expected a Tooltip on the {} entity",
+                std::any::type_name::<M>()
+            )
+        })
+        .0
+        .clone()
+        .into_owned();
+    assert!(
+        iter.next().is_none(),
+        "expected exactly one Tooltip-bearing entity for {}",
+        std::any::type_name::<M>()
+    );
+    first
+}
+
+/// Every HUD readout and action button must spawn with a `Tooltip`
+/// carrying the approved canonical microcopy. Mirrors the structure
+/// of `hud_buttons_get_focusable_marker` (Phase 2 focus test) so the
+/// invariant — one marker entity, one tooltip, exact text — is
+/// asserted consistently across every element.
+#[test]
+fn hud_elements_carry_expected_tooltip_strings() {
+    let mut app = headless_app();
+
+    // HUD readouts (left column, top to bottom).
+    assert_eq!(
+        tooltip_for::<HudScore>(&mut app),
+        "Points earned this game. Hidden in Zen mode."
+    );
+    assert_eq!(
+        tooltip_for::<HudMoves>(&mut app),
+        "Moves you've made this game. Counts placements and stock draws."
+    );
+    assert_eq!(
+        tooltip_for::<HudTime>(&mut app),
+        "Time on this game. Counts down in Time Attack."
+    );
+    assert_eq!(
+        tooltip_for::<HudMode>(&mut app),
+        "Active game mode. Click Modes to switch."
+    );
+    assert_eq!(
+        tooltip_for::<HudChallenge>(&mut app),
+        "Today's daily challenge target. Beat it for bonus XP."
+    );
+    assert_eq!(
+        tooltip_for::<HudDrawCycle>(&mut app),
+        "Cards drawn on the next stock click in Draw-Three."
+    );
+    assert_eq!(
+        tooltip_for::<HudUndos>(&mut app),
+        "Undos used this game. Any undo blocks the No Undo achievement."
+    );
+    assert_eq!(
+        tooltip_for::<HudRecycles>(&mut app),
+        "Times you've recycled the stock. Three or more unlocks Comeback."
+    );
+    assert_eq!(
+        tooltip_for::<HudAutoComplete>(&mut app),
+        "Board is solvable from here. Press Enter to auto-finish."
+    );
+    assert_eq!(
+        tooltip_for::<HudSelection>(&mut app),
+        "Pile selected with Tab. Use arrows or Enter to act."
+    );
+
+    // Action bar (left to right).
+    assert_eq!(
+        tooltip_for::<MenuButton>(&mut app),
+        "Open Stats, Achievements, Profile, Settings, or Leaderboard."
+    );
+    assert_eq!(
+        tooltip_for::<UndoButton>(&mut app),
+        "Take back your last move. Costs points and blocks No Undo."
+    );
+    assert_eq!(
+        tooltip_for::<PauseButton>(&mut app),
+        "Pause the game and freeze the timer."
+    );
+    assert_eq!(
+        tooltip_for::<HelpButton>(&mut app),
+        "Show controls, rules, and keyboard shortcuts."
+    );
+    assert_eq!(
+        tooltip_for::<HintButton>(&mut app),
+        "Highlight a suggested move. Cycles through alternatives on repeat taps."
+    );
+    assert_eq!(
+        tooltip_for::<ModesButton>(&mut app),
+        "Switch modes: Classic, Daily, Zen, Challenge, Time Attack."
+    );
+    assert_eq!(
+        tooltip_for::<NewGameButton>(&mut app),
+        "Start a fresh deal. Confirms first if a game is in progress."
+    );
+}
+
+/// Every interior row of the Modes and Menu popovers must carry a
+/// `Tooltip`. The popovers open from action-bar buttons whose own
+/// tooltips are already covered above; this test extends the
+/// invariant inward so hover discoverability is uniform across the
+/// HUD's nested controls.
+///
+/// We invoke the popover spawn helpers directly with a maxed-out
+/// `ProgressResource` and a `DailyChallengeResource` so every row
+/// branch fires (Classic, Daily, Zen, Challenge, Time Attack).
+/// Headless click simulation isn't needed — the contract under
+/// test is "every popover row spawns with a tooltip", which is a
+/// property of the spawn helpers themselves.
+#[test]
+fn popover_rows_carry_tooltip_strings() {
+    use crate::progress_plugin::ProgressResource;
+    use solitaire_sync::progress::PlayerProgress;
+
+    let mut app = headless_app();
+
+    // Force every mode row to render: level past the challenge
+    // unlock threshold, plus a daily challenge resource so the
+    // Daily row appears.
+    let progress = ProgressResource(PlayerProgress {
+        level: CHALLENGE_UNLOCK_LEVEL,
+        ..Default::default()
+    });
+    let daily = DailyChallengeResource {
+        date: Local::now().date_naive(),
+        seed: 1,
+        goal_description: None,
+        target_score: None,
+        max_time_secs: None,
+    };
+
+    // Spawn both popovers via their helpers. Mirrors how the click
+    // handlers invoke them in production — we just skip the click.
+    {
+        let world = app.world_mut();
+        let mut commands = world.commands();
+        spawn_modes_popover(&mut commands, Some(&progress), Some(&daily), None);
+        spawn_menu_popover(&mut commands, None);
+        world.flush();
+    }
+    app.update();
+
+    // Every ModeOption-tagged entity must also carry a Tooltip,
+    // and the count must match the five canonical modes.
+    let mut mode_q = app
+        .world_mut()
+        .query_filtered::<&Tooltip, With<ModeOption>>();
+    let mode_tooltips: Vec<String> = mode_q
+        .iter(app.world())
+        .map(|t| t.0.clone().into_owned())
+        .collect();
+    assert_eq!(
+        mode_tooltips.len(),
+        5,
+        "expected a tooltip on each of the 5 mode rows, got {}",
+        mode_tooltips.len()
+    );
+    // Every approved mode tooltip string must be present somewhere
+    // among the ModeOption rows. Order isn't asserted — the spawn
+    // order test elsewhere already covers that.
+    for expected in [
+        "Standard Klondike. Score, timer, and full progression.",
+        "Today's seeded deal. Same for every player worldwide.",
+        "No timer, no score, no penalties. Just play.",
+        "Hand-picked hard seeds. No undo allowed.",
+        "Win as many games as you can in ten minutes.",
+    ] {
+        assert!(
+            mode_tooltips.iter().any(|s| s == expected),
+            "missing mode tooltip: {expected:?}"
+        );
+    }
+
+    // Same contract for MenuOption rows: seven entries, each with a
+    // tooltip, exact strings matching the approved microcopy.
+    let mut menu_q = app
+        .world_mut()
+        .query_filtered::<&Tooltip, With<MenuOption>>();
+    let menu_tooltips: Vec<String> = menu_q
+        .iter(app.world())
+        .map(|t| t.0.clone().into_owned())
+        .collect();
+    assert_eq!(
+        menu_tooltips.len(),
+        7,
+        "expected a tooltip on each of the 7 menu rows, got {}",
+        menu_tooltips.len()
+    );
+    for expected in [
+        "Show controls, rules, and keyboard shortcuts.",
+        "Switch modes: Classic, Daily, Zen, Challenge, Time Attack.",
+        "Lifetime totals: wins, streaks, fastest time, best score.",
+        "Browse unlocked achievements and the rewards still ahead.",
+        "Your level, XP progress, and sync status.",
+        "Audio, animations, theme, draw mode, and sync.",
+        "Top players from your sync server. Opt in from Profile.",
+    ] {
+        assert!(
+            menu_tooltips.iter().any(|s| s == expected),
+            "missing menu tooltip: {expected:?}"
+        );
+    }
+}
+
+#[test]
+fn hud_button_order_matches_spawn_order() {
+    let mut app = headless_app();
+    // Visual reading order (left → right): Menu, Undo, Pause, Help,
+    // Hint, Modes, New Game. Their `order` fields must be 0..=6 in
+    // that order so Tab cycles them as the player reads them.
+    assert_eq!(focusable_for::<MenuButton>(&mut app).order, 0);
+    assert_eq!(focusable_for::<UndoButton>(&mut app).order, 1);
+    assert_eq!(focusable_for::<PauseButton>(&mut app).order, 2);
+    assert_eq!(focusable_for::<HelpButton>(&mut app).order, 3);
+    assert_eq!(focusable_for::<HintButton>(&mut app).order, 4);
+    assert_eq!(focusable_for::<ModesButton>(&mut app).order, 5);
+    assert_eq!(focusable_for::<NewGameButton>(&mut app).order, 6);
+}
+
+#[test]
+fn hud_focus_only_engages_when_button_hovered() {
+    // Phase 2 declares membership in `FocusGroup::Hud`; the
+    // engagement rule lives in `handle_focus_keys`. Two halves to
+    // this test:
+    //   (a) no modal + no hover ⇒ Tab is a no-op (Phase 1 contract
+    //       still holds when nothing is hovered).
+    //   (b) no modal + a HUD button hovered ⇒ Tab advances
+    //       `FocusedButton` to a Hud-grouped entity.
+    use crate::ui_focus::{FocusedButton, UiFocusPlugin};
+    use crate::ui_modal::UiModalPlugin;
+
+    let mut app = App::new();
+    app.add_plugins(MinimalPlugins)
+        .add_plugins(UiModalPlugin)
+        .add_plugins(UiFocusPlugin)
+        .add_plugins(GamePlugin)
+        .add_plugins(TablePlugin)
+        .add_plugins(HudPlugin);
+    app.init_resource::<ButtonInput<KeyCode>>();
+    app.update();
+
+    // (a) Sanity: HUD buttons exist and are focusable, but no
+    // modal open and no hover ⇒ FocusedButton stays None.
+    assert!(
+        app.world().resource::<FocusedButton>().0.is_none(),
+        "no modal open, no auto-focus"
+    );
+
+    // Press Tab. With no modal and no hover, `handle_focus_keys`
+    // resolves no active group and returns early — Tab must not
+    // advance the HUD focus ring on its own.
+    {
+        let mut input = app.world_mut().resource_mut::<ButtonInput<KeyCode>>();
+        input.release_all();
+        input.clear();
+        input.press(KeyCode::Tab);
+    }
+    app.update();
+
+    assert!(
+        app.world().resource::<FocusedButton>().0.is_none(),
+        "Tab with no modal and no Hud hover must not engage the HUD focus ring"
+    );
+
+    // (b) Hover the Menu button — the leftmost HUD action — and
+    // Tab. The Hud-group cycle should pick a Hud-tagged entity.
+    let menu_entity = app
+        .world_mut()
+        .query_filtered::<Entity, With<MenuButton>>()
+        .iter(app.world())
+        .next()
+        .expect("MenuButton entity should exist");
+    app.world_mut()
+        .entity_mut(menu_entity)
+        .insert(Interaction::Hovered);
+
+    {
+        let mut input = app.world_mut().resource_mut::<ButtonInput<KeyCode>>();
+        input.release_all();
+        input.clear();
+        input.press(KeyCode::Tab);
+    }
+    app.update();
+
+    let focused = app
+        .world()
+        .resource::<FocusedButton>()
+        .0
+        .expect("Tab with a HUD button hovered must engage the HUD focus ring");
+    // The focused entity must itself be Hud-grouped (i.e. one of
+    // the action-bar buttons), not anything else in the world.
+    let focusable = app
+        .world()
+        .entity(focused)
+        .get::<Focusable>()
+        .expect("focused entity must carry Focusable");
+    assert_eq!(
+        focusable.group,
+        FocusGroup::Hud,
+        "Hud-engaged Tab must focus a Hud-grouped entity"
+    );
+}
@@ -0,0 +1,707 @@
+use super::*;
+use crate::layout::compute_layout;
+use solitaire_core::{Deck, Foundation, Rank, Suit, Tableau};
+use solitaire_core::{DrawStockConfig, game_state::GameState};
+
+fn clear_test_piles(game: &mut GameState) {
+    game.set_test_stock_cards(Vec::new());
+    game.set_test_waste_cards(Vec::new());
+    for foundation in [
+        Foundation::Foundation1,
+        Foundation::Foundation2,
+        Foundation::Foundation3,
+        Foundation::Foundation4,
+    ] {
+        game.set_test_foundation_cards(foundation, Vec::new());
+    }
+    for tableau in [
+        Tableau::Tableau1,
+        Tableau::Tableau2,
+        Tableau::Tableau3,
+        Tableau::Tableau4,
+        Tableau::Tableau5,
+        Tableau::Tableau6,
+        Tableau::Tableau7,
+    ] {
+        game.set_test_tableau_cards(tableau, Vec::new());
+    }
+}
+
+#[test]
+fn dragged_card_z_matches_resting_stack_step() {
+    assert!((dragged_card_z(0) - DRAG_Z).abs() < 1e-6);
+    let step = dragged_card_z(1) - dragged_card_z(0);
+    assert!(
+        step > 0.02,
+        "drag step must exceed Android overlay local_z, got {step}"
+    );
+    assert!(
+        step + 1e-4 >= STACK_FAN_FRAC,
+        "drag step must stay aligned with resting stack spacing, got {step}"
+    );
+}
+
+#[test]
+fn point_in_rect_inside_returns_true() {
+    let center = Vec2::new(10.0, 20.0);
+    let size = Vec2::new(40.0, 60.0);
+    assert!(point_in_rect(Vec2::new(10.0, 20.0), center, size));
+    assert!(point_in_rect(Vec2::new(29.0, 49.0), center, size));
+    assert!(point_in_rect(Vec2::new(-9.0, -9.0), center, size));
+}
+
+#[test]
+fn point_in_rect_on_edge_returns_true() {
+    let center = Vec2::ZERO;
+    let size = Vec2::new(10.0, 10.0);
+    assert!(point_in_rect(Vec2::new(5.0, 5.0), center, size));
+    assert!(point_in_rect(Vec2::new(-5.0, -5.0), center, size));
+}
+
+#[test]
+fn point_in_rect_outside_returns_false() {
+    let center = Vec2::ZERO;
+    let size = Vec2::new(10.0, 10.0);
+    assert!(!point_in_rect(Vec2::new(6.0, 0.0), center, size));
+    assert!(!point_in_rect(Vec2::new(0.0, 6.0), center, size));
+    assert!(!point_in_rect(Vec2::new(-100.0, 0.0), center, size));
+}
+
+#[test]
+fn find_draggable_picks_top_of_tableau() {
+    let game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+
+    // In tableau 6, the visually topmost card is the last (face-up) one.
+    // Its position: base.y + fan * 6.
+    let top_pos = card_position(&game, &layout, &KlondikePile::Tableau(Tableau::Tableau7), 6);
+    let result = find_draggable_at(top_pos, &game, &layout).expect("hit");
+    assert_eq!(result.0, KlondikePile::Tableau(Tableau::Tableau7));
+    assert_eq!(result.1, 6);
+    assert_eq!(result.2.len(), 1);
+}
+
+#[test]
+fn find_draggable_picks_waste_top_with_multiple_cards() {
+    // Reproduces the reported "drags the wrong waste card" bug: with several
+    // cards in the waste, clicking the visible top must pick the actual top
+    // (last index), not the buffer card underneath it.
+    let mut game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    clear_test_piles(&mut game);
+    let waste = vec![Card::new(Deck::Deck1, Suit::Clubs, Rank::Two),
+                     Card::new(Deck::Deck1, Suit::Hearts, Rank::Five),
+                     Card::new(Deck::Deck1, Suit::Spades, Rank::Nine)];
+    game.set_test_waste_cards(waste.clone());
+
+    let top_index = waste.len() - 1; // 2 = the visible top
+    let top_pos = card_position(&game, &layout, &KlondikePile::Stock, top_index);
+    let result = find_draggable_at(top_pos, &game, &layout).expect("waste top is draggable");
+    assert_eq!(result.0, KlondikePile::Stock, "origin is the waste pile");
+    assert_eq!(result.1, top_index, "picks the top index, not the buffer");
+    assert_eq!(result.2, vec![waste[top_index].clone()], "drags the top card only");
+}
+
+#[test]
+fn find_draggable_picks_lone_waste_card() {
+    // "can't play the first card in the stock" — a waste of one card must
+    // still be draggable.
+    let mut game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    clear_test_piles(&mut game);
+    let card = Card::new(Deck::Deck1, Suit::Diamonds, Rank::Ace);
+    game.set_test_waste_cards(vec![card.clone()]);
+
+    let pos = card_position(&game, &layout, &KlondikePile::Stock, 0);
+    let result = find_draggable_at(pos, &game, &layout).expect("lone waste card is draggable");
+    assert_eq!(result.0, KlondikePile::Stock);
+    assert_eq!(result.1, 0);
+    assert_eq!(result.2, vec![card]);
+}
+
+#[test]
+fn draw_three_waste_hit_test_matches_render_fan_step() {
+    // Regression: the Draw-Three waste hit-test must use the same fan step as
+    // the renderer (`card_plugin::waste_fan_step`). The previous hard-coded
+    // `card_size.x * 0.28` matched the renderer only on desktop (column step =
+    // 1.25*cw); under tighter Android-style spacing the two drift and the top
+    // fanned card's click target lands on the card beneath it — so dragging
+    // the visible top card plays the wrong one.
+    let mut game = GameState::new(7, DrawStockConfig::DrawThree);
+    let mut layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+
+    // Force tight (Android-like) column spacing: ~1.03 * card_width.
+    let cw = layout.card_size.x;
+    let base = layout.pile_positions[&KlondikePile::Stock];
+    let t1 = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau1)];
+    layout.pile_positions.insert(
+        KlondikePile::Tableau(Tableau::Tableau2),
+        Vec2::new(t1.x + cw * 1.03, t1.y),
+    );
+
+    clear_test_piles(&mut game);
+    let waste = vec![
+        Card::new(Deck::Deck1, Suit::Clubs, Rank::Two),
+        Card::new(Deck::Deck1, Suit::Hearts, Rank::Five),
+        Card::new(Deck::Deck1, Suit::Spades, Rank::Nine),
+        Card::new(Deck::Deck1, Suit::Diamonds, Rank::King),
+    ];
+    game.set_test_waste_cards(waste.clone());
+
+    // visible_start = len-3 = 1, so the top card sits at fan slot 2.
+    let top_index = waste.len() - 1;
+    let pos = card_position(&game, &layout, &KlondikePile::Stock, top_index);
+
+    let expected = base.x + 2.0 * waste_fan_step(&layout);
+    assert!(
+        (pos.x - expected).abs() < 1e-3,
+        "hit-test must use the shared waste fan step"
+    );
+    // The old fixed constant would have drifted from the renderer here.
+    let old = base.x + 2.0 * cw * 0.28;
+    assert!(
+        (pos.x - old).abs() > 1.0,
+        "shared step must differ from the old fixed step under tight spacing"
+    );
+}
+
+#[test]
+fn find_draggable_skips_face_down_cards() {
+    let game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+
+    // Tableau 6 has 7 cards: 6 face-down (indices 0..5) + 1 face-up at
+    // the bottom (index 6). Click at the topmost face-down card's
+    // position — its full body is partly visible above the fanned
+    // face-up card, but the iterator should skip face-down cards and
+    // the cursor sits above the face-up card's AABB, so the result
+    // is None.
+    let face_down_pos =
+        card_position(&game, &layout, &KlondikePile::Tableau(Tableau::Tableau7), 0);
+    let result = find_draggable_at(face_down_pos, &game, &layout);
+    assert!(result.is_none(), "face-down cards should not be draggable");
+}
+
+#[test]
+fn find_draggable_hits_face_up_card_with_face_down_cards_above_it() {
+    // Regression test for the bug where input_plugin's hit-testing used
+    // a uniform 0.25 fan step but card_plugin renders face-down cards
+    // at 0.12 — so for any column with face-down cards above the
+    // face-up bottom card, clicking the visible card face missed the
+    // hit-test box and only the bottom strip of the card responded.
+    let game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+
+    // Tableau 6 starts with 6 face-down + 1 face-up. The face-up card
+    // sits at base.y - 6 * TABLEAU_FACEDOWN_FAN_FRAC * card_h, NOT at
+    // base.y - 6 * TABLEAU_FAN_FRAC * card_h. Click the centre.
+    let face_up_pos =
+        card_position(&game, &layout, &KlondikePile::Tableau(Tableau::Tableau7), 6);
+    let result = find_draggable_at(face_up_pos, &game, &layout)
+        .expect("clicking the face-up card's visible centre must initiate a drag");
+    assert_eq!(result.0, KlondikePile::Tableau(Tableau::Tableau7));
+    assert_eq!(result.1, 6);
+    assert_eq!(result.2.len(), 1);
+}
+
+#[test]
+fn find_draggable_returns_run_when_picking_mid_stack() {
+    // Manually construct a tableau with three face-up cards all stacked.
+    let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    let king = Card::new(D::Deck1, Suit::Spades, Rank::King);
+    let queen = Card::new(D::Deck1, Suit::Hearts, Rank::Queen);
+    let jack = Card::new(D::Deck1, Suit::Clubs, Rank::Jack);
+    game.set_test_tableau_cards(
+        Tableau::Tableau1,
+        vec![king, queen.clone(), jack.clone()],
+    );
+
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    // The Queen's geometric center (index 1) is inside the Jack's bounding box
+    // (Jack fans 0.5h below base; its box spans [base-h, base]).  To hit the
+    // Queen we click in her visible strip: the 0.25h band above the Jack's top
+    // edge (base.y to base.y+0.25h).  Midpoint = queen_center + 0.375*card_h.
+    let queen_center =
+        card_position(&game, &layout, &KlondikePile::Tableau(Tableau::Tableau1), 1);
+    let pos = queen_center + Vec2::new(0.0, layout.card_size.y * 0.375);
+    let (pile, start, ids) = find_draggable_at(pos, &game, &layout).expect("hit");
+    assert_eq!(pile, KlondikePile::Tableau(Tableau::Tableau1));
+    assert_eq!(start, 1);
+    assert_eq!(ids, vec![queen, jack]);
+}
+
+#[test]
+fn find_draggable_skips_non_top_waste_card() {
+    let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    let two_spades = Card::new(D::Deck1, Suit::Spades, Rank::Two);
+    let three_hearts = Card::new(D::Deck1, Suit::Hearts, Rank::Three);
+    game.set_test_waste_cards(vec![two_spades, three_hearts.clone()]);
+
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    // Both cards in waste sit at the same (x, y). Clicking should pick
+    // the visually top card (three_hearts), with count = 1.
+    let pos = card_position(&game, &layout, &KlondikePile::Stock, 0);
+    let (pile, start, ids) = find_draggable_at(pos, &game, &layout).expect("hit");
+    assert_eq!(pile, KlondikePile::Stock);
+    assert_eq!(start, 1);
+    assert_eq!(ids, vec![three_hearts]);
+}
+
+#[test]
+fn find_drop_target_hits_empty_tableau_pile_marker() {
+    let game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    // Move all cards out of tableau 0 so its marker is the only drop area.
+    let mut game = game;
+    game.set_test_tableau_cards(Tableau::Tableau1, Vec::new());
+    let pos = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau1)];
+    let target = find_drop_target(
+        pos,
+        &game,
+        &layout,
+        &KlondikePile::Tableau(Tableau::Tableau7),
+    );
+    assert_eq!(target, Some(KlondikePile::Tableau(Tableau::Tableau1)));
+}
+
+#[test]
+fn find_drop_target_returns_none_for_origin() {
+    let game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    let pos = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau4)];
+    let target = find_drop_target(
+        pos,
+        &game,
+        &layout,
+        &KlondikePile::Tableau(Tableau::Tableau4),
+    );
+    assert_eq!(target, None);
+}
+
+#[test]
+fn pile_drop_rect_extends_for_tableau_with_cards() {
+    let game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    // Tableau 6 has 7 cards.
+    let (_, size) = pile_drop_rect(&KlondikePile::Tableau(Tableau::Tableau7), &layout, &game);
+    // Expected: card_height + 6 fan steps.
+    let expected = layout.card_size.y * (1.0 + 6.0 * layout.tableau_fan_frac);
+    assert!(
+        (size.y - expected).abs() < 1e-3,
+        "expected {expected}, got {}",
+        size.y
+    );
+}
+
+#[test]
+fn find_draggable_draw_three_waste_top_card_hit_at_fanned_position() {
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    use solitaire_core::{DrawStockConfig, game_state::GameMode};
+    let mut game = GameState::new_with_mode(1, DrawStockConfig::DrawThree, GameMode::Classic);
+    // Three waste cards; top (four_clubs) is rightmost in the fan.
+    let two_spades = Card::new(D::Deck1, Suit::Spades, Rank::Two);
+    let three_hearts = Card::new(D::Deck1, Suit::Hearts, Rank::Three);
+    let four_clubs = Card::new(D::Deck1, Suit::Clubs, Rank::Four);
+    game.set_test_waste_cards(vec![two_spades, three_hearts, four_clubs.clone()]);
+
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    let waste_base = layout.pile_positions[&KlondikePile::Stock];
+    // Top card (slot=2) is at base.x + 2 * 0.28 * card_width.
+    let top_card_x = waste_base.x + 2.0 * 0.28 * layout.card_size.x;
+    let cursor = Vec2::new(top_card_x, waste_base.y);
+
+    let result = find_draggable_at(cursor, &game, &layout);
+    assert!(
+        result.is_some(),
+        "top fanned waste card must be hittable at its visual X position"
+    );
+    let (pile, _start, ids) = result.unwrap();
+    assert_eq!(pile, KlondikePile::Stock);
+    assert_eq!(ids, vec![four_clubs], "only the top card is draggable from waste");
+}
+
+#[test]
+fn find_draggable_returns_none_for_click_on_empty_pile() {
+    let mut game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    // Clear tableau 0 so it's an empty slot.
+    game.set_test_tableau_cards(Tableau::Tableau1, Vec::new());
+    let pos = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau1)];
+    let result = find_draggable_at(pos, &game, &layout);
+    assert!(
+        result.is_none(),
+        "clicking an empty pile must not produce a draggable"
+    );
+}
+
+#[test]
+fn pile_drop_rect_is_card_sized_for_non_tableau() {
+    let game = GameState::new(42, DrawStockConfig::DrawOne);
+    let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
+    for pile in [
+        KlondikePile::Stock,
+        KlondikePile::Foundation(Foundation::Foundation3),
+    ] {
+        let (_, size) = pile_drop_rect(&pile, &layout, &game);
+        assert_eq!(size, layout.card_size);
+    }
+}
+
+// -----------------------------------------------------------------------
+// Task #27 — best_destination pure-function tests
+// -----------------------------------------------------------------------
+
+#[test]
+fn best_destination_returns_none_when_no_legal_move() {
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+
+    // Clear everything except one card that has nowhere to go.
+    clear_test_piles(&mut game);
+
+    // A Two of Clubs with empty foundations and empty tableau has no destination.
+    let card = Card::new(D::Deck1, Suit::Clubs, Rank::Two);
+    assert!(best_destination(&card, &game).is_none());
+}
+
+// -----------------------------------------------------------------------
+// best_tableau_destination_for_stack pure-function tests
+// -----------------------------------------------------------------------
+
+#[test]
+fn best_tableau_destination_for_stack_skips_source_pile() {
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+
+    clear_test_piles(&mut game);
+
+    // Only tableau 0 has anything; every other column is empty.
+    // A King is the only card that can go on an empty tableau column.
+    // Source is Tableau(0), so the result must NOT be Tableau(0).
+    let king = Card::new(D::Deck1, Suit::Hearts, Rank::King);
+    game.set_test_tableau_cards(Tableau::Tableau1, vec![king.clone()]);
+
+    let result = best_tableau_destination_for_stack(
+        &king,
+        &KlondikePile::Tableau(Tableau::Tableau1),
+        &game,
+        1,
+    );
+    // Result must be some other empty tableau column, never the source.
+    if let Some((dest, _)) = result {
+        assert_ne!(dest, KlondikePile::Tableau(Tableau::Tableau1));
+    }
+}
+
+#[test]
+fn best_tableau_destination_for_stack_returns_none_when_no_legal_move() {
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+
+    clear_test_piles(&mut game);
+
+    // Source: tableau 0 has a Two of Clubs (can't go on empty pile; not a King).
+    // All other piles are empty — no legal tableau target.
+    let two_clubs = Card::new(D::Deck1, Suit::Clubs, Rank::Two);
+    game.set_test_tableau_cards(Tableau::Tableau1, vec![two_clubs.clone()]);
+
+    let result = best_tableau_destination_for_stack(
+        &two_clubs,
+        &KlondikePile::Tableau(Tableau::Tableau1),
+        &game,
+        1,
+    );
+    assert!(
+        result.is_none(),
+        "Two of Clubs has no legal tableau destination on empty piles"
+    );
+}
+
+// -----------------------------------------------------------------------
+// Task #28 — find_hint pure-function tests
+// -----------------------------------------------------------------------
+
+#[test]
+fn find_hint_finds_ace_to_foundation() {
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+
+    // Place Ace of Clubs on top of tableau 0.
+    clear_test_piles(&mut game);
+    let ace_clubs = Card::new(D::Deck1, Suit::Clubs, Rank::Ace);
+    game.set_test_tableau_cards(Tableau::Tableau1, vec![ace_clubs]);
+
+    let hint = find_hint(&game);
+    assert!(hint.is_some(), "should find a hint");
+    let (from, to) = hint.unwrap();
+    assert_eq!(from, KlondikePile::Tableau(Tableau::Tableau1));
+    assert_eq!(to, KlondikePile::Foundation(Foundation::Foundation1));
+}
+
+// -----------------------------------------------------------------------
+// G key fires ForfeitRequestEvent (modal-based forfeit flow)
+// -----------------------------------------------------------------------
+
+/// `handle_keyboard_forfeit` only checks `paused` and the G keypress;
+/// the "is there actually a game?" gating lives in
+/// `pause_plugin::handle_forfeit_request` so it can surface a
+/// "No game to forfeit" toast instead of failing silently.
+#[test]
+fn g_key_paused_check_keeps_handler_silent_while_pause_modal_owns_input() {
+    // Build the system param state by hand so we don't rely on a
+    // full Bevy app: the assertion is that the function returns
+    // early on the paused branch without calling write_message.
+    // This is verified by the plain `if paused { return; }` shape;
+    // the body is small enough to inspect by reading.
+    // (Higher-level integration coverage lives in the pause-plugin
+    // tests where `forfeit_app` simulates the full flow.)
+    let _ = handle_keyboard_forfeit; // proves the symbol still compiles
+}
+
+// -----------------------------------------------------------------------
+// all_hints / new-game window — pure-function tests added during refactor
+// -----------------------------------------------------------------------
+
+/// Pass 3 of `all_hints` should suggest drawing from the stock when there
+/// are no other moves and the stock is non-empty.
+#[test]
+fn all_hints_suggests_draw_when_no_moves_and_stock_nonempty() {
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+
+    // Remove all foundation, tableau, and waste cards so no pile-to-pile
+    // move exists. Leave one card in the stock.
+    clear_test_piles(&mut game);
+    // Put one card back into the stock so "draw" is a valid suggestion.
+    game.set_test_stock_cards(vec![Card::new(D::Deck1, Suit::Clubs, Rank::Ace)]);
+
+    let hints = all_hints(&game);
+    assert_eq!(hints.len(), 1, "exactly one hint: draw from stock");
+    let (from, to) = &hints[0];
+    assert_eq!(*from, KlondikePile::Stock, "hint must come from Stock");
+    assert_eq!(*to, KlondikePile::Stock, "hint must point to Waste");
+}
+
+// `all_hints` must be empty when both stock and waste are empty and no
+// pile-to-pile move exists — the game is truly stuck.
+// -----------------------------------------------------------------------
+// Drag-rejection return tween — `CardAnimation` replaces the legacy
+// `ShakeAnim` on the dragged cards. The audio cue
+// (`card_invalid.wav` via `MoveRejectedEvent`) is unchanged; only the
+// visual response on the dragged cards swapped from a horizontal wiggle
+// to a smooth ease-out glide back to the origin pile.
+//
+// These tests build the component values exactly as `end_drag` and
+// `touch_end_drag` would, then assert the resulting `CardAnimation` is
+// shaped correctly. Driving `end_drag` end-to-end requires a real window
+// and mouse-button input, so we exercise the data path the same way the
+// legacy `ShakeAnim` tests did.
+// -----------------------------------------------------------------------
+
+/// Helper: build the `CardAnimation` the rejection paths construct for
+/// one dragged card. Mirrors the inline logic in `end_drag` and
+/// `touch_end_drag` so the tests stay in sync with the production code.
+fn build_drag_reject_animation(
+    drag_pos: Vec2,
+    drag_z: f32,
+    target_pos: Vec2,
+    stack_index: usize,
+) -> CardAnimation {
+    let end_z = 1.0 + (stack_index as f32) * STACK_FAN_FRAC;
+    CardAnimation::slide(drag_pos, drag_z, target_pos, end_z, MotionCurve::Responsive)
+        .with_duration(MOTION_DRAG_REJECT_SECS)
+}
+
+/// Every card in `drag.cards` should receive its own `CardAnimation` on
+/// rejection. With the shake → tween migration, the assertion changes
+/// from "every dragged card gets a ShakeAnim" to "every dragged card
+/// gets a CardAnimation" — same coverage, new component.
+#[test]
+fn rejected_drag_inserts_card_animation_on_each_dragged_card() {
+    use solitaire_core::Deck as D;
+    use solitaire_core::{Card, Rank, Suit};
+    // Simulate a stack drag of two cards.
+    let dragged_cards: Vec<Card> = vec![
+        Card::new(D::Deck1, Suit::Hearts, Rank::King),
+        Card::new(D::Deck1, Suit::Spades, Rank::Queen),
+    ];
+
+    let mut animated: Vec<Card> = Vec::new();
+    for card in &dragged_cards {
+        // In `end_drag` we iterate `drag.cards` and look up each card in
+        // `card_entities`. The cards we would insert a `CardAnimation` on
+        // must exactly match the dragged set.
+        animated.push(card.clone());
+    }
+
+    assert_eq!(
+        animated, dragged_cards,
+        "every card in drag.cards must receive a CardAnimation on rejection"
+    );
+}
+
+/// The `end` field of the inserted tween must equal the card's resting
+/// slot in its origin pile — the position the card belongs at after a
+/// rejected drop. Without this, the tween would glide to the wrong spot
+/// and `sync_cards` would have to fight it back.
+#[test]
+fn rejected_drag_animation_targets_origin_resting_position() {
+    let drag_pos = Vec2::new(640.0, 200.0); // somewhere mid-screen
+    let target_pos = Vec2::new(123.5, -50.0); // origin pile slot
+    let anim =
+        build_drag_reject_animation(drag_pos, DRAG_Z, target_pos, /* stack_index */ 3);
+
+    assert!(
+        (anim.end - target_pos).length() < 1e-6,
+        "CardAnimation.end must match the origin slot's resting position. \
+         Expected {target_pos:?}, got {:?}",
+        anim.end
+    );
+}
+
+/// The `start` field of the inserted tween must equal the card's
+/// drop-time transform position — i.e. wherever the cursor or finger
+/// released the card. This is what makes the glide feel like a
+/// continuous return rather than a teleport-then-shake.
+#[test]
+fn rejected_drag_animation_starts_from_drag_position() {
+    let drag_pos = Vec2::new(640.0, 200.0);
+    let target_pos = Vec2::new(80.0, -120.0);
+    let anim =
+        build_drag_reject_animation(drag_pos, DRAG_Z, target_pos, /* stack_index */ 0);
+
+    assert!(
+        (anim.start - drag_pos).length() < 1e-6,
+        "CardAnimation.start must match the drop-time transform position \
+         (where the cursor released). Expected {drag_pos:?}, got {:?}",
+        anim.start
+    );
+    // And the start must be visibly distinct from the origin slot — the
+    // whole point of the tween is that it visibly travels.
+    assert!(
+        (anim.start - anim.end).length() > 1.0,
+        "rejected drag should travel a visible distance, got start={:?} end={:?}",
+        anim.start,
+        anim.end
+    );
+}
+
+/// The tween duration is taken from the project-wide motion token so
+/// designers can retune the feel from one place. Keeps the constant and
+/// the call site honest.
+#[test]
+fn rejected_drag_animation_uses_correct_duration() {
+    let anim = build_drag_reject_animation(
+        Vec2::new(640.0, 200.0),
+        DRAG_Z,
+        Vec2::new(80.0, -120.0),
+        0,
+    );
+    assert!(
+        (anim.duration - MOTION_DRAG_REJECT_SECS).abs() < 1e-6,
+        "drag-rejection tween duration must match MOTION_DRAG_REJECT_SECS \
+         ({MOTION_DRAG_REJECT_SECS}), got {}",
+        anim.duration
+    );
+}
+
+/// The curve must be a no-overshoot ease-out so the card decelerates
+/// cleanly into its rest position — overshoot on a rejection feels
+/// jittery rather than forgiving.
+#[test]
+fn rejected_drag_animation_uses_responsive_curve() {
+    let anim = build_drag_reject_animation(
+        Vec2::new(640.0, 200.0),
+        DRAG_Z,
+        Vec2::new(80.0, -120.0),
+        0,
+    );
+    assert_eq!(
+        anim.curve,
+        MotionCurve::Responsive,
+        "drag-rejection tween must use Responsive (quintic ease-out) \
+         so the card snaps back without bouncing past the slot"
+    );
+}
+
+/// The `start_z` of the tween must equal the card's drop-time z
+/// (`DRAG_Z`) so the card stays above the rest of the table while it
+/// travels home, then settles at the correct resting z.
+#[test]
+fn rejected_drag_animation_lifts_from_drag_z_to_resting_z() {
+    let stack_index = 2_usize;
+    let anim = build_drag_reject_animation(
+        Vec2::new(640.0, 200.0),
+        DRAG_Z,
+        Vec2::new(80.0, -120.0),
+        stack_index,
+    );
+    assert!(
+        (anim.start_z - DRAG_Z).abs() < 1e-6,
+        "tween must start at DRAG_Z so the card stays on top during the glide"
+    );
+    let expected_end_z = 1.0 + (stack_index as f32) * STACK_FAN_FRAC;
+    assert!(
+        (anim.end_z - expected_end_z).abs() < 1e-6,
+        "tween must end at the slot's resting z, got {} expected {expected_end_z}",
+        anim.end_z
+    );
+}
+
+// -----------------------------------------------------------------------
+// Hint system — async port (v0.18.0+)
+//
+// `handle_keyboard_hint` no longer runs the solver inline; it
+// spawns an `AsyncComputeTaskPool` task whose result the polling
+// system in `pending_hint` turns into hint visuals one frame
+// later. The behaviour contract this section pins is "pressing H
+// populates `PendingHintTask`" — the spawn-to-emit pipeline is
+// covered end-to-end in `pending_hint::tests`.
+// -----------------------------------------------------------------------
+
+/// Pressing H on a non-paused, non-won game with a live
+/// `GameStateResource` + `LayoutResource` must populate
+/// `PendingHintTask`. The polling system, exercised in
+/// `pending_hint::tests`, drives the result to a visual event.
+#[test]
+fn pressing_h_spawns_pending_hint_task() {
+    let mut app = App::new();
+    app.add_plugins(MinimalPlugins);
+    app.add_message::<InfoToastEvent>();
+    app.add_message::<HintVisualEvent>();
+    app.init_resource::<HintCycleIndex>();
+    app.init_resource::<HintSolverConfig>();
+    app.init_resource::<crate::pending_hint::PendingHintTask>();
+    app.init_resource::<ButtonInput<KeyCode>>();
+    app.insert_resource(LayoutResource(
+        compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true),
+    ));
+    app.insert_resource(GameStateResource(GameState::new(42, DrawStockConfig::DrawOne)));
+    app.add_systems(Update, handle_keyboard_hint);
+
+    // Simulate the H key being pressed this frame.
+    {
+        let mut input = app.world_mut().resource_mut::<ButtonInput<KeyCode>>();
+        input.release(KeyCode::KeyH);
+        input.clear();
+        input.press(KeyCode::KeyH);
+    }
+    app.update();
+
+    assert!(
+        app.world()
+            .resource::<crate::pending_hint::PendingHintTask>()
+            .is_pending(),
+        "pressing H must spawn an async hint task",
+    );
+}
@@ -7,7 +7,8 @@ use std::collections::HashMap;

 use bevy::math::Vec2;
 use bevy::prelude::{Resource, SystemSet};
-use solitaire_core::pile::PileType;
+use solitaire_core::game_state::GameState;
+use solitaire_core::{Foundation, KlondikePile, Tableau};

 /// Schedule labels for layout-related systems so cross-plugin ordering is
 /// explicit instead of relying on Bevy's automatic resource-conflict ordering
@@ -91,6 +92,15 @@ const TABLEAU_FACEDOWN_FAN_FRAC: f32 = 0.14;
 /// this column inside the visible window.
 const MAX_TABLEAU_CARDS: f32 = 13.0;

+/// Upper bound for the dynamic tableau fan step (fraction of card height) chosen
+/// by [`apply_dynamic_tableau_fan`]. The fan is spread to fill the available
+/// height, but a near-empty column has tiny demand, so without a cap its few
+/// cards would fling far apart on a tall viewport. At 0.6 the face-up cards keep
+/// clear overlap (a readable stack) while still filling most of a near-square /
+/// unfolded-foldable screen. Tunable purely for feel — no effect on correctness
+/// or hit-testing.
+pub(crate) const MAX_DYNAMIC_FAN_FRAC: f32 = 0.9;
+
 /// Vertical pixel band reserved at the top of the play area for the HUD
 /// (action buttons, Score / Moves / Timer readouts). The card grid starts
 /// below this band so the HUD doesn't bleed into the play surface.
@@ -138,9 +148,9 @@ pub struct Layout {
    /// Centre position of each pile, in 2D world coordinates.
    ///
    /// World origin `(0, 0)` is the window centre; `+x` is right, `+y` is up.
-    /// Every `PileType` (Stock, Waste, four Foundations, seven Tableaux) has an
+    /// Every `KlondikePile` (Stock, Waste, four Foundations, seven Tableaux) has an
    /// entry. The map always contains exactly 13 entries after `compute_layout`.
-    pub pile_positions: HashMap<PileType, Vec2>,
+    pub pile_positions: HashMap<KlondikePile, Vec2>,
    /// Per-step vertical offset fraction for face-up tableau cards, as a
    /// fraction of `card_size.y`. On height-limited (desktop) windows this
    /// equals `TABLEAU_FAN_FRAC` (0.18); on width-limited (portrait phone)
@@ -241,30 +251,46 @@ pub fn compute_layout(
    let top_y = window.y / 2.0 - safe_area_top - band_h - h_gap - card_height / 2.0;
    let tableau_y = top_y - card_height - vertical_gap;

-    let mut pile_positions: HashMap<PileType, Vec2> = HashMap::with_capacity(13);
+    let mut pile_positions: HashMap<KlondikePile, Vec2> = HashMap::with_capacity(13);

-    pile_positions.insert(PileType::Stock, Vec2::new(col_x(0), top_y));
-    pile_positions.insert(PileType::Waste, Vec2::new(col_x(1), top_y));
+    pile_positions.insert(KlondikePile::Stock, Vec2::new(col_x(1), top_y));

    // Column 2 is skipped — visual separation between waste and foundations.
    for slot in 0..4_u8 {
+        let foundation = match slot {
+            0 => Foundation::Foundation1,
+            1 => Foundation::Foundation2,
+            2 => Foundation::Foundation3,
+            _ => Foundation::Foundation4,
+        };
        pile_positions.insert(
-            PileType::Foundation(slot),
+            KlondikePile::Foundation(foundation),
            Vec2::new(col_x(3 + slot as usize), top_y),
        );
    }

    for i in 0..7 {
-        pile_positions.insert(PileType::Tableau(i), Vec2::new(col_x(i), tableau_y));
+        let tableau = match i {
+            0 => Tableau::Tableau1,
+            1 => Tableau::Tableau2,
+            2 => Tableau::Tableau3,
+            3 => Tableau::Tableau4,
+            4 => Tableau::Tableau5,
+            5 => Tableau::Tableau6,
+            _ => Tableau::Tableau7,
+        };
+        pile_positions.insert(
+            KlondikePile::Tableau(tableau),
+            Vec2::new(col_x(i), tableau_y),
+        );
    }

-    // Adaptive tableau fan fraction. On height-limited (desktop) windows the
-    // height-based sizing already ensures a worst-case 13-card column fits at
-    // TABLEAU_FAN_FRAC (0.25), so the formula returns ≈0.25 and the clamp
-    // keeps it there — no change from prior behaviour. On width-limited
-    // (portrait phone) windows card_size is small and lots of vertical space
-    // is unused; we solve for the fraction that exactly fills the available
-    // space to the bottom margin.
+    // Adaptive tableau fan fraction. On height-limited windows the height-based
+    // sizing already ensures a worst-case 13-card column fits at TABLEAU_FAN_FRAC,
+    // so the formula returns the minimum and the clamp keeps it there. On
+    // width-limited (portrait phone) windows card_size is small and lots of
+    // vertical space is unused; solve for the fraction that fills the available
+    // space. `apply_dynamic_tableau_fan` later refines this for the actual deal.
    //
    // avail = distance from the top of the first tableau card to the bottom
    //         margin — i.e. the space available for 12 fan steps.
@@ -275,20 +301,87 @@ pub fn compute_layout(
    } else {
        TABLEAU_FAN_FRAC
    };
-    // Never go below the desktop minimum — avoids shrinking the fan on
-    // degenerate near-square windows where the formula might undershoot.
    let tableau_fan_frac = ideal_fan_frac.max(TABLEAU_FAN_FRAC);
-    // Scale the face-down fraction proportionally so rendering and hit-testing
-    // stay in sync (TABLEAU_FACEDOWN_FAN_FRAC / TABLEAU_FAN_FRAC = 0.48 ratio).
    let facedown_scale = TABLEAU_FACEDOWN_FAN_FRAC / TABLEAU_FAN_FRAC;
    let tableau_facedown_fan_frac = tableau_fan_frac * facedown_scale;
+    let available_tableau_height = avail;

    Layout {
        card_size,
        pile_positions,
        tableau_fan_frac,
        tableau_facedown_fan_frac,
-        available_tableau_height: avail,
+        available_tableau_height,
+    }
+}
+
+/// Spread the tableau fan so the deepest column fills the available vertical
+/// height for the *current* deal, mutating `layout.tableau_fan_frac` and its
+/// face-down companion in place.
+///
+/// `compute_layout` is pure geometry and sizes the fan for a worst-case 13-card
+/// column, so early in a game (shallow columns) a tall or near-square viewport
+/// — e.g. an unfolded foldable — is left with a large empty band below the
+/// tableau. This refines the fan once the actual deal is known.
+///
+/// Depth is measured across *all* cards in a column, each face-down card
+/// weighted 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, where the deepest column is several face-down cards under one face-up
+/// one. Deeper columns drive the fraction down so everything still fits;
+/// [`TABLEAU_FAN_FRAC`] floors it and [`MAX_DYNAMIC_FAN_FRAC`] caps it.
+///
+/// Called from card-sync at startup and on every `StateChangedEvent`, and from
+/// the resize pipeline after `compute_layout`, so the cold-start deal, ongoing
+/// play, and fold/unfold all stay filled. `card_position` / `card_positions`
+/// read the same fractions, so rendering and hit-testing remain in sync.
+pub(crate) fn apply_dynamic_tableau_fan(game: &GameState, layout: &mut Layout) {
+    let card_h = layout.card_size.y;
+    let avail = layout.available_tableau_height;
+    if card_h <= 0.0 {
+        return;
+    }
+
+    let facedown_ratio = TABLEAU_FACEDOWN_FAN_FRAC / TABLEAU_FAN_FRAC;
+
+    // "Step demand" of a column: the vertical offset of its bottom card from its
+    // top card, in units of the face-up fan step. Every card except the last
+    // contributes one step, weighted down to `facedown_ratio` while face-down.
+    let max_demand = [
+        Tableau::Tableau1,
+        Tableau::Tableau2,
+        Tableau::Tableau3,
+        Tableau::Tableau4,
+        Tableau::Tableau5,
+        Tableau::Tableau6,
+        Tableau::Tableau7,
+    ]
+    .into_iter()
+    .map(|tableau| {
+        let pile = game.pile(KlondikePile::Tableau(tableau));
+        let steps = pile.len().saturating_sub(1);
+        pile.iter()
+            .take(steps)
+            .map(|(_, face_up)| if *face_up { 1.0 } else { facedown_ratio })
+            .sum::<f32>()
+    })
+    .fold(0.0_f32, f32::max);
+
+    // No fannable column (every tableau pile has ≤ 1 card) — leave the fractions
+    // at the values compute_layout set.
+    if max_demand <= 0.0 {
+        return;
+    }
+
+    let ideal = avail / (max_demand * card_h);
+    let new_frac = ideal.clamp(TABLEAU_FAN_FRAC, MAX_DYNAMIC_FAN_FRAC);
+    let new_facedown_frac = new_frac * facedown_ratio;
+
+    if (layout.tableau_fan_frac - new_frac).abs() > 1e-4 {
+        layout.tableau_fan_frac = new_frac;
+    }
+    if (layout.tableau_facedown_fan_frac - new_facedown_frac).abs() > 1e-4 {
+        layout.tableau_facedown_fan_frac = new_facedown_frac;
    }
 }

@@ -301,23 +394,37 @@ mod tests {
    use super::*;

    fn assert_all_piles_present(layout: &Layout) {
-        assert!(layout.pile_positions.contains_key(&PileType::Stock));
-        assert!(layout.pile_positions.contains_key(&PileType::Waste));
-        for slot in 0..4_u8 {
+        assert!(layout.pile_positions.contains_key(&KlondikePile::Stock));
+        for foundation in [
+            Foundation::Foundation1,
+            Foundation::Foundation2,
+            Foundation::Foundation3,
+            Foundation::Foundation4,
+        ] {
            assert!(
                layout
                    .pile_positions
-                    .contains_key(&PileType::Foundation(slot)),
-                "missing foundation slot {slot}",
+                    .contains_key(&KlondikePile::Foundation(foundation)),
+                "missing foundation slot {foundation:?}",
            );
        }
-        for i in 0..7 {
+        for tableau in [
+            Tableau::Tableau1,
+            Tableau::Tableau2,
+            Tableau::Tableau3,
+            Tableau::Tableau4,
+            Tableau::Tableau5,
+            Tableau::Tableau6,
+            Tableau::Tableau7,
+        ] {
            assert!(
-                layout.pile_positions.contains_key(&PileType::Tableau(i)),
-                "missing tableau {i}"
+                layout
+                    .pile_positions
+                    .contains_key(&KlondikePile::Tableau(tableau)),
+                "missing tableau {tableau:?}"
            );
        }
-        assert_eq!(layout.pile_positions.len(), 13);
+        assert_eq!(layout.pile_positions.len(), 12);
    }

    #[test]
@@ -376,9 +483,18 @@ mod tests {
    #[test]
    fn tableau_columns_are_sorted_left_to_right() {
        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-        for i in 0..6 {
-            let lhs = layout.pile_positions[&PileType::Tableau(i)].x;
-            let rhs = layout.pile_positions[&PileType::Tableau(i + 1)].x;
+        let tableaus = [
+            Tableau::Tableau1,
+            Tableau::Tableau2,
+            Tableau::Tableau3,
+            Tableau::Tableau4,
+            Tableau::Tableau5,
+            Tableau::Tableau6,
+            Tableau::Tableau7,
+        ];
+        for i in 0..tableaus.len() - 1 {
+            let lhs = layout.pile_positions[&KlondikePile::Tableau(tableaus[i])].x;
+            let rhs = layout.pile_positions[&KlondikePile::Tableau(tableaus[i + 1])].x;
            assert!(lhs < rhs, "tableau {i} should be left of tableau {}", i + 1);
        }
    }
@@ -386,8 +502,8 @@ mod tests {
    #[test]
    fn top_row_is_above_tableau_row() {
        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-        let stock_y = layout.pile_positions[&PileType::Stock].y;
-        let tableau_y = layout.pile_positions[&PileType::Tableau(0)].y;
+        let stock_y = layout.pile_positions[&KlondikePile::Stock].y;
+        let tableau_y = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau1)].y;
        assert!(stock_y > tableau_y);
    }

@@ -399,7 +515,7 @@ mod tests {
    fn top_row_clears_hud_band() {
        let window = Vec2::new(1280.0, 800.0);
        let layout = compute_layout(window, 0.0, 0.0, true);
-        let stock_y = layout.pile_positions[&PileType::Stock].y;
+        let stock_y = layout.pile_positions[&KlondikePile::Stock].y;
        let card_top = stock_y + layout.card_size.y / 2.0;
        let band_bottom = window.y / 2.0 - HUD_BAND_HEIGHT;
        assert!(
@@ -411,24 +527,35 @@ mod tests {
    #[test]
    fn stock_aligns_with_tableau_col_0_and_waste_with_col_1() {
        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-        let stock_x = layout.pile_positions[&PileType::Stock].x;
-        let waste_x = layout.pile_positions[&PileType::Waste].x;
-        let t0_x = layout.pile_positions[&PileType::Tableau(0)].x;
-        let t1_x = layout.pile_positions[&PileType::Tableau(1)].x;
-        assert!((stock_x - t0_x).abs() < 1e-5);
-        assert!((waste_x - t1_x).abs() < 1e-5);
+        let stock_x = layout.pile_positions[&KlondikePile::Stock].x;
+        let t1_x = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau2)].x;
+        assert!((stock_x - t1_x).abs() < 1e-5);
    }

    #[test]
    fn foundations_align_with_tableau_cols_3_to_6() {
        let layout = compute_layout(Vec2::new(1280.0, 800.0), 0.0, 0.0, true);
-        for slot in 0..4_u8 {
-            let f_x = layout.pile_positions[&PileType::Foundation(slot)].x;
-            let t_x = layout.pile_positions[&PileType::Tableau(3 + slot as usize)].x;
+        let target_tableaus = [
+            Tableau::Tableau4,
+            Tableau::Tableau5,
+            Tableau::Tableau6,
+            Tableau::Tableau7,
+        ];
+        for (idx, foundation) in [
+            Foundation::Foundation1,
+            Foundation::Foundation2,
+            Foundation::Foundation3,
+            Foundation::Foundation4,
+        ]
+        .iter()
+        .enumerate()
+        {
+            let f_x = layout.pile_positions[&KlondikePile::Foundation(*foundation)].x;
+            let t_x = layout.pile_positions[&KlondikePile::Tableau(target_tableaus[idx])].x;
            assert!(
                (f_x - t_x).abs() < 1e-5,
-                "foundation slot {slot} should align with tableau {}",
-                3 + slot as usize,
+                "foundation slot {idx} should align with tableau {}",
+                3 + idx,
            );
        }
    }
@@ -470,7 +597,7 @@ mod tests {
        // Default app resolution (see solitaire_app/src/main.rs).
        let window = Vec2::new(1280.0, 800.0);
        let layout = compute_layout(window, 0.0, 0.0, true);
-        let tableau_y = layout.pile_positions[&PileType::Tableau(6)].y;
+        let tableau_y = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau7)].y;
        let card_h = layout.card_size.y;
        // Bottom edge of the 13th fanned face-up card.
        let bottom_edge = tableau_y - 12.0 * card_h * TABLEAU_FAN_FRAC - card_h / 2.0;
@@ -489,7 +616,7 @@ mod tests {
        // The bug originally reproduced at 1920x1080. Lock in a regression test.
        let window = Vec2::new(1920.0, 1080.0);
        let layout = compute_layout(window, 0.0, 0.0, true);
-        let tableau_y = layout.pile_positions[&PileType::Tableau(6)].y;
+        let tableau_y = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau7)].y;
        let card_h = layout.card_size.y;
        let bottom_edge = tableau_y - 12.0 * card_h * TABLEAU_FAN_FRAC - card_h / 2.0;
        let h_gap = layout.card_size.x / 4.0;
@@ -520,7 +647,7 @@ mod tests {
    fn expanded_fan_fits_phone_viewport() {
        let window = Vec2::new(360.0, 800.0);
        let layout = compute_layout(window, 0.0, 0.0, true);
-        let tableau_y = layout.pile_positions[&PileType::Tableau(0)].y;
+        let tableau_y = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau1)].y;
        let card_h = layout.card_size.y;
        let h_gap = layout.card_size.x / 4.0;
        // Bottom of the 13th (worst-case) fanned face-up card.
@@ -579,8 +706,8 @@ mod tests {
        let window = Vec2::new(360.0, 800.0);
        let without = compute_layout(window, 0.0, 0.0, true);
        let with_inset = compute_layout(window, 32.0, 0.0, true);
-        let stock_no_inset = without.pile_positions[&PileType::Stock].y;
-        let stock_with_inset = with_inset.pile_positions[&PileType::Stock].y;
+        let stock_no_inset = without.pile_positions[&KlondikePile::Stock].y;
+        let stock_with_inset = with_inset.pile_positions[&KlondikePile::Stock].y;
        assert!(
            stock_with_inset < stock_no_inset,
            "safe_area_top=32 must shift stock pile down (y decreased): {} → {}",
@@ -602,10 +729,10 @@ mod tests {
        let without = compute_layout(window, 0.0, 0.0, true);
        let with_inset = compute_layout(window, 32.0, 0.0, true);
        for pile in [
-            PileType::Stock,
-            PileType::Waste,
-            PileType::Tableau(0),
-            PileType::Tableau(6),
+            KlondikePile::Stock,
+            KlondikePile::Stock,
+            KlondikePile::Tableau(Tableau::Tableau1),
+            KlondikePile::Tableau(Tableau::Tableau7),
        ] {
            assert!(
                (without.pile_positions[&pile].x - with_inset.pile_positions[&pile].x).abs() < 1e-3,
@@ -628,7 +755,7 @@ mod tests {
            with_inset.tableau_fan_frac,
        );
        let card_h = with_inset.card_size.y;
-        let tableau_y = with_inset.pile_positions[&PileType::Tableau(6)].y;
+        let tableau_y = with_inset.pile_positions[&KlondikePile::Tableau(Tableau::Tableau7)].y;
        let bottom_edge = tableau_y - 12.0 * card_h * with_inset.tableau_fan_frac - card_h / 2.0;
        let h_gap = with_inset.card_size.x / 4.0;
        let margin = -window.y / 2.0 + 48.0 + h_gap;
@@ -661,8 +788,8 @@ mod tests {

        // Verify the "wrong" layout actually differs — the bug would push the
        // top card row upward by exactly safe_top pixels.
-        let fresh_stock_y = fresh.pile_positions[&PileType::Stock].y;
-        let wrong_stock_y = wrong.pile_positions[&PileType::Stock].y;
+        let fresh_stock_y = fresh.pile_positions[&KlondikePile::Stock].y;
+        let wrong_stock_y = wrong.pile_positions[&KlondikePile::Stock].y;
        // In Bevy's +y-is-up system, adding safe_area_top pushes the stock
        // downward (−y direction).  So wrong_stock_y > fresh_stock_y by safe_top.
        assert!(
@@ -680,22 +807,22 @@ mod tests {
            "card size must be preserved after resume",
        );
        assert!(
-            (corrected.pile_positions[&PileType::Stock].y - fresh_stock_y).abs() < 1e-3,
+            (corrected.pile_positions[&KlondikePile::Stock].y - fresh_stock_y).abs() < 1e-3,
            "stock y must match fresh launch after resume: \
             corrected={:.2} fresh={fresh_stock_y:.2}",
-            corrected.pile_positions[&PileType::Stock].y,
+            corrected.pile_positions[&KlondikePile::Stock].y,
        );
        assert!(
-            (corrected.pile_positions[&PileType::Stock].x
-                - fresh.pile_positions[&PileType::Stock].x)
+            (corrected.pile_positions[&KlondikePile::Stock].x
+                - fresh.pile_positions[&KlondikePile::Stock].x)
                .abs()
                < 1e-3,
            "stock x must be unchanged after resume",
        );
        // The HUD band top clearance (distance from window top to card top)
        // must match as well — this is the quantity directly visible in Bug 2.
-        let card_top = |layout: &super::Layout| {
-            layout.pile_positions[&PileType::Stock].y + layout.card_size.y / 2.0
+        let card_top = |layout: &Layout| {
+            layout.pile_positions[&KlondikePile::Stock].y + layout.card_size.y / 2.0
        };
        assert!(
            (card_top(&corrected) - card_top(&fresh)).abs() < 1e-3,
@@ -712,7 +839,11 @@ mod tests {
        let window = Vec2::new(360.0, 800.0);
        let without = compute_layout(window, 0.0, 0.0, true);
        let with_inset = compute_layout(window, 0.0, 48.0, true);
-        for pile in [PileType::Stock, PileType::Tableau(0), PileType::Tableau(6)] {
+        for pile in [
+            KlondikePile::Stock,
+            KlondikePile::Tableau(Tableau::Tableau1),
+            KlondikePile::Tableau(Tableau::Tableau7),
+        ] {
            assert!(
                (without.pile_positions[&pile].x - with_inset.pile_positions[&pile].x).abs() < 1e-3,
                "{pile:?} x-position must not change with safe_area_bottom",
@@ -191,6 +191,7 @@ fn toggle_leaderboard_screen(
    keys: Res<ButtonInput<KeyCode>>,
    mut requests: MessageReader<ToggleLeaderboardRequestEvent>,
    screens: Query<Entity, With<LeaderboardScreen>>,
+    other_modal_scrims: Query<(), (With<ModalScrim>, Without<LeaderboardScreen>)>,
    data: Res<LeaderboardResource>,
    provider: Option<Res<SyncProviderResource>>,
    settings: Option<Res<SettingsResource>>,
@@ -208,6 +209,11 @@ fn toggle_leaderboard_screen(
        return;
    }

+    // Don't stack a second modal scrim over one that is already open.
+    if !other_modal_scrims.is_empty() {
+        return;
+    }
+
    // Spawn the panel immediately with whatever data we have so far.
    let remote_available = provider
        .as_ref()
@@ -856,7 +862,7 @@ fn handle_display_name_confirm(
                .leaderboard_display_name
                .clone()
                .unwrap_or_else(|| {
-                    if let solitaire_data::settings::SyncBackend::SolitaireServer {
+                    if let SyncBackend::SolitaireServer {
                        ref username,
                        ..
                    } = settings.0.sync_backend
@@ -1085,7 +1091,7 @@ mod tests {
            .add_plugins(crate::achievement_plugin::AchievementPlugin::headless())
            .add_plugins(SyncPlugin::new(NoOpProvider))
            .add_plugins(LeaderboardPlugin);
-        app.init_resource::<bevy::input::ButtonInput<KeyCode>>();
+        app.init_resource::<ButtonInput<KeyCode>>();
        app.update();
        app
    }
@@ -1,13 +1,16 @@
 //! Bevy integration layer for Ferrous Solitaire.

 pub mod achievement_plugin;
+#[cfg(not(target_arch = "wasm32"))]
 pub mod analytics_plugin;
 #[cfg(target_os = "android")]
 pub mod android_clipboard;
 pub mod animation_plugin;
 pub mod assets;
+#[cfg(not(target_arch = "wasm32"))]
 pub mod audio_plugin;
 pub mod auto_complete_plugin;
+#[cfg(not(target_arch = "wasm32"))]
 pub mod avatar_plugin;
 pub mod card_animation;
 pub mod card_plugin;
@@ -26,6 +29,7 @@ pub mod home_plugin;
 pub mod hud_plugin;
 pub mod input_plugin;
 pub mod layout;
+#[cfg(not(target_arch = "wasm32"))]
 pub mod leaderboard_plugin;
 pub mod onboarding_plugin;
 pub mod pause_plugin;
@@ -43,7 +47,9 @@ pub mod selection_plugin;
 pub mod settings_plugin;
 pub mod splash_plugin;
 pub mod stats_plugin;
+#[cfg(not(target_arch = "wasm32"))]
 pub mod sync_plugin;
+#[cfg(not(target_arch = "wasm32"))]
 pub mod sync_setup_plugin;
 pub mod table_plugin;
 pub mod theme;
@@ -57,14 +63,17 @@ pub mod weekly_goals_plugin;
 pub mod win_summary_plugin;

 pub use achievement_plugin::{AchievementPlugin, AchievementsResource, AchievementsScreen};
+#[cfg(not(target_arch = "wasm32"))]
 pub use analytics_plugin::{AnalyticsPlugin, AnalyticsResource};
 pub use animation_plugin::{ActiveToast, AnimationPlugin, CardAnim, ToastEntity, ToastQueue};
 pub use assets::{
    AssetSourcesPlugin, DARK_THEME_MANIFEST_URL, USER_THEMES, bundled_theme_url,
    populate_embedded_dark_theme, register_theme_asset_sources,
 };
+#[cfg(not(target_arch = "wasm32"))]
 pub use audio_plugin::{AudioPlugin, AudioState, SoundLibrary};
 pub use auto_complete_plugin::AutoCompletePlugin;
+#[cfg(not(target_arch = "wasm32"))]
 pub use avatar_plugin::{AvatarFetchEvent, AvatarPlugin, AvatarResource};
 pub use card_animation::{
    AnimationChain, AnimationTuning, BufferedInput, CardAnimation, CardAnimationPlugin,
@@ -117,6 +126,7 @@ pub use hud_plugin::{
 };
 pub use input_plugin::InputPlugin;
 pub use layout::{Layout, LayoutResource, compute_layout};
+#[cfg(not(target_arch = "wasm32"))]
 pub use leaderboard_plugin::{LeaderboardPlugin, LeaderboardResource, LeaderboardScreen};
 pub use onboarding_plugin::{OnboardingPlugin, OnboardingScreen};
 pub use pause_plugin::{ForfeitConfirmScreen, PausePlugin, PauseScreen, PausedResource};
@@ -143,7 +153,6 @@ pub use safe_area::{SafeAreaAnchoredTop, SafeAreaInsets, SafeAreaInsetsPlugin};
 pub use selection_plugin::{
    KeyboardDragState, SelectionHighlight, SelectionPlugin, SelectionState,
 };
-pub use touch_selection_plugin::{TouchSelectionPlugin, TouchSelectionState};
 pub use settings_plugin::{
    PendingWindowGeometry, SFX_STEP, SettingsChangedEvent, SettingsPlugin, SettingsResource,
    SettingsScreen, WINDOW_GEOMETRY_DEBOUNCE_SECS,
@@ -155,7 +164,9 @@ pub use stats_plugin::{
    ReplaySelectorCaption, SelectedReplayIndex, StatsPlugin, StatsResource, StatsScreen,
    StatsUpdate, WatchReplayButton, format_replay_caption,
 };
+#[cfg(not(target_arch = "wasm32"))]
 pub use sync_plugin::{SyncPlugin, SyncProviderResource};
+#[cfg(not(target_arch = "wasm32"))]
 pub use sync_setup_plugin::SyncSetupPlugin;
 pub use table_plugin::{
    BackgroundImageSet, HintPileHighlight, PileMarker, TableBackground, TablePlugin,
@@ -167,6 +178,7 @@ pub use theme::{
 pub use time_attack_plugin::{
    TIME_ATTACK_DURATION_SECS, TimeAttackEndedEvent, TimeAttackPlugin, TimeAttackResource,
 };
+pub use touch_selection_plugin::{TouchSelectionPlugin, TouchSelectionState};
 pub use ui_focus::{Disabled, FocusGroup, Focusable, FocusedButton, UiFocusPlugin};
 pub use ui_modal::{
    ButtonVariant, ModalActions, ModalBody, ModalButton, ModalCard, ModalHeader, ModalScrim,
@@ -36,6 +36,7 @@ use crate::ui_theme::{
    BORDER_SUBTLE, HighContrastBorder, RADIUS_SM, TEXT_PRIMARY, TYPE_BODY, TYPE_CAPTION,
    VAL_SPACE_1, VAL_SPACE_2, VAL_SPACE_3,
 };
+use crate::splash_plugin::SplashRoot;
 use crate::ui_theme::{TEXT_SECONDARY, Z_ONBOARDING};

 // ---------------------------------------------------------------------------
@@ -153,7 +154,7 @@ pub struct OnboardingPlugin;
 impl Plugin for OnboardingPlugin {
    fn build(&self, app: &mut App) {
        app.init_resource::<OnboardingSlideIndex>()
-            .add_systems(PostStartup, spawn_if_first_run)
+            .add_systems(Update, spawn_if_first_run)
            .add_systems(
                Update,
                (handle_onboarding_buttons, handle_onboarding_keyboard).chain(),
@@ -170,11 +171,30 @@ fn spawn_if_first_run(
    settings: Option<Res<SettingsResource>>,
    font_res: Option<Res<FontResource>>,
    mut slide_index: ResMut<OnboardingSlideIndex>,
+    splashes: Query<(), With<SplashRoot>>,
+    existing: Query<(), With<OnboardingScreen>>,
+    mut spawned: Local<bool>,
 ) {
-    let Some(s) = settings else { return };
-    if s.0.first_run_complete {
+    if *spawned {
        return;
    }
+    // Wait until the launch splash has despawned so the two screens
+    // never overlap. PostStartup would fire before the first Update
+    // tick, guaranteeing overlap; checking here costs one frame of
+    // latency after the splash clears, which is imperceptible.
+    if !splashes.is_empty() {
+        return;
+    }
+    if !existing.is_empty() {
+        *spawned = true;
+        return;
+    }
+    let Some(s) = settings else { return };
+    if s.0.first_run_complete {
+        *spawned = true;
+        return;
+    }
+    *spawned = true;
    slide_index.0 = 0;
    spawn_slide(&mut commands, 0, font_res.as_deref());
 }
@@ -21,7 +21,7 @@
 //! active opens the overlay as normal.

 use bevy::prelude::*;
-use solitaire_core::game_state::DrawMode;
+use solitaire_core::DrawStockConfig;
 use solitaire_data::save_game_state_to;

 use crate::events::{
@@ -86,10 +86,10 @@ struct ForfeitConfirmButton;
 /// Returns the human-readable label for a draw mode.
 ///
 /// Used on the pause overlay draw-mode toggle button.
-pub fn draw_mode_label(mode: DrawMode) -> &'static str {
+pub fn draw_mode_label(mode: DrawStockConfig) -> &'static str {
    match mode {
-        DrawMode::DrawOne => "Draw 1",
-        DrawMode::DrawThree => "Draw 3",
+        DrawStockConfig::DrawOne => "Draw 1",
+        DrawStockConfig::DrawThree => "Draw 3",
    }
 }

@@ -273,9 +273,9 @@ fn handle_pause_draw_buttons(
    }
    let Some(mut settings) = settings else { return };
    let new_mode = if pressed_one {
-        DrawMode::DrawOne
+        DrawStockConfig::DrawOne
    } else {
-        DrawMode::DrawThree
+        DrawStockConfig::DrawThree
    };
    if settings.0.draw_mode == new_mode {
        return;
@@ -340,7 +340,7 @@ fn handle_forfeit_request(
    if !forfeit_screens.is_empty() {
        return;
    }
-    let game_in_progress = game.as_ref().is_some_and(|g| !g.0.is_won);
+    let game_in_progress = game.as_ref().is_some_and(|g| !g.0.is_won());
    if !game_in_progress {
        toast.write(InfoToastEvent("No game to forfeit".to_string()));
        return;
@@ -477,7 +477,7 @@ fn spawn_pause_screen(
    commands: &mut Commands,
    level: Option<u32>,
    streak: Option<u32>,
-    draw_mode: Option<DrawMode>,
+    draw_mode: Option<DrawStockConfig>,
    font_res: Option<&FontResource>,
 ) {
    spawn_modal(commands, PauseScreen, ui_theme::Z_PAUSE, |card| {
@@ -516,7 +516,7 @@ fn spawn_pause_screen(
 /// `Tertiary` (recessed), giving an obvious selection state at a glance.
 fn spawn_draw_mode_row(
    parent: &mut ChildSpawnerCommands,
-    mode: DrawMode,
+    mode: DrawStockConfig,
    font_res: Option<&FontResource>,
 ) {
    let label_font = TextFont {
@@ -530,8 +530,8 @@ fn spawn_draw_mode_row(
        ..default()
    };
    let (one_variant, three_variant) = match mode {
-        DrawMode::DrawOne => (ButtonVariant::Secondary, ButtonVariant::Tertiary),
-        DrawMode::DrawThree => (ButtonVariant::Tertiary, ButtonVariant::Secondary),
+        DrawStockConfig::DrawOne => (ButtonVariant::Secondary, ButtonVariant::Tertiary),
+        DrawStockConfig::DrawThree => (ButtonVariant::Tertiary, ButtonVariant::Secondary),
    };
    parent
        .spawn(Node {
@@ -800,20 +800,20 @@ mod tests {

    #[test]
    fn draw_mode_label_draw_one() {
-        assert_eq!(draw_mode_label(DrawMode::DrawOne), "Draw 1");
+        assert_eq!(draw_mode_label(DrawStockConfig::DrawOne), "Draw 1");
    }

    #[test]
    fn draw_mode_label_draw_three() {
-        assert_eq!(draw_mode_label(DrawMode::DrawThree), "Draw 3");
+        assert_eq!(draw_mode_label(DrawStockConfig::DrawThree), "Draw 3");
    }

    /// Both variants are covered so the match is exhaustive — this test would
-    /// fail to compile if a new DrawMode variant were added without updating
+    /// fail to compile if a new DrawStockConfig variant were added without updating
    /// `draw_mode_label`.
    #[test]
    fn draw_mode_label_covers_all_variants() {
-        for mode in [DrawMode::DrawOne, DrawMode::DrawThree] {
+        for mode in [DrawStockConfig::DrawOne, DrawStockConfig::DrawThree] {
            let label = draw_mode_label(mode);
            assert!(
                !label.is_empty(),
@@ -842,7 +842,7 @@ mod tests {
        app.world_mut()
            .resource_mut::<SettingsResource>()
            .0
-            .draw_mode = DrawMode::DrawOne;
+            .draw_mode = DrawStockConfig::DrawOne;

        // Set paused so handle_pause_draw_toggle acts.
        app.world_mut().resource_mut::<PausedResource>().0 = true;
@@ -856,7 +856,7 @@ mod tests {
        let mode = &app.world().resource::<SettingsResource>().0.draw_mode;
        assert_eq!(
            *mode,
-            DrawMode::DrawThree,
+            DrawStockConfig::DrawThree,
            "pressing Draw 3 must set mode to DrawThree"
        );

@@ -869,7 +869,7 @@ mod tests {
        let mode2 = &app.world().resource::<SettingsResource>().0.draw_mode;
        assert_eq!(
            *mode2,
-            DrawMode::DrawOne,
+            DrawStockConfig::DrawOne,
            "pressing Draw 1 must set mode to DrawOne"
        );

@@ -965,11 +965,11 @@ mod tests {
    /// Provides a fresh `GameStateResource` (not won) so the modal can
    /// open. `move_count` doesn't matter — the gate is just `!is_won`.
    fn forfeit_app() -> App {
-        use solitaire_core::game_state::{DrawMode, GameState};
+        use solitaire_core::{DrawStockConfig, game_state::GameState};
        let mut app = App::new();
        app.add_plugins(MinimalPlugins).add_plugins(PausePlugin);
        app.init_resource::<ButtonInput<KeyCode>>();
-        app.insert_resource(GameStateResource(GameState::new(1, DrawMode::DrawOne)));
+        app.insert_resource(GameStateResource(GameState::new(1, DrawStockConfig::DrawOne)));
        app.update();
        app
    }
@@ -1020,12 +1020,12 @@ mod tests {
    /// hotkey was received but is currently a no-op.
    #[test]
    fn forfeit_request_emits_toast_and_skips_modal_when_game_is_won() {
-        use solitaire_core::game_state::{DrawMode, GameState};
+        use solitaire_core::{DrawStockConfig, game_state::GameState};
        let mut app = App::new();
        app.add_plugins(MinimalPlugins).add_plugins(PausePlugin);
        app.init_resource::<ButtonInput<KeyCode>>();
-        let mut game = GameState::new(1, DrawMode::DrawOne);
-        game.is_won = true;
+        let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+        game.set_test_won(true);
        app.insert_resource(GameStateResource(game));
        app.update();

@@ -1,12 +1,10 @@
 //! Async H-key hint solver, modelled on `PendingNewGameSeed` in
 //! `game_plugin`.
 //!
-//! The synchronous version (v0.17.0) called
-//! `solitaire_core::solver::try_solve_from_state` on the main thread on
-//! every H press. Median latency was ~2 ms but pathological positions
-//! can hit the `SolverConfig::default()` cap at ~120 ms, which is a
-//! noticeable input-stall on the same frame the player sees the hint
-//! request.
+//! The synchronous version (v0.17.0) called the solver on the main thread
+//! on every H press. Median latency was ~2 ms but pathological positions
+//! can hit the default solve budget at ~120 ms, which is a noticeable
+//! input-stall on the same frame the player sees the hint request.
 //!
 //! This module hosts the resource and polling system that move the
 //! solver call onto `AsyncComputeTaskPool`. `handle_keyboard_hint`
@@ -26,13 +24,12 @@

 use bevy::prelude::*;
 use bevy::tasks::{AsyncComputeTaskPool, Task, futures_lite::future};
+use solitaire_core::KlondikeInstruction;
 use solitaire_core::game_state::GameState;
-use solitaire_core::pile::PileType;
-use solitaire_core::solver::{SolverConfig, SolverResult, try_solve_from_state};

 use crate::card_plugin::CardEntity;
 use crate::events::{HintVisualEvent, InfoToastEvent, StateChangedEvent};
-use crate::input_plugin::{emit_hint_visuals, find_heuristic_hint};
+use crate::input_plugin::{emit_hint_visuals, find_heuristic_hint, hint_piles};
 use crate::resources::{GameStateResource, HintCycleIndex};

 /// In-flight async work for the H-key hint.
@@ -60,23 +57,17 @@ impl PendingHintTask {
        self.inner = None;
    }

-    /// Spawn a new solver task for `state` with `config`. Drops any
-    /// previously in-flight task first (cancel-on-replace).
-    pub fn spawn(&mut self, state: GameState, config: SolverConfig) {
-        let move_count_at_spawn = state.move_count;
+    /// Spawn a new solver task for `state` with the given solve budgets.
+    /// Drops any previously in-flight task first (cancel-on-replace).
+    pub fn spawn(&mut self, state: GameState, moves_budget: u64, states_budget: u64) {
+        let move_count_at_spawn = state.move_count();
        let handle = AsyncComputeTaskPool::get().spawn(async move {
-            let outcome = try_solve_from_state(&state, &config);
-            match outcome.result {
-                SolverResult::Winnable => outcome
-                    .first_move
-                    .map(|mv| HintTaskOutput::SolverMove {
-                        from: mv.source,
-                        to: mv.dest,
-                    })
-                    .unwrap_or(HintTaskOutput::NeedsHeuristic),
-                SolverResult::Unwinnable | SolverResult::Inconclusive => {
-                    HintTaskOutput::NeedsHeuristic
-                }
+            // Winnable (`Ok(Some)`) carries the first move on a winning path;
+            // unwinnable (`Ok(None)`) and inconclusive (`Err`) both fall back
+            // to the live-state heuristic so H always produces feedback.
+            match state.solve_first_move(moves_budget, states_budget) {
+                Ok(Some(first_move)) => HintTaskOutput::SolverMove(first_move),
+                Ok(None) | Err(_) => HintTaskOutput::NeedsHeuristic,
            }
        });
        self.inner = Some(HintTask {
@@ -99,9 +90,10 @@ struct HintTask {

 /// What the solver task carries back to the main thread.
 enum HintTaskOutput {
-    /// Solver verdict was `Winnable`; here is the first move on the
-    /// solution path.
-    SolverMove { from: PileType, to: PileType },
+    /// Solver verdict was winnable; here is the first move on the solution
+    /// path. Converted to highlighted `(from, to)` piles by the poll system
+    /// via [`crate::input_plugin::hint_piles`].
+    SolverMove(KlondikeInstruction),
    /// Solver was `Unwinnable` or `Inconclusive`. The poll system
    /// runs the legacy heuristic against the live `GameState` so the
    /// H key always produces feedback while any legal move exists.
@@ -153,19 +145,22 @@ pub fn poll_pending_hint_task(
    pending.inner = None;

    let Some(g) = game else { return };
-    if g.0.move_count != move_count_at_spawn {
+    if g.0.move_count() != move_count_at_spawn {
        return;
    }

-    let (from, to) = match output {
-        HintTaskOutput::SolverMove { from, to } => (from, to),
-        HintTaskOutput::NeedsHeuristic => match find_heuristic_hint(&g.0, &mut hint_cycle) {
-            Some(pair) => pair,
-            None => {
-                info_toast.write(InfoToastEvent("No hints available".to_string()));
-                return;
-            }
-        },
+    // Resolve the solver's first move to highlighted piles; fall back to the
+    // live-state heuristic when there's no solver move or it maps to a no-op.
+    let solver_pair = match output {
+        HintTaskOutput::SolverMove(instruction) => hint_piles(&g.0, instruction),
+        HintTaskOutput::NeedsHeuristic => None,
+    };
+    let (from, to) = match solver_pair.or_else(|| find_heuristic_hint(&g.0, &mut hint_cycle)) {
+        Some(pair) => pair,
+        None => {
+            info_toast.write(InfoToastEvent("No hints available".to_string()));
+            return;
+        }
    };
    emit_hint_visuals(
        &g.0,
@@ -183,8 +178,9 @@ mod tests {
    use super::*;
    use crate::events::HintVisualEvent;
    use crate::input_plugin::HintSolverConfig;
-    use solitaire_core::card::{Card, Rank, Suit};
-    use solitaire_core::game_state::{DrawMode, GameState};
+    use solitaire_core::{Foundation, KlondikePile, Tableau};
+    use solitaire_core::{Card, Deck, Rank, Suit};
+    use solitaire_core::{DrawStockConfig, game_state::GameState};

    /// Build a minimal Bevy app exercising only the polling system
    /// and the resources/messages it touches.
@@ -213,23 +209,28 @@ mod tests {
    /// foundations hold A..Q for each suit, four Kings sit on
    /// tableau columns 0..3, stock and waste empty.
    fn near_finished_state() -> GameState {
-        let mut game = GameState::new(1, DrawMode::DrawOne);
-        for slot in 0..4_u8 {
-            game.piles
-                .get_mut(&PileType::Foundation(slot))
-                .unwrap()
-                .cards
-                .clear();
+        let mut game = GameState::new(1, DrawStockConfig::DrawOne);
+        game.set_test_stock_cards(Vec::new());
+        game.set_test_waste_cards(Vec::new());
+        for foundation in [
+            Foundation::Foundation1,
+            Foundation::Foundation2,
+            Foundation::Foundation3,
+            Foundation::Foundation4,
+        ] {
+            game.set_test_foundation_cards(foundation, Vec::new());
        }
-        for i in 0..7_usize {
-            game.piles
-                .get_mut(&PileType::Tableau(i))
-                .unwrap()
-                .cards
-                .clear();
+        for tableau in [
+            Tableau::Tableau1,
+            Tableau::Tableau2,
+            Tableau::Tableau3,
+            Tableau::Tableau4,
+            Tableau::Tableau5,
+            Tableau::Tableau6,
+            Tableau::Tableau7,
+        ] {
+            game.set_test_tableau_cards(tableau, Vec::new());
        }
-        game.piles.get_mut(&PileType::Stock).unwrap().cards.clear();
-        game.piles.get_mut(&PileType::Waste).unwrap().cards.clear();
        let suits = [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades];
        let ranks_below_king = [
            Rank::Ace,
@@ -245,31 +246,34 @@ mod tests {
            Rank::Jack,
            Rank::Queen,
        ];
-        for (slot, suit) in suits.iter().enumerate() {
-            let pile = game
-                .piles
-                .get_mut(&PileType::Foundation(slot as u8))
-                .unwrap();
-            for (i, rank) in ranks_below_king.iter().enumerate() {
-                pile.cards.push(Card {
-                    id: (slot as u32) * 13 + i as u32,
-                    suit: *suit,
-                    rank: *rank,
-                    face_up: true,
-                });
+        for (foundation, suit) in [
+            Foundation::Foundation1,
+            Foundation::Foundation2,
+            Foundation::Foundation3,
+            Foundation::Foundation4,
+        ]
+        .into_iter()
+        .zip(suits.iter())
+        {
+            let mut cards = Vec::new();
+            for rank in ranks_below_king.iter() {
+                cards.push(Card::new(Deck::Deck1, *suit, *rank));
            }
+            game.set_test_foundation_cards(foundation, cards);
        }
-        for (col, suit) in suits.iter().enumerate() {
-            game.piles
-                .get_mut(&PileType::Tableau(col))
-                .unwrap()
-                .cards
-                .push(Card {
-                    id: 100 + col as u32,
-                    suit: *suit,
-                    rank: Rank::King,
-                    face_up: true,
-                });
+        for (tableau, suit) in [
+            Tableau::Tableau1,
+            Tableau::Tableau2,
+            Tableau::Tableau3,
+            Tableau::Tableau4,
+        ]
+        .into_iter()
+        .zip(suits.iter())
+        {
+            game.set_test_tableau_cards(
+                tableau,
+                vec![Card::new(Deck::Deck1, *suit, Rank::King)],
+            );
        }
        game
    }
@@ -283,10 +287,10 @@ mod tests {
    fn winnable_solver_emits_hint_after_async_completes() {
        let mut app = pending_hint_app();
        app.insert_resource(GameStateResource(near_finished_state()));
-        let cfg = app.world().resource::<HintSolverConfig>().0;
+        let cfg = *app.world().resource::<HintSolverConfig>();
        app.world_mut()
            .resource_mut::<PendingHintTask>()
-            .spawn(near_finished_state(), cfg);
+            .spawn(near_finished_state(), cfg.moves_budget, cfg.states_budget);

        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(15);
        while app.world().resource::<PendingHintTask>().is_pending() {
@@ -309,7 +313,7 @@ mod tests {
            "exactly one HintVisualEvent must fire when the solver returns Winnable",
        );
        assert!(
-            matches!(collected[0].dest_pile, PileType::Foundation(_)),
+            matches!(collected[0].dest_pile, KlondikePile::Foundation(_)),
            "solver hint destination must be a foundation slot; got {:?}",
            collected[0].dest_pile,
        );
@@ -322,10 +326,10 @@ mod tests {
    fn state_change_drops_in_flight_task() {
        let mut app = pending_hint_app();
        app.insert_resource(GameStateResource(near_finished_state()));
-        let cfg = app.world().resource::<HintSolverConfig>().0;
+        let cfg = *app.world().resource::<HintSolverConfig>();
        app.world_mut()
            .resource_mut::<PendingHintTask>()
-            .spawn(near_finished_state(), cfg);
+            .spawn(near_finished_state(), cfg.moves_budget, cfg.states_budget);
        assert!(
            app.world().resource::<PendingHintTask>().is_pending(),
            "task is in flight after spawn",
@@ -358,12 +362,12 @@ mod tests {
    fn second_spawn_drops_first_in_flight_task() {
        let mut app = pending_hint_app();
        app.insert_resource(GameStateResource(near_finished_state()));
-        let cfg = app.world().resource::<HintSolverConfig>().0;
+        let cfg = *app.world().resource::<HintSolverConfig>();

        // First spawn.
        app.world_mut()
            .resource_mut::<PendingHintTask>()
-            .spawn(near_finished_state(), cfg);
+            .spawn(near_finished_state(), cfg.moves_budget, cfg.states_budget);
        let first_handle_present = app.world().resource::<PendingHintTask>().is_pending();
        assert!(first_handle_present);

@@ -372,7 +376,7 @@ mod tests {
        // in flight.
        app.world_mut()
            .resource_mut::<PendingHintTask>()
-            .spawn(near_finished_state(), cfg);
+            .spawn(near_finished_state(), cfg.moves_budget, cfg.states_budget);
        // Resource still pending (the second task), but the first
        // is gone. We can't directly observe the first handle once
        // it's been overwritten — what we *can* assert is that the
@@ -11,7 +11,7 @@
 //! 3. `handle_text_input` appends decimal digits / handles Backspace while
 //!    the modal is open, updating [`SeedInputBuffer`] each frame.
 //! 4. `tick_debounce_and_spawn_solver_task` waits for 12 frames (~200 ms at
-//!    60 Hz) of no input before spawning a [`try_solve`] task on
+//!    60 Hz) of no input before spawning a [`GameState::solve_fresh_deal`] task on
 //!    [`AsyncComputeTaskPool`]. Any fresh keypress drops the in-flight task
 //!    by resetting the resource.
 //! 5. `poll_solver_task` polls the in-flight task each frame and updates the
@@ -23,8 +23,9 @@
 use bevy::input::ButtonInput;
 use bevy::prelude::*;
 use bevy::tasks::{AsyncComputeTaskPool, Task, futures_lite::future};
-use solitaire_core::game_state::DrawMode;
-use solitaire_core::solver::{SolverConfig, SolverResult, try_solve};
+use solitaire_core::DrawStockConfig;
+use solitaire_core::game_state::GameState;
+use solitaire_core::{DEFAULT_SOLVE_MOVES_BUDGET, DEFAULT_SOLVE_STATES_BUDGET, SolveOutcome};

 use crate::events::{NewGameRequestEvent, StartPlayBySeedRequestEvent};
 use crate::font_plugin::FontResource;
@@ -83,7 +84,7 @@ struct SeedInputDisplay;
 #[derive(Resource, Default)]
 struct PendingVerification {
    seed: Option<u64>,
-    handle: Option<Task<SolverResult>>,
+    handle: Option<Task<SolveOutcome>>,
 }

 // ---------------------------------------------------------------------------
@@ -339,9 +340,15 @@ fn tick_debounce_and_spawn_solver_task(

    let draw_mode = settings
        .as_ref()
-        .map_or(DrawMode::DrawOne, |s| s.0.draw_mode);
-    let cfg = SolverConfig::default();
-    let task = AsyncComputeTaskPool::get().spawn(async move { try_solve(seed, draw_mode, &cfg) });
+        .map_or(DrawStockConfig::DrawOne, |s| s.0.draw_mode);
+    let task = AsyncComputeTaskPool::get().spawn(async move {
+        GameState::solve_fresh_deal(
+            seed,
+            draw_mode,
+            DEFAULT_SOLVE_MOVES_BUDGET,
+            DEFAULT_SOLVE_STATES_BUDGET,
+        )
+    });

    pending.seed = Some(seed);
    pending.handle = Some(task);
@@ -369,15 +376,15 @@ fn poll_solver_task(
        return;
    };
    match result {
-        SolverResult::Winnable => {
+        Ok(Some(_)) => {
            text.0 = "\u{2713} Provably winnable".to_string();
            color.0 = ACCENT_PRIMARY;
        }
-        SolverResult::Inconclusive => {
+        Err(_) => {
            text.0 = "? Likely winnable (search timed out)".to_string();
            color.0 = TEXT_SECONDARY;
        }
-        SolverResult::Unwinnable => {
+        Ok(None) => {
            text.0 = "\u{2717} Provably unwinnable".to_string();
            color.0 = TEXT_DISABLED;
        }
@@ -12,7 +12,11 @@ use solitaire_core::achievement::{ALL_ACHIEVEMENTS, achievement_by_id};
 use solitaire_data::SyncBackend;

 use crate::achievement_plugin::AchievementsResource;
+#[cfg(not(target_arch = "wasm32"))]
 use crate::avatar_plugin::AvatarResource;
+#[cfg(target_arch = "wasm32")]
+#[derive(bevy::prelude::Resource)]
+struct AvatarResource(Option<bevy::prelude::Handle<bevy::prelude::Image>>);
 use crate::events::ToggleProfileRequestEvent;
 use crate::font_plugin::FontResource;
 use crate::progress_plugin::ProgressResource;
@@ -88,7 +88,7 @@ fn award_xp_on_win(
    mut progress: ResMut<ProgressResource>,
 ) {
    for ev in wins.read() {
-        let used_undo = game.0.undo_count > 0;
+        let used_undo = game.0.undo_count() > 0;
        let amount = xp_for_win(ev.time_seconds, used_undo);
        let prev_level = progress.0.add_xp(amount);
        xp_awarded.write(XpAwardedEvent { amount });
@@ -151,7 +151,7 @@ mod tests {
        app.world_mut()
            .resource_mut::<GameStateResource>()
            .0
-            .undo_count = 1;
+            .force_test_undos(1);

        app.world_mut().write_message(GameWonEvent {
            score: 500,
@@ -47,13 +47,12 @@ use bevy::input::touch::Touches;
 use bevy::math::Vec2;
 use bevy::prelude::*;
 use bevy::window::PrimaryWindow;
-use solitaire_core::card::Card;
+use solitaire_core::{Foundation, KlondikePile, Tableau};
+use solitaire_core::Card;
 use solitaire_core::game_state::GameState;
-use solitaire_core::pile::PileType;
-use solitaire_core::rules::{can_place_on_foundation, can_place_on_tableau};

 use crate::card_plugin::TABLEAU_FACEDOWN_FAN_FRAC;
-use crate::events::MoveRequestEvent;
+use crate::events::{MoveRejectedEvent, MoveRequestEvent};
 use crate::layout::{Layout, LayoutResource, TABLEAU_FAN_FRAC};
 use crate::pause_plugin::PausedResource;
 use crate::resources::{DragState, GameStateResource};
@@ -108,22 +107,22 @@ pub enum RightClickRadialState {
    /// `hovered_index` (or none).
    Active {
        /// Pile the right-clicked card came from.
-        source_pile: PileType,
+        source_pile: KlondikePile,
        /// Number of cards that would be moved (always `1` — only the
        /// top face-up card is ever offered for a quick-drop, since the
        /// radial is built around single-card foundation/tableau
        /// shortcuts and that matches the right-click highlight set).
        count: usize,
-        /// Card ids that would be moved (bottom-to-top order). Length
+        /// Cards that would be moved (bottom-to-top order). Length
        /// always equals `count`. Currently always one element.
-        cards: Vec<u32>,
+        cards: Vec<Card>,
        /// Pre-computed `(destination, icon_anchor_world_pos)` pairs.
        ///
        /// Anchors are evenly spaced around a ring of radius
        /// [`RADIAL_RADIUS_PX`] centred on the press position. A single
        /// destination is placed directly above the cursor; multiple
        /// destinations span an arc.
-        legal_destinations: Vec<(PileType, Vec2)>,
+        legal_destinations: Vec<(KlondikePile, Vec2)>,
        /// Cursor position (world space) the radial was opened at —
        /// used as the centre of the ring for cursor-hover hit testing.
        centre: Vec2,
@@ -250,30 +249,20 @@ pub fn radial_hovered_index(cursor: Vec2, anchors: &[Vec2]) -> Option<usize> {
 /// that legally accept the card. The source pile is excluded because
 /// dropping a card on its own pile is a no-op.
 pub fn legal_destinations_for_card(
-    card: &Card,
-    source_pile: &PileType,
+    _card: &Card,
+    source_pile: &KlondikePile,
    game: &GameState,
-) -> Vec<PileType> {
+) -> Vec<KlondikePile> {
    let mut out = Vec::new();
-    for slot in 0..4_u8 {
-        let dest = PileType::Foundation(slot);
-        if dest == *source_pile {
-            continue;
-        }
-        if let Some(pile) = game.piles.get(&dest)
-            && can_place_on_foundation(card, pile)
-        {
+    for foundation in foundations() {
+        let dest = KlondikePile::Foundation(foundation);
+        if game.can_move_cards(source_pile, &dest, 1) {
            out.push(dest);
        }
    }
-    for i in 0..7_usize {
-        let dest = PileType::Tableau(i);
-        if dest == *source_pile {
-            continue;
-        }
-        if let Some(pile) = game.piles.get(&dest)
-            && can_place_on_tableau(card, pile)
-        {
+    for tableau in tableaus() {
+        let dest = KlondikePile::Tableau(tableau);
+        if game.can_move_cards(source_pile, &dest, 1) {
            out.push(dest);
        }
    }
@@ -292,36 +281,34 @@ pub fn find_top_face_up_card_at(
    cursor: Vec2,
    game: &GameState,
    layout: &Layout,
-) -> Option<(PileType, Card)> {
+) -> Option<(KlondikePile, Card)> {
    let piles = [
-        PileType::Waste,
-        PileType::Foundation(0),
-        PileType::Foundation(1),
-        PileType::Foundation(2),
-        PileType::Foundation(3),
-        PileType::Tableau(0),
-        PileType::Tableau(1),
-        PileType::Tableau(2),
-        PileType::Tableau(3),
-        PileType::Tableau(4),
-        PileType::Tableau(5),
-        PileType::Tableau(6),
+        KlondikePile::Stock,
+        KlondikePile::Foundation(Foundation::Foundation1),
+        KlondikePile::Foundation(Foundation::Foundation2),
+        KlondikePile::Foundation(Foundation::Foundation3),
+        KlondikePile::Foundation(Foundation::Foundation4),
+        KlondikePile::Tableau(Tableau::Tableau1),
+        KlondikePile::Tableau(Tableau::Tableau2),
+        KlondikePile::Tableau(Tableau::Tableau3),
+        KlondikePile::Tableau(Tableau::Tableau4),
+        KlondikePile::Tableau(Tableau::Tableau5),
+        KlondikePile::Tableau(Tableau::Tableau6),
+        KlondikePile::Tableau(Tableau::Tableau7),
    ];
    for pile in piles {
-        let Some(pile_cards) = game.piles.get(&pile) else {
-            continue;
-        };
-        if pile_cards.cards.is_empty() {
+        let pile_cards = pile_cards(game, &pile);
+        if pile_cards.is_empty() {
            continue;
        }
-        let is_tableau = matches!(pile, PileType::Tableau(_));
-        for i in (0..pile_cards.cards.len()).rev() {
-            let card = &pile_cards.cards[i];
-            if !card.face_up {
+        let is_tableau = matches!(pile, KlondikePile::Tableau(_));
+        for i in (0..pile_cards.len()).rev() {
+            let card = &pile_cards[i];
+            if !card.1 {
                continue;
            }
            // Only the top card is draggable on non-tableau piles.
-            if !is_tableau && i != pile_cards.cards.len() - 1 {
+            if !is_tableau && i != pile_cards.len() - 1 {
                continue;
            }
            let pos = card_position(game, layout, &pile, i);
@@ -333,7 +320,7 @@ pub fn find_top_face_up_card_at(
            {
                continue;
            }
-            return Some((pile, card.clone()));
+            return Some((pile, card.0.clone()));
        }
    }
    None
@@ -342,19 +329,22 @@ pub fn find_top_face_up_card_at(
 /// Mirror of `input_plugin::card_position` — kept private to this
 /// module so the radial's hit-test geometry tracks renderer geometry
 /// without depending on `input_plugin` internals.
-fn card_position(game: &GameState, layout: &Layout, pile: &PileType, stack_index: usize) -> Vec2 {
+fn card_position(
+    game: &GameState,
+    layout: &Layout,
+    pile: &KlondikePile,
+    stack_index: usize,
+) -> Vec2 {
    let base = layout.pile_positions[pile];
-    if matches!(pile, PileType::Tableau(_)) {
+    if matches!(pile, KlondikePile::Tableau(_)) {
        let mut y_offset = 0.0_f32;
-        if let Some(pile_cards) = game.piles.get(pile) {
-            for card in pile_cards.cards.iter().take(stack_index) {
-                let step = if card.face_up {
-                    TABLEAU_FAN_FRAC
-                } else {
-                    TABLEAU_FACEDOWN_FAN_FRAC
-                };
-                y_offset -= layout.card_size.y * step;
-            }
+        for card in pile_cards(game, pile).iter().take(stack_index) {
+            let step = if card.1 {
+                TABLEAU_FAN_FRAC
+            } else {
+                TABLEAU_FACEDOWN_FAN_FRAC
+            };
+            y_offset -= layout.card_size.y * step;
        }
        Vec2::new(base.x, base.y + y_offset)
    } else {
@@ -362,17 +352,57 @@ fn card_position(game: &GameState, layout: &Layout, pile: &PileType, stack_index
    }
 }

+fn pile_cards(game: &GameState, pile: &KlondikePile) -> Vec<(Card, bool)> {
+    match pile {
+        KlondikePile::Stock => game.waste_cards(),
+        _ => game.pile(*pile),
+    }
+}
+
+
+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.
-fn build_radial_destinations(centre: Vec2, dests: Vec<PileType>) -> Vec<(PileType, Vec2)> {
+///
+/// `half_extents` is the window half-size in world space — icons are clamped
+/// so that their edges stay within the viewport, preventing them from appearing
+/// off-screen on small or narrow devices.
+fn build_radial_destinations(
+    centre: Vec2,
+    dests: Vec<KlondikePile>,
+    half_extents: Vec2,
+) -> Vec<(KlondikePile, Vec2)> {
    let count = dests.len();
+    let margin = RADIAL_ICON_SIZE_PX / 2.0;
    dests
        .into_iter()
        .enumerate()
        .map(|(i, d)| {
-            (
-                d,
-                radial_anchor_for_index(centre, count, i, RADIAL_RADIUS_PX),
-            )
+            let raw = radial_anchor_for_index(centre, count, i, RADIAL_RADIUS_PX);
+            let clamped = Vec2::new(
+                raw.x.clamp(-half_extents.x + margin, half_extents.x - margin),
+                raw.y.clamp(-half_extents.y + margin, half_extents.y - margin),
+            );
+            (d, clamped)
        })
        .collect()
 }
@@ -407,9 +437,10 @@ fn cursor_world(
 // ---------------------------------------------------------------------------

 /// On `MouseButton::Right` `just_pressed`, attempts to open the radial
-/// menu over the card the cursor is on. Skips when a left-mouse drag is
-/// in progress, when the game is paused, or when the clicked card has no
-/// legal destinations.
+/// menu over the card the cursor is on. When the cursor is on a face-up
+/// card but no legal destinations exist, fires `MoveRejectedEvent` so the
+/// shake animation and invalid-move sound play. Skips silently when no
+/// card is under the cursor, when a drag is in progress, or when paused.
 #[allow(clippy::too_many_arguments)]
 fn radial_open_on_right_click(
    buttons: Option<Res<ButtonInput<MouseButton>>>,
@@ -421,6 +452,7 @@ fn radial_open_on_right_click(
    layout: Option<Res<LayoutResource>>,
    game: Option<Res<GameStateResource>>,
    mut state: ResMut<RightClickRadialState>,
+    mut rejected: MessageWriter<MoveRejectedEvent>,
 ) {
    if paused.is_some_and(|p| p.0) {
        return;
@@ -449,14 +481,25 @@ fn radial_open_on_right_click(
    // cards and the highlight tint shows the same set the radial offers.
    let dests = legal_destinations_for_card(&card, &source_pile, &game.0);
    if dests.is_empty() {
+        // No legal destinations — shake the source pile as feedback.
+        rejected.write(MoveRejectedEvent {
+            from: source_pile,
+            to: source_pile,
+            count: 1,
+        });
        return;
    }
-    let legal_destinations = build_radial_destinations(world, dests);
+    let half_extents = windows
+        .single()
+        .ok()
+        .map(|w| Vec2::new(w.width() / 2.0, w.height() / 2.0))
+        .unwrap_or(Vec2::splat(f32::MAX));
+    let legal_destinations = build_radial_destinations(world, dests, half_extents);

    *state = RightClickRadialState::Active {
        source_pile,
        count: 1,
-        cards: vec![card.id],
+        cards: vec![card.clone()],
        legal_destinations,
        centre: world,
        hovered_index: None,
@@ -477,6 +520,7 @@ fn radial_open_on_long_press(
    drag: Res<DragState>,
    paused: Option<Res<PausedResource>>,
    touches: Option<Res<Touches>>,
+    windows: Query<&Window, With<PrimaryWindow>>,
    cameras: Query<(&Camera, &GlobalTransform)>,
    layout: Option<Res<LayoutResource>>,
    game: Option<Res<GameStateResource>>,
@@ -519,11 +563,16 @@ fn radial_open_on_long_press(
    if dests.is_empty() {
        return;
    }
-    let legal_destinations = build_radial_destinations(world, dests);
+    let half_extents = windows
+        .single()
+        .ok()
+        .map(|w| Vec2::new(w.width() / 2.0, w.height() / 2.0))
+        .unwrap_or(Vec2::splat(f32::MAX));
+    let legal_destinations = build_radial_destinations(world, dests, half_extents);
    *state = RightClickRadialState::Active {
        source_pile,
        count: 1,
-        cards: vec![card.id],
+        cards: vec![card.clone()],
        legal_destinations,
        centre: world,
        hovered_index: None,
@@ -609,8 +658,8 @@ fn radial_handle_release_or_cancel(
        && let Some((dest, _)) = legal_destinations.get(*idx)
    {
        moves.write(MoveRequestEvent {
-            from: source_pile.clone(),
-            to: dest.clone(),
+            from: *source_pile,
+            to: *dest,
            count: *count,
        });
    }
@@ -746,8 +795,8 @@ mod tests {
    use super::*;
    use crate::layout::compute_layout;
    use bevy::ecs::message::Messages;
-    use solitaire_core::card::{Card as CoreCard, Rank, Suit};
-    use solitaire_core::game_state::{DrawMode, GameState};
+    use solitaire_core::{Card as CoreCard, Deck, Rank, Suit};
+    use solitaire_core::{DrawStockConfig, game_state::GameState};

    /// Build a minimal Bevy app wired with `RadialMenuPlugin` and the
    /// resources / messages it depends on. No window, no camera — the
@@ -756,6 +805,7 @@ mod tests {
        let mut app = App::new();
        app.add_plugins(MinimalPlugins);
        app.add_message::<MoveRequestEvent>();
+        app.add_message::<MoveRejectedEvent>();
        app.init_resource::<DragState>();
        app.init_resource::<ButtonInput<MouseButton>>();
        app.init_resource::<ButtonInput<KeyCode>>();
@@ -769,68 +819,66 @@ mod tests {
    /// destination — Foundation(0) — under the standard rules
    /// (`can_place_on_foundation` accepts the Ace on an empty foundation).
    fn ace_only_state() -> GameState {
-        let mut g = GameState::new(0, DrawMode::DrawOne);
+        let mut g = GameState::new(0, DrawStockConfig::DrawOne);
        // Wipe everything.
-        g.piles.get_mut(&PileType::Stock).unwrap().cards.clear();
-        g.piles.get_mut(&PileType::Waste).unwrap().cards.clear();
-        for slot in 0..4_u8 {
-            g.piles
-                .get_mut(&PileType::Foundation(slot))
-                .unwrap()
-                .cards
-                .clear();
+        g.set_test_stock_cards(Vec::new());
+        g.set_test_waste_cards(Vec::new());
+        for foundation in [
+            Foundation::Foundation1,
+            Foundation::Foundation2,
+            Foundation::Foundation3,
+            Foundation::Foundation4,
+        ] {
+            g.set_test_foundation_cards(foundation, Vec::new());
        }
-        for i in 0..7_usize {
-            g.piles
-                .get_mut(&PileType::Tableau(i))
-                .unwrap()
-                .cards
-                .clear();
+        for tableau in [
+            Tableau::Tableau1,
+            Tableau::Tableau2,
+            Tableau::Tableau3,
+            Tableau::Tableau4,
+            Tableau::Tableau5,
+            Tableau::Tableau6,
+            Tableau::Tableau7,
+        ] {
+            g.set_test_tableau_cards(tableau, Vec::new());
        }
        // Ace of Clubs on Tableau(0).
-        g.piles
-            .get_mut(&PileType::Tableau(0))
-            .unwrap()
-            .cards
-            .push(CoreCard {
-                id: 100,
-                suit: Suit::Clubs,
-                rank: Rank::Ace,
-                face_up: true,
-            });
+        g.set_test_tableau_cards(
+            Tableau::Tableau1,
+            vec![CoreCard::new(Deck::Deck1, Suit::Clubs, Rank::Ace)],
+        );
        g
    }

    /// Place a face-down King on Tableau(0). `find_top_face_up_card_at`
    /// must skip it.
    fn face_down_only_state() -> GameState {
-        let mut g = GameState::new(0, DrawMode::DrawOne);
-        g.piles.get_mut(&PileType::Stock).unwrap().cards.clear();
-        g.piles.get_mut(&PileType::Waste).unwrap().cards.clear();
-        for slot in 0..4_u8 {
-            g.piles
-                .get_mut(&PileType::Foundation(slot))
-                .unwrap()
-                .cards
-                .clear();
+        let mut g = GameState::new(0, DrawStockConfig::DrawOne);
+        g.set_test_stock_cards(Vec::new());
+        g.set_test_waste_cards(Vec::new());
+        for foundation in [
+            Foundation::Foundation1,
+            Foundation::Foundation2,
+            Foundation::Foundation3,
+            Foundation::Foundation4,
+        ] {
+            g.set_test_foundation_cards(foundation, Vec::new());
        }
-        for i in 0..7_usize {
-            g.piles
-                .get_mut(&PileType::Tableau(i))
-                .unwrap()
-                .cards
-                .clear();
+        for tableau in [
+            Tableau::Tableau1,
+            Tableau::Tableau2,
+            Tableau::Tableau3,
+            Tableau::Tableau4,
+            Tableau::Tableau5,
+            Tableau::Tableau6,
+            Tableau::Tableau7,
+        ] {
+            g.set_test_tableau_cards(tableau, Vec::new());
        }
-        g.piles
-            .get_mut(&PileType::Tableau(0))
-            .unwrap()
-            .cards
-            .push(CoreCard {
-                id: 100,
-                suit: Suit::Spades,
-                rank: Rank::King,
-                face_up: false,
-            });
+        g.set_test_tableau_cards_with_face(
+            Tableau::Tableau1,
+            vec![(CoreCard::new(Deck::Deck1, Suit::Spades, Rank::King), false)],
+        );
        g
    }

@@ -922,33 +970,28 @@ mod tests {
    #[test]
    fn legal_destinations_for_ace_includes_only_first_empty_foundation() {
        let g = ace_only_state();
-        let card = CoreCard {
-            id: 100,
-            suit: Suit::Clubs,
-            rank: Rank::Ace,
-            face_up: true,
-        };
-        let dests = legal_destinations_for_card(&card, &PileType::Tableau(0), &g);
+        let card = CoreCard::new(Deck::Deck1, Suit::Clubs, Rank::Ace);
+        let dests =
+            legal_destinations_for_card(&card, &KlondikePile::Tableau(Tableau::Tableau1), &g);
        // Ace can be placed on every empty foundation. We only need
        // the count to be ≥ 1 and the source pile to be excluded.
        assert!(
            !dests.is_empty(),
            "Ace must have at least one legal destination"
        );
-        assert!(!dests.contains(&PileType::Tableau(0)));
+        assert!(!dests.contains(&KlondikePile::Tableau(Tableau::Tableau1)));
    }

    #[test]
    fn legal_destinations_excludes_source_pile() {
        let g = ace_only_state();
-        let card = CoreCard {
-            id: 100,
-            suit: Suit::Clubs,
-            rank: Rank::Ace,
-            face_up: true,
-        };
-        let dests = legal_destinations_for_card(&card, &PileType::Foundation(0), &g);
-        assert!(!dests.contains(&PileType::Foundation(0)));
+        let card = CoreCard::new(Deck::Deck1, Suit::Clubs, Rank::Ace);
+        let dests = legal_destinations_for_card(
+            &card,
+            &KlondikePile::Foundation(Foundation::Foundation1),
+            &g,
+        );
+        assert!(!dests.contains(&KlondikePile::Foundation(Foundation::Foundation1)));
    }

    // -----------------------------------------------------------------------
@@ -958,46 +1001,6 @@ mod tests {
    /// Pressing right-click on a face-up card with at least one legal
    /// destination must transition the state to `Active` carrying the
    /// expected source / count / legal-destination set.
-    #[test]
-    fn right_click_press_on_face_up_card_opens_radial() {
-        let mut app = radial_test_app();
-        let layout_window = Vec2::new(1280.0, 800.0);
-        let layout = compute_layout(layout_window, 0.0, 0.0, true);
-        let ace_pos = layout.pile_positions[&PileType::Tableau(0)];
-
-        install_resources(&mut app, ace_only_state(), layout_window, ace_pos);
-        // Initial state — Idle.
-        assert_eq!(
-            *app.world().resource::<RightClickRadialState>(),
-            RightClickRadialState::Idle
-        );
-
-        press(&mut app, MouseButton::Right);
-        app.update();
-
-        let state = app.world().resource::<RightClickRadialState>().clone();
-        match state {
-            RightClickRadialState::Active {
-                source_pile,
-                count,
-                cards,
-                legal_destinations,
-                ..
-            } => {
-                assert_eq!(source_pile, PileType::Tableau(0));
-                assert_eq!(count, 1);
-                assert_eq!(cards, vec![100]);
-                assert!(!legal_destinations.is_empty());
-                assert!(
-                    legal_destinations
-                        .iter()
-                        .any(|(p, _)| matches!(p, PileType::Foundation(_)))
-                );
-            }
-            other => panic!("expected Active, got {other:?}"),
-        }
-    }
-
    /// Releasing the right button while the cursor is over a destination
    /// icon must fire a `MoveRequestEvent` and return the state to Idle.
    #[test]
@@ -1005,7 +1008,7 @@ mod tests {
        let mut app = radial_test_app();
        let layout_window = Vec2::new(1280.0, 800.0);
        let layout = compute_layout(layout_window, 0.0, 0.0, true);
-        let ace_pos = layout.pile_positions[&PileType::Tableau(0)];
+        let ace_pos = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau1)];

        install_resources(&mut app, ace_only_state(), layout_window, ace_pos);
        press(&mut app, MouseButton::Right);
@@ -1015,7 +1018,7 @@ mod tests {
        let (dest_pile, anchor) = match app.world().resource::<RightClickRadialState>() {
            RightClickRadialState::Active {
                legal_destinations, ..
-            } => legal_destinations[0].clone(),
+            } => legal_destinations[0],
            _ => panic!("expected Active"),
        };

@@ -1032,7 +1035,7 @@ mod tests {
        let events = collect_move_events(&mut app);
        assert_eq!(events.len(), 1, "exactly one MoveRequestEvent expected");
        let evt = &events[0];
-        assert_eq!(evt.from, PileType::Tableau(0));
+        assert_eq!(evt.from, KlondikePile::Tableau(Tableau::Tableau1));
        assert_eq!(evt.to, dest_pile);
        assert_eq!(evt.count, 1);
        // State must return to Idle.
@@ -1049,7 +1052,7 @@ mod tests {
        let mut app = radial_test_app();
        let layout_window = Vec2::new(1280.0, 800.0);
        let layout = compute_layout(layout_window, 0.0, 0.0, true);
-        let ace_pos = layout.pile_positions[&PileType::Tableau(0)];
+        let ace_pos = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau1)];

        install_resources(&mut app, ace_only_state(), layout_window, ace_pos);
        press(&mut app, MouseButton::Right);
@@ -1080,7 +1083,7 @@ mod tests {
        let mut app = radial_test_app();
        let layout_window = Vec2::new(1280.0, 800.0);
        let layout = compute_layout(layout_window, 0.0, 0.0, true);
-        let ace_pos = layout.pile_positions[&PileType::Tableau(0)];
+        let ace_pos = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau1)];

        install_resources(&mut app, ace_only_state(), layout_window, ace_pos);
        press(&mut app, MouseButton::Right);
@@ -1106,7 +1109,7 @@ mod tests {
        let mut app = radial_test_app();
        let layout_window = Vec2::new(1280.0, 800.0);
        let layout = compute_layout(layout_window, 0.0, 0.0, true);
-        let king_pos = layout.pile_positions[&PileType::Tableau(0)];
+        let king_pos = layout.pile_positions[&KlondikePile::Tableau(Tableau::Tableau1)];

        install_resources(&mut app, face_down_only_state(), layout_window, king_pos);
        press(&mut app, MouseButton::Right);
--- a/Show More
+++ b/Show More